本页内容
本页内容
代理运行时
网关架构
概览
-
一个长期运行的 Gateway 负责所有消息接入面(通过 Baileys 的 WhatsApp、通过 grammY 的 Telegram、Slack、Discord、Signal、iMessage、WebChat)。
-
Control-plane 客户端(macOS 应用程序、CLI、Web UI、自动化)通过配置的绑定主机上的 WebSocket 连接到网关(默认
127.0.0.1:18789)。 -
Nodes (macOS/iOS/Android/headless) 也通过 WebSocket 连接,但使用显式 caps/commands. 声明
role: node -
每个主机一个网关。这是打开 WhatsApp 会话的唯一位置。
-
托管小部件表面由网关HTTP服务器提供服务,位于:
/__openclaw__/canvas/(托管小部件文档)/__openclaw__/a2ui/(A2UI 渲染器资源)
它使用与 Gateway 相同的端口(默认
18789)。
组件与流程
Gateway(守护进程)
- 维护 provider 连接。
- 暴露类型化的 WS API(请求、响应、服务端推送事件)。
- 根据 JSON Schema 验证入站帧。
- 发出诸如
agent、chat、presence、health、heartbeat、cron的事件。
客户端(mac 应用 / CLI / web 管理)
- 每个客户端一个 WS 连接。
- 发送请求(
health、status、send、agent、system-presence)。 - 订阅事件(
tick、agent、presence、shutdown)。
Nodes(macOS / iOS / Android / 无头环境)
- 以
role: node连接到 同一个 WS 服务器。 - 在
connect中提供设备标识。配对是基于 设备的(角色node),并且批准位于设备配对存储中。 - 公开
camera.*、screen.record和location.get等命令。 macOS 应用程序还在canvas.*下公开小部件面板命令。
Protocol details: Gateway 协议
WebChat
- 静态 UI,使用网关 WS API 进行聊天历史记录并发送。
- 在远程部署中,通过与其他客户端相同的 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 payload。
- 首帧必须是
connect。 - 完成握手后:
- 请求:
{type:"req", id, method, params}→{type:"res", id, ok, payload|error} - 事件:
{type:"event", event, payload, seq?, stateVersion?}
- 请求:
hello-ok.features.methods/events是发现元数据,而不是每一个可调用 helper 路由的生成式导出。- 共享密钥身份验证接受
connect.params.auth.token或connect.params.auth.password中配置的密钥。gateway.auth.mode选择配置的值(gateway.auth.token或gateway.auth.password),而不是所需的接线字段。 - 带身份模式,例如 Tailscale Serve (
gateway.auth.allowTailscale: true)或非 loopback 的gateway.auth.mode: "trusted-proxy",会通过请求头而不是connect.params.auth.*满足认证。 - Private-ingress
gateway.auth.mode: "none"完全禁用共享秘密身份验证。保持该模式远离公共或不受信任的入口。 - 副作用方法(
send、agent)需要 Idempotency 密钥才能安全重试。服务器保留短暂的重复数据删除缓存。 - 节点必须包含
role: "node"以及connect中的 caps/commands/permissions。
配对与本地信任
- 所有 WS 客户端(操作员 + 节点)在
connect时都包含一个 设备身份。 - 新设备 ID 需要配对批准。网关为后续连接颁发 设备令牌。
- 直接的本地回环连接可以自动批准,以保持同主机 UX 的流畅性。
- OpenClaw 还具有用于可信共享秘密帮助程序流的狭窄 backend/container-local 自连接路径。
- Tailnet 和 LAN 连接,包括同主机 tailnet 绑定,仍然需要显式的配对批准。
- 所有连接都必须对
connect.challenge随机数进行签名。签名负载v3还绑定platform和deviceFamily。网关在重新连接时固定配对元数据,并需要针对元数据更改进行修复配对。 - 非本地 连接仍然需要显式批准。
- Gateway 认证(
gateway.auth.*)仍然适用于所有连接,无论本地还是远程。
详情:Gateway protocol、Pairing、 Security。
协议类型与代码生成
- TypeBox schemas 定义协议。
- JSON Schema 从这些 schemas 生成。
- Swift models 从 JSON Schema 生成。
远程访问
-
首选:Tailscale 或 VPN。
-
替代方案:SSH 隧道
bash -
隧道中仍适用相同的握手 + 认证令牌。
-
远程部署中的 WS 可启用 TLS + 可选 pinning。
运行概览
- 启动:
openclaw gateway(前台运行,日志输出到 stdout)。 - 健康检查:通过 WS 的
health(也会包含在hello-ok中)。 - 守护:使用 launchd/systemd 自动重启。
定时工作和关机
网关内核拥有一个 GatewayScheduler 用于注册维护和 cron 唤醒。所有者收到该实例并注册作业;一个主机定时器驱动下一次唤醒。对于持久工作,商店保留最后期限,并且其所有者在启动时重建时间表,而不是保留第二个调度程序状态。
睡眠后,延迟唤醒会分派每个可运行对象,并为该唤醒注册一次。定期注册在开始下一个间隔之前等待其回调和跟踪工作完成;错过的刻度被合并。墙上时间赶上睡眠,而经过时间则通过向后时钟校正保持相对延迟和节奏移动。默认情况下,重新安排会替换等待的作业; mode: "earliest" 保留同一作业 ID 的较早墙和已过的最后期限,因此过时的读取不能推迟已承诺的唤醒。
beginClose() 关闭调度准入,取消挂起的唤醒,并发出关闭信号。 stop() 加入已经运行的回调并由其异步范围跟踪工作;网关生命周期拥有外部关闭预算和资源拆卸。请求截止日期、流本地计时器和子进程清理由其操作所有者保留。 SQLite WAL 检查点计时器由存储所有者保留。
插件通过其服务或通道帐户生命周期接收版本化的 PluginServiceSchedulerV1 功能。其beginClose()取消待处理工作并关闭入场; stop() 在主机释放生命周期之前加入正在运行的回调和子作用域。插件仍然拥有域清理顺序,包括套接字关闭和持久刷新。参见服务调度。
不变量
- 每台主机上仅有一个 Gateway 控制一个 Baileys 会话。
- 握手是强制性的。任何非 JSON 或非连接第一帧都是硬关闭。
- 事件不会重播。客户必须刷新空白。
相关内容
- Agent Loop — 详细的 agent 执行周期
- Gateway Protocol — WebSocket 协议契约
- Queue — 命令队列与并发
- Security — 信任模型与加固
- Network — OpenClaw 如何跨本地主机、LAN 和尾网连接、配对和保护设备的集线器
