跳到內容
OpenClaw

OpenClaw 控制介面設定：快速連線與裝置配對指南

有時候你只是想有個直觀的介面來管理你的機器人，而不是一直盯著終端機看。Control UI 讓你不需要寫任何前端程式碼，就能直接透過瀏覽器操控你的 Gateway，讓除錯和設定變得更輕鬆。

控制介面 (瀏覽器)

Section titled “控制介面 (瀏覽器)”

Control UI 是一個由 Gateway 提供的輕量化 Vite + Lit 單頁應用程式：

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

它會直接連線到相同連接埠上的 Gateway WebSocket。

快速開啟 (本地)

Section titled “快速開啟 (本地)”

如果 Gateway 正在你的電腦上執行，請開啟：

如果頁面載入失敗，請先啟動 Gateway：openclaw gateway。

身份驗證會在 WebSocket 握手期間透過以下參數提供：

  • connect.params.auth.token
  • connect.params.auth.password

控制面板的設定頁面會為目前的瀏覽器分頁工作階段和選定的 Gateway URL 保留 token；密碼則不會被儲存。 初始設定預設會產生一個 Gateway token，所以第一次連線時請將它貼到這裡。

裝置配對 (首次連線)

Section titled “裝置配對 (首次連線)”

當你從新的瀏覽器或裝置連線到 Control UI 時，即使你在同一個 Tailnet 且設定了 gateway.auth.allowTailscale: true，Gateway 仍會要求一次性的配對核准。這是一項防止未經授權存取的安全措施。

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

如何核准裝置：

Terminal window
# List pending requests
openclaw devices list


# Approve by request ID
openclaw devices approve <requestId>

如果瀏覽器使用變更後的驗證詳細資訊（role/scopes/public key）重試配對，之前的待處理請求會被取代，並建立新的 requestId。核准前請重新執行 openclaw devices list。

一旦核准，系統就會記住該裝置，除非你使用 openclaw devices revoke --device <id> --role <role> 撤銷它，否則不需要重新核准。關於 token 輪換和撤銷，請參閱 Devices CLI。

注意事項：

  • 本地連線 (127.0.0.1) 會自動核准。
  • 遠端連線（LAN, Tailnet 等）需要明確核准。
  • 每個瀏覽器設定檔都會產生唯一的裝置 ID，因此切換瀏覽器或清除瀏覽器資料將需要重新配對。

語言支援

Section titled “語言支援”

Control UI 在首次載入時會根據你的瀏覽器語系自動切換語言，你之後也可以在 Access 卡片的語言選擇器中進行更改。

  • 支援的語系：en, zh-CN, zh-TW, pt-BR, de, es
  • 非英文翻譯在瀏覽器中採延遲載入 (lazy-loaded)。
  • 選定的語系會儲存在瀏覽器空間中，供下次造訪時使用。
  • 缺失的翻譯鍵值會回退到英文。

目前支援的功能

Section titled “目前支援的功能”
  • 透過 Gateway WS 與模型聊天 (chat.history, chat.send, chat.abort, chat.inject)
  • 在聊天中串流顯示 tool calls + 即時工具輸出卡片（agent 事件）
  • 頻道：WhatsApp/Telegram/Discord/Slack + 外掛頻道（Mattermost 等）狀態 + QR 登入 + 各頻道獨立設定 (channels.status, web.login.*, config.patch)
  • 執行個體：存在列表 + 重新整理 (system-presence)
  • 工作階段：列表 + 各別工作階段的 thinking/fast/verbose/reasoning 覆寫 (sessions.list, sessions.patch)
  • Cron 排程任務：列表/新增/編輯/執行/啟用/停用 + 執行紀錄 (cron.*)
  • Skills：狀態、啟用/停用、安裝、API key 更新 (skills.*)
  • Nodes：列表 + 功能 (node.list)
  • Exec 核准：編輯 Gateway 或 Node 允許清單 + exec host=gateway/node 的詢問策略 (exec.approvals.*)
  • 設定：查看/編輯 ~/.openclaw/openclaw.json (config.get, config.set)
  • 設定：套用 + 驗證後重啟 (config.apply) 並喚醒最後一個活動中的工作階段
  • 設定寫入包含 base-hash 保護，以防止覆蓋同時進行的編輯
  • 設定寫入（config.set/config.apply/config.patch）也會對提交的設定內容中的 SecretRef 進行預檢；未解析的活動 SecretRef 會在寫入前被拒絕
  • 設定結構化定義 (Schema) + 表單渲染（config.schema，包含外掛與頻道定義）；原始 JSON 編輯器僅在快照可以安全地進行原始資料來回轉換時才可用
  • 如果快照無法安全地轉換原始文字，Control UI 會強制使用表單模式並停用該快照的原始模式
  • 結構化的 SecretRef 物件值在表單文字輸入框中會以唯讀方式呈現，以防止意外將物件損壞為字串
  • 除錯：狀態/健康檢查/模型快照 + 事件日誌 + 手動 RPC 呼叫 (status, health, models.list)
  • 日誌：即時追蹤 Gateway 檔案日誌，支援過濾與匯出 (logs.tail)
  • 更新：執行套件/git 更新 + 重啟 (update.run) 並附帶重啟報告

Cron 任務面板說明：

  • 對於獨立任務，傳送方式預設為宣告摘要。如果你想要僅限內部執行，可以切換為 none。
  • 選擇宣告 (announce) 時會出現頻道/目標欄位。
  • Webhook 模式使用 delivery.mode = "webhook"，並將 delivery.to 設定為有效的 HTTP(S) webhook URL。
  • 對於主工作階段任務，支援 webhook 和 none 傳送模式。
  • 進階編輯控制包含執行後刪除、清除 agent 覆寫、cron 精確/交錯選項、agent 模型/thinking 覆寫，以及盡力傳送開關。
  • 表單驗證具備欄位級錯誤提示；無效值會停用儲存按鈕直到修正為止。
  • 設定 cron.webhookToken 以傳送專用的 bearer token，如果省略，webhook 將在不帶驗證標頭的情況下傳送。
  • 棄用的回退方案：帶有 notify: true 的舊版儲存任務仍可使用 cron.webhook 直到遷移完成。

聊天行為

Section titled “聊天行為”
  • chat.send 是非阻塞的：它會立即回傳 { runId, status: "started" }，回應則透過 chat 事件串流傳輸。
  • 使用相同的 idempotencyKey 重新傳送時，執行中會回傳 { status: "in_flight" }，完成後回傳 { status: "ok" }。
  • chat.history 的回應有大小限制以確保 UI 安全。當對話紀錄條目太大時，Gateway 可能會截斷長文字欄位、省略大型元數據區塊，並用佔位符取代過大的訊息 ([chat.history omitted: message too large])。
  • chat.inject 會在工作階段紀錄中附加一條助理筆記，並廣播一個 chat 事件僅供 UI 更新（不觸發 agent 執行，不進行頻道傳送）。
  • 停止：
    • 點擊 Stop (呼叫 chat.abort)
    • 輸入 /stop (或獨立的終止詞彙如 stop, stop action, stop run, stop openclaw, please stop) 來進行頻外終止
    • chat.abort 支援 { sessionKey }（不需 runId）來終止該工作階段的所有活動執行
  • 終止後的片段保留：
    • 當執行被終止時，UI 仍可顯示部分的助理文字
    • 當緩衝輸出存在時，Gateway 會將終止前的部分助理文字持久化到紀錄中
    • 持久化的條目包含終止元數據，讓紀錄讀取者能分辨這是終止產生的片段還是正常的完整輸出

Tailnet 存取 (推薦方式)

Section titled “Tailnet 存取 (推薦方式)”

整合式 Tailscale Serve (首選)

Section titled “整合式 Tailscale Serve (首選)”

讓 Gateway 保持在 loopback，並讓 Tailscale Serve 透過 HTTPS 代理它：

Terminal window
openclaw gateway --tailscale serve

開啟：

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

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

綁定到 Tailnet + Token

Section titled “綁定到 Tailnet + Token”
Terminal window
openclaw gateway --bind tailnet --token "$(openssl rand -hex 32)"

然後開啟：

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

將 token 貼到 UI 設定中（作為 connect.params.auth.token 傳送）。

不安全的 HTTP

Section titled “不安全的 HTTP”

如果你透過純 HTTP（http://<lan-ip> 或 http://<tailscale-ip>）開啟控制面板，瀏覽器會執行於非安全上下文並阻擋 WebCrypto。預設情況下，OpenClaw 會阻擋沒有裝置身份的 Control 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 的 Control UI 工作階段在非安全 HTTP 上下文中無需裝置身份即可繼續。
  • 它不會繞過配對檢查。
  • 它不會放寬遠端（非 localhost）的裝置身份要求。

僅限緊急使用：

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

dangerouslyDisableDeviceAuth 會停用 Control UI 的裝置身份檢查，這是一個嚴重的安全降級。緊急使用後請迅速恢復。

關於 HTTPS 設定指南，請參閱 Tailscale。

建置 UI

Section titled “建置 UI”

Gateway 從 dist/control-ui 提供靜態檔案。使用以下指令建置：

Terminal window
pnpm ui:build # auto-installs UI deps on first run

選填的絕對路徑前綴（當你需要固定資產 URL 時）：

Terminal window
OPENCLAW_CONTROL_UI_BASE_PATH=/openclaw/ pnpm ui:build

本地開發（獨立開發伺服器）：

Terminal window
pnpm ui:dev # auto-installs UI deps on first run

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

除錯與測試：開發伺服器 + 遠端 Gateway

Section titled “除錯與測試：開發伺服器 + 遠端 Gateway”

Control UI 是靜態檔案；WebSocket 目標是可配置的，且可以與 HTTP 來源不同。當你想要在本地使用 Vite 開發伺服器，但 Gateway 在其他地方執行時，這非常方便。

  1. 啟動 UI 開發伺服器：pnpm ui:dev
  2. 開啟如下網址：
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 (#token=...) 傳遞。Fragment 不會傳送到伺服器，這可以避免請求日誌和 Referer 洩漏。舊有的 ?token= 查詢參數仍會為了相容性匯入一次，但僅作為回退方案，並在啟動後立即清除。
  • password 僅保留在記憶體中。
  • 當設定了 gatewayUrl 時，UI 不會回退到設定檔或環境變數中的憑證。請明確提供 token（或 password）。缺少明確憑證將導致錯誤。
  • 當 Gateway 位於 TLS 之後（Tailscale Serve, HTTPS 代理等）時，請使用 wss://。
  • gatewayUrl 僅在頂層視窗（非嵌入式）中被接受，以防止點擊劫持。
  • 非 loopback 的 Control UI 部署必須明確設定 gateway.controlUi.allowedOrigins（完整來源）。這包含遠端開發設定。
  • 除非是受到嚴格控制的本地測試，否則不要使用 gateway.controlUi.allowedOrigins: ["*"]。這意味著允許任何瀏覽器來源，而不是「匹配我正在使用的任何主機」。
  • gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true 會啟用 Host-header 來源回退模式，但這是一個危險的安全模式。

範例：

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

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

相關連結

Section titled “相關連結”

想要更快速地完成設定嗎？試試我們的 AI Setup Assistant。

下一步

Section titled “下一步”
OpenClaw

OpenClaw Expert

還是卡住了？

如果這篇文件沒有解決你的情境，直接問 OpenClaw Expert，拿到可執行步驟。