OpenClaw 한국어 문서

Appearance

검색 및 전송 ​

OpenClaw에는 표면적으로는 유사해 보이는 두 가지 서로 다른 문제가 있습니다.

  1. 오퍼레이터 원격 제어: macOS 메뉴 바 앱이 다른 곳에서 실행 중인 게이트웨이를 제어합니다.
  2. 노드 페어링: iOS/Android(및 미래의 노드)가 게이트웨이를 찾아 안전하게 페어링합니다.

설계 목표는 모든 네트워크 검색/광고를 노드 게이트웨이(openclaw gateway)에 유지하고 클라이언트(mac 앱, iOS)는 소비자로 유지하는 것입니다.

용어 ​

  • 게이트웨이: 상태(세션, 페어링, 노드 레지스트리)를 소유하고 채널을 실행하는 단일 장시간 실행 게이트웨이 프로세스. 대부분의 설정에서는 호스트당 하나를 사용하며, 격리된 멀티 게이트웨이 설정도 가능합니다.
  • 게이트웨이 WS(컨트롤 플레인): 기본적으로 127.0.0.1:18789의 WebSocket 엔드포인트. gateway.bind를 통해 LAN/tailnet에 바인딩할 수 있습니다.
  • 직접 WS 전송: LAN/tailnet을 대상으로 하는 게이트웨이 WS 엔드포인트(SSH 없음).
  • SSH 전송(폴백): 127.0.0.1:18789를 SSH를 통해 포워딩하는 원격 제어.
  • 레거시 TCP 브리지(제거됨): 이전 노드 전송(브리지 프로토콜 참조). 더 이상 검색 광고되지 않으며 현재 빌드의 일부가 아닙니다.

프로토콜 세부 사항:

"직접 연결"과 SSH를 모두 유지하는 이유 ​

  • 직접 WS는 동일 네트워크 및 tailnet 내에서 최고의 UX를 제공합니다:
    • Bonjour를 통한 LAN 자동 검색
    • 게이트웨이가 소유하는 페어링 토큰 + ACL
    • 쉘 액세스 불필요; 프로토콜 표면이 엄격하고 감사 가능하게 유지됩니다
  • SSH는 범용 폴백으로 남아 있습니다:
    • SSH 액세스가 있는 곳이라면 어디서든 작동합니다 (관련 없는 네트워크에서도)
    • 멀티캐스트/mDNS 문제에서 살아남습니다
    • SSH 외에는 새로운 인바운드 포트가 필요 없습니다

검색 입력 (클라이언트가 게이트웨이 위치를 파악하는 방법) ​

1) Bonjour / DNS-SD 검색 ​

멀티캐스트 Bonjour는 최선을 다하지만 네트워크를 넘지 않습니다. OpenClaw는 구성된 광역 DNS-SD 도메인을 통해 동일한 게이트웨이 비콘을 탐색할 수 있으므로 검색은 다음을 커버할 수 있습니다:

  • 동일 LAN의 local.
  • 크로스 네트워크 검색을 위한 구성된 유니캐스트 DNS-SD 도메인

목표 방향:

  • 게이트웨이는 Bonjour를 통해 WS 엔드포인트를 광고합니다.
  • 클라이언트는 탐색하고 "게이트웨이 선택" 목록을 표시한 다음, 선택된 엔드포인트를 저장합니다.

문제 해결 및 비콘 세부 사항: Bonjour.

서비스 비콘 세부 사항 ​

  • 서비스 유형:
    • _openclaw-gw._tcp (게이트웨이 전송 비콘)
  • TXT 키 (비시크릿):
    • role=gateway
    • transport=gateway
    • displayName=<친숙한 이름> (오퍼레이터 구성 표시 이름)
    • lanHost=<hostname>.local
    • gatewayPort=18789 (게이트웨이 WS + HTTP)
    • gatewayTls=1 (TLS 활성화 시에만)
    • gatewayTlsSha256=<sha256> (TLS가 활성화되고 지문이 사용 가능한 경우에만)
    • canvasPort=<port> (캔버스 호스트 포트; 현재 캔버스 호스트가 활성화된 경우 gatewayPort와 동일)
    • tailnetDns=<magicdns> (선택적 힌트; Tailscale 사용 가능 시 자동 감지)
    • sshPort=<port> (mDNS 전체 모드 전용; 광역 DNS-SD는 생략할 수 있으며, 이 경우 SSH 기본값은 22)
    • cliPath=<path> (mDNS 전체 모드 전용; 광역 DNS-SD는 원격 설치 힌트로 계속 기록)

보안 참고 사항:

  • Bonjour/mDNS TXT 레코드는 인증되지 않습니다. 클라이언트는 TXT 값을 UX 힌트로만 취급해야 합니다.
  • 라우팅(호스트/포트)은 TXT에서 제공하는 lanHost, tailnetDns, 또는 gatewayPort보다 해결된 서비스 엔드포인트(SRV + A/AAAA)를 우선해야 합니다.
  • TLS 핀닝은 광고된 gatewayTlsSha256이 이전에 저장된 핀을 재정의하도록 허용해서는 안 됩니다.
  • iOS/Android 노드는 선택된 경로가 보안/TLS 기반인 경우 처음 핀을 저장하기 전에 명시적인 "이 지문을 신뢰" 확인이 필요합니다 (대역 외 검증).

비활성화/재정의:

  • OPENCLAW_DISABLE_BONJOUR=1은 광고를 비활성화합니다.
  • ~/.openclaw/openclaw.json의 gateway.bind는 게이트웨이 바인딩 모드를 제어합니다.
  • OPENCLAW_SSH_PORT는 sshPort가 내보내질 때 광고되는 SSH 포트를 재정의합니다.
  • OPENCLAW_TAILNET_DNS는 tailnetDns 힌트(MagicDNS)를 게시합니다.
  • OPENCLAW_CLI_PATH는 광고된 CLI 경로를 재정의합니다.

2) Tailnet (크로스 네트워크) ​

런던/비엔나 스타일 설정의 경우 Bonjour는 도움이 되지 않습니다. 권장 "직접" 대상은:

  • Tailscale MagicDNS 이름(선호) 또는 안정적인 tailnet IP.

게이트웨이가 Tailscale 아래에서 실행되고 있음을 감지할 수 있는 경우, 클라이언트(광역 비콘 포함)를 위한 선택적 힌트로 tailnetDns를 게시합니다.

macOS 앱은 이제 게이트웨이 검색에서 원시 Tailscale IP보다 MagicDNS 이름을 우선합니다. 이는 tailnet IP가 변경될 때(예: 노드 재시작 또는 CGNAT 재할당 후) MagicDNS 이름이 자동으로 현재 IP로 해석되므로 안정성이 향상됩니다.

모바일 노드 페어링의 경우, 검색 힌트는 tailnet/공용 경로에서 전송 보안을 완화하지 않습니다:

  • iOS/Android는 보안된 첫 번째 tailnet/공용 연결 경로(wss:// 또는 Tailscale Serve/Funnel)를 여전히 필요로 합니다.
  • 발견된 원시 tailnet IP는 라우팅 힌트이지, 일반 텍스트 원격 ws://를 사용할 권한이 아닙니다.
  • 개인 LAN 직접 연결 ws://는 지원됩니다.
  • 모바일 노드를 위한 가장 단순한 Tailscale 경로를 원한다면, 검색과 설정 코드가 모두 동일한 보안 MagicDNS 엔드포인트로 해결되도록 Tailscale Serve를 사용하십시오.

3) 수동 / SSH 대상 ​

직접 경로가 없는 경우(또는 직접 연결이 비활성화된 경우), 클라이언트는 루프백 게이트웨이 포트를 포워딩하여 SSH를 통해 항상 연결할 수 있습니다.

원격 액세스 참조.

전송 선택 (클라이언트 정책) ​

권장 클라이언트 동작:

  1. 페어링된 직접 엔드포인트가 구성되어 있고 연결 가능하면 그것을 사용합니다.
  2. 그렇지 않으면, 검색이 local. 또는 구성된 광역 도메인에서 게이트웨이를 찾으면, 원탭 "이 게이트웨이 사용" 선택을 제공하고 직접 엔드포인트로 저장합니다.
  3. 그렇지 않으면, tailnet DNS/IP가 구성되어 있으면 직접 연결을 시도합니다. tailnet/공용 경로의 모바일 노드의 경우, 직접은 일반 텍스트 원격 ws://가 아닌 보안 엔드포인트를 의미합니다.
  4. 그렇지 않으면 SSH로 폴백합니다.

페어링 + 인증 (직접 전송) ​

게이트웨이는 노드/클라이언트 승인의 신뢰 소스입니다.

  • 페어링 요청은 게이트웨이에서 생성/승인/거부됩니다 (게이트웨이 페어링 참조).
  • 게이트웨이는 다음을 강제합니다:
    • 인증 (토큰 / 키페어)
    • 범위/ACL (게이트웨이는 모든 메서드에 대한 원시 프록시가 아닙니다)
    • 속도 제한

컴포넌트별 책임 ​

  • 게이트웨이: 검색 비콘을 광고하고, 페어링 결정을 소유하며, WS 엔드포인트를 호스팅합니다.
  • macOS 앱: 게이트웨이 선택을 돕고, 페어링 프롬프트를 표시하며, SSH는 폴백으로만 사용합니다.
  • iOS/Android 노드: Bonjour를 편의 수단으로 탐색하고 페어링된 게이트웨이 WS에 연결합니다.