6.3 Bridge协议

Bridge 协议是 OpenClaw 的传统节点传输协议，基于 TCP JSONL 实现。本文档作为历史参考保留，当前版本已废弃，推荐使用 Gateway WebSocket 协议。

为何同时存在两种协议

Bridge 协议与 Gateway 协议并存的原因：

• 安全边界：Bridge 使用白名单机制，而 Gateway 提供完整 API 访问
• 配对与节点身份：由 Gateway 通过每节点令牌管理
• 发现用户体验：支持 Bonjour（局域网）或 Tailnet 直接连接
• 环回 WebSocket：控制平面保持本地，除非通过 SSH 隧道

传输机制

Bridge 协议使用 TCP 传输，每行一个 JSON 对象（JSONL 格式）。

基本特性

• 协议：TCP
• 格式：JSONL（每行一个 JSON 对象）
• 默认端口：18790（传统）
• TLS 支持：可选（通过 bridge.tls.enabled 启用）

TLS 配置

启用 TLS 后，TXT 记录会包含以下字段：

• bridgeTls=1：表示启用 TLS
• bridgeTlsSha256：用于证书固定的 SHA256 指纹

握手与配对流程

连接建立

1. 客户端发送 hello：包含元数据和令牌（如已配对）
2. 未配对响应：网关返回 error（NOT_PAIR 或 UNAUTHORIZED）
3. 配对请求：客户端发送 pair-request
4. 配对确认：网关批准后发送 pair-ok 和 hello-ok

hello-ok 响应字段

• serverName：服务器名称（必填）
• canvasHostUrl：Canvas 主机 URL（可选）

消息帧类型

客户端到网关

帧类型	用途	示例
req	RPC 请求	聊天、会话、配置等
res	RPC 响应	响应网关的 invoke
event	事件通知	语音转录、代理请求等

网关到客户端

帧类型	用途	示例
invoke	调用客户端功能	canvas.*、camera.*、sms.send
invoke-res	invoke 响应	调用结果
event	事件推送	聊天更新
ping/pong	心跳检测	保持连接活跃

Exec 生命周期事件

节点会发出以下执行事件：

事件类型

• exec.finished：执行完成
• exec.denied：执行被拒绝
• exec.started：执行开始（传统，可能发出）

事件载荷字段

字段	必填	说明
sessionKey	是	会话标识
runId	否	运行 ID
command	否	执行的命令
exitCode	否	退出码
timedOut	否	是否超时
success	否	是否成功
output	否	输出内容
reason	否	失败原因

Tailnet 使用

在 Tailscale 网络中使用 Bridge 协议：

配置方法

在 ~/.openclaw/openclaw.json 中设置：

{
  "bridge": {
    "bind": "tailnet"
  }
}

连接方式

• 通过 MagicDNS 连接
• 通过 Tailnet IP 地址连接

版本控制

• 当前版本：隐式 v1
• 版本协商：无
• 向后兼容：预期保持向后兼容
• 破坏性变更：在引入破坏性变更前需要版本字段

迁移建议

对于仍在使用 Bridge 协议的用户，建议迁移到 Gateway WebSocket 协议：

1. 更新 OpenClaw 到最新版本
2. 将客户端连接方式从 Bridge 切换到 Gateway
3. 移除配置文件中的 bridge.* 配置项
4. 使用 Gateway 协议的配对和认证机制