5.1 Gateway架构

核心概念核心概念

概述

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

组件和流程

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 / headless）

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

协议详情：Gateway 协议

WebChat

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

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

客户端                            Gateway
|                                   |
|---- req:connect -------->|
|<------ res (ok) ---------| (或 res error + close)
| (payload=hello-ok 携带快照: presence + health)
|                                   |
|<------ event:presence ---|
|<------ event:tick -------|
|                                   |
|------- req:agent ------->
|<------ res:agent --------| (ack: {runId,status:"accepted"})
|<------ event:agent ------| (流式传输)
|<------ res:agent --------| (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 随机数并需要明确批准
  • Gateway 身份验证（gateway.auth.*）仍适用于所有连接，无论是本地还是远程

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

协议类型和代码生成

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

远程访问

  • 首选：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 或非连接的第一帧都是硬关闭
  • 事件不会重放；客户端必须在间隙时刷新