跳到主要内容

网关架构 (Gateway architecture)

最后更新时间：2026-01-22

概览 (Overview)​

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

组件和流程 (Components and flows)​

网关 (守护进程)​

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

连接生命周期 (单个客户端)​

客户端 (Client)             网关 (Gateway)
  |                          |
  |---- req:connect -------->|
  |<------ res (ok) ---------|   (或 res error + close)
  |   (payload=hello-ok 携带快照：presence + health)
  |                          |
  |<------ event:presence ---|
  |<------ event:tick -------|
  |                          |
  |------- req:agent ------->|
  |<------ res:agent --------|   (确认：{runId,status:"accepted"})
  |<------ event:agent ------|   (流式传输)
  |<------ res:agent --------|   (最终：{runId,status,summary})
  |                          |

有线协议摘要 (Wire protocol)​

  • 传输层：WebSocket，带有 JSON 负载的文本帧。
  • 第一帧 必须 是 connect。
  • 握手后：
    • 请求：{type:"req", id, method, params} → {type:"res", id, ok, payload|error}
    • 事件：{type:"event", event, payload, seq?, stateVersion?}
  • 如果设置了 CLAWDBOT_GATEWAY_TOKEN (或 --token)，connect.params.auth.token 必须匹配，否则套接字关闭。
  • 带有副作用的方法 (send, agent) 需要幂等键以安全重试；服务器保留短期的去重缓存。
  • 节点必须在 connect 中包含 role: "node" 以及能力/命令/权限。

配对 + 本地信任 (Pairing + local trust)​

  • 所有 WS 客户端（操作员 + 节点）在 connect 时都包含 设备身份 (device identity)。
  • 新的设备 ID 需要配对审批；网关会为随后的连接颁发 设备令牌 (device token)。
  • 本地 连接（回环地址或网关主机自身的 tailnet 地址）可以自动审批，以保持同主机体验流畅。
  • 非本地 连接必须对 connect.challenge 随机数进行签名，并需要显式审批。
  • 网关身份验证 (gateway.auth.*) 仍适用于 所有 连接（无论本地还是远程）。

详情：网关协议, 配对, 安全。

协议类型化和代码生成 (Protocol typing and codegen)​

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

远程访问 (Remote access)​

  • 首选：Tailscale 或 VPN。
  • 备选：SSH 隧道 
    ssh -N -L 18789:127.0.0.1:18789 user@host
  • 握手 + 身份验证令牌同样适用于该隧道。
  • 在远程设置中，可以为 WS 启用 TLS + 可选的固定 (pinning)。

运维快照 (Operations snapshot)​

  • 启动：clawdbot gateway（前台运行，日志输出到 stdout）。
  • 健康检查：通过 WS 进行 health（也包含在 hello-ok 中）。
  • 监控：使用 launchd/systemd 进行自动重启。

不变量 (Invariants)​

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