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

桥接协议是旧版节点传输（TCP JSONL）。新节点客户端应改用统一的网关 WebSocket 协议。若你在开发运维端或节点客户端，请使用 网关协议。说明： 当前 Moltbot 构建已不再包含 TCP 桥接监听器；本文档仅作历史参考。旧版 bridge.* 配置键已不再属于配置 schema。

为何曾有两种方式

• 安全边界：桥接只暴露小范围白名单，而非完整网关 API。
• 配对与节点身份：节点准入由网关管理，并与每节点 token 绑定。
• 发现体验：节点可通过 LAN 上的 Bonjour 发现网关，或经 tailnet 直连。
• 回环 WS：完整 WS 控制面保持本地，除非经 SSH 隧道暴露。

传输

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

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

握手与配对

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

hello-ok 返回 serverName，并可包含 canvasHostUrl。

帧

客户端 → 网关：

• req / res：限定范围的网关 RPC（chat、sessions、config、health、voicewake、skills.bins）
• event：节点信号（语音转写、agent 请求、聊天订阅、exec 生命周期）

网关 → 客户端：

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

旧版白名单执行曾位于 src/gateway/server-bridge.ts（已移除）。

Exec 生命周期事件

节点可发送 exec.finished 或 exec.denied 事件以暴露 system.run 活动，这些会映射为网关中的系统事件。（旧版节点可能仍发送 exec.started。）Payload 字段（除注明外均为可选）：

• sessionKey（必填）：接收系统事件的 agent 会话。
• runId：用于分组的唯一 exec id。
• command：原始或格式化命令字符串。
• exitCode、timedOut、success、output：完成详情（仅 finished）。
• reason：拒绝原因（仅 denied）。

Tailnet 使用

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

版本

桥接当前为隐式 v1（无最小/最大版本协商）。预期保持向后兼容；在做破坏性变更前应先增加桥接协议版本字段。