文档
网关架构

网关架构

适用范围

在以下情况使用此页面：

  • 处理网关协议、客户端或传输

最后更新：2026-01-22

概述

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

组件和流程

网关（守护进程）

  • 维护提供程序连接。
  • 公开类型化 WS API（请求、响应、服务器推送事件）。
  • 根据 JSON 架构验证入站帧。
  • 发出诸如 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

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

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

客户端                    网关
  |                          |
  |---- 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?}
  • 如果设置了 MOLTBOT_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 架构从这些架构生成。
  • Swift 模型从 JSON 架构生成。

远程访问

  • 首选：Tailscale 或 VPN。
  • 替代方案：SSH 隧道
    ssh -N -L 18789:127.0.0.1:18789 user@host
  • 通过隧道应用相同的握手 + 身份验证令牌。
  • 可以为远程设置中的 WS 启用 TLS + 可选固定。

操作快照

  • 启动：moltbot gateway（前台，日志记录到 stdout）。
  • 健康状况：通过 WS 进行 health（也包括在 hello-ok 中）。
  • 监督：launchd/systemd 用于自动重启。

不变量

  • 恰好一个网关控制每主机单个 Baileys 会话。
  • 握手是强制性的；任何非 JSON 或非连接的第一帧都是硬关闭。
  • 事件不重播；客户端必须在差距时刷新。
通道与路由消息