OpenClaw 的核心是一个单一的长驻 Gateway 进程，它统一管理所有消息渠道和 AI Agent 会话。理解其架构，有助于你做出更好的部署决策和排查问题。
总体架构概览
- 单一长驻 Gateway 拥有所有消息接口（WhatsApp via Baileys、Telegram via grammY、Slack、Discord、Signal、iMessage、WebChat）
- 控制平面客户端（macOS 应用、CLI、Web UI、自动化脚本）通过 WebSocket 连接 Gateway
- Nodes（macOS/iOS/Android/无头设备）也通过 WebSocket 连接，但声明
role: node - 每台主机只有一个 Gateway；它是唯一开启 WhatsApp 会话的地方
核心组件详解
Gateway（守护进程）
- 维护所有消息提供者的连接
- 暴露类型化的 WebSocket API（请求、响应、服务器推送事件）
- 根据 JSON Schema 验证入站消息帧
- 发出
agent、chat、presence、health、heartbeat、cron等事件
客户端（macOS 应用 / CLI / Web 管理界面）
- 每个客户端一个 WebSocket 连接
- 发送请求：
health、status、send、agent、system-presence - 订阅事件：
tick、agent、presence、shutdown
Nodes（macOS / iOS / Android / 无头设备）
- 连接到同一个 WebSocket 服务器，但带
role: node - 在
connect时提供设备身份；配对基于设备（角色node） - 暴露命令如
canvas.*、camera.*、screen.record、location.get
WebChat
- 静态 UI，使用 Gateway WebSocket API 获取聊天历史和发送消息
- 在远程部署场景中，通过 SSH/Tailscale 隧道连接
WebSocket 通信协议
连接生命周期
- 客户端建立 WebSocket 连接
- 发送
connect帧（必须是第一帧） - Gateway 验证设备身份和认证 Token
- 握手完成后进入正常通信模式
消息格式
json
// 请求
{ "type": "req", "id": "unique-id", "method": "send", "params": {} }
// 响应
{ "type": "res", "id": "unique-id", "ok": true, "payload": {} }
// 服务器推送事件
{ "type": "event", "event": "agent", "payload": {}, "seq": 1 }认证与幂等性
- 如果设置了
OPENCLAW_GATEWAY_TOKEN，connect.params.auth.token必须匹配 - 副作用方法（
send、agent）需要幂等性 Key，服务端维护短期去重缓存 - Nodes 必须在
connect时包含role: "node"以及 caps/commands/permissions
配对与本地信任
- 所有 WebSocket 客户端（操作者 + Nodes）在
connect时提供设备身份 - 新设备 ID 需要配对审批；Gateway 为后续连接颁发设备 Token
- 本地连接（回环地址或 Gateway 主机的 Tailnet 地址）可自动审批
- 所有连接必须对
connect.challenge随机数签名 - 签名 Payload
v3还绑定了platform+deviceFamily；Gateway 在重连时固定已配对的元数据，元数据变化需要重新配对 - 非本地连接仍需要明确审批
远程访问方案
推荐：Tailscale 或 VPN
最简单、最安全的方式，无需额外配置。
替代：SSH 隧道
bash
ssh -N -L 18789:127.0.0.1:18789 user@remote-host相同的握手和认证 Token 通过隧道生效。
Gateway 运维快速参考
bash
# 前台启动（调试）
openclaw gateway
# 以服务方式运行（launchd/systemd）
openclaw gateway status
openclaw gateway start
openclaw gateway stop
openclaw gateway restart重要不变式
- 每台主机只有一个 Gateway 控制一个 Baileys（WhatsApp）会话
- 握手是强制的；非 JSON 或非
connect的第一帧会导致连接直接关闭 - 事件不会重放；客户端必须在断开后主动刷新状态
Canvas 与 A2UI
Gateway HTTP 服务器还提供 Canvas 宿主：
/__openclaw__/canvas/：Agent 可编辑的 HTML/CSS/JS/__openclaw__/a2ui/：A2UI 宿主
与 Gateway 使用同一端口（默认 18789）。
原文：Gateway Architecture - OpenClaw | 来源：OpenClaw 官方文档