Gateway 架构

概览

• 单个长期运行的 Gateway 管理所有消息渠道（通过 Baileys 连 WhatsApp、通过 grammY 连 Telegram、以及 Slack、Discord、Signal、iMessage、WebChat）。
• 控制平面客户端（macOS 应用、CLI、Web UI、自动化脚本）通过 WebSocket 连接到 Gateway，绑定地址默认为 127.0.0.1:18789。
• Nodes（macOS/iOS/Android/无头设备）同样通过 WebSocket 连接，但会声明 role: node 并附带明确的能力/命令列表。
• 每台宿主机只运行一个 Gateway；它是唯一打开 WhatsApp 会话的地方。
• canvas host 由 Gateway 的 HTTP 服务器提供，地址如下（与 Gateway 共用同一端口，默认 18789）：
  • /__openclaw__/canvas/（Agent 可编辑的 HTML/CSS/JS）
  • /__openclaw__/a2ui/（A2UI 宿主）

组件与数据流

Gateway（守护进程）

• 维护与各 Provider 的连接。
• 暴露带类型约束的 WebSocket API（请求、响应、服务端推送事件）。
• 对入站帧进行 JSON Schema 校验。
• 发出 agent、chat、presence、health、heartbeat、cron 等事件。

客户端（Mac 应用 / CLI / Web 管理界面）

• 每个客户端持有一条 WebSocket 连接。
• 发送请求（health、status、send、agent、system-presence）。
• 订阅事件（tick、agent、presence、shutdown）。

Nodes（macOS / iOS / Android / 无头设备）

• 连接到同一个 WebSocket 服务器，但携带 role: node。
• 在 connect 时提供设备身份；配对是基于设备的（角色为 node），审批信息存储在设备配对库中。
• 暴露 canvas.*、camera.*、screen.record、location.get 等命令。

协议详情见：Gateway 协议

WebChat

• 静态 UI，通过 Gateway WebSocket 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?}
• 如果设置了 OPENCLAW_GATEWAY_TOKEN（或 --token），connect.params.auth.token 必须匹配，否则关闭连接。
• 有副作用的方法（send、agent）需要幂等键，以便安全重试；服务端维护一个短时去重缓存。
• Nodes 必须在 connect 中携带 role: "node" 及能力/命令/权限信息。

配对与本地信任

• 所有 WebSocket 客户端（操作员和 Nodes）在 connect 时都包含设备身份。
• 新设备 ID 需要配对审批；Gateway 为后续连接颁发设备 token。
• 本地连接（回环地址或 Gateway 所在主机的 Tailnet 地址）可自动审批，保持同机使用的流畅体验。
• 所有连接都必须对 connect.challenge nonce 进行签名。
• v3 签名 payload 还绑定了 platform 和 deviceFamily；Gateway 在重新连接时会校验已配对的元数据，若元数据发生变化则要求重新配对。
• 非本地连接仍需显式审批。
• Gateway 认证（gateway.auth.*）对所有连接生效，无论本地还是远程。

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

协议类型与代码生成

• 使用 TypeBox schemas 定义协议。
• 从 schemas 生成 JSON Schema。
• 从 JSON Schema 生成 Swift 模型。

远程访问

• 推荐：Tailscale 或 VPN。

• 备选：SSH 隧道

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

• 握手和 auth token 同样适用于隧道连接。

• 在远程部署中可为 WebSocket 开启 TLS 和可选证书锁定。

运维概览

• 启动：openclaw gateway（前台运行，日志输出到 stdout）。
• 健康检查：通过 WebSocket 发送 health 请求（也包含在 hello-ok 中）。
• 进程守护：使用 launchd/systemd 实现自动重启。

不变量

• 每台宿主机只有一个 Gateway 控制一个 Baileys 会话。
• 握手是强制的；任何非 JSON 或非 connect 的首帧都会直接关闭连接。
• 事件不会重放；客户端必须在出现间隙时主动刷新。