OpenClaw 🦞

Bridge 协议

Bridge 协议（旧版节点传输）

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

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

注意： 当前的 OpenClaw 构建不再提供 TCP bridge 监听器；本文档保留供历史参考。 旧版 bridge.* 配置密钥不再是配置模式的一部分。

为什么我们两者都有

  • 安全边界：bridge 公开一个小的允许列表，而不是 完整的 gateway API 表面。
  • 配对 + 节点身份：节点准入由 gateway 拥有，并绑定 到每节点令牌。
  • 发现 UX：节点可以通过 LAN 上的 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，包含节点元数据 + 令牌（如果已配对）。
  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：节点信号（语音转录、代理请求、chat 订阅、exec 生命周期）

Gateway → 客户端：

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

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

Exec 生命周期事件

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

负载字段（所有可选，除非注明）：

  • sessionKey（必需）：接收系统事件的代理会话。
  • 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 不 跨越网络；需要时使用手动主机/端口或广域 DNS‑SD。

版本控制

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