閘道架構

概觀

單一長期存活的 Gateway 擁有所有訊息介面（透過 Baileys 的 WhatsApp、透過 grammY 的 Telegram、Slack、Discord、Signal、iMessage、WebChat）。
控制平面用戶端（macOS 應用程式、CLI、Web UI、自動化）透過 WebSocket 連接到閘道，連接至設定的綁定主機（預設為 127.0.0.1:18789）。
Nodes (macOS/iOS/Android/headless) 也透過 WebSocket 連線，但宣告 role: node 並附帶明確的 caps/commands。
每個主機一個 Gateway；這是開啟 WhatsApp 會話的唯一位置。
canvas host 由 Gateway HTTP 伺服器提供服務，位於：
- /__openclaw__/canvas/ (agent-editable HTML/CSS/JS)
- /__openclaw__/a2ui/ (A2UI host) 它使用與 Gateway 相同的連接埠（預設 18789）。

元件與流程

Gateway (daemon)

維護提供者連線。
公開類型化的 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 / headless)

使用 role: node 連接到 相同的 WS 伺服器。
在 connect 中提供裝置身分識別；配對是 以裝置為基礎 (role node)，且核准存儲在裝置配對存儲中。
公開指令如 canvas.*、camera.*、screen.record、location.get。

協議詳情：

Gateway 協定

WebChat

使用 Gateway WS API 進行聊天歷史記錄與發送的靜態 UI。
在遠端設置中，透過與其他客戶端相同的 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，帶有 JSON 載荷的文字幀。
第一幀必須為 connect。
交握後：
- 請求：{type:"req", id, method, params} → {type:"res", id, ok, payload|error}
- 事件：{type:"event", event, payload, seq?, stateVersion?}
hello-ok.features.methods / events 是探索元數據，並非每個可呼叫輔助路由的生成傾印。
共用金鑰驗證使用 connect.params.auth.token 或 connect.params.auth.password，具體取決於設定的 Gateway 驗證模式。
攜帶身分識別的模式，例如 Tailscale Serve (gateway.auth.allowTailscale: true) 或非迴路 gateway.auth.mode: "trusted-proxy"，是從請求標頭滿足驗證而非 connect.params.auth.*。
Private-ingress gateway.auth.mode: "none" 會完全停用共用金鑰驗證；請勿在公開/不信任的入口處使用該模式。
等冪性金鑰對於具有副作用的方法 (send, agent) 是必需的，以便安全地重試；伺服器會維護一個短期去重快取。
節點必須在 connect 中包含 role: "node" 以及 caps/commands/permissions。

配對 + 本機信任

所有 WS 用戶端 (操作員 + 節點) 都會在 connect 上包含 裝置身分識別。
新的裝置 ID 需要配對核准；Gateway 會發出 裝置權杖 供後續連線使用。
直接的本機迴路連線可以自動核准，以保持同主機 UX 順暢。
OpenClaw 也有一個狹窄的後端/容器本機自連線路徑，用於受信任的共用金鑰輔助流程。
Tailnet 和 LAN 連線（包括同主機 tailnet 綁定）仍然需要明確的配對核准。
所有連線都必須簽署 connect.challenge nonce。
簽章負載 v3 也綁定了 platform + deviceFamily；Gateway 會在重新連線時鎖定配對的元數據，並要求修復配對以處理元數據變更。
非本機 連線仍然需要明確核准。
Gateway 驗證 (gateway.auth.*) 仍然適用於所有連線，無論是本機還是遠端。

詳情：Gateway 協定、配對、安全性。

協定型別與程式碼生成

TypeBox schemas 定義了該協定。
JSON Schema 是從這些 schemas 生成的。
Swift 模型是從 JSON Schema 生成的。

遠端存取

首選：Tailscale 或 VPN。

替代方案：SSH tunnel

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

相同的 handshake + auth token 也適用於 tunnel。
TLS + 選用的 pinning 可以在遠端設定中為 WS 啟用。

運作快照

啟動：openclaw gateway（前景，記錄至 stdout）。
健康狀態：透過 WS 發送 health（也包含在 hello-ok 中）。
監督：使用 launchd/systemd 自動重啟。

不變量

每個主機上只有一個 Gateway 控制單一 Baileys session。
Handshake 是強制的；任何非 JSON 或非 connect 的第一幀都會導致強制關閉連線。
事件不會重播；客戶端必須在出現間隙時重新整理。

閘道架構

閘道架構

概觀

元件與流程

Gateway (daemon)

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

節點 (macOS / iOS / Android / headless)

WebChat

連接生命週期（單一客戶端）

線路協議（摘要）

配對 + 本機信任

協定型別與程式碼生成

遠端存取

運作快照

不變量

相關