理解 Gateway 架构

OpenClaw Gateway 的长驻进程模型、WebSocket 控制面、nodes、pairing、远程访问和运行不变量。

OpenClaw 的中心不是某个聊天窗口，而是 Gateway。Gateway 是长期运行的进程，负责接入消息渠道、维护会话、调度 Agent、暴露控制面，并把来自聊天软件、CLI、Web UI、macOS app、移动设备和自动化任务的请求收束到同一个运行时。

一句话理解 Gateway

Gateway 是 OpenClaw 的控制面。

它做四件事：

连接消息平台，例如 WhatsApp、Telegram、Slack、Discord、Signal、iMessage、WebChat。
接收控制端连接，例如 CLI、macOS app、Web UI、自动化脚本。
接收 node 连接，例如 macOS、iOS、Android 或 headless 节点暴露的设备能力。
负责会话、健康状态、心跳、cron、hooks 和 Agent 运行事件。

默认情况下，控制面监听在：

127.0.0.1:18789

这个默认值很关键：OpenClaw 默认把 Gateway 放在本机回环地址上，而不是直接暴露到公网。

组件分工

Gateway daemon：

维护各个 provider 的连接。
暴露 WebSocket API。
校验入站 JSON frame。
推送 agent、chat、presence、health、heartbeat、cron 等事件。

控制端 clients：

CLI、macOS app、Web admin、自动化脚本都属于控制端。
每个 client 建立一条 WebSocket 连接。
常见请求包括 health、status、send、agent、system-presence。

Nodes：

node 不是 Gateway，也不接管消息渠道。
node 用 role: "node" 连接同一个 WebSocket server。
node 暴露设备能力，例如 canvas.*、camera.*、screen.record、location.get、system.*。

WebChat：

WebChat 是静态聊天界面。
它通过 Gateway WebSocket API 读历史和发送消息。
远程部署时，它应该走同一条 SSH 或 Tailscale 入口，而不是另开一个无保护入口。

为什么官方强调一个 host 一个 Gateway

一个 host 上只应该有一个长期 Gateway 控制同一组渠道状态。尤其是 WhatsApp 这类渠道，官方架构里强调 Gateway 是打开会话的唯一位置。

如果同一台机器起多个 Gateway 去抢同一个渠道，会出现三类问题：

provider session 被重复登录或互相踢下线。
session、pairing、allowlist、cron 状态分裂。
Agent 记忆和 workspace 写入分叉，排障时无法判断哪个进程是真正入口。

实践判断很简单：一个机器、一个信任边界、一个 Gateway。

WebSocket 握手

Gateway 的协议是 WebSocket 文本 frame，payload 是 JSON。第一个 frame 必须是 connect。握手后才进入请求、响应和事件流。

常见结构可以理解为：

{ "type": "req", "id": "1", "method": "health", "params": {} }

响应：

{ "type": "res", "id": "1", "ok": true, "payload": {} }

事件：

{ "type": "event", "event": "health", "payload": {} }

副作用请求需要 idempotency key，避免重试时重复发送消息或重复触发 Agent。

Pairing 和本地信任

所有 WebSocket 客户端和 nodes 都会在 connect 阶段带设备身份。新设备需要 pairing approval，Gateway 会给后续连接发设备 token。

可以这样理解：

本机 loopback 连接可以有更顺滑的体验。
非本地连接仍然需要显式 approval。
Gateway 的 gateway.auth.* 仍然适用于本地和远程连接。
Tailscale、trusted proxy、shared-secret 只是不同认证入口，不是绕过 pairing 的理由。

这也是为什么官方安全文档反复强调：OpenClaw 是个人助手信任模型，不是给互不信任用户共享一个 Agent 的多租户边界。

Canvas 和 A2UI

Gateway HTTP server 也承载两个内置路径：

/__openclaw__/canvas/
/__openclaw__/a2ui/

它们复用 Gateway 端口。Canvas 面向 Agent 可编辑的 HTML/CSS/JS，A2UI 面向 Agent-to-UI 的交互宿主。你不需要把它们理解成单独服务；它们属于 Gateway 运行时的一部分。

远程访问

远程访问优先级：

Tailscale 或 VPN。
SSH tunnel。
有明确认证、TLS、反向代理和审计的受控入口。

SSH tunnel 示例：

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

这条命令的意思是：本机访问 127.0.0.1:18789，实际转发到远端机器的 Gateway loopback 端口。Gateway 仍然不用直接暴露公网端口。

运维快照

前台启动：

openclaw gateway

查看状态：

openclaw health
openclaw status
openclaw gateway status

生产使用时，应该交给 launchd、systemd 或 macOS app 监督重启。不要依赖一个临时终端窗口长期托管。

不变量

一个 host 上一个 Gateway 控制同一套渠道。
Gateway 默认监听 loopback。
第一帧必须是 connect。
非 JSON 或非 connect 首帧会被关闭。
events 不保证 replay，客户端发现事件 gap 后应该重新拉状态。
远程入口仍然需要 auth 和 pairing。