OpenClaw 게이트웨이 설정 및 네트워크 연결 가이드

여러 기기를 연결해서 사용하다 보면 네트워크 환경 때문에 골치 아픈 적이 많죠? 로컬 네트워크에서는 잘 작동하다가도 외부로 나가면 연결이 끊기거나, 매번 복잡한 IP 설정을 바꿔야 하는 번거로움은 개발자의 생산성을 떨어뜨리는 주범이에요. OpenClaw는 이런 문제를 해결하기 위해 Discovery와 Transport 구조를 아주 영리하게 설계했어요.

OpenClaw에는 겉보기에는 비슷하지만 서로 다른 두 가지 문제가 있어요.

1. Operator remote control: 다른 곳에서 실행 중인 Gateway를 제어하는 macOS 메뉴 바 앱.
2. Node pairing: iOS/Android(및 향후 노드)가 Gateway를 찾아 안전하게 페어링하는 과정.

디자인 목표는 모든 네트워크 Discovery와 광고(Advertising) 기능을 Node Gateway(openclaw gateway)에 집중시키고, 클라이언트(macOS 앱, iOS)는 이를 소비하는 구조를 유지하는 것이에요.

용어 정리

• Gateway: 상태(세션, 페어링, 노드 레지스트리)를 소유하고 채널을 실행하는 단일 롱러닝 Gateway 프로세스예요. 보통 호스트당 하나를 사용하지만, 격리된 멀티 Gateway 설정도 가능해요.
• Gateway WS (control plane): 기본적으로 127.0.0.1:18789에서 동작하는 WebSocket 엔드포인트예요. gateway.bind를 통해 LAN이나 tailnet에 바인딩할 수 있어요.
• Direct WS transport: SSH를 거치지 않고 LAN/tailnet을 직접 바라보는 Gateway WS 엔드포인트예요.
• SSH transport (fallback): SSH를 통해 127.0.0.1:18789를 포워딩하여 원격 제어하는 방식이에요.
• Legacy TCP bridge (deprecated/removed): 오래된 노드 transport 방식이며( Bridge protocol 참고), 더 이상 Discovery용으로 광고되지 않아요.

프로토콜 상세 내용:

• Gateway protocol
• Bridge protocol (legacy)

왜 “Direct”와 SSH를 모두 유지하나요?

• Direct WS는 동일 네트워크나 tailnet 내에서 최고의 UX를 제공해요.
  • Bonjour를 통한 LAN 자동 Discovery 지원
  • Gateway가 소유하는 페어링 토큰 및 ACL
  • Shell 액세스가 필요 없어서 프로토콜 범위를 좁고 검토 가능하게 유지할 수 있음
• SSH는 언제 어디서나 사용할 수 있는 범용적인 대비책(fallback)이에요.
  • SSH 접근만 가능하다면 어디서든 작동 (서로 다른 네트워크 간에도 가능)
  • Multicast나 mDNS 문제가 발생해도 영향받지 않음
  • SSH 외에 새로운 인바운드 포트를 열 필요가 없음

Discovery 입력 (클라이언트가 Gateway 위치를 찾는 방법)

1) Bonjour / mDNS (LAN 전용)

Bonjour는 최선을 다하지만 네트워크를 넘나들지는 못해요. 오직 “동일 LAN” 내에서의 편의를 위해서만 사용돼요.

대상 방향:

• Gateway는 Bonjour를 통해 자신의 WS 엔드포인트를 광고해요.
• 클라이언트는 이를 탐색하여 “Gateway 선택” 목록을 보여주고, 선택된 엔드포인트를 저장해요.

문제 해결 및 비콘 상세 정보: Bonjour.

서비스 비콘 상세 정보

• Service types:
  • _openclaw-gw._tcp (gateway transport beacon)
• TXT keys (비공개 아님):
  • role=gateway
  • transport=gateway
  • displayName=<friendly name> (운영자가 설정한 표시 이름)
  • lanHost=<hostname>.local
  • sshPort=22 (또는 광고된 포트)
  • gatewayPort=18789 (Gateway WS + HTTP)
  • gatewayTls=1 (TLS 활성화 시에만)
  • gatewayTlsSha256=<sha256> (TLS 활성화 및 지문 사용 가능 시에만)
  • canvasPort=<port> (canvas 호스트 포트; 현재 canvas 호스트 활성화 시 gatewayPort와 동일)
  • cliPath=<path> (선택 사항; 실행 가능한 openclaw 엔트리포인트 또는 바이너리의 절대 경로)
  • tailnetDns=<magicdns> (선택 사항 힌트; Tailscale 사용 가능 시 자동 감지)

보안 참고 사항:

• Bonjour/mDNS TXT 레코드는 인증되지 않은(unauthenticated) 정보예요. 클라이언트는 TXT 값을 UX 힌트로만 취급해야 해요.
• 라우팅(호스트/포트)은 TXT에서 제공하는 lanHost, tailnetDns, gatewayPort보다 해결된 서비스 엔드포인트(SRV + A/AAAA)를 우선시해야 해요.
• TLS pinning 시 광고된 gatewayTlsSha256이 이전에 저장된 핀을 덮어쓰도록 허용해서는 안 돼요.
• iOS/Android 노드는 Discovery 기반의 직접 연결을 TLS 전용으로 취급해야 하며, 처음 핀을 저장하기 전에 명시적인 “이 지문 신뢰” 확인(out-of-band verification)을 요구해야 해요.

비활성화/재정의:

• OPENCLAW_DISABLE_BONJOUR=1은 광고 기능을 비활성화해요.
• ~/.openclaw/openclaw.json의 gateway.bind 설정으로 Gateway 바인드 모드를 제어해요.
• OPENCLAW_SSH_PORT는 TXT에 광고되는 SSH 포트를 재정의해요 (기본값 22).
• OPENCLAW_TAILNET_DNS는 tailnetDns 힌트(MagicDNS)를 게시해요.
• OPENCLAW_CLI_PATH는 광고되는 CLI 경로를 재정의해요.

2) Tailnet (네트워크 간 연결)

런던과 비엔나 사이의 연결 같은 설정에서는 Bonjour가 도움이 되지 않아요. 이럴 때 권장되는 “Direct” 대상은 다음과 같아요.

• Tailscale MagicDNS 이름(권장) 또는 고정된 tailnet IP.

Gateway가 Tailscale 환경에서 실행 중임을 감지하면, 클라이언트를 위한 선택적 힌트로 tailnetDns를 게시해요 (광역 비콘 포함).

macOS 앱은 이제 Gateway Discovery 시 가공되지 않은 Tailscale IP보다 MagicDNS 이름을 선호해요. MagicDNS 이름은 현재 IP로 자동 해석되기 때문에, 노드 재시작이나 CGNAT 재할당 등으로 tailnet IP가 변경되어도 연결 안정성이 높아져요.

3) 수동 / SSH 타겟

직접적인 경로가 없거나 Direct 방식이 비활성화된 경우, 클라이언트는 루프백 Gateway 포트를 포워딩하여 언제든지 SSH를 통해 연결할 수 있어요.

Remote access 문서를 참고하세요.

Transport 선택 (클라이언트 정책)

권장되는 클라이언트 동작 순서예요.

1. 페어링된 Direct 엔드포인트가 설정되어 있고 도달 가능하다면, 그것을 사용하세요.
2. 그렇지 않고, Bonjour가 LAN에서 Gateway를 찾았다면 “이 Gateway 사용” 선택지를 제공하고 이를 Direct 엔드포인트로 저장하세요.
3. 그렇지 않고, tailnet DNS/IP가 설정되어 있다면 Direct 연결을 시도하세요.
4. 모두 실패하면 SSH로 돌아가세요.

Pairing + 인증 (Direct Transport)

Gateway는 노드와 클라이언트의 입장을 허가하는 진실의 원천(source of truth)이에요.

• 페어링 요청은 Gateway에서 생성, 승인 또는 거부돼요 (Gateway pairing 참고).
• Gateway는 다음 사항을 강제해요.
  • 인증 (토큰 / 키 쌍)
  • 범위(Scopes)/ACL (Gateway는 모든 메서드에 대한 단순 프록시가 아니에요)
  • Rate limits (속도 제한)

컴포넌트별 역할

• Gateway: Discovery 비콘을 광고하고, 페어링 결정을 소유하며, WS 엔드포인트를 호스팅해요.
• macOS 앱: 사용자가 Gateway를 선택하도록 돕고, 페어링 프롬프트를 표시하며, SSH는 대비책으로만 사용해요.
• iOS/Android 노드: 편의를 위해 Bonjour를 탐색하고 페어링된 Gateway WS에 연결해요.

AI Setup Assistant

다음 단계

• Gateway protocol
• Remote access
• Gateway pairing