网关架构

最后更新：2026-01-22

概述

• 单个长期运行的网关拥有所有消息界面（WhatsApp 通过 Baileys、Telegram 通过 grammY、Slack、Discord、Signal、iMessage、WebChat）。
• 控制平面客户端（macOS 应用、CLI、Web UI、自动化）通过配置的绑定主机（默认 127.0.0.1:18789）上的 WebSocket 连接到网关。
• 节点（macOS/iOS/Android/无头）也通过 WebSocket 连接，但声明 role: node 并带有明确的 caps/commands。
• 每个主机一个网关；它是唯一打开 WhatsApp 会话的地方。
• 画布主机（默认 18793）提供智能体可编辑的 HTML 和 A2UI。

组件和流程

网关（守护进程）

• 维护提供商连接。
• 暴露类型化的 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

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

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

客户端                    网关
  |                          |
  |---- req:connect -------->|
  |<------ res (ok) ---------|   (或 res 错误 + 关闭)
  |   (payload=hello-ok 携带 snapshot: presence + health)
  |                          |
  |<------ event:presence ---|
  |<------ event:tick -------|
  |                          |
  |------- req:agent ------->|
  |<------ res:agent --------|   (ack: {runId,status:"accepted"})
  |<------ event:agent ------|   (流式)
  |<------ res:agent --------|   (最终: {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 需要配对批准；网关为后续连接颁发设备令牌。
• 本地连接（环回或网关主机的 tailnet 地址）可以自动批准，以保持同主机 UX 流畅。
• 非本地连接必须对 connect.challenge nonce 进行签名，并需要明确批准。
• 网关认证（gateway.auth.*）仍然适用于所有连接，无论是本地还是远程。

详情：网关协议、配对、安全

协议类型和代码生成

• 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 用于自动重启。

不变量

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