Gateway 架构

最后更新：2026-01-22 · 翻译自 docs.openclaw.ai

概述

一个单一的、长期运行的 Gateway 拥有所有消息传递界面（通过 Baileys 的 WhatsApp、通过 grammY 的 Telegram、Slack、Discord、Signal、iMessage、WebChat）。
控制平面客户端（macOS 应用、CLI、Web UI、自动化工具）通过配置的绑定主机（默认 127.0.0.1:18789）上的 WebSocket 连接到 Gateway。
节点（macOS/iOS/Android/无头模式）也通过 WebSocket 连接，但声明角色为 node，并带有显式的能力（caps）和命令（commands）。
每个主机只有一个 Gateway；它是唯一打开 WhatsApp 会话的地方。
一个画布主机（默认端口 18793）提供代理可编辑的 HTML 和 A2UI。

组件和流程

Gateway（守护进程）

维护与各提供商（Provider）的连接。
公开一个类型化的 WS API（请求、响应、服务器推送事件）。
根据 JSON Schema 验证入站帧。
发出事件，如 agent、chat、presence、health、heartbeat、cron。

客户端（macOS 应用 / CLI / Web 管理界面）

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

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

连接到相同的 WS 服务器，角色为 role: node。
在连接时提供设备身份（device identity）；配对基于设备（角色为 node），批准信息存储在设备配对存储中。
公开命令，如 canvas.*、camera.*、screen.record、location.get。

协议细节：Gateway 协议

WebChat

使用 Gateway WS API 进行聊天历史记录和消息发送的静态 UI。
在远程设置中，通过与其他客户端相同的 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 ------|  (流式传输)
  |<------ res:agent --------|  (最终: {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），需要幂等键（idempotency key）才能安全重试；服务器保留一个短期的去重缓存。
节点必须在 connect 中包含 role: "node" 以及 caps/commands/permissions。

配对 + 本地信任

所有 WS 客户端（操作员 + 节点）在连接时都包含设备身份。
新的设备 ID 需要配对批准；Gateway 为后续连接颁发设备令牌（device token）。
本地连接（环回地址或 Gateway 主机自身的 tailnet 地址）可以自动批准，以保持同主机的用户体验顺畅。
非本地连接必须签署 connect.challenge 的 nonce，并需要明确批准。
Gateway 身份验证（gateway.auth.*）仍然适用于所有连接，无论本地还是远程。

协议类型和代码生成

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

远程访问

首选：Tailscale 或 VPN。
备选方案：SSH 隧道 — ssh -N -L 18789:127.0.0.1:18789 user@host
相同的握手 + 身份验证令牌适用于隧道。
可以为远程设置中的 WS 启用 TLS + 可选的证书固定（pinning）。

操作快照

启动：openclaw gateway（前台运行，日志输出到 stdout）。
健康检查：通过 WS 的 health 请求（也包含在 hello-ok 中）。
进程监督：使用 launchd/systemd 实现自动重启。

不变量

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