Gateway 架构

最后更新：2026-01-22

概述

  • 一个单一的长期运行的 Gateway 拥有所有消息界面（WhatsApp 通过 Baileys、Telegram 通过 grammY、Slack、Discord、Signal、iMessage、WebChat）?
  • 控制平面客户端（macOS 应用、CLI、Web UI、自动化）通过 WebSocket 连接到配置绑定主机上?Gateway（默?127.0.0.1:18789）?
  • 节点（macOS/iOS/Android/无头）也通过 WebSocket 连接，但声明 role: node 并带有明确的 caps/commands?
  • 每个主机一?Gateway；它是唯一打开 WhatsApp 会话的地方?
  • canvas 主机 ?Gateway HTTP 服务器提供服务：
    • /__openclaw__/canvas/（代理可编辑?HTML/CSS/JS?
    • /__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）?

节点（macOS / iOS / Android / 无头?

  • 使用 role: node 连接?同一 WS 服务??
  • ?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: 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?}
  • 如果设置?OPENCLAW_GATEWAY_TOKEN（或 --token），connect.params.auth.token 必须匹配，否则套接字关闭?
  • 对于有副作用的方法（send、agent）需要幂等键以安全重试；服务器保留短期去重缓存?
  • 节点必须?connect 中包?role: "node" 加上 caps/commands/permissions?

配对 + 本地信任

  • 所?WS 客户端（操作?+ 节点）在 connect 时包?设备身份*?
  • 新设?ID 需要配对批准；Gateway 颁发设备令牌用于后续连接?
  • 本地连接（loopback ?gateway 主机?tailnet 地址）可以自动批准，以保持同主机用户体验流畅?
  • 所有连接必须签?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 的第一帧都会导致硬关闭?
  • 事件不会重放；客户端必须在间隙时刷新?