架构

概览

• 单个长期运行的 Gateway 拥有所有消息通道（WhatsApp via Baileys、Telegram via grammY、Slack、Discord、Signal、iMessage、WebChat）
• 控制面板客户端（macOS 应用、CLI、Web UI、自动化）通过 WebSocket 连接到网关，默认绑定 127.0.0.1:18789
• 节点（macOS/iOS/Android/headless）也通过 WebSocket 连接，但声明 role: node 及明确的能力/命令
• 每台主机一个网关；它是唯一打开 WhatsApp 会话的地方
• Canvas 主机（默认 18793）提供智能体可编辑的 HTML 和 A2UI

组件和流程

Gateway（守护进程）

• 维护 provider 连接
• 暴露类型化的 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 / headless）

• 连接到同一 WS 服务器，带 role: node
• 在 connect 中提供设备身份；配对是基于设备的（角色 node），审批存储在设备配对存储中
• 暴露命令如 canvas.*、camera.*、screen.record、location.get

WebChat

• 静态 UI，使用网关 WS API 进行聊天历史和发送
• 远程设置中，通过与其他客户端相同的 SSH/Tailscale 隧道连接

连接生命周期（单客户端）

Client                          Gateway
  |                               |
  |---- req:connect ------------>|
  |<------ res (ok) -------------|  (或 res error + close)
  |  (payload=hello-ok 携带快照: presence + health)
  |                               |
  |<------ event:presence -------|
  |<------ event:tick -----------|
  |                               |
  |------- req:agent ----------->|
  |<------ res:agent ------------|  (ack: {runId,status:"accepted"})
  |<------ event:agent ----------|  (streaming)
  |<------ res:agent ------------|  (final: {runId,status,summary})
  |                               |

线协议（摘要）

• 传输：WebSocket，文本帧带 JSON 负载
• 第一帧必须是 connect
• 握手后：
  • 请求：{type:"req", id, method, params} → {type:"res", id, ok, payload|error}
  • 事件：{type:"event", event, payload, seq?, stateVersion?}
• 如果设置了 OPENCLAW_GATEWAY_TOKEN（或 --token），connect.params.auth.token 必须匹配，否则套接字关闭
• 副作用方法（send、agent）需要幂等键以安全重试；服务器保持短期去重缓存
• 节点必须在 connect 中包含 role: "node" 及 caps/commands/permissions

配对与本地信任

• 所有 WS 客户端（操作员 + 节点）在 connect 时包含设备身份
• 新设备 ID 需要配对审批；网关为后续连接颁发设备 token
• 本地连接（回环或网关主机自己的 tailnet 地址）可以自动审批以保持同主机 UX 流畅
• 非本地连接必须签署 connect.challenge nonce 并需要明确审批
• 网关认证（gateway.auth.*）仍适用于所有连接，本地或远程

远程访问

• 首选：Tailscale 或 VPN
• 替代：SSH 隧道

ssh -N -L 18789:127.0.0.1:18789 user@host

• 隧道上应用相同的握手 + 认证 token
• 远程设置中可以启用 TLS + 可选固定

操作快照

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

不变量

• 每台主机正好一个 Gateway 控制单个 Baileys 会话
• 握手是必需的；任何非 JSON 或非 connect 的第一帧都会硬关闭
• 事件不重放；客户端必须在间隙时刷新