代理架构

最后更新：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 连接，但声明 role: node 并具有明确的能力/命令
▹每个主机一个网关；它是唯一打开 WhatsApp 会话的地方
▹
Canvas 主机由网关 HTTP 服务器提供：
- ▹/__openclaw__/canvas/（代理可编辑的 HTML/CSS/JS）
- ▹/__openclaw__/a2ui/（A2UI 主机）
- ▹使用与网关相同的端口（默认 18789）

组件和流程

网关（守护进程）

▹维护提供商连接
▹公开类型化的 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 中提供设备身份；配对基于设备（角色节点），批准存储在设备配对存储中
▹公开命令，如 canvas.*、camera.*、screen.record、location.get

协议详情：网关协议

WebChat

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

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


mermaid
sequenceDiagram
    participant C as 客户端
    participant G as 网关
    
    C->>G: connect（带身份验证）
    G->>C: hello-ok（快照）
    
    loop 会话
        C->>G: req（方法、参数）
        G->>C: res（ok/payload 或 error）
        G->>C: event（agent、chat、presence 等）
    end
    
    G->>C: shutdown
    G->>C: 关闭套接字

线路协议（摘要）

传输：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 客户端（操作员 + 节点）在连接时包含设备身份
▹新设备 ID 需要配对批准；网关为后续连接颁发设备令牌
▹本地连接（回环或网关主机自己的 tailnet 地址）可以自动批准，以保持同主机 UX 流畅
▹所有连接必须签署 connect.challenge 随机数
▹非本地连接仍需要明确批准
▹网关身份验证（gateway.auth.*）仍适用于所有连接，无论本地还是远程

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

协议类型和代码生成

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

远程访问

首选：Tailscale 或 VPN

备选：SSH 隧道


bash
ssh -N -L 18789:127.0.0.1:18789 user@host

相同的握手 + 身份验证令牌适用于隧道。

TLS + 可选固定可以在远程设置中为 WS 启用。

运维快照

▹启动：openclaw gateway（前台，日志到 stdout）
▹健康：通过 WS 的 health（也包含在 hello-ok 中）
▹监督：launchd/systemd 用于自动重启

不变量

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

架构图


mermaid
graph TB
    subgraph "网关进程"
        GW[网关核心]
        WS[WebSocket 服务器]
        HTTP[HTTP 服务器]
        
        GW --> WS
        GW --> HTTP
    end
    
    subgraph "渠道"
        WA[WhatsApp<br/>Baileys]
        TG[Telegram<br/>grammY]
        DC[Discord]
        SL[Slack]
    end
    
    subgraph "客户端"
        MAC[macOS 应用]
        CLI[CLI]
        WEB[Web UI]
    end
    
    subgraph "节点"
        IOS[iOS 节点]
        AND[Android 节点]
        MN[Mac 节点]
    end
    
    WA --> GW
    TG --> GW
    DC --> GW
    SL --> GW
    
    MAC --> WS
    CLI --> WS
    WEB --> HTTP
    
    IOS --> WS
    AND --> WS
    MN --> WS