Bridge 协议（遗留节点传输）

Bridge 协议是一种遗留节点传输方式（TCP JSONL）。新的节点客户端应改用统一的 Gateway WebSocket 协议。

如果你在构建 operator 或节点客户端，请使用 Gateway 协议。

注意： 当前 OpenClaw 版本不再内置 TCP bridge 监听器；本文档仅供历史参考。 遗留的 bridge.* 配置键已不再是配置 schema 的一部分。

为什么同时存在两种协议

• 安全边界：bridge 暴露的是小型 allowlist，而不是完整的 gateway API 面。
• 配对 + 节点身份：节点准入由 gateway 负责，并与每个节点的 token 绑定。
• 发现体验：节点可以通过 Bonjour 在局域网发现 gateway，或通过 tailnet 直连。
• 回环 WS：完整的 WS 控制平面保持本地，除非通过 SSH 隧道。

传输

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

TLS 启用时，发现 TXT 记录包含 bridgeTls=1 和 bridgeTlsSha256 作为非机密提示。注意 Bonjour/mDNS TXT 记录未经认证；客户端不得在没有明确用户意图或其他带外验证的情况下，将广播的指纹视为权威固定值。

握手 + 配对

1. 客户端发送 hello，包含节点元数据 + token（如果已配对）。
2. 如果未配对，gateway 回复 error（NOT_PAIRED/UNAUTHORIZED）。
3. 客户端发送 pair-request。
4. Gateway 等待审批，然后发送 pair-ok 和 hello-ok。

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

帧格式

客户端 → Gateway：

• req / res：范围限定的 gateway RPC（chat、sessions、config、health、voicewake、skills.bins）
• event：节点信号（语音转录、agent 请求、chat 订阅、exec 生命周期）

Gateway → 客户端：

• invoke / invoke-res：节点命令（canvas.*、camera.*、screen.record、location.get、sms.send）
• event：订阅会话的 chat 更新
• ping / pong：保活

遗留的 allowlist 强制执行代码位于 src/gateway/server-bridge.ts（已移除）。

Exec 生命周期事件

节点可以触发 exec.finished 或 exec.denied 事件来展示 system.run 活动。 这些事件会被映射到 gateway 的系统事件中。（遗留节点仍可能触发 exec.started。）

Payload 字段（除非注明，否则均为可选）：

• sessionKey（必填）：接收系统事件的 agent 会话。
• 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 或广域 DNS-SD。

版本控制

Bridge 目前是隐式 v1（无最小/最大版本协商）。预期向后兼容；在进行任何破坏性更改前请添加 bridge 协议版本字段。