Gateway 架構

最後更新：2026-01-22

概覽

一個長期運行的 Gateway 掌管所有通訊介面（透過 Baileys 的 WhatsApp、透過 grammY 的 Telegram、Slack、Discord、Signal、iMessage、WebChat）。
控制面用戶端（macOS 應用程式、CLI、網頁 UI、自動化流程）透過 WebSocket 連線到 Gateway，使用設定的綁定位址（預設 127.0.0.1:18789）。
節點（macOS/iOS/Android/headless）也透過 WebSocket 連線，但會宣告 role: node 並帶有明確的能力/指令。
每台主機一個 Gateway；這是唯一開啟 WhatsApp session 的地方。
Canvas 主機 由 Gateway HTTP 伺服器提供服務，路徑為：
- /__openclaw__/canvas/（agent 可編輯的 HTML/CSS/JS）
- /__openclaw__/a2ui/（A2UI 主機）使用與 Gateway 相同的連接埠（預設 18789）。

元件與流程

Gateway（常駐程式）

維護 provider 連線。
提供型別化的 WS API（請求、回應、伺服器推送事件）。
依據 JSON Schema 驗證入站 frame。
發出 agent、chat、presence、health、heartbeat、cron 等事件。

用戶端（macOS 應用程式 / CLI / 網頁管理介面）

每個用戶端一條 WS 連線。
發送請求（health、status、send、agent、system-presence）。
訂閱事件（tick、agent、presence、shutdown）。

節點（macOS / iOS / Android / headless）

連線到同一個 WS 伺服器，使用 role: node。
在 connect 時提供裝置身分；配對基於裝置（role node），核准狀態存放在裝置配對儲存區。
提供 canvas.*、camera.*、screen.record、location.get 等指令。

協定細節：

Gateway protocol

WebChat

靜態 UI，使用 Gateway WS API 取得聊天記錄和發送訊息。
遠端部署時，透過與其他用戶端相同的 SSH/Tailscale 隧道連線。

連線生命週期（單一用戶端）

sequenceDiagram
    participant Client
    participant Gateway

    Client->>Gateway: req:connect
    Gateway-->>Client: res (ok)
    Note right of Gateway: or res error + close
    Note left of Client: payload=hello-ok<br>snapshot: presence + health

    Gateway-->>Client: event:presence
    Gateway-->>Client: event:tick

    Client->>Gateway: req:agent
    Gateway-->>Client: res:agent<br>ack {runId, status:"accepted"}
    Gateway-->>Client: event:agent<br>(streaming)
    Gateway-->>Client: res:agent<br>final {runId, status, summary}

通訊協定（摘要）

傳輸層：WebSocket，文字 frame 搭配 JSON payload。
第一個 frame 必須是 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 必須吻合，否則 socket 會被關閉。
有副作用的方法（send、agent）需要冪等鍵，以便安全重試；伺服器維護一個短期去重快取。
節點在 connect 時必須包含 role: "node" 加上能力/指令/權限。

配對與本地信任

所有 WS 用戶端（操作者 + 節點）在 connect 時都要附帶裝置身分。
新的裝置 ID 需要配對核准；Gateway 會核發裝置 token 供後續連線使用。
本地連線（loopback 或 gateway 主機自身的 tailnet 位址）可以自動核准，保持同主機的流暢體驗。
所有連線都必須簽署 connect.challenge nonce。
簽章 payload v3 還會綁定 platform + deviceFamily；gateway 在重連時會釘住已配對的中繼資料，中繼資料變更時需要重新配對。
非本地連線仍然需要明確核准。
Gateway 認證（gateway.auth.*）適用於所有連線，無論本地或遠端。

細節：Gateway protocol、Pairing、Security。

協定型別與程式碼生成

TypeBox schema 定義協定。
從這些 schema 生成 JSON Schema。
從 JSON Schema 生成 Swift 模型。

遠端存取

推薦：Tailscale 或 VPN。

替代方案：SSH 隧道

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

隧道中使用相同的握手 + 認證 token。
遠端部署可為 WS 啟用 TLS + 選用的憑證釘選。

運維快照

啟動：openclaw gateway（前台，log 輸出到 stdout）。
健康檢查：透過 WS 的 health（也包含在 hello-ok 中）。
監控：用 launchd/systemd 自動重啟。

不變式

每台主機恰好一個 Gateway 控制一個 Baileys session。
握手是必要的；第一個 frame 如果不是 JSON 或不是 connect，會直接斷開。
事件不會重播；用戶端在資料間隙時必須自行重新整理。