桥接协议（传统节点传输）
适用范围
在以下情况使用此页面：
- 构建或调试节点客户端（iOS/Android/macOS 节点模式）
- 调查配对或桥接身份验证失败
- 审计网关暴露的节点表面
桥接协议是 传统 节点传输（TCP JSONL）。新的节点客户端 应该改用统一的网关 WebSocket 协议。
如果您正在构建操作员或节点客户端，请使用 网关协议。
注意： 当前的 Moltbot 构建版本不再附带 TCP 桥接监听器；此文档仅供历史参考。
传统的 bridge.* 配置键不再是配置架构的一部分。
为什么我们两者都有
- 安全边界：桥接暴露了一个小的允许列表，而不是 完整的网关 API 表面。
- 配对 + 节点身份：节点准入由网关拥有，并绑定到 每节点令牌。
- 发现 UX：节点可以通过 LAN 上的 Bonjour 发现网关，或通过 tailnet 直接连接。
- 回环 WS：完整的 WS 控制平面保持本地，除非通过 SSH 隧道传输。
传输
- TCP，每行一个 JSON 对象（JSONL）。
- 可选的 TLS（当
bridge.tls.enabled为 true 时）。 - 传统默认监听器端口是
18790（当前构建版本不启动 TCP 桥接）。
启用 TLS 时，发现 TXT 记录包括 bridgeTls=1 加上
bridgeTlsSha256，以便节点可以固定证书。
握手 + 配对
- 客户端发送带有节点元数据 + 令牌的
hello（如果已配对）。 - 如果未配对，网关回复
error（NOT_PAIRED/UNAUTHORIZED）。 - 客户端发送
pair-request。 - 网关等待批准，然后发送
pair-ok和hello-ok。
hello-ok 返回 serverName，可能包括 canvasHostUrl。
帧
客户端 → 网关：
req/res：作用域网关 RPC（chat、sessions、config、health、voicewake、skills.bins）event：节点信号（voice transcript、agent request、chat subscribe、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。）
负载字段（除非注明，否则都是可选的）：
sessionKey（必需）：接收系统事件的代理会话。runId：用于分组的唯一 exec id。command：原始或格式化的命令字符串。exitCode、timedOut、success、output：完成详细信息（仅限完成）。reason：拒绝原因（仅限拒绝）。
Tailnet 使用
- 将桥接绑定到 tailnet IP：
~/.moltbot/moltbot.json中的bridge.bind: "tailnet"。 - 客户端通过 MagicDNS 名称或 tailnet IP 连接。
- Bonjour 不跨网络；在需要时使用手动主机/端口或广域 DNS‑SD。
版本控制
桥接目前是 隐式 v1（无最小/最大协商）。期望向后兼容； 在任何重大更改之前添加桥接协议版本字段。