OpenClaw WebChat 頻道
即時通訊
簡單
WebChat 是 OpenClaw Gateway 內建的聊天介面。它透過 WebSocket 直接連線——無需外部服務、API 金鑰或第三方帳號。只需啟動 Gateway、設定驗證方式，然後開啟 WebChat 介面即可開始與 AI 助手對話。所有訊息均採用確定性路由，代表回覆一定會回傳到發起對話的 WebChat 工作階段。
快速資訊
難度簡單
分類即時通訊
支援功能數1 / 6
WebChat 支援功能
文字訊息
支援
媒體與檔案
不支援
表情回應
不支援
討論串
不支援
語音訊息
不支援
群組聊天
不支援
WebChat 前置條件
- OpenClaw Gateway 已安裝並執行
- Gateway 驗證已設定（token 或密碼模式）
- 現代網頁瀏覽器（Control UI）或原生 macOS/iOS 用戶端
- 可存取 Gateway WebSocket 連接埠的網路環境（預設：3000）
WebChat 快速設定
1
啟動 Gateway
啟動您的 OpenClaw Gateway。WebChat 是內建功能——無需另外安裝或外掛。執行 'openclaw start' 即可啟動 Gateway 服務。
2
設定驗證方式
在 openclaw.json 中設定 gateway.auth.mode，選擇 'token' 或 'password' 驗證方式。所有連線（包括 localhost）都必須進行驗證。
3
開啟 WebChat
透過瀏覽器中的 Control UI 聊天分頁存取 WebChat 介面，或啟動原生 macOS/iOS 用戶端。連線到 ws://localhost:3000（或您設定的主機和連接埠）。
4
開始聊天
傳送一條測試訊息以驗證連線。您的 AI 助手將透過同一個 WebChat 工作階段回覆。對話記錄由 Gateway 管理，並在重新連線後保持不變。
WebChat 設定範例
config.json
{
"gateway": {
"port": 3000,
"bind": "127.0.0.1",
"auth": {
"mode": "token",
"token": "YOUR_SECRET_TOKEN"
}
}
}WebChat 深入了解
架構概述
WebChat 透過 WebSocket 連線與 OpenClaw Gateway 通訊，主要使用三種操作：
• chat.history — 從 Gateway 擷取對話記錄
• chat.send — 將使用者訊息傳送給 AI 助手
• chat.inject — 直接將助手備註附加到對話紀錄並廣播到介面，而不觸發代理執行
與依賴外部服務和 Webhook 的其他頻道不同，WebChat 完全內建於 Gateway。訊息不會離開您的基礎架構——WebSocket 連線是介面用戶端與 Gateway 程序之間的直接連線。路由是確定性的：AI 的回覆一定會回傳到發起對話的 WebChat 工作階段。
WebChat 是最容易設定的頻道，因為它不需要任何外部帳號或 API 金鑰——只需 Gateway 本身即可。
chat.inject 操作適合在對話中新增系統備註或上下文，而不觸發 AI 回覆。
Gateway 驗證
所有 WebChat 連線都需要驗證，即使在本機迴路（localhost）上也是如此。這可以防止未經授權存取您的 AI 助手。
OpenClaw 支援兩種驗證模式：
• token — 在 WebSocket 交握時傳遞的共用密鑰。適合程式化存取和單一使用者環境。
• password — 基於密碼的驗證。適合每位使用者擁有獨立憑證的多使用者環境。
必須至少設定 token 或 password 之一，WebChat 才會接受連線。請在 openclaw.json 的 gateway.auth 設定中進行配置。
openclaw.json
{
"gateway": {
"auth": {
"mode": "token",
"token": "a-strong-random-token-here"
}
}
}即使是 localhost 連線也必須進行驗證。切勿在未設定驗證的情況下執行 Gateway——機器上的任何程序都可能存取您的 AI 助手。
遠端存取
WebChat 支援遠端連線，無需執行獨立的網頁伺服器。推薦兩種方式：
• SSH 通道 — 透過 SSH 轉發 Gateway 連接埠：ssh -L 3000:localhost:3000 user@remote-host。這讓您可以在本機存取 WebChat，而 Gateway 執行在遠端機器上。
• Tailscale — 透過 Tailscale 的網狀 VPN 連接您的裝置。Gateway 可透過其 Tailscale IP 位址存取，無需連接埠轉發或防火牆設定。
對於遠端連線，請在 gateway.remote 設定中配置目標 WebSocket URL 和驗證憑證。原生用戶端會在網路狀況改變時自動處理重新連線。
openclaw.json
{
"gateway": {
"remote": {
"url": "wss://your-remote-host:3000",
"token": "YOUR_REMOTE_TOKEN"
}
}
}SSH 通道是取得遠端存取最快的方式，無需任何額外軟體——只需確保可以透過 SSH 存取 Gateway 主機即可。
Tailscale 提供零設定 VPN，讓 Gateway 無需連接埠轉發即可在所有裝置上存取。
工作階段管理
WebChat 使用 Gateway 管理的工作階段來維護對話上下文。每個 WebChat 連線都關聯到一個工作階段，用於儲存對話記錄和 AI 上下文。
工作階段在重新連線後保持不變——如果 WebSocket 斷線並重新連線，對話會從中斷處繼續。chat.history 操作會在重新連線時從 Gateway 擷取完整對話記錄。
工作階段設定透過 openclaw.json 中的 session.* 設定管理，包括儲存後端和預設工作階段金鑰。
對話記錄來源於 Gateway，而非本機儲存。這表示您可以切換裝置並接續同一段對話。
使用 session.defaultKey 為您的 WebChat 對話指定一致的工作階段識別碼。
唯讀模式
當 Gateway 無法連線時，WebChat 會自動進入唯讀模式。在此狀態下：
• 先前的對話記錄仍可檢視
• 無法傳送新訊息
• 介面會顯示斷線狀態
• 背景自動嘗試重新連線
一旦 Gateway 恢復上線，WebChat 會自動重新連線並恢復完整功能。由於所有記錄來源於 Gateway，因此對話記錄不會遺失。
唯讀模式是一種優雅降級——使用者在 Gateway 暫時無法使用時仍可回顧過去的對話。
原生用戶端功能
WebChat 在 Apple 平台上以原生 SwiftUI 應用程式實作：
• macOS — 完整桌面體驗，支援鍵盤快速鍵、系統通知和選單列整合
• iOS — 行動裝置最佳化介面，支援推播通知和背景重新整理
原生實作提供回應迅速、符合平台風格的體驗，無需嵌入式瀏覽器或 Electron 包裝的額外負擔。文字渲染、捲動和輸入處理均使用原生平台元件。
在其他平台（Windows、Linux、Android）上，可透過任何現代網頁瀏覽器中的 Control UI 聊天分頁存取 WebChat。
原生 macOS/iOS 用戶端提供最佳體驗，具備系統通知和鍵盤快速鍵等平台專屬功能。
基於瀏覽器的 Control UI 聊天分頁適用於所有平台，提供相同的核心功能。
訊息傳遞
WebChat 透過 WebSocket 連線處理訊息傳遞，並可針對較長的 AI 回覆設定分塊方式：
• textChunkLimit — 每個訊息分塊的最大字元數（預設：2000）。較長的回覆會自動分割。
• blockStreaming — 啟用後，回覆會在產生過程中以區塊形式傳送，提供即時回饋。
訊息透過 WebSocket 即時傳遞——沒有輪詢或 Webhook 延遲。雙向 WebSocket 連線意味著傳送和接收都是即時的。
openclaw.json
{
"channels": {
"webchat": {
"textChunkLimit": 2000,
"blockStreaming": true
}
}
}安全性最佳實踐
WebChat 的安全性建立在 Gateway 驗證層之上。請遵循以下最佳實踐以確保部署安全：
• 務必設定驗證 — 不允許匿名存取
• 使用 TLS 加密 — 所有遠端連線請透過 wss://（WebSocket Secure）連線
• 限制繫結位址 — 僅限本機存取時使用 gateway.bind: "127.0.0.1"；除非在反向代理之後，否則避免繫結到 0.0.0.0
• 使用強憑證 — 產生隨機 token 或強密碼
• 反向代理 — 正式環境部署時，請將 Gateway 置於反向代理（nginx、Caddy）之後，並啟用 TLS 終端
如果在同一台機器上使用反向代理，請設定 gateway.trustedProxies 以確保正確偵測用戶端 IP。
切勿在沒有 TLS 加密和強驗證的情況下將 Gateway WebSocket 連接埠直接暴露在網際網路上。正式環境部署請使用帶有 TLS 終端的反向代理。
WebChat 設定參考
| Key | Type | Default | Description |
|---|---|---|---|
| gateway.port | number | 3000 | Gateway 的 WebSocket 連接埠號 |
| gateway.bind | string | "127.0.0.1" | Gateway 繫結的 WebSocket 連線主機位址 |
| gateway.auth.mode | string | "token" | 驗證模式：'token' 為共用密鑰，'password' 為基於憑證的驗證 |
| gateway.auth.token | string | "" | WebSocket 驗證的共用密鑰 token |
| gateway.auth.password | string | "" | WebSocket 驗證的密碼 |
| gateway.remote.url | string | "" | 遠端 Gateway WebSocket URL（例如 wss://remote-host:3000） |
| gateway.remote.token | string | "" | 連線到遠端 Gateway 的驗證 token |
| gateway.remote.password | string | "" | 連線到遠端 Gateway 的驗證密碼 |
| session.defaultKey | string | "" | WebChat 對話的預設工作階段金鑰 |
| session.storage | string | "memory" | 工作階段儲存後端（memory、file、redis 等） |
| textChunkLimit | number | 2000 | 每個輸出訊息分塊的最大字元數 |
| blockStreaming | boolean | false | 在產生過程中以區塊形式傳送回覆，提供即時回饋 |
gateway.port
Type: numberDefault: 3000
Gateway 的 WebSocket 連接埠號
gateway.bind
Type: stringDefault: "127.0.0.1"
Gateway 繫結的 WebSocket 連線主機位址
gateway.auth.mode
Type: stringDefault: "token"
驗證模式：'token' 為共用密鑰，'password' 為基於憑證的驗證
gateway.auth.token
Type: stringDefault: ""
WebSocket 驗證的共用密鑰 token
gateway.auth.password
Type: stringDefault: ""
WebSocket 驗證的密碼
gateway.remote.url
Type: stringDefault: ""
遠端 Gateway WebSocket URL（例如 wss://remote-host:3000）
gateway.remote.token
Type: stringDefault: ""
連線到遠端 Gateway 的驗證 token
gateway.remote.password
Type: stringDefault: ""
連線到遠端 Gateway 的驗證密碼
session.defaultKey
Type: stringDefault: ""
WebChat 對話的預設工作階段金鑰
session.storage
Type: stringDefault: "memory"
工作階段儲存後端（memory、file、redis 等）
textChunkLimit
Type: numberDefault: 2000
每個輸出訊息分塊的最大字元數
blockStreaming
Type: booleanDefault: false
在產生過程中以區塊形式傳送回覆，提供即時回饋
WebChat 常見問題
WebChat 故障排除
WebChat 顯示「已斷線」且無法重新連線
Gateway 未執行，或 WebSocket 連接埠被防火牆封鎖。
使用 'openclaw status' 確認 Gateway 正在執行。檢查設定的 gateway.port 是否被防火牆封鎖。確認 gateway.bind 允許來自您用戶端網路位址的連線。
連線時驗證失敗
token 或密碼與 Gateway 設定不符。
確認 gateway.auth.token 或 gateway.auth.password 與您的用戶端憑證完全一致。檢查是否有尾隨空格或編碼問題。變更驗證設定後請重新啟動 Gateway。
訊息已傳送但沒有 AI 回覆
AI 代理未設定，或 AI 供應商的 API 金鑰無效。
檢查 Gateway 日誌中的錯誤。驗證 openclaw.json 中的代理設定。確認 AI 供應商（例如 OpenAI、Anthropic）的 API 金鑰有效且有可用額度。
透過 SSH 通道的遠端連線失敗
SSH 通道未轉發正確的連接埠，或 Gateway 未在預期的位址上監聽。
確認 SSH 指令與 Gateway 連接埠一致：ssh -L 3000:localhost:3000 user@host。在遠端機器上確認 Gateway 正在預期的連接埠上監聽。檢查 gateway.bind 是否設為 127.0.0.1 以供 SSH 通道存取。
重新連線後對話記錄為空
工作階段在兩次連線之間過期或被清除。
檢查 openclaw.json 中的工作階段設定。確認 Gateway 有足夠的儲存空間以維持工作階段持久化。驗證兩次連線之間的工作階段金鑰是否一致。