网关架构
概述¶
- 单个长期运行的网关(Gateway)拥有所有消息界面(通过 Baileys 接入 WhatsApp,通过 grammY 接入 Telegram,以及 Slack、Discord、Signal、iMessage、WebChat)。
- 控制面客户端(macOS 应用、CLI、Web UI、自动化)通过WebSocket连接到网关的配置绑定主机(默认
127.0.0.1:18789)。 - 节点(Nodes)(macOS/iOS/Android/headless)也通过WebSocket连接,但声明
role: node并带有显式的 caps/commands。 - 每个主机一个网关。它是唯一打开 WhatsApp 会话的地方。
- 托管 widget 界面由网关 HTTP 服务器提供服务,路径如下:
/__openclaw__/canvas/(托管 widget 文档)/__openclaw__/a2ui/(A2UI 渲染器资源)
它使用与网关相同的端口(默认 18789)。
组件与流程¶
网关(守护进程)¶
- 维护提供方连接。
- 暴露类型化 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 / headless)¶
- 以
role: node连接到同一个 WS 服务器。 - 在
connect中提供设备身份。配对是基于设备的(角色为node),审批存储在设备配对存储中。 - 暴露
camera.*、screen.record、location.get等命令。macOS 应用还在canvas.*下暴露 widget 面板命令。
协议详情:网关协议
WebChat¶
- 使用网关 WS API 获取聊天历史和发送消息的静态 UI。
- 在远程部署中,与其他客户端一样通过相同的 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?} hello-ok.features.methods/events是发现元数据,而不是所有可调用辅助路由的转储。- 共享密钥认证接受配置的密钥,可放在
connect.params.auth.token或connect.params.auth.password中。gateway.auth.mode选择配置的值(gateway.auth.token或gateway.auth.password),而不是要求的线路字段。 - 携带身份的模式,如 Tailscale Serve(
gateway.auth.allowTailscale: true)或非回环gateway.auth.mode: "trusted-proxy",通过请求头满足认证,而不是connect.params.auth.*。 - 私有入口
gateway.auth.mode: "none"完全禁用共享密钥认证。切勿在公共或不可信入口使用该模式。 - 对于有副作用的方法(
send、agent),需要幂等键才能安全重试。服务器会保留短期的去重缓存。 - 节点必须在
connect中包含role: "node"以及 caps/commands/permissions。
配对与本地信任¶
- 所有 WS 客户端(操作员 + 节点)在
connect中包含设备身份。 - 新设备 ID 需要配对审批。网关为后续连接签发设备令牌(device token)。
- 直接本地回环连接可以自动批准,以保持同主机 UX 顺畅。
- OpenClaw 还有一条受限的后端/容器本地自连接路径,用于受信任的共享密钥辅助流程。
- Tailnet 和 LAN 连接(包括同主机 tailnet 绑定)仍需要明确的配对审批。
- 所有连接都必须对
connect.challengenonce 签名。签名负载v3还绑定platform和deviceFamily。网关在重连时固定已配对的元数据,并要求重新配对以处理元数据变更。 - 非本地连接仍需要明确批准。
- 网关认证(
gateway.auth.*)仍然适用于所有连接,无论本地还是远程。
协议类型与代码生成¶
- TypeBox 模式定义该协议。
- JSON Schema 从这些模式生成。
- Swift 模型从 JSON Schema 生成。
远程访问¶
- 首选:Tailscale 或 VPN。
- 备选:SSH 隧道
- 相同的握手 + 认证令牌同样适用于隧道。
- 在远程部署中,可以为 WS 启用 TLS 及可选的证书固定(pinning)。
运维概览¶
- 启动:
openclaw gateway(前台运行,日志输出到 stdout)。 - 健康检查:通过 WS 发送
health(也包含在hello-ok中)。 - 守护:使用 launchd/systemd 实现自动重启。
定时任务与关闭¶
网关内核持有一个 GatewayScheduler,用于处理已注册的维护和 cron 唤醒。各所有者接收该实例并注册任务;一个主机定时器驱动下一次唤醒。对于持久化工作,存储会保留截止时间,其所有者在启动时重建调度,而不是持久化第二个调度器状态。
休眠后,迟到的唤醒会对每个可运行且到期的注册项调度一次。周期性注册会等待其回调和被跟踪的工作完成后再开始下一个间隔;错过的 tick 会被合并。墙钟时间会包含休眠时长,而经过时间通过向后时钟校正保持相对延迟和节奏持续推进。默认情况下,重新调度会替换等待中的任务;mode: "earliest" 会为同一任务 ID 保留更早的墙钟和经过时间截止点,这样过期的读取不会推迟已经承诺的唤醒。
beginClose() 关闭调度准入,取消待处理的唤醒,并发送关闭信号。stop() 会等待已运行的回调及其异步作用域所跟踪的工作完成;Gateway 生命周期负责外层关闭预算和资源拆除。请求截止时间、流本地计时器以及子进程清理仍由其操作所有者负责。SQLite WAL 检查点计时器仍由存储所有者负责。
插件通过其服务或 channel-account 生命周期接收版本化的 PluginServiceSchedulerV1 能力。其 beginClose() 会取消待处理工作并关闭准入;stop() 会在宿主释放生命周期之前等待运行中的回调和子作用域完成。插件仍负责领域清理顺序,包括套接字关闭和持久化刷新。参见 服务调度。
不变量¶
- 每个主机上,恰好一个 Gateway 控制单个 Baileys 会话。
- 握手是强制的。任何非 JSON 或非 connect 的首帧都会导致硬关闭。
- 事件不会重放。客户端必须在出现间隙时刷新。
相关¶
- 代理循环 — 详细的代理执行循环
- Gateway 协议 — WebSocket 协议契约
- 队列 — 命令队列和并发
- 安全 — 信任模型和加固
- 网络 — OpenClaw 如何在 localhost、LAN 和 tailnet 上连接、配对并保护设备的中枢
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw