Bridge protocol (giao thức node cũ)

Bridge protocol là giao thức node cũ (TCP JSONL). Các node client mới nên dùng Gateway WebSocket protocol thống nhất thay thế.

Nếu các bạn đang xây dựng operator hoặc node client, hãy dùng Gateway protocol.

Lưu ý: Các bản build OpenClaw hiện tại không còn đi kèm TCP bridge listener nữa; tài liệu này được giữ lại để tham khảo lịch sử. Các config key bridge.* cũ không còn nằm trong config schema nữa.

Tại sao có cả hai

  • Security boundary: bridge chỉ expose một allowlist nhỏ thay vì toàn bộ API surface của gateway.
  • Pairing + node identity: việc cho phép node truy cập do gateway quản lý và gắn với token riêng cho từng node.
  • Discovery UX: các node có thể tìm gateway qua Bonjour trên LAN, hoặc kết nối trực tiếp qua tailnet.
  • Loopback WS: toàn bộ WS control plane ở local trừ khi được tunnel qua SSH.

Transport

  • TCP, mỗi dòng là một JSON object (JSONL).
  • TLS tùy chọn (khi bridge.tls.enabled là true).
  • Port listener mặc định cũ là 18790 (các build hiện tại không khởi động TCP bridge).

Khi TLS được bật, các discovery TXT record sẽ bao gồm bridgeTls=1 cộng với bridgeTlsSha256 để các node có thể pin certificate.

Handshake + pairing

  1. Client gửi hello với node metadata + token (nếu đã paired).
  2. Nếu chưa paired, gateway trả về error (NOT_PAIRED/UNAUTHORIZED).
  3. Client gửi pair-request.
  4. Gateway đợi phê duyệt, sau đó gửi pair-ok và hello-ok.

hello-ok trả về serverName và có thể bao gồm canvasHostUrl.

Frames

Client → Gateway:

  • req / res: scoped gateway RPC (chat, sessions, config, health, voicewake, skills.bins)
  • event: node signals (voice transcript, agent request, chat subscribe, exec lifecycle)

Gateway → Client:

  • invoke / invoke-res: node commands (canvas.*, camera.*, screen.record, location.get, sms.send)
  • event: chat updates cho các session đã subscribe
  • ping / pong: keepalive

Legacy allowlist enforcement trước đây nằm trong src/gateway/server-bridge.ts (đã xóa).

Exec lifecycle events

Các node có thể emit event exec.finished hoặc exec.denied để hiển thị hoạt động system.run. Những event này được map thành system events trong gateway. (Các node cũ có thể vẫn emit exec.started.)

Các trường payload (tất cả đều optional trừ khi có ghi chú):

  • sessionKey (bắt buộc): agent session nhận system event.
  • runId: exec id duy nhất để nhóm.
  • command: chuỗi lệnh thô hoặc đã format.
  • exitCode, timedOut, success, output: chi tiết hoàn thành (chỉ cho finished).
  • reason: lý do từ chối (chỉ cho denied).

Sử dụng Tailnet

  • Bind bridge vào tailnet IP: bridge.bind: "tailnet" trong ~/.openclaw/openclaw.json.
  • Các client kết nối qua MagicDNS name hoặc tailnet IP.
  • Bonjour không hoạt động xuyên mạng; dùng manual host/port hoặc wide-area DNS‑SD khi cần.

Versioning

Bridge hiện tại là implicit v1 (không có min/max negotiation). Backward‑compat được mong đợi; thêm trường bridge protocol version trước khi có breaking changes.