Skip to main content

​
Gateway architecture

最後更新：2026-01-22

​
概述

  • 一個單一長壽命的 Gateway 擁有所有訊息介面（WhatsApp 透過 Baileys、Telegram 透過 grammY、Slack、Discord、Signal、iMessage、WebChat）。
  • 控制平面客戶端（macOS 應用程式、CLI、Web UI、自動化）透過 WebSocket 連接到 Gateway，在設定的綁定主機上（預設 127.0.0.1:18789）。
  • 節點（macOS/iOS/Android/無頭）也透過 WebSocket 連接，但宣告 role: node 並帶有明確的 caps/commands。
  • 每台主機一個 Gateway；它是唯一開啟 WhatsApp 會話的地方。
  • Canvas 主機由 Gateway HTTP 伺服器在以下路徑提供：
    • /__openclaw__/canvas/（Agent 可編輯的 HTML/CSS/JS）
    • /__openclaw__/a2ui/（A2UI 主機） 它使用與 Gateway 相同的埠（預設 18789）。

​
元件和流程

​
Gateway（守護程序）

  • 維護供應商連線。
  • 公開類型化的 WS API（請求、回應、伺服器推送事件）。
  • 對照 JSON Schema 驗證入站幀。
  • 發出事件如 agent、chat、presence、health、heartbeat、cron。

​
客戶端（mac app / CLI / web admin）

  • 每個客戶端一個 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

  • 使用 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 ----------| (最終 {runId, status, summary})

​
Wire 協議（摘要）

  • 傳輸：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 必須匹配，否則 socket 關閉。
  • 冪等鍵對於有副作用的方法（send、agent）是必需的，以便安全重試；伺服器保留短壽命的去重快取。
  • 節點必須在 connect 中包含 role: "node" 加上 caps/commands/permissions。

​
配對 + 本地信任

  • 所有 WS 客戶端（操作員 + 節點）在 connect 時包含設備身份。
  • 新設備 ID 需要配對批准；Gateway 為後續連接發出設備令牌。
  • 本地連接（loopback 或 Gateway 主機自己的 tailnet 地址）可以自動批准以保持同主機 UX 順暢。
  • 所有連接必須簽署 connect.challenge nonce。
  • 簽名負載 v3 也綁定 platform + deviceFamily；Gateway 在重新連接時固定配對的中繼資料，並為中繼資料更改需要重新配對。
  • 非本地連接仍需明確批准。
  • Gateway 認證（gateway.auth.*）仍適用於所有連接，無論本地或遠端。
詳情：Gateway protocol、Pairing、Security。

​
協議類型和程式碼生成

  • TypeBox schemas 定義協議。
  • JSON Schema 從這些 schemas 生成。
  • Swift 模型從 JSON Schema 生成。

​
遠端存取

  • 首選：Tailscale 或 VPN。
  • 替代方案：SSH 隧道 
    ssh -N -L 18789:127.0.0.1:18789 user@host
  • 相同的握手 + 認證令牌適用於隧道。
  • 在遠端設定中可以為 WS 啟用 TLS + 可選的 pinning。

​
操作快照

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

​
不變量

  • 恰好一個 Gateway 控制每台主機的單一 Baileys 會話。
  • 握手是強制的；任何非 JSON 或非 connect 的第一幀都會硬性關閉。
  • 事件不會重播；客戶端必須在間隙時刷新。