跳转至

网关架构

概述

  • 单个长期运行的网关(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.challenge nonce 签名。签名负载 v3 还绑定 platform 和 deviceFamily。网关在重连时固定已配对的元数据,并要求重新配对以处理元数据变更。
  • 非本地连接仍需要明确批准。
  • 网关认证(gateway.auth.*)仍然适用于所有连接,无论本地还是远程。

详情:网关协议、配对、安全。

协议类型与代码生成

  • TypeBox 模式定义该协议。
  • JSON Schema 从这些模式生成。
  • Swift 模型从 JSON Schema 生成。

远程访问

  • 首选:Tailscale 或 VPN。
  • 备选:SSH 隧道
ssh -N -L 18789:127.0.0.1:18789 user@gateway-host
  • 相同的握手 + 认证令牌同样适用于隧道。
  • 在远程部署中,可以为 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