OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Fundamentals

閘道架構

概述

  • 單一長期執行的閘道負責所有訊息介面（透過 Baileys 的 WhatsApp、透過 grammY 的 Telegram、Slack、Discord、Signal、iMessage、WebChat）。

  • 控制層用戶端（macOS 應用程式、命令列介面、網頁介面、自動化流程）透過設定之繫結主機上的 WebSocket 連線至閘道（預設為 127.0.0.1:18789）。

  • 節點（macOS/iOS/Android/無頭模式）也透過 WebSocket 連線，但會宣告 role: node，並明確指定能力與命令。

  • 每部主機僅有一個閘道；它是唯一會開啟 WhatsApp 工作階段的位置。

  • 畫布主機由閘道 HTTP 伺服器在以下路徑提供：

    • /__openclaw__/canvas/（代理程式可編輯的 HTML/CSS/JS）
    • /__openclaw__/a2ui/（A2UI 主機）

    它與閘道使用相同的連接埠（預設為 18789）。

元件與流程

閘道（常駐程式）

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

用戶端（Mac 應用程式／命令列介面／網頁管理介面）

  • 每個用戶端各有一個 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

  • 使用閘道 WS API 取得聊天記錄並傳送訊息的靜態介面。
  • 在遠端設定中，透過與其他用戶端相同的 SSH/Tailscale 通道連線。

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

sequenceDiagram
    participant Client
    participant Gateway

    Client->>Gateway: req:connect
    Gateway-->>Client: res (ok)
    Note right of Gateway: 或回傳 res 錯誤後關閉
    Note left of Client: payload=hello-ok<br>快照：presence + health

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

    Client->>Gateway: req:agent
    Gateway-->>Client: res:agent<br>確認 {runId, status:"accepted"}
    Gateway-->>Client: event:agent<br>（串流傳輸）
    Gateway-->>Client: res:agent<br>最終結果 {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。
  • 具身分資訊的模式，例如 Tailscale Serve（gateway.auth.allowTailscale: true）或非迴路位址的 gateway.auth.mode: "trusted-proxy"，會透過請求標頭完成驗證，而非使用 connect.params.auth.*。
  • 私有入口的 gateway.auth.mode: "none" 會完全停用共用祕密驗證；請勿在公開或不受信任的入口使用此模式。
  • 具有副作用的方法（send、agent）必須使用冪等性金鑰，才能安全重試；伺服器會保留短期的重複資料刪除快取。
  • 節點必須在 connect 中包含 role: "node"，以及能力、命令和權限。

配對與本機信任

  • 所有 WS 用戶端（操作端與節點）都會在 connect 中包含裝置身分。
  • 新的裝置 ID 必須經過配對核准；閘道會核發裝置權杖供後續連線使用。
  • 直接透過 local loopback 的連線可自動核准，以維持同一主機上的順暢使用體驗。
  • OpenClaw 也為受信任的共用祕密輔助流程提供範圍有限的後端／容器本機自我連線路徑。
  • Tailnet 與區域網路連線（包括同一主機上的 Tailnet 繫結）仍須明確核准配對。
  • 所有連線都必須簽署 connect.challenge 隨機數。簽章承載內容 v3 也會繫結 platform 與 deviceFamily；重新連線時，閘道會鎖定已配對的中繼資料，若中繼資料變更則須進行修復配對。
  • 非本機連線仍須明確核准。
  • 無論本機或遠端，閘道驗證（gateway.auth.*）仍適用於所有連線。

詳細資訊：閘道通訊協定、配對、 安全性。

通訊協定型別與程式碼產生

  • TypeBox 結構描述定義通訊協定。
  • JSON Schema 由這些結構描述產生。
  • Swift 模型由 JSON Schema 產生。

遠端存取

  • 建議使用：Tailscale 或 VPN。

  • 替代方案：SSH 通道

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

  • 通道上會套用相同的交握程序與驗證權杖。

  • 在遠端設定中，可為 WS 啟用 TLS 與選用的憑證固定。

操作摘要

  • 啟動：openclaw gateway（前景執行，將記錄輸出至標準輸出）。
  • 健康狀態：透過 WS 使用 health（也包含於 hello-ok 中）。
  • 監督：使用 launchd/systemd 自動重新啟動。

不變條件

  • 每部主機恰好由一個閘道控制單一 Baileys 工作階段。
  • 交握是必要程序；任何非 JSON 或第一個訊框不是 connect 的情況，都會立即關閉連線。
  • 事件不會重播；發生缺漏時，用戶端必須重新整理。

相關內容

Was this useful?
On this page

On this page