OpenClawSkills
GitHub
核心概念 • 5 分钟阅读

网关架构

WebSocket 网关架构、组件和客户端流程

最后更新：2026-01-22

Tutorial.step

概述

- 一个长期存在的 网关 拥有所有消息传递界面（通过 WhatsApp

Baileys、GrammY 电报、Slack、Discord、Signal、iMessage、WebChat）。

- 控制平面客户端（macOS 应用程序、CLI、Web UI、自动化）连接到

配置绑定主机上通过 WebSocket 的网关（默认

''127.0.0.1:18789'')。

- 节点（macOS/iOS/Android/无头）也通过 WebSocket 连接，但是

使用显式大写/命令声明 ''role: node''。

- 每台主机一个网关；这是唯一打开 WhatsApp 会话的地方。

Tutorial.step

组件和流程

#

Tutorial.step

网关（守护进程）

- 维护提供商连接。

- 公开类型化的 WS API（请求、响应、服务器推送事件）。

- 根据 JSON 模式验证入站帧。

- 发出 ''agent''、''chat''、''presence''、''health''、''heartbeat''、''cron'' 等事件。

#

Tutorial.step

客户端（mac 应用程序/CLI/Web 管理）

- 每个客户端一个 WS 连接。

- 发送请求（''health''、''status''、''send''、''agent''、''system-presence''）。

- 订阅事件（''tick''、''agent''、''presence''、''shutdown''）。

#

Tutorial.step

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

- 使用 ''role: node'' 连接到 ''同一 WS 服务器''。

- 在 ''connect'' 中提供设备标识；配对是''基于设备''（角色 ''node''）并且

批准存在于设备配对存储中。

- 公开诸如 ''canvas.*''、''camera.*''、''screen.record''、''location.get'' 之类的命令。

协议详细信息：

- ''网关协议''

#

Tutorial.step

网络聊天

- 使用 Gateway WS API 进行聊天历史记录和发送的静态 UI。

- 在远程设置中，通过与其他设备相同的 SSH/Tailscale 隧道进行连接

客户。

Tutorial.step

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

Terminal
Client                    Gateway
  |                          |
  ||   (or res error + close)
  |   (payload=hello-ok carries snapshot: presence + health)
  |                          |
  |< event:presence -----|   (final: {runId,status,summary})
  |                          |
Tutorial.step

有线协议（摘要）

- 传输：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''）需要幂等键

安全地重试；服务器保留短暂的重复数据删除缓存。

Tutorial.step

配对+本地信任

- 所有 WS 客户端（运营商 + 节点）都包含 ''connect'' 上的 ''设备身份''。

- 新设备 ID 需要配对批准；网关发出设备令牌

用于后续连接。

- 本地连接（环回或网关主机自己的tailnet地址）可以

自动批准以保持同一主机用户体验的流畅。

- ''非本地''连接必须签署 ''connect.challenge'' 随机数并要求

明确批准。

- 网关身份验证 (''gateway.auth.*'') 仍然适用于''所有''连接，本地或

远程。详细信息：''网关协议''、''配对''、''安全''。

Tutorial.step

协议类型和代码生成

- TypeBox 模式定义协议。

- JSON 模式是从这些模式生成的。

- Swift 模型是从 JSON 模式生成的。

Tutorial.step

远程访问

- 首选：Tailscale 或 VPN。

- 替代方案：SSH 隧道

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

- 相同的握手+身份验证令牌适用于隧道。

- 可以在远程设置中为 WS 启用 TLS + 可选固定。

Tutorial.step

操作快照

- 开始：''openclaw gateway''（前台，记录到标准输出）。

- 生命值：''health'' 超过 WS（也包含在 ''hello-ok'' 中）。

- 监督：launchd/systemd 用于自动重启。

Tutorial.step

不变量

- 每个主机只有一个网关控制一个 Baileys 会话。

- 握手是强制性的；任何非 JSON 或非连接第一帧都是硬关闭。

- 事件不会重播；客户必须刷新差距。