Gateway 架构

最后更新: 2026-01-22

概述

单个长期运行的 Gateway 管理所有消息平台(通过 Baileys 连接 WhatsApp、通过 grammY 连接 Telegram、Slack、Discord、Signal、iMessage、WebChat)。
控制平面客户端(macOS 应用、CLI、Web UI、自动化脚本)通过 WebSocket 连接到 Gateway,默认绑定地址是 127.0.0.1:18789。
Node 节点(macOS/iOS/Android/无头模式)也通过 WebSocket 连接,但会声明 role: node 并明确指定能力和命令。
每台主机只运行一个 Gateway;它是唯一打开 WhatsApp Session 的地方。
Canvas host 服务(默认端口 18793)提供 Agent 可编辑的 HTML 和 A2UI。

组件和流程

Gateway (守护进程)

维护与各个消息平台的连接。
提供类型化的 WS API(请求、响应、服务端推送事件)。
根据 JSON Schema 验证入站帧。
发出事件,如 agent、chat、presence、health、heartbeat、cron。

客户端 (Mac 应用 / CLI / Web 管理界面)

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

Node 节点 (macOS / iOS / Android / 无头模式)

连接到同一个 WS 服务器,使用 role: node。
在 connect 时提供设备身份;Pairing 是基于设备的(角色为 node),审批信息存储在设备配对存储中。
暴露命令,如 canvas.*、camera.*、screen.record、location.get。

协议详情:

Gateway 协议

WebChat

静态 UI,使用 Gateway WS API 获取聊天历史和发送消息。
在远程设置中,通过与其他客户端相同的 SSH/Tailscale 隧道连接。

连接生命周期(单个客户端)

Client                    Gateway
  |                          |
  |---- req:connect -------->|
  |<------ res (ok) ---------|   (or res error + close)
  |   (payload=hello-ok carries snapshot: 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 必须匹配,否则 socket 会关闭。
有副作用的方法(send、agent)需要幂等键来安全重试;服务器会保留一个短期的去重缓存。
Node 节点必须在 connect 中包含 role: "node" 以及能力、命令和权限。

Pairing 和本地信任

所有 WS 客户端(操作者和节点)在 connect 时都要包含设备身份。
新设备 ID 需要配对审批;Gateway 会为后续连接颁发设备令牌。
本地连接(回环地址或 Gateway 主机自己的 Tailnet 地址)可以自动审批,保持同主机使用体验流畅。
非本地连接必须签名 connect.challenge 随机数,并需要明确审批。
Gateway 认证(gateway.auth.*)仍然适用于所有连接,无论本地还是远程。

详情: Gateway 协议、Pairing、安全。

协议类型和代码生成

TypeBox schemas 定义协议。
从这些 schemas 生成 JSON Schema。
从 JSON Schema 生成 Swift 模型。

远程访问

推荐: Tailscale 或 VPN。

备选方案: SSH 隧道

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

相同的握手和认证令牌通过隧道应用。
在远程设置中可以为 WS 启用 TLS 和可选的证书固定。

运维快照

启动: openclaw gateway(前台运行,日志输出到 stdout)。
健康检查: 通过 WS 发送 health(也包含在 hello-ok 中)。
监督: 使用 launchd/systemd 实现自动重启。

不变量

每台主机只有一个 Gateway 控制单个 Baileys Session。
握手是强制的;任何非 JSON 或非 connect 的首帧都会导致硬关闭。
事件不会重放;客户端必须在出现间隙时刷新。