OpenClaw 🦞

Gateway 架构

Gateway 架构

最后更新：2026-01-22

概述

  • 单个长期运行的 Gateway 拥有所有消息表面（通过 Baileys 的 WhatsApp、 通过 grammY 的 Telegram、Slack、Discord、Signal、iMessage、WebChat）。
  • 控制平面客户端（macOS 应用、CLI、Web UI、自动化）通过 WebSocket 连接到 Gateway， 在配置的绑定主机上（默认 127.0.0.1:18789）。
  • 节点（macOS/iOS/Android/无头）也通过 WebSocket 连接，但声明 role: node 并带有显式能力/命令。
  • 每个主机一个 Gateway；它是打开 WhatsApp 会话的唯一位置。
  • Canvas 主机 由 Gateway HTTP 服务器在以下位置提供服务：
    • /__openclaw__/canvas/（Agent 可编辑的 HTML/CSS/JS）
    • /__openclaw__/a2ui/（A2UI 主机） 它使用与 Gateway 相同的端口（默认 18789）。

组件和流

Gateway（守护进程）

  • 维护提供程序连接。
  • 公开类型化的 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 / 无头）

  • 连接到同一个 WS 服务器，使用 role: node。
  • 在 connect 中提供设备身份；配对是基于设备的（角色 node）， 批准存在于设备配对存储中。
  • 公开命令如 canvas.*、camera.*、screen.record、location.get。

协议详情：

WebChat

  • 使用 Gateway WS API 进行聊天历史和发送的静态 UI。
  • 在远程设置中，通过与其他客户端相同的 SSH/Tailscale 隧道连接。

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

sequenceDiagram
    participant Client
    participant Gateway

    Client->>Gateway: req:connect
    Gateway-->>Client: res (ok)
    Note right of Gateway: 或 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>（流式传输）
    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?}
  • 如果设置了 OPENCLAW_GATEWAY_TOKEN（或 --token），connect.params.auth.token 必须匹配，否则套接字关闭。
  • 幂等键对于副作用方法（send、agent）是必需的，以安全重试； 服务器保留短期去重缓存。
  • 节点必须在 connect 中包含 role: "node" 加上能力/命令/权限。

配对 + 本地信任

  • 所有 WS 客户端（操作员 + 节点）在 connect 上包含设备身份。
  • 新设备 ID 需要配对批准；Gateway 为后续连接发出设备令牌。
  • 本地连接（环回或网关主机自己的 tailnet 地址）可以自动批准以保持同主机 UX 流畅。
  • 所有连接必须签署 connect.challenge 随机数。
  • 签名负载 v3 还绑定 platform + deviceFamily；Gateway 在重新连接时固定配对的元数据， 并要求元数据更改时重新配对。
  • 非本地连接仍然需要显式批准。
  • Gateway 身份验证（gateway.auth.*）仍然适用于所有连接，本地或远程。

详情：Gateway 协议、配对、 安全。

协议类型化和代码生成

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

远程访问

  • 首选：Tailscale 或 VPN。

  • 替代：SSH 隧道

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

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

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

操作快照

  • 启动：openclaw gateway（前台，日志输出到 stdout）。
  • 健康：通过 WS 的 health（也包含在 hello-ok 中）。
  • 监督：launchd/systemd 用于自动重启。

不变量

  • 每个主机恰好一个 Gateway 控制单个 Baileys 会话。
  • 握手是强制性的；任何非 JSON 或非 connect 第一帧都是硬关闭。
  • 事件不重放；客户端必须在间隙时刷新。