OpenClaw Gateway 架構指南：WebSocket 整合與連線流程

每次開發通訊機器人或自動化工具時，最痛苦的就是要處理各種平台的 API 限制，還有那種斷線後狀態對不上的混亂感。如果你也曾為了同步多個裝置的訊息而抓狂，或者在處理不同平台的連線協議時感到心力交瘁，那麼理解 Gateway 的架構會讓你輕鬆很多。

這篇文章會帶你深入了解 Gateway 的運作邏輯，看看它是如何作為核心中樞，幫你搞定所有複雜的通訊流程。

概覽 (Overview)

• 由一個長效運行的 Gateway 掌控所有的通訊介面（包括透過 Baileys 運作的 WhatsApp，以及 Telegram via grammY, Slack, Discord, Signal, iMessage, WebChat）。
• 控制平面用戶端（macOS app, CLI, web UI, 自動化工具）會透過 WebSocket 連線到 Gateway，預設的綁定主機為 127.0.0.1:18789。
• Nodes（macOS/iOS/Android/headless）同樣透過 WebSocket 連線，但會宣告 role: node 並帶有明確的 caps/commands。
• 每個主機只有一個 Gateway；它是唯一開啟 WhatsApp session 的地方。
• canvas host 由 Gateway 的 HTTP server 提供服務，路徑如下：
  • /__openclaw__/canvas/（Agent 可編輯的 HTML/CSS/JS）
  • /__openclaw__/a2ui/（A2UI host） 它使用與 Gateway 相同的連接埠（預設為 18789）。

組件與流程 (Components and flows)

Gateway (daemon)

• 維持與各個 Provider 的連線。
• 提供具備型別定義的 WS API（包含 requests, responses, server‑push events）。
• 根據 JSON Schema 驗證傳入的 frame。
• 發送 agent, chat, presence, health, heartbeat, cron 等事件。

用戶端 (mac app / CLI / web admin)

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

Nodes (macOS / iOS / Android / headless)

• 使用 role: node 連線到同一個 WS server。
• 在 connect 時提供裝置識別資訊；配對是基於裝置的（role node），且核准資訊儲存在裝置配對儲存區中。
• 提供 canvas.*, camera.*, screen.record, location.get 等指令。

協定細節請參考：

• Gateway protocol

WebChat

• 靜態 UI，使用 Gateway WS API 獲取聊天紀錄並發送訊息。
• 在遠端設定中，透過與其他用戶端相同的 SSH/Tailscale 隧道進行連線。

連線生命週期 (單一用戶端) (Connection lifecycle (single client))

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}

傳輸協定 (摘要) (Wire protocol (summary))

• 傳輸方式：WebSocket，使用 JSON payload 的文字 frame。
• 第一個 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）需要 Idempotency keys 以確保重試時的安全性；伺服器會保留短暫的去重快取。
• Nodes 必須在 connect 中包含 role: "node" 以及 caps/commands/permissions。

配對與本地信任 (Pairing + local trust)

• 所有 WS 用戶端（操作者與 nodes）在 connect 時都會包含一個裝置識別碼。
• 新的裝置 ID 需要配對核准；Gateway 會為後續連線核發 device token。
• 本地連線（loopback 或 gateway 主機自身的 tailnet 位址）可以被自動核准，讓同主機的使用體驗更順暢。
• 所有連線都必須對 connect.challenge nonce 進行簽署。
• v3 版本的簽署 payload 還會綁定 platform 與 deviceFamily；Gateway 會在重新連線時固定已配對的元數據，若元數據變更則需要重新配對。
• 非本地連線仍然需要明確的核准。
• Gateway 認證（gateway.auth.*）仍然適用於所有連線，無論是本地還是遠端。

細節請見：Gateway protocol, Pairing, Security。

協定型別與程式碼生成 (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

• 透過隧道連線時，同樣適用握手流程與 auth token。

• 在遠端設定中，可以為 WS 啟用 TLS 與選用的 pinning。

維運快照 (Operations snapshot)

• 啟動：openclaw gateway（前景執行，日誌輸出至 stdout）。
• 健康檢查：透過 WS 進行 health 檢查（也包含在 hello-ok 中）。
• 監控：使用 launchd/systemd 進行自動重啟。

不變性原則 (Invariants)

• 每個主機恰好只有一個 Gateway 控制單一 Baileys session。
• 握手是強制性的；任何非 JSON 或首個 frame 不是 connect 的情況都會被強制關閉連線。
• 事件不會重播；用戶端必須在連線中斷時自行重新整理。

相關文件 (Related)

• Agent Loop — 詳細的 Agent 執行週期
• Gateway Protocol — WebSocket 協定規範
• Queue — 指令隊列與並行處理
• Security — 信任模型與安全性強化

下一步

• 想要實作自己的 Client？參考 Gateway Protocol
• 了解自動化核心：Agent Loop

如果你在設定過程中遇到任何問題，可以詢問我們的 AI Setup Assistant。