Bridge protocol（旧版 node 传输）

Bridge 协议是一个 旧版 的 node 传输（TCP JSONL）。新的 node 客户端应使用统一的 Gateway WebSocket 协议。

如果你在构建 operator 或 node 客户端，请使用： Gateway protocol。

注意： 当前 OpenClaw 构建已不再包含 TCP bridge listener；本文仅作为历史参考保留。 旧的 bridge.* 配置 key 也不再属于 config schema 的一部分。

为什么曾经同时存在两套

• 安全边界：bridge 只暴露一个小的 allowlist，而不是完整的 gateway API 面。
• 配对 + node 身份：node 的准入由 gateway 负责，并绑定到每个 node 的 token。
• Discovery 体验：node 可在 LAN 上通过 Bonjour 发现 gateway，或通过 tailnet 直接连接。
• Loopback WS：完整 WS 控制面默认保持本地，除非通过 SSH 隧道转发。

传输层

• TCP，每行一个 JSON 对象（JSONL）。
• 可选 TLS（当 bridge.tls.enabled 为 true）。
• 旧版默认监听端口为 18790（当前构建不会启动 TCP bridge）。

当启用 TLS 时，discovery TXT 记录会包含 bridgeTls=1 以及 bridgeTlsSha256，以便 node pin 证书。

握手 + 配对

1. 客户端发送 hello（node 元数据 + token；若已配对）。
2. 若未配对，gateway 回复 error（NOT_PAIRED/UNAUTHORIZED）。
3. 客户端发送 pair-request。
4. gateway 等待批准，然后发送 pair-ok 与 hello-ok。

hello-ok 会返回 serverName，并且可能包含 canvasHostUrl。

帧（Frames）

Client → Gateway：

• req / res：按 scope 的 gateway RPC（chat、sessions、config、health、voicewake、skills.bins）
• event：node 信号（语音转写、agent request、chat subscribe、exec lifecycle）

Gateway → Client：

• invoke / invoke-res：对 node 的命令（canvas.*、camera.*、screen.record、location.get、sms.send）
• event：订阅 session 的 chat 更新
• ping / pong：keepalive

旧版 allowlist enforcement 位于 src/gateway/server-bridge.ts（已移除）。

Exec 生命周期事件

Nodes 可以发出 exec.finished 或 exec.denied 事件，用于暴露 system.run 活动。 这些会被映射为 gateway 里的 system events。（旧版 nodes 可能仍会发送 exec.started。）

Payload 字段（除特别说明外均可选）：

• sessionKey（必填）：接收 system event 的 agent session。
• runId：用于分组的唯一 exec id。
• command：原始或格式化后的命令字符串。
• exitCode、timedOut、success、output：完成细节（仅 finished）。
• reason：拒绝原因（仅 denied）。

Tailnet 使用

• 将 bridge 绑定到 tailnet IP：在 ~/.openclaw/openclaw.json 中设置 bridge.bind: "tailnet"。
• 客户端通过 MagicDNS 名称或 tailnet IP 连接。
• Bonjour 无法跨网络；需要时使用手工 host/port 或 wide-area DNS‑SD。

版本管理

Bridge 目前是 隐式 v1（没有 min/max 协商）。预期应保持向后兼容；如果要做破坏性变更，应先增加 bridge 协议版本字段。