Gateway 架构

最后更新：2026-01-22

概览

单一长驻 Gateway 负责所有消息通道（WhatsApp via Baileys、Telegram via grammY、Slack、Discord、Signal、iMessage、WebChat）。
控制面客户端（macOS 应用、CLI、Web UI、自动化工具）通过 WebSocket 连接到 Gateway 的绑定地址（默认 127.0.0.1:18789）。
节点（macOS/iOS/Android/无头模式）也通过 WebSocket 连接，但声明 role: node 并带有明确的能力/命令。
每台主机一个 Gateway；它是唯一打开 WhatsApp 会话的地方。
Canvas 宿主 由 Gateway HTTP 服务器托管：
- /__openclaw__/canvas/（agent 可编辑的 HTML/CSS/JS）
- /__openclaw__/a2ui/（A2UI 宿主）与 Gateway 使用同一个端口（默认 18789）。

组件与流程

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 / 无头模式）

连接到同一个 WS 服务器，声明 role: node。
在 connect 时提供设备身份；配对是基于设备的（role node），审批信息存储在设备配对存储中。
暴露 canvas.*、camera.*、screen.record、location.get 等命令。

协议细节：

Gateway 协议

WebChat

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

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

sequenceDiagram
    participant Client
    participant Gateway

    Client->>Gateway: req:connect
    Gateway-->>Client: res (ok)
    Note right of Gateway: or res error + close
    Note left of Client: payload=hello-ok<br>snapshot: presence + health

    Gateway-->>Client: event:presence
    Gateway-->>Client: event:tick

    Client->>Gateway: req:agent
    Gateway-->>Client: res:agent<br>ack {runId, status:"accepted"}
    Gateway-->>Client: event:agent<br>(streaming)
    Gateway-->>Client: res:agent<br>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）需要幂等 key，以便安全重试；服务端维护一个短期去重缓存。
节点必须在 connect 中包含 role: "node" 以及能力/命令/权限。

配对与本地信任

所有 WS 客户端（操作者和节点）在 connect 时都需要包含设备身份。
新设备 ID 需要配对审批；Gateway 为后续连接签发设备 token。
本地连接（回环地址或 Gateway 主机自身的 tailnet 地址）可以自动审批，保持同主机操作的流畅体验。
所有连接都需要对 connect.challenge nonce 进行签名。
签名载荷 v3 还绑定了 platform + deviceFamily；Gateway 会在重连时锁定已配对的元数据，元数据变更需要重新配对。
非本地连接仍需显式审批。
Gateway 认证（gateway.auth.*）对所有连接生效，无论本地还是远程。

详情：Gateway 协议、配对、安全。

协议类型定义与代码生成

TypeBox schema 定义了协议。
从 schema 生成 JSON Schema。
从 JSON Schema 生成 Swift 模型。

远程访问

推荐方式：Tailscale 或 VPN。

替代方式：SSH 隧道

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

隧道上使用相同的握手 + auth token。
远程部署中可以为 WS 启用 TLS + 可选证书锁定。

运维概要

启动：openclaw gateway（前台运行，日志输出到 stdout）。
健康检查：WS 上发送 health（也包含在 hello-ok 中）。
进程管理：launchd/systemd 实现自动重启。

约束

每台主机上只有一个 Gateway 控制一个 Baileys 会话。
握手是强制的；任何非 JSON 或非 connect 的首帧会立即断开。
事件不会重放；客户端需要在中断后自行刷新。