桥接协议

# 它曾经存在的原因

• 安全边界：bridge 暴露的是小范围允许列表，而不是完整的 Gateway 网关 API 表面。
• 配对 + 节点身份：节点准入由 Gateway 网关负责，并绑定到每个节点专属的 token。
• 设备发现 UX：节点可以通过局域网上的 Bonjour 发现 Gateway 网关，或通过 tailnet 直接连接。
• Loopback WS：完整的 WS 控制平面会保持在本地，除非通过 SSH 隧道转发。

# 传输协议

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

启用 TLS 时，设备发现 TXT 记录会包含 bridgeTls=1，并包含 bridgeTlsSha256 作为非机密提示。请注意，Bonjour/mDNS TXT 记录未经认证；除非有明确的用户意图或其他带外验证，客户端不得将广播的指纹视为权威 pin。

# 握手 + 配对

1. 客户端发送带有节点元数据 + token（如果已配对）的 hello。
2. 如果未配对，Gateway 网关回复 error（NOT_PAIRED/UNAUTHORIZED）。
3. 客户端发送 pair-request。
4. Gateway 网关等待批准，然后发送 pair-ok 和 hello-ok。

历史上，hello-ok 会返回 serverName；托管插件表面现在通过 pluginSurfaceUrls 广播。Canvas/A2UI 使用 pluginSurfaceUrls.canvas；已弃用的 canvasHostUrl 别名不属于重构后的协议。

# 帧

客户端 → Gateway 网关：

• req / res：限定范围的 Gateway 网关 RPC（聊天、会话、配置、健康检查、voicewake、skills.bins）
• event：节点信号（语音转写、智能体请求、聊天订阅、exec 生命周期）

Gateway 网关 → 客户端：

• invoke / invoke-res：节点命令（canvas.*、camera.*、screen.record、 location.get、sms.send）
• event：已订阅会话的聊天更新
• ping / pong：keepalive

旧版允许列表强制执行位于 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"（仅历史用法；bridge.* 不再有效）。
• 客户端通过 MagicDNS 名称或 tailnet IP 连接。
• Bonjour 不会跨网络工作；需要时请使用手动 host/port 或广域 DNS-SD。

# 版本控制

bridge 曾是隐式 v1（没有 min/max 协商）。本节仅为历史参考；当前节点/操作员客户端使用 WebSocket Gateway 网关协议。

# 相关

• Gateway 网关协议
• 节点