桥接协议（旧版节点传输）

桥接协议是一�?*旧版**节点传输（TCP JSONL）。新节点客户�? 应改为使用统一�?Gateway WebSocket 协议�?

如果您正在构�?operator 或节点客户端，请使用 Gateway 协议�?

**注意�?*Claw 构建不再 当前 Open包含 TCP 桥接监听器；本文档保留作为历史参考�? 旧版 bridge.* 配置键不再是配置架构的一部分�?

为什么两者都�?

• 安全边界：桥接暴露一个小白名单，而不是完整的 Gateway API 表面�?
• 配对 + 节点身份：节点准入由 Gateway 拥有，并绑定�? 每个节点的令牌�?
• 发现用户体验：节点可以通过 LAN 上的 Bonjour 发现 Gateway，或通过 tailnet 直接连接�?
• 回环 WS：完整的 WS 控制平面保持在本地，除非通过 SSH 隧道�?

传输

• TCP，每行一�?JSON 对象（JSONL）�?
• 可�?TLS（当 bridge.tls.enabled �?true 时）�?
• 旧版默认监听端口�?18790（当前构建不启动 TCP 桥接）�?

启用 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（聊天、会话、配置、健康、语音唤醒、skills.bins�?
• event：节点信号（语音转录、代理请求、聊天订阅、执行生命周期）

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（必需）：接收系统事件的代理会话�?
• runId：用于分组的唯一执行 ID�?
• command：原始或格式化的命令字符串�?
• exitCode、timedOut、success、output：完成详情（�?finished）�?
• reason：拒绝原因（�?denied）�?

Tailnet 使用

将桥接绑定到 tailnet IP：在 ~/.openclaw/openclaw.json 中设�?bridge.bind: "tailnet"�?

客户端通过 MagicDNS 名称�?tailnet IP 连接�? Bonjour **�?*跨网络；如需要，使用手动主机/端口或广�?DNS‑SD�?

版本控制

桥接当前�?隐式 v1*（无最�?最大协商）。预计向后兼容； 在进行任何破坏性更改之前，添加桥接协议版本字段�?