桥接协议(传统节点传输)

桥接协议是一种传统节点传输方式(TCP JSONL)。新的节点客户端应使用统一的网关 WebSocket 协议。

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

注意: 当前的 OpenClaw 构建版本不再提供 TCP 桥接监听器;本文档仅作为历史参考保留。传统的 bridge.* 配置键不再是配置模式的一部分。

为什么同时存在两种协议

• 安全边界:桥接暴露一个小的允许列表,而不是完整的网关 API 接口。
• 配对 + 节点身份:节点准入由网关管理,并绑定到每个节点的令牌。
• 发现用户体验:节点可以通过局域网上的 Bonjour 发现网关,或直接通过 tailnet 连接。
• 回环 WS:完整的 WS 控制平面保持本地,除非通过 SSH 隧道传输。

传输

• TCP,每行一个 JSON 对象(JSONL)。
• 可选的 TLS(当 bridge.tls.enabled 为 true 时)。
• 传统默认监听端口为 18790(当前构建不启动 TCP 桥接)。

启用 TLS 时,发现 TXT 记录包含 bridgeTls=1 和 bridgeTlsSha256,以便节点可以固定证书。

握手 + 配对

1. 客户端发送 hello,包含节点元数据 + 令牌(如果已配对)。
2. 如果未配对,网关回复 error(NOT_PAIRED/UNAUTHORIZED)。
3. 客户端发送 pair-request。
4. 网关等待批准,然后发送 pair-ok 和 hello-ok。

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

帧

客户端 → 网关:

• req / res:作用域网关 RPC(聊天、会话、配置、健康、语音唤醒、技能二进制文件)
• event:节点信号(语音转录、代理请求、聊天订阅、执行生命周期)

网关 → 客户端:

• 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 活动。这些事件在网关中被映射为系统事件。(传统节点可能仍会发出 exec.started。)

负载字段(除非标注,所有字段都是可选的):

• sessionKey(必需):接收系统事件的代理会话。
• runId:用于分组的唯一执行 ID。
• command:原始或格式化的命令字符串。
• exitCode、timedOut、success、output:完成详情(仅完成时)。
• reason:拒绝原因(仅拒绝时)。

Tailnet 使用

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

版本控制

桥接目前是隐式 v1(无最小/最大协商)。预期向后兼容;在任何破坏性更改之前添加桥接协议版本字段。