网关架构

各组件如何组合：网关、代理、频道。

概览

• 单一长驻 网关 拥有所有消息面（WhatsApp 经 Baileys、Telegram 经 grammY、Slack、Discord、Signal、iMessage、WebChat）。
• 控制面客户端（macOS 应用、CLI、Web 管理、自动化）通过** WebSocket** 在配置的绑定主机（默认 127.0.0.1:18789）连接网关。
• 节点（macOS/iOS/Android/无头）也通过 WebSocket 连接，但声明 role: node 及显式能力/命令。
• 每主机一个网关；它是唯一打开 WhatsApp 会话的地方。
• 画布主机（默认 18793）提供代理可编辑的 HTML 与 A2UI。

组件与流程

网关（守护进程）

维护提供商连接；暴露类型化 WS API（请求、响应、服务端推送事件）；按 JSON Schema 校验入站帧；发出 agent、chat、presence、health、heartbeat、cron 等事件。

客户端（Mac 应用 / CLI / Web 管理）

每客户端一个 WS 连接。发送请求（health、status、send、agent、system-presence）。订阅事件（tick、agent、presence、shutdown）。

节点（macOS / iOS / Android / 无头）

以 role: node 连接同一 WS 服务。在 connect 中提供设备身份；配对是基于设备的（角色 node），审批存储在设备配对库。暴露 canvas.*、camera.*、screen.record、location.get 等命令。协议细节：网关协议。

WebChat

使用网关 WS API 获取聊天历史与发送的静态 UI。远程部署时通过与其他客户端相同的 SSH/Tailscale 隧道连接。

连接生命周期、线缆协议、配对与本地信任

• 首帧必须为 connect；握手后请求/响应与事件格式固定。
• 若设置 CLAWDBOT_GATEWAY_TOKEN（或 --token），connect.params.auth.token 必须匹配否则关闭连接。
• 有副作用的方法（send、agent）需要幂等键以便安全重试。
• 节点必须在 connect 中包含 role: "node" 及 caps/commands/permissions。
• 所有 WS 客户端（操作员与节点）在 connect 时包含设备身份；新设备 ID 需配对审批，网关颁发设备令牌供后续连接。本地连接可自动批准；非本地连接需对 connect.challenge 签名并显式批准。详见 网关协议、配对、安全。

远程访问

推荐：Tailscale 或 VPN。备选：SSH 隧道 ssh -N -L 18789:127.0.0.1:18789 user@host。隧道上使用相同握手与认证令牌。远程部署可为 WS 启用 TLS 与可选证书固定。

运维

启动：moltbot gateway（前台，日志到 stdout）。健康：通过 WS 的 health（也包含在 hello-ok 中）。监管：launchd/systemd 自动重启。

不变量

每主机恰好一个网关控制单一 Baileys 会话。握手必须；首帧非 JSON 或非 connect 则强制关闭。事件不重放；客户端需在断档时自行刷新。