Bridge 协议是一种 旧版 节点传输 (TCP JSONL)。新节点客户端应使用统一的 Gateway WebSocket 协议。

如果您正在构建操作员或节点客户端，请使用 Gateway 协议。

注意： 当前的 OpenClaw 构建不再附带 TCP bridge 监听器；保留此文档以供历史参考。旧版 bridge.* 配置键不再是配置架构的一部分。

• 安全边界：bridge 暴露了一个小的允许列表，而不是完整的 gateway API 表面。
• 配对 + 节点身份：节点准入归 gateway 所有，并绑定到每个节点的令牌。
• 发现体验：节点可以通过 Bonjour 在 LAN 上发现 gateway，或通过 tailnet 直接连接。
• 环回 WS：除非通过 SSH 隧道，否则完整的 WS 控制平面保持本地。

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

启用 TLS 时，发现 TXT 记录包括 bridgeTls=1 加上 bridgeTlsSha256，以便节点可以固定证书。

1. 客户端发送带有节点元数据 + 令牌（如果已配对）的 hello。
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：节点信号 (voice transcript, agent request, chat subscribe, exec lifecycle)

Gateway → 客户端：

• invoke / invoke-res：节点命令 (canvas.*, camera.*, screen.record, location.get, sms.send)
• event：已订阅会话的聊天更新
• ping / pong：心跳

旧版允许列表强制执行位于 src/gateway/server-bridge.ts（已移除）。

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

有效负载字段（除非另有说明，否则全部可选）：

• sessionKey (必填)：接收系统事件的 agent 会话。
• runId: 用于分组的唯一 exec id。
• command: 原始或格式化的命令字符串。
• exitCode, timedOut, success, output: 完成详情（仅 finished）。
• reason: 拒绝原因（仅 denied）。

• 将 bridge 绑定到 tailnet IP：在 ~/.openclaw/openclaw.json 中设置 bridge.bind: "tailnet"。
• 客户端通过 MagicDNS 名称或 tailnet IP 连接。
• Bonjour 不会 跨越网络；需要时使用手动主机/端口或广域 DNS‑SD。

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