控制台 UI（瀏覽器）

控制台 UI 是一個由 Gateway 提供的小型 Vite + Lit 單頁應用程式：

  • 預設位址：http://<host>:18789/
  • 可選前綴：設定 gateway.controlUi.basePath（如 /openclaw）

它透過同一埠直接與 Gateway WebSocket 通訊。

快速開啟（本機）

如果 Gateway 在同一台電腦上執行，開啟：

頁面無法載入時，請先啟動 Gateway：openclaw gateway。

驗證透過 WebSocket 握手時提供：

  • connect.params.auth.token
  • connect.params.auth.password 儀表板設定面板會為當前瀏覽器分頁工作階段和選定的 gateway URL 保存 token；密碼不會持久化。 初始設定精靈預設會產生 gateway token，首次連線時在此貼上。

裝置配對（首次連線）

從新的瀏覽器或裝置連線到控制台 UI 時，Gateway 會要求一次性配對核准——即使你在同一個 Tailnet 上且 gateway.auth.allowTailscale: true 也不例外。這是防止未經授權存取的安全措施。

你會看到： “disconnected (1008): pairing required”

核准裝置：

# 列出待處理的請求
openclaw devices list

# 依 request ID 核准
openclaw devices approve <requestId>

核准後，該裝置會被記住，除非你透過 openclaw devices revoke --device <id> --role <role> 撤銷。詳見 裝置 CLI 的 token 輪換與撤銷說明。

注意：

  • 本機連線（127.0.0.1）會自動核准。
  • 遠端連線（區域網路、Tailnet 等）需要明確核准。
  • 每個瀏覽器設定檔會產生唯一的裝置 ID，切換瀏覽器或清除瀏覽器資料需要重新配對。

語言支援

控制台 UI 首次載入時可根據瀏覽器語系自動在地化，之後可在 Access 卡片的語言選擇器中覆寫。

  • 支援語系：en、zh-CN、zh-TW、pt-BR、de、es
  • 非英語翻譯在瀏覽器中延遲載入。
  • 選定的語系存在瀏覽器 storage 中，未來造訪時重複使用。
  • 缺少的翻譯鍵值退回英文。

目前功能

  • 透過 Gateway WS 與模型聊天（chat.history、chat.send、chat.abort、chat.inject）
  • 串流工具呼叫 + 即時工具輸出卡片（agent 事件）
  • 頻道：WhatsApp/Telegram/Discord/Slack + 外掛頻道（Mattermost 等）狀態 + QR 碼登入 + 按頻道設定（channels.status、web.login.*、config.patch）
  • 實例：在線列表 + 重新整理（system-presence）
  • 工作階段：列表 + 按工作階段的 thinking/fast/verbose/reasoning 覆寫（sessions.list、sessions.patch）
  • 排程工作：列表/新增/編輯/執行/啟用/停用 + 執行歷史（cron.*）
  • 技能：狀態、啟用/停用、安裝、API 金鑰更新（skills.*）
  • 節點：列表 + 功能（node.list）
  • Exec 核准：編輯 gateway 或節點的允許清單 + ask 策略，用於 exec host=gateway/node（exec.approvals.*）
  • 設定：檢視/編輯 ~/.openclaw/openclaw.json（config.get、config.set）
  • 設定：套用 + 重新啟動（含驗證）（config.apply）並喚醒上次的活躍工作階段
  • 設定寫入包含 base-hash 保護，防止覆蓋並行的編輯
  • 設定 schema + 表單呈現（config.schema，包含外掛 + 頻道 schema）；原始 JSON 編輯器仍可使用
  • 除錯：狀態/健康/模型快照 + 事件記錄 + 手動 RPC 呼叫（status、health、models.list）
  • 記錄：即時追蹤 gateway 檔案記錄，含篩選/匯出功能（logs.tail）
  • 更新：執行套件/git 更新 + 重新啟動（update.run），附帶重新啟動報告

排程工作面板注意事項：

  • 對於隔離的工作，傳遞預設為摘要通知。你可以切換為「無」以進行僅內部的執行。
  • 選擇通知時會出現頻道/目標欄位。
  • Webhook 模式使用 delivery.mode = "webhook"，delivery.to 設為有效的 HTTP(S) webhook URL。
  • 主工作階段的工作支援 webhook 和「無」傳遞模式。
  • 進階編輯控制項包括執行後刪除、清除 agent 覆寫、cron 精確/分散選項、agent 模型/thinking 覆寫，以及盡力傳遞開關。
  • 表單驗證為內嵌式，含欄位層級錯誤；無效值會停用儲存按鈕直到修正。
  • 設定 cron.webhookToken 以傳送專用 bearer token；省略時 webhook 不附帶驗證標頭。
  • 棄用的退回方式：存有 notify: true 的舊版工作仍可使用 cron.webhook，直到遷移完成。

聊天行為

  • chat.send 是非阻塞的：立即確認並回傳 { runId, status: "started" }，回應透過 chat 事件串流。
  • 使用相同 idempotencyKey 重新傳送時，執行中回傳 { status: "in_flight" }，完成後回傳 { status: "ok" }。
  • chat.history 的回應有大小限制以確保 UI 穩定。當轉錄條目過大時，Gateway 可能裁切長文字欄位、省略大量 metadata 區塊，並以佔位符（[chat.history omitted: message too large]）取代過大的訊息。
  • chat.inject 在工作階段轉錄中附加一則助理備註，並廣播 chat 事件供 UI 更新（不觸發 agent 執行，不傳送到頻道）。
  • 停止：
    • 點擊停止（呼叫 chat.abort）
    • 輸入 /stop（或獨立的中止短語如 stop、stop action、stop run、stop openclaw、please stop）以帶外中止
    • chat.abort 支援 { sessionKey }（無需 runId）以中止該工作階段的所有執行中的回合
  • 中止後的部分保留：
    • 回合被中止時，部分助理文字仍可在 UI 中顯示
    • 當存在已緩衝的輸出時，Gateway 會將中止的部分助理文字持久化到轉錄歷史
    • 持久化的條目包含中止 metadata，讓轉錄消費者能區分中止的部分輸出與正常完成的輸出

Tailnet 存取（建議）

整合式 Tailscale Serve（首選）

將 Gateway 保持在 loopback，讓 Tailscale Serve 以 HTTPS 代理：

openclaw gateway --tailscale serve

開啟：

  • https://<magicdns>/（或你設定的 gateway.controlUi.basePath）

預設情況下，當 gateway.auth.allowTailscale 為 true 時，控制台 UI/WebSocket 的 Serve 請求可透過 Tailscale 身分標頭（tailscale-user-login）驗證。OpenClaw 會透過 tailscale whois 解析 x-forwarded-for 位址並與標頭比對來驗證身分，且僅在請求命中 loopback 且帶有 Tailscale 的 x-forwarded-* 標頭時接受。設定 gateway.auth.allowTailscale: false（或強制 gateway.auth.mode: "password"）可要求即使是 Serve 流量也需要 token/密碼。 無 token 的 Serve 驗證假設 gateway 主機是可信的。如果不可信的本機程式碼可能在該主機上執行，請要求 token/密碼驗證。

繫結到 tailnet + token

openclaw gateway --bind tailnet --token "$(openssl rand -hex 32)"

然後開啟：

  • http://<tailscale-ip>:18789/（或你設定的 gateway.controlUi.basePath）

在 UI 設定中貼上 token（以 connect.params.auth.token 傳送）。

非安全 HTTP

如果透過純 HTTP 開啟儀表板（http://<lan-ip> 或 http://<tailscale-ip>），瀏覽器在非安全上下文中執行並封鎖 WebCrypto。預設情況下，OpenClaw 阻擋沒有裝置身分的控制台 UI 連線。

建議修正方式： 使用 HTTPS（Tailscale Serve）或在本機開啟 UI：

  • https://<magicdns>/（Serve）
  • http://127.0.0.1:18789/（在 gateway 主機上）

非安全驗證開關行為：

{
  gateway: {
    controlUi: { allowInsecureAuth: true },
    bind: "tailnet",
    auth: { mode: "token", token: "replace-me" },
  },
}

allowInsecureAuth 僅為本機相容性開關：

  • 允許 localhost 的控制台 UI 工作階段在非安全 HTTP 上下文中不提供裝置身分即可繼續。
  • 不會繞過配對檢查。
  • 不會放寬遠端（非 localhost）的裝置身分要求。

緊急備用方案：

{
  gateway: {
    controlUi: { dangerouslyDisableDeviceAuth: true },
    bind: "tailnet",
    auth: { mode: "token", token: "replace-me" },
  },
}

dangerouslyDisableDeviceAuth 停用控制台 UI 的裝置身分檢查，這是嚴重的安全降級。緊急使用後請盡速恢復。

詳見 Tailscale 的 HTTPS 設定指引。

建構 UI

Gateway 從 dist/control-ui 提供靜態檔案。建構方式：

pnpm ui:build # 首次執行時自動安裝 UI 相依套件

使用絕對基礎路徑（需要固定資源 URL 時）：

OPENCLAW_CONTROL_UI_BASE_PATH=/openclaw/ pnpm ui:build

本機開發（獨立 dev server）：

pnpm ui:dev # 首次執行時自動安裝 UI 相依套件

然後將 UI 指向你的 Gateway WS URL（如 ws://127.0.0.1:18789）。

除錯/測試：dev server + 遠端 Gateway

控制台 UI 是靜態檔案；WebSocket 目標可設定，且可與 HTTP 來源不同。當你想在本機使用 Vite dev server 但 Gateway 在其他地方執行時很方便。

  1. 啟動 UI dev server：pnpm ui:dev
  2. 開啟類似以下的 URL：
http://localhost:5173/?gatewayUrl=ws://<gateway-host>:18789

需要時可附帶一次性驗證：

http://localhost:5173/?gatewayUrl=wss://<gateway-host>:18789#token=<gateway-token>

注意：

  • gatewayUrl 載入後存入 localStorage 並從 URL 中移除。
  • token 從 URL fragment 匯入，存入 sessionStorage（當前瀏覽器分頁工作階段和選定的 gateway URL），並從 URL 中移除；不存入 localStorage。
  • password 僅保留在記憶體中。
  • 設定 gatewayUrl 時，UI 不會退回到設定檔或環境憑證。請明確提供 token（或 password）。缺少明確憑證為錯誤。
  • Gateway 在 TLS 後方時（Tailscale Serve、HTTPS 代理等），使用 wss://。
  • gatewayUrl 僅在頂層視窗中接受（非嵌入），以防止點擊劫持。
  • 非 loopback 的控制台 UI 部署必須明確設定 gateway.controlUi.allowedOrigins（完整 origin）。包括遠端開發環境。
  • gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true 啟用 Host 標頭 origin 退回模式，但這是危險的安全模式。

範例：

{
  gateway: {
    controlUi: {
      allowedOrigins: ["http://localhost:5173"],
    },
  },
}

遠端存取設定詳情：遠端存取。

arrow_back
上一頁
Web
下一頁
Dashboard
arrow_forward