> ## Documentation Index
> Fetch the complete documentation index at: https://openclaw.veiseule.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Gateway 閘道器架構

# Gateway 閘道器架構

最後更新：2026-01-22

## 概覽

* 單一長時間存活的 **Gateway 閘道器** 擁有所有訊息介面（WhatsApp 透過
  Baileys、Telegram 透過 grammY、Slack、Discord、Signal、iMessage、WebChat）。
* 控制平面客戶端（macOS 應用程式、CLI、Web UI、自動化）透過 **WebSocket** 連線到
  設定的綁定位址上的 Gateway 閘道器（預設
  `127.0.0.1:18789`）。
* **Nodes**（macOS/iOS/Android/無介面）也透過 **WebSocket** 連線，但
  會宣告 `role: node` 並附上明確的能力／命令。
* 每台主機僅有一個 Gateway 閘道器；它是唯一會開啟 WhatsApp 工作階段的地方。
* **canvas host** 由 Gateway HTTP 伺服器提供，路徑為：
  * `/__openclaw__/canvas/`（agent 可編輯的 HTML/CSS/JS）
  * `/__openclaw__/a2ui/`（A2UI host）
    使用與 Gateway 相同的連接埠（預設 `18789`）。

## 元件與流程

### Gateway（常駐程式）

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

### 客戶端（mac 應用程式／CLI／Web 管理介面）

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

### Nodes（macOS／iOS／Android／無介面）

* 使用 `role: node` 連線到**相同的 WS 伺服器**。
* 在 `connect` 中提供裝置身分；配對為**以裝置為基礎**（角色 `node`），
  核准狀態保存在裝置配對儲存區。
* 提供命令，例如 `canvas.*`、`camera.*`、`screen.record`、`location.get`。

18. 協定細節：

* [Gateway protocol](/gateway/protocol)

### WebChat

* 使用 Gateway WS API 的靜態 UI，用於聊天紀錄與傳送。
* 在遠端設定中，透過與其他客戶端相同的 SSH／Tailscale 通道連線。

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

```mermaid theme={"theme":{"light":"min-light","dark":"min-dark"}}
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?}`
* 若設定了 `OPENCLAW_GATEWAY_TOKEN`（或 `--token`），`connect.params.auth.token`
  必須相符，否則連線會關閉。
* 具副作用的方法（`send`、`agent`）需要冪等鍵以
  安全重試；伺服器會保留短期的去重快取。
* Nodes 必須在 `role: "node"` 中包含資訊，並在 `connect` 中提供能力／命令／權限。

## 配對＋本地信任

* 所有 WS 客戶端（操作人員＋ nodes）都在 `connect` 上包含**裝置身分**。
* 新的裝置 ID 需要配對核准；Gateway 閘道器會發出**裝置權杖**供後續連線使用。
* **本地**連線（loopback 或 Gateway 閘道器主機自身的 tailnet 位址）可自動核准，
  以維持同主機的順暢 UX。
* **非本地**連線必須簽署 `connect.challenge` nonce，且需要明確核准。
* Gateway 身分驗證（`gateway.auth.*`）仍適用於**所有**連線，不論本地或遠端。

詳細資訊：[Gateway protocol](/gateway/protocol)、[Pairing](/channels/pairing)、
[Security](/gateway/security)。

## 19. 協定型別與程式碼產生

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

## 20. 遠端存取

* 首選：Tailscale 或 VPN。

* 替代方案：SSH 通道

  ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
  ssh -N -L 18789:127.0.0.1:18789 user@host
  ```

* 21. 相同的交握流程與驗證權杖會套用於通道中。

* 在遠端設定中可啟用 WS 的 TLS＋選用釘選。

## 操作快照

* 啟動：`openclaw gateway`（前景執行，日誌輸出至 stdout）。
* 健康狀態：透過 WS 的 `health`（亦包含於 `hello-ok`）。
* 監督：使用 launchd／systemd 進行自動重新啟動。

## 23. 不變條件

* 每台主機僅有一個 Gateway 閘道器控制單一 Baileys 工作階段。
* 交握為必要；任何非 JSON 或非 connect 的第一個訊框都會被強制關閉。
* 事件不會重播；客戶端在發生間隙時必須重新整理。