桥接协议

The Bridge protocol is a **legacy** node transport (TCP JSONL). New node clients should use the unified Gateway WebSocket protocol.

If you're an operator or building a node client, use the Gateway protocol.

Gateway 协议 请参阅。

注意： 现在的 OpenClaw 是 TCP 桥接监听器提供不会执行。本页面是歴史的参照作为残已被。

旧 bridge.* 的设置密钥是、也是与设置模式的一部不是。

• Security boundary: the bridge exposes a small allowlist instead of the full gateway API surface.
• Pairing + node identity: node admission is owned by the gateway and tied to a per-node token.
• Discovery UX: nodes can discover gateways via Bonjour on LAN, or connect directly over a tailnet.
• Loopback WS: the full WS control plane stays local unless tunneled via SSH.

• TCP（1行在次机1次的 JSON 对象：JSONL）。
• TLS 是任意（bridge.tls.enabled 但 true 的場合）。
• 旧默认的待受端口是 18790（现在是 TCP 桥接起動不会执行）。

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

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 范围（聊天、会话、配置、健康检查、语音唤醒、技能二进制）。
• event：节点信号（语音录音、代理请求、聊天订阅、exec 生命周期）。

Gateway → 客户端：

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

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

Nodes can emit exec.finished or exec.denied events to surface system.run activity. These are mapped to system events in the gateway. (Legacy nodes may still emit exec.started.)

Payload fields (all optional unless noted):

payload 字段（注記没有限里任意）：

• sessionKey (required): agent session to receive the system event.
• runId: unique exec id for grouping.
• command：生的/整形済见命令字符串。
• exitCode、timedOut、success、output：完成時的详情（finished 仅）。
• reason：拒绝理由（denied 仅）。

• 桥接 tailnet IP 在绑定：bridge.bind: "tailnet" 在 ~/.openclaw/openclaw.json。
• 客户端是 MagicDNS 名或 tailnet IP 在连接执行。
• Bonjour does **not** cross networks; use manual host/port or wide-area DNS‑SD when needed.

Bridge is currently **implicit v1** (no min/max negotiation). Backward‑compat is expected; add a bridge protocol version field before any breaking changes.