메인 콘텐츠로 건너뛰기

​
검색 및 전송 프로토콜

OpenClaw에는 표면적으로는 유사해 보이는 두 가지 뚜렷한 문제가 있습니다:
  1. 운영자 원격 제어: 다른 곳에서 실행 중인 게이트웨이를 제어하는 macOS 메뉴 바 앱.
  2. 노드 페어링: iOS/Android(및 향후 노드들)가 게이트웨이를 찾아 안전하게 페어링하기.
설계 목표는 모든 네트워크 검색/광고를 노드 게이트웨이(openclaw gateway)에 집중하고 클라이언트(mac 앱, iOS)는 소비자 역할만 하도록 유지하는 것입니다.

​
용어

  • Gateway (게이트웨이): 상태(세션, 페어링, 노드 레지스트리)를 소유하고 채널을 실행하는 단일 장기 실행 게이트웨이 프로세스. 대부분의 설정에서는 호스트당 하나를 사용하며, 격리된 다중 게이트웨이 설정도 가능합니다.
  • Gateway 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 내에서 최고의 사용자 경험을 제공합니다:
    • Bonjour를 통한 LAN 자동 검색
    • 게이트웨이가 소유하는 페어링 토큰 + ACL
    • 셸 접근 불필요; 프로토콜 표면을 엄격하고 감사 가능하게 유지 가능
  • SSH는 보편적인 대체 수단으로 유지됩니다:
    • SSH 접근이 가능한 어디서나 작동 (관련 없는 네트워크에서도)
    • 멀티캐스트/mDNS 문제를 우회할 수 있음
    • SSH 외에 새로운 인바운드 포트 불필요

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

​
1) Bonjour / mDNS (LAN 전용)

Bonjour는 최선을 다하지만 네트워크를 넘어가지 않습니다. “동일 LAN” 편의를 위해서만 사용됩니다. 대상 방향:
  • 게이트웨이는 Bonjour를 통해 WS 엔드포인트를 광고합니다.
  • 클라이언트는 탐색하여 “게이트웨이 선택” 목록을 표시하고, 선택한 엔드포인트를 저장합니다.
문제 해결 및 비콘 세부 사항: Bonjour.

​
서비스 비콘 세부 사항

  • 서비스 유형:
    • _openclaw-gw._tcp (게이트웨이 전송 비콘)
  • TXT 키 (비밀 아님):
    • role=gateway
    • lanHost=<hostname>.local
    • sshPort=22 (광고된 값)
    • gatewayPort=18789 (게이트웨이 WS + HTTP)
    • gatewayTls=1 (TLS가 활성화된 경우에만)
    • gatewayTlsSha256=<sha256> (TLS가 활성화되고 지문이 사용 가능한 경우에만)
    • canvasPort=<port> (캔버스 호스트 포트; 현재 캔버스 호스트가 활성화된 경우 gatewayPort와 동일)
    • cliPath=<path> (선택; 실행 가능한 openclaw 진입점 또는 바이너리의 절대 경로)
    • tailnetDns=<magicdns> (선택적 힌트; Tailscale 사용 시 자동 감지됨)
보안 주의사항:
  • Bonjour/mDNS TXT 레코드는 인증되지 않습니다. 클라이언트는 TXT 값을 UX 힌트로만 처리해야 합니다.
  • 라우팅(호스트/포트)은 TXT로 제공된 lanHost, tailnetDns, 또는 gatewayPort보다 해결된 서비스 엔드포인트(SRV + A/AAAA)를 우선해야 합니다.
  • TLS 피닝(pinning)은 이전에 저장된 핀을 광고된 gatewayTlsSha256이 덮어쓰지 않도록 해야 합니다.
  • iOS/Android 노드는 검색 기반 직접 연결을 TLS 전용으로 처리하고, 첫 번째 핀 저장 전에 명시적인 “이 지문 신뢰” 확인이 필요합니다 (대역 외 검증).
비활성화/재정의:
  • OPENCLAW_DISABLE_BONJOUR=1은 광고를 비활성화합니다.
  • ~/.openclaw/openclaw.json의 gateway.bind는 게이트웨이 바인드 모드를 제어합니다.
  • OPENCLAW_SSH_PORT는 TXT에서 광고하는 SSH 포트를 재정의합니다 (기본값: 22).
  • OPENCLAW_TAILNET_DNS는 tailnetDns 힌트(MagicDNS)를 게시합니다.
  • OPENCLAW_CLI_PATH는 광고된 CLI 경로를 재정의합니다.

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

런던/비엔나 스타일 설정처럼 서로 다른 네트워크에서는 Bonjour가 도움이 되지 않습니다. 권장하는 “직접” 대상은:
  • Tailscale MagicDNS 이름(권장) 또는 안정적인 tailnet IP입니다.
게이트웨이가 Tailscale 환경에서 실행 중임을 감지할 수 있다면, 클라이언트에 대한 선택적 힌트로 tailnetDns를 게시합니다 (광역 비콘 포함).

​
3) 수동 / SSH 대상

직접 경로가 없거나 비활성화된 경우, 클라이언트는 루프백 게이트웨이 포트를 SSH로 포워딩하여 항상 연결할 수 있습니다. 원격 접근을 참조하세요.

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

권장 클라이언트 동작:
  1. 페어링된 직접 엔드포인트가 설정되어 있고 도달 가능하면 사용합니다.
  2. 그렇지 않으면, Bonjour가 LAN에서 게이트웨이를 발견하면 “이 게이트웨이 사용” 선택지를 제공하고 직접 엔드포인트로 저장하세요.
  3. 그렇지 않으면, tailnet DNS/IP가 설정되어 있으면 직접 연결을 시도하세요.
  4. 그렇지 않으면, SSH로 대체합니다.

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

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

​
구성 요소별 책임

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