탐색 & 전송

OpenClaw에는 표면적으로 비슷해 보이는 두 가지 별개의 문제가 있습니다:

설계 목표는 모든 네트워크 탐색/광고를 노드 게이트웨이(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 브릿지 (폐기/제거됨): 이전 노드 전송 (브릿지 프로토콜 참조). 탐색을 위해 더 이상 광고되지 않음.

프로토콜 세부 사항:

직접 WS는 동일 네트워크와 Tailnet 내에서 최고의 UX입니다:
- LAN에서 Bonjour를 통한 자동 탐색
- 게이트웨이가 소유하는 페어링 토큰 + ACL
- 셸 접근 불필요. 프로토콜 표면을 타이트하고 감사 가능하게 유지 가능
SSH는 범용 폴백으로 유지됩니다:
- SSH 접근이 있는 곳이면 어디서든 동작 (관련 없는 네트워크 간에도)
- 멀티캐스트/mDNS 문제에서 생존
- SSH 이외의 새로운 인바운드 포트 불필요

Bonjour는 최선형이며 네트워크를 넘지 못합니다. “동일 LAN” 편의를 위해서만 사용됩니다.

목표 방향:

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

보안 참고 사항:

Bonjour/mDNS TXT 레코드는 인증되지 않습니다. 클라이언트는 TXT 값을 UX 힌트로만 취급해야 합니다.
라우팅(호스트/포트)은 TXT가 제공하는 lanHost, tailnetDns, gatewayPort보다 해석된 서비스 엔드포인트(SRV + A/AAAA)를 선호해야 합니다.
TLS 고정은 광고된 gatewayTlsSha256이 이전에 저장된 핀을 덮어쓰는 것을 절대 허용해서는 안 됩니다.
iOS/Android 노드는 탐색 기반 직접 연결을 TLS 전용으로 취급하고, 최초 핀을 저장하기 전에 명시적인 “이 핑거프린트 신뢰” 확인을 요구해야 합니다 (대역 외 검증).

비활성화/오버라이드:

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

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

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

원격 접근을 참조하세요.

권장 클라이언트 동작:

게이트웨이가 노드/클라이언트 승인의 진실 소스입니다.