Bridge protocol (레거시 Node 전송 방식)

새로운 시스템을 구축하다 보면 이전 버전과의 호환성을 유지하거나 예전 방식을 파헤쳐야 할 때가 있죠. 특히 네트워크 프로토콜이 바뀌는 과정에서 기존 연결 방식을 이해하고 마이그레이션을 준비하는 과정은 개발자에게 꽤나 번거로운 작업이에요.

Bridge protocol은 TCP JSONL 기반의 레거시 전송 방식이에요. 현재 새로운 node 클라이언트를 만들고 있다면 이 방식 대신 통합된 Gateway WebSocket 프로토콜을 사용해야 해요.

필요한 것

• OpenClaw 레거시 빌드 (최신 빌드는 TCP bridge listener를 포함하지 않아요)
• TCP JSONL 통신이 가능한 환경
• Tailscale (Tailnet 연결을 사용하는 경우)

빠른 시작

Bridge protocol을 사용해 연결하는 최소한의 단계예요. 현재 빌드에서는 bridge.* 설정 키가 더 이상 사용되지 않으니 참고하세요.

1. TCP 연결: 기본 포트인 18790으로 TCP 연결을 시작하세요.
2. Handshake: 클라이언트에서 노드 메타데이터와 토큰을 담은 hello 메시지를 보냅니다.
3. Pairing: 페어링되지 않은 상태라면 Gateway가 NOT_PAIRED 에러를 보냅니다. 이때 pair-request를 전송하고 승인을 기다리세요.
4. 데이터 교환: 페어링이 완료되면 req, res, event 프레임을 통해 데이터를 주고받을 수 있어요.

Why we have both

왜 Gateway API와 Bridge protocol이 공존했는지 그 이유예요.

• 보안 경계: Bridge는 전체 Gateway API 대신 허용된 리스트(allowlist)만 노출해요.
• 페어링 및 노드 식별: 노드 승인은 Gateway가 관리하며 노드별 토큰과 연결돼요.
• 검색 UX: Bonjour를 통해 LAN에서 Gateway를 찾거나 Tailnet을 통해 직접 연결할 수 있어요.
• Loopback WS: SSH 터널링을 사용하지 않는 한 전체 WS 제어 평면은 로컬에 유지돼요.

Transport & Frames

이 프로토콜은 한 줄에 하나의 JSON 객체를 사용하는 TCP JSONL 방식을 사용해요. bridge.tls.enabled가 true인 경우 TLS를 선택적으로 사용할 수 있어요.

클라이언트는 req, res, event 프레임을 Gateway로 보내 RPC를 호출하거나 노드 신호를 전달해요. 반대로 Gateway는 invoke, invoke-res를 통해 노드에 명령(카메라, 스크린 녹화 등)을 내리거나 ping, pong으로 연결 상태를 확인해요.

노드는 exec.finished나 exec.denied 같은 이벤트를 발생시켜 시스템 실행 활동을 알릴 수 있어요. 이때 sessionKey는 필수 항목이에요.

문제 해결

• NOT_PAIRED 또는 UNAUTHORIZED 에러: 클라이언트가 아직 페어링되지 않았거나 토큰이 잘못된 경우예요. pair-request를 먼저 보내고 승인을 받아야 해요.
• Bonjour 검색 실패: Bonjour는 네트워크를 넘나들지 못해요. Tailnet 같은 환경에서는 MagicDNS 이름이나 Tailnet IP를 사용해 직접 연결하세요.

AI Setup Assistant

다음 단계

• Gateway protocol