브릿지 프로토콜 (레거시 노드 전송)

브릿지 프로토콜은 레거시 노드 전송(TCP JSONL)입니다. 새로운 노드 클라이언트는 대신 통합 게이트웨이 WebSocket 프로토콜을 사용해야 합니다.

오퍼레이터 또는 노드 클라이언트를 구축하는 경우, 게이트웨이 프로토콜을 사용하세요.

참고: 현재 OpenClaw 빌드에는 더 이상 TCP 브릿지 리스너가 포함되어 있지 않습니다. 이 문서는 역사적 참고 자료로 유지됩니다. 레거시 bridge.* 설정 키는 더 이상 설정 스키마에 포함되지 않습니다.

두 가지를 모두 유지하는 이유

보안 경계: 브릿지는 전체 게이트웨이 API 표면 대신 작은 허용 목록만 노출합니다.
페어링 + 노드 ID: 노드 승인은 게이트웨이가 소유하며 노드별 토큰에 연결됩니다.
탐색 UX: 노드는 LAN에서 Bonjour를 통해 게이트웨이를 탐색하거나, Tailnet을 통해 직접 연결할 수 있습니다.
루프백 WS: 전체 WS 제어 플레인은 SSH를 통해 터널링하지 않는 한 로컬에 유지됩니다.

전송

TCP, 줄당 하나의 JSON 객체 (JSONL).
선택적 TLS (bridge.tls.enabled가 true인 경우).
레거시 기본 리스너 포트는 18790이었습니다 (현재 빌드에서는 TCP 브릿지를 시작하지 않음).

TLS가 활성화되면, 탐색 TXT 레코드에 bridgeTls=1과 비밀이 아닌 힌트로 bridgeTlsSha256이 포함됩니다. Bonjour/mDNS TXT 레코드는 인증되지 않으므로, 클라이언트는 명시적인 사용자 의도나 다른 대역 외 검증 없이 광고된 핑거프린트를 신뢰할 수 있는 핀으로 취급해서는 안 됩니다.

핸드셰이크 + 페어링

클라이언트가 노드 메타데이터 + 토큰(이미 페어링된 경우)과 함께 hello를 보냅니다.
페어링되지 않은 경우, 게이트웨이는 error (NOT_PAIRED/UNAUTHORIZED)로 응답합니다.
클라이언트가 pair-request를 보냅니다.
게이트웨이는 승인을 기다린 후 pair-ok와 hello-ok를 보냅니다.

hello-ok는 serverName을 반환하며 canvasHostUrl을 포함할 수 있습니다.

프레임

클라이언트 → 게이트웨이:

req / res: 범위 지정 게이트웨이 RPC (chat, sessions, config, health, voicewake, skills.bins)
event: 노드 시그널 (음성 트랜스크립트, 에이전트 요청, 채팅 구독, exec 라이프사이클)

게이트웨이 → 클라이언트:

invoke / invoke-res: 노드 명령어 (canvas.*, camera.*, screen.record, location.get, sms.send)
event: 구독된 세션의 채팅 업데이트
ping / pong: 킵얼라이브

레거시 허용 목록 적용은 src/gateway/server-bridge.ts에 있었습니다 (제거됨).

Exec 라이프사이클 이벤트

노드는 exec.finished 또는 exec.denied 이벤트를 발생시켜 system.run 활동을 표시할 수 있습니다. 이들은 게이트웨이에서 시스템 이벤트로 매핑됩니다. (레거시 노드는 여전히 exec.started를 발생시킬 수 있습니다.)

페이로드 필드 (명시되지 않는 한 모두 선택적):

sessionKey (필수): 시스템 이벤트를 수신할 에이전트 세션.
runId: 그룹화를 위한 고유 exec ID.
command: 원시 또는 포맷된 명령어 문자열.
exitCode, timedOut, success, output: 완료 세부 정보 (finished만 해당).
reason: 거부 사유 (denied만 해당).

Tailnet 사용

브릿지를 Tailnet IP에 바인딩: ~/.openclaw/openclaw.json에서 bridge.bind: "tailnet".
클라이언트는 MagicDNS 이름 또는 Tailnet IP를 통해 연결합니다.
Bonjour는 네트워크를 넘지 못합니다. 필요 시 수동 호스트/포트 또는 광역 DNS-SD를 사용하세요.

버전 관리

브릿지는 현재 암시적 v1입니다 (min/max 협상 없음). 하위 호환성이 예상됩니다. 호환성을 깨는 변경 전에 브릿지 프로토콜 버전 필드를 추가하세요.