控制介面

Control UI 是由閘道提供服務的小型 Vite + Lit 單頁應用程式：

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

它會透過相同連接埠，直接連線至閘道 WebSocket。

快速開啟（本機）

如果閘道在同一台電腦上執行，請開啟 http://127.0.0.1:18789/（或 http://localhost:18789/）。

如果頁面無法載入，請先啟動閘道：openclaw gateway。

驗證會在 WebSocket 交握期間透過下列方式提供：

• connect.params.auth.token
• connect.params.auth.password
• 當 gateway.auth.allowTailscale: true 時的 Tailscale Serve 身分標頭
• 當 gateway.auth.mode: "trusted-proxy" 時的受信任 Proxy 身分標頭

儀表板設定面板會保留目前瀏覽器分頁工作階段的權杖與所選的閘道 URL；密碼不會持久保存。首次連線時，初始設定通常會產生用於共享密鑰驗證的閘道權杖，但當 gateway.auth.mode 為 "password" 時，也可使用密碼驗證。

裝置配對（首次連線）

從新的瀏覽器或裝置連線時，通常需要一次性配對核准，顯示為 disconnected (1008): pairing required。

openclaw devices list

openclaw devices approve <requestId>

如果瀏覽器使用變更後的驗證詳細資料（角色／範圍／公開金鑰）重試配對，先前待處理的要求會被取代，並建立新的 requestId；請在核准前重新執行 openclaw devices list。

將已配對的瀏覽器從讀取存取權切換為寫入／管理員存取權，會視為核准升級，而不是無提示地重新連線：OpenClaw 會維持舊核准有效、封鎖權限更廣的重新連線，並要求你明確核准新的範圍集合。

核准後，裝置會被記住，除非你使用 openclaw devices revoke --device <id> --role <role> 撤銷，否則不需要重新核准。如需權杖輪替、撤銷，以及 Paperclip／openclaw_gateway 首次執行核准流程，請參閱裝置命令列介面。

配對行動裝置

已配對的管理員可以建立 iOS／Android 連線 QR Code，而不必開啟終端機：

建立設定碼需要 operator.admin；沒有該權限的工作階段會停用按鈕。設定碼包含短效的啟動認證資訊，因此在有效期間，請將 QR Code 與複製的程式碼視同密碼。若要進行遠端配對，閘道必須解析為 wss://（例如透過 Tailscale Serve/Funnel）；純 ws:// 僅限回送位址與私人 LAN 位址。如需完整的安全性與後援詳細資訊，請參閱配對。

個人身分（瀏覽器本機）

Control UI 支援每個瀏覽器各自的個人身分（顯示名稱與頭像），並將其附加至送出的訊息，以便在共用工作階段中標示來源。這些資料存放於瀏覽器儲存空間中，範圍限定於目前的瀏覽器設定檔，不會同步到其他裝置，也不會在伺服器端持久保存；唯一例外是你所傳送訊息中的一般逐字稿作者中繼資料。清除網站資料或切換瀏覽器會將其重設為空白。

助理頭像覆寫也遵循相同的瀏覽器本機模式：上傳的覆寫會在本機疊加於閘道解析的身分之上，且絕不會透過 config.patch 往返傳輸。共用的 ui.assistant.avatar 設定欄位仍可供直接寫入該欄位的非 UI 用戶端使用。

執行階段設定端點

Control UI 會從 /control-ui-config.json 擷取其執行階段設定，並以閘道的 Control UI 基底路徑為基準解析（例如基底路徑 /__openclaw__/ 下的 /__openclaw__/control-ui-config.json）。該端點受到與其餘 HTTP 介面相同的閘道驗證保護：未驗證的瀏覽器無法擷取，而且成功擷取需要有效的閘道權杖／密碼、Tailscale Serve 身分或受信任 Proxy 身分。

閘道主機狀態

在簡易檢視中開啟 Settings，即可查看 Gateway Host 卡片，其中包含閘道機器、LAN 位址、作業系統、執行階段、運作時間、CPU 負載、記憶體及狀態磁碟區磁碟空間。卡片顯示時，會每 10 秒透過 system.info 閘道 RPC 重新整理，而這需要 operator.read 範圍。較舊的閘道以及沒有該範圍的連線不會顯示此卡片。

語言支援

Control UI 首次載入時，會根據你的瀏覽器地區設定自動本地化。若要稍後覆寫，請開啟 Settings -> General -> Language（選擇器位於 General 快速設定卡片中，而不是 Appearance 之下）。

• 支援的地區設定：en、ar、de、es、fa、fr、hi、id、it、ja-JP、ko、nl、pl、pt-BR、ru、th、tr、uk、vi、zh-CN、zh-TW
• 非英文翻譯會在瀏覽器中延遲載入。
• 所選地區設定會儲存在瀏覽器儲存空間中，並在日後造訪時重複使用。
• 缺少的翻譯鍵會回退至英文。

文件翻譯也會針對相同的非英文地區設定集合產生，但文件網站內建的 Mintlify 語言選擇器只會列出 Mintlify 接受的地區設定代碼。泰文（th）與波斯文（fa）文件仍會在發布儲存庫中產生；在 Mintlify 支援這些代碼之前，它們可能不會出現在該選擇器中。

外觀主題

Appearance 面板內建 Claw、Knot 與 Dash 主題（預設為 Claw），另有一個僅限瀏覽器本機的 tweakcn 匯入欄位。若要匯入主題，請開啟 tweakcn 編輯器，選擇或建立主題、按一下 Share，然後將複製的連結貼到 Appearance 中。匯入工具也接受 https://tweakcn.com/r/themes/<id> 登錄 URL、如 https://tweakcn.com/editor/theme?theme=amethyst-haze 的編輯器 URL、相對 /themes/<id> 路徑、原始主題 ID，以及如 amethyst-haze 的預設主題名稱。

匯入的主題只會儲存在目前的瀏覽器設定檔中；不會寫入閘道設定，也不會跨裝置同步。替換匯入的主題會更新該本機欄位；如果匯入的主題為使用中，清除後會切換回 Claw。

Appearance 另有僅限瀏覽器本機的文字大小設定，與其餘 Control UI 偏好設定一起儲存。它會套用至聊天文字、撰寫器文字、工具卡片及聊天側邊欄，並讓文字輸入框至少維持 16px，避免行動版 Safari 在取得焦點時自動縮放。

管理外掛

開啟側邊欄中的 Plugins，或使用相對於已設定 Control UI 基底路徑的 /settings/plugins，即可在不離開 Control UI 的情況下瀏覽及管理外掛。例如，基底路徑 /openclaw 會使用 /openclaw/settings/plugins。 即使所有選用外掛都已停用，此頁面仍隨時可用。

Plugins 是包含四個分頁的中樞：Installed 與 Discover 會在 /settings/plugins 管理外掛程式碼；Skills 會在 /skills 提供個別代理程式的技能管理員；而 Workshop 會在 /skills/workshop 提供 Skill Workshop 提案審查。每個分頁都會保留自己的 URL，而側邊欄會為所有分頁顯示單一 Plugins 項目。

Installed 分頁會依類別顯示完整的本機清單， 並提供概覽數量。每一列都可開啟詳細資料檢視；其溢位（…）選單可 啟用或停用外掛，並為外部安裝的外掛提供 Remove。 它也會列出已設定的 MCP 伺服器，並支援直接加入、停用 及移除。Discover 分頁是商店：其中包含 OpenClaw 隨附的精選外掛、官方外部外掛，以及適用於熱門服務的一鍵式 MCP 連接器。 在搜尋方塊中輸入內容會直接查詢 ClawHub，並附加 From ClawHub 區段，其中包含下載次數與來源驗證徽章。深層連結可使用 /settings/plugins?tab=discover 直接指向商店。

Skills 分頁會保留技能狀態報告、啟用／停用切換、API 金鑰輸入，以及內嵌 ClawHub 技能搜尋，範圍限定於所選代理程式。 Workshop 分頁會保留 Skill Workshop 看板與 Today 審查流程，用於 技能提案。Find skill ideas 會從最新到最舊， 審查一定範圍內具實質內容的工作階段，並將所有結果保留為 待處理提案。面板會顯示累計涵蓋範圍；Scan earlier work 會從持久保存的游標繼續，較舊的歷史記錄全部掃描完畢後， 就會變成 Scan new work。停用自主自我學習時， 仍可進行手動歷史記錄審查，並使用所選代理程式設定的模型。

隨附的外掛已存在於閘道上，並會顯示 Enable 或 Disable，而不是 Install。例如，Workboard 隨 OpenClaw 提供，但預設停用，因此其動作為 Enable。內建外掛 無法移除，只能停用。

讀取目錄及搜尋 ClawHub 需要 operator.read。安裝、 啟用、停用或移除外掛，以及變更 MCP 伺服器，都需要 operator.admin；這些動作對唯讀操作員維持停用狀態。

ClawHub 安裝會透過閘道執行，並採用與其他閘道媒介安裝相同的信任、完整性 及外掛安裝原則檢查。安裝或移除外掛程式碼需要重新啟動閘道。 若外掛及目前的閘道執行階段支援，啟用或停用已安裝的外掛可在 不重新啟動的情況下生效；否則 UI 會回報需要重新啟動。 以 OAuth 為基礎的 MCP 連接器在加入後，需要從命令列介面執行一次 openclaw mcp login <name>。

此頁面刻意聚焦於清單、探索、安裝、啟用 及移除。若要使用任意 npm、git 或本機路徑來源、進行更新及進階外掛設定， 請使用 openclaw plugins。

側邊欄導覽

側邊欄會將導覽列固定在可捲動的工作階段清單上方。在多代理程式設定中，每個代理程式都會顯示為可收合的頂層區段；展開代理程式即可瀏覽其工作階段，而不會離開目前開啟的聊天，收合的代理程式則會顯示未讀指示。每個代理程式的清單會分為：已釘選、每個已連線頻道各自的內建區段（Telegram、Slack、WhatsApp 等）、供繫結至受管理工作樹或執行節點之工作階段使用的內建 工作 區段（資料列會顯示一行 repo ⎇ branch 以及節點主機）、自訂群組（工作階段 category），以及容納其餘項目的 聊天。頻道與工作區段會自動分類資料列；將工作階段指派至自訂群組一律具有優先權。開啟工作階段只會移動選取醒目提示，不會重新排序資料列。自上次讀取後有新活動的工作階段會顯示未讀圓點，開啟後即標示為已讀。每個工作階段資料列都有內容選單（烤肉串按鈕或按右鍵），其中包含釘選／取消釘選、標示為未讀／已讀、重新命名、分支、移至群組（包括新增群組及從群組移除）、封存及刪除；觸控版面會讓直接釘選與選單控制項保持可見。按住 Cmd/Ctrl 並按一下可切換資料列的多重選取狀態，按住 Shift 並按一下則會依可見順序延伸選取範圍；接著在已選取的資料列上開啟選單，便會提供批次動作（將 N 個項目標示為未讀／已讀、將 N 個項目移至群組、封存 N 個項目、刪除 N 個項目），並套用至所有已選取的工作階段，而批次刪除只需確認一次。將工作階段拖曳至自訂群組或 聊天 即可移動。自訂群組標頭可以收合、展開或透過拖曳重新排序；群組名稱及其順序會儲存在閘道中（sessions.groups.*），因此可跨瀏覽器同步，而收合狀態則保留在瀏覽器設定檔中。群組標頭也有內容選單（烤肉串按鈕或按右鍵），其中包含重新命名群組、新增群組及刪除群組；重新命名或刪除群組時，伺服器端會更新每個成員工作階段，包括已封存的工作階段，而刪除群組會保留其中的工作階段，並將其移回聊天。工作階段清單標頭中唯一的 + 會開啟新增工作階段頁面（見下文）。排序控制項也有「分組方式」切換選項：分組（預設）或無，後者會顯示單一扁平清單（已釘選仍維持獨立）；此選擇會儲存在目前的瀏覽器設定檔中。用量、自動化及外掛預設會釘選；更多資料列會開啟包含所有其他目的地的選單，其中也包括外掛提供的分頁。在該選單中選取 編輯釘選項目，或在導覽區域按右鍵，即可釘選或取消釘選目的地，以及還原預設值。釘選集合會儲存在目前的瀏覽器設定檔中，並在重新載入後保留。

新增工作階段頁面

側邊欄工作階段清單標頭中的 + 會在 /new 開啟全頁草稿：在你傳送第一則訊息前，不會建立任何項目。訊息方塊上方的目標資料列可選擇工作階段的運作位置：代理程式（多代理程式設定）、執行作業的運行位置（閘道 · 本機，或公開 system.run 的已配對節點；需要 operator.admin）、資料夾（預設為代理程式工作區；其他絕對閘道路徑需要 operator.admin 及工作樹），以及選用的 工作樹 切換開關與基礎分支選擇器（由 worktrees.branches 提供，因此不會執行擷取），另可選填工作樹名稱（分支會變成 openclaw/<name>）。資料夾方塊的瀏覽按鈕會開啟由僅限管理員使用的 fs.listDir 方法提供支援的行內目錄選擇器。其頂層會顯示閘道與每個已知節點；離線節點及不支援目錄瀏覽的節點仍會顯示，但處於停用狀態。選取閘道後，會從目前資料夾或閘道主目錄開始瀏覽。選取具備所需功能的節點後，會瀏覽該節點的主機檔案系統、將執行作業繫結至該節點，並直接使用所選取的絕對節點路徑（受管理工作樹仍僅限閘道使用）。提交時會使用第一則訊息呼叫 sessions.create，因此執行作業會在同一次往返中開始，使用者介面則會跳至新工作階段的聊天。如果閘道建立了工作階段，但拒絕該次首次傳送，聊天會在重新載入後保留提示詞與錯誤；重試會透過已建立的工作階段傳送訊息，而不會再建立另一個工作階段。

在 Settings 中，專用側邊欄的開頭設有 Search settings 欄位，可快速尋找設定區段。

側邊欄頂端的 Search 欄位會開啟命令選擇區（⌘K）。按一下側邊欄標頭中的 OpenClaw 品牌，即會開啟簡潔的「新增工作階段」起始畫面。當有事項需要處理時（例如失敗或逾期的排程工作、即將到期或已到期的模型驗證），側邊欄頁尾上方會顯示精簡的提醒標籤，按一下即可前往相應頁面。頁尾會以標籤顯示作用中的代理程式，包括頭像（身分圖片或表情符號）、名稱、連線狀態點及即時副標題，旁邊另有 + 可建立新工作階段。按一下該標籤會開啟代理程式選單，其中包含代理程式切換器（多代理程式設定）、「這個代理程式能做什麼？」、代理程式設定、設定、行動裝置配對、文件、建置版本標籤，以及色彩模式切換開關。代理程式超過十個時，清單會顯示篩選欄位，並優先列出已釘選的代理程式；可從「代理程式設定」頁面釘選或取消釘選代理程式，釘選項目會儲存在瀏覽器設定檔中。選擇代理程式後，「聊天」、「用量」、「自動化」、「任務」、「工作看板」及「工作階段」都會限定於該代理程式。每個限定範圍的頁面都提供 代理程式 控制項，並可選擇 所有代理程式 以解除限制；這會擴大共用頁面的範圍，但不會變更實際的聊天代理程式，而工作階段的直接連結仍會開啟其目標。代理程式設定頁面會保留自己的 ?agent= 選取項目，不會跟隨共用頁面的範圍。當閘道從原始碼簽出版本執行，且所在分支不是 main 時，頁尾也會以紅色顯示該分支名稱，讓使用者一眼就能看出這是非發行版本的閘道（發行版安裝絕不會顯示）。按 Shift-Command-Comma 可開啟 設定，且不會覆寫瀏覽器的 Command-Comma 快捷鍵。側邊欄標頭也包含收合切換按鈕（⌘B）；收合後會完全隱藏側邊欄，提供全寬工作區，而浮動的展開控制項（或 ⌘B）可將其恢復；macOS 應用程式則改為在標題列原生提供此切換按鈕。側邊欄是桌面版唯一的導覽介面，不設頂端列。狹窄的檢視區會將側邊欄替換為滑入式抽屜，並在精簡標頭列後方提供抽屜切換按鈕、品牌及命令選擇區搜尋；在 macOS 應用程式中，該標頭列會將標題列的預留空間整合成位於視窗控制項旁的單一精簡橫條。導覽使用一般瀏覽器歷程記錄，因此可使用瀏覽器的上一頁／下一頁按鈕巡覽；macOS 應用程式還會在視窗控制項旁新增原生側邊欄切換按鈕，並支援觸控式軌跡板滑動手勢。側邊欄展開時，其右側邊緣會顯示上一頁／下一頁按鈕；收合時則會顯示原生搜尋（命令選擇區）及新增工作階段按鈕。

目前可執行的功能

匯入助理記憶

開啟 設定 → 匯入記憶，將本機 Codex 或 Claude Code 記憶匯入 OpenClaw 代理程式。閘道會自行探索其主機上支援的本機記憶，因此遠端控制介面會從閘道電腦匯入，而不是從瀏覽器電腦匯入。

1. 選擇目的地代理程式。
2. 檢視偵測到的來源集合和 Markdown 檔名。檔案內容不會在計畫回應中傳送，也不會顯示於頁面。
3. 選取要匯入的集合並確認。套用會在寫入前重建計畫，讓過時的選取項目安全地失敗。
4. 若檔案已存在，請啟用 取代現有匯入項目、重新整理預覽，然後確認取代。

Codex 僅匯入其彙整的 MEMORY.md 和 memory_summary.md。Claude Code 會從專案自動記憶目錄和已設定的 autoMemoryDirectory 匯入 Markdown；此頁面不會匯入工作階段、設定、指示或認證資訊。檔案會複製到所選工作區的 memory/imports/ 下，供使用中的記憶外掛建立索引。來源永遠不會變更。

規劃與套用需要 operator.admin。每次套用時，若存在狀態，皆會建立經過驗證的 OpenClaw 備份、寫入已遮蔽敏感資訊的移轉報告，並在取代現有目的地檔案前保留 項目層級的備份。路徑與 記憶回想行為請參閱記憶體概覽。

MCP 頁面

專用的 MCP 頁面是供操作者檢視 OpenClaw 所管理之 MCP 伺服器的介面，這些伺服器位於 mcp.servers 下。此頁面本身不會啟動 MCP 傳輸；請用它檢查及編輯已儲存的設定，並在需要即時伺服器驗證時使用 openclaw mcp doctor --probe。

一般工作流程：

1. 從側邊欄開啟 MCP。
2. 查看摘要卡片中的伺服器總數、已啟用、OAuth 及已篩選數量。
3. 檢視每個伺服器資料列的傳輸方式、啟用狀態、驗證、篩選器、逾時及命令提示。
4. 在 外掛頁面上管理伺服器（新增、啟用／停用、移除）；該頁面是 mcp.servers 唯一的互動式寫入介面，而此處的資料列清單會連結至該頁面。
5. 編輯具範圍限定的 mcp 設定區段，以設定伺服器定義、標頭、TLS/mTLS 路徑、OAuth 中繼資料、工具篩選器及 Codex 投影中繼資料。
6. 使用儲存寫入設定；若應讓執行中的閘道套用變更後的設定，則使用儲存並發布。
7. 從終端機執行 openclaw mcp status --verbose、openclaw mcp doctor --probe 或 openclaw mcp reload，以進行靜態診斷、即時驗證或清除快取的執行階段。

此頁面會在呈現前遮蔽 URL 類型值中包含的認證資訊，並在命令片段中以引號括住伺服器名稱，確保複製的命令即使包含空格或 shell 中繼字元仍可正常運作。完整的命令列介面與設定參考：MCP。

活動分頁

活動分頁位於設定 › 系統，在記錄與偵錯旁邊。它是瀏覽器本機的暫時性即時工具活動觀察器，衍生自與聊天工具卡片相同的閘道 session.tool／工具事件串流。它不會新增其他閘道事件系列、端點、持久性活動儲存區、指標動態消息或外部觀察器串流。

活動項目只會保留經過清理的摘要，以及已遮蔽敏感資訊並截短的輸出預覽。工具引數值不會儲存在活動狀態中；UI 會顯示引數已隱藏，並只記錄引數欄位數量。記憶體內的清單會跟隨目前的瀏覽器分頁，在控制 UI 內導覽時仍會保留，並在重新載入頁面、切換工作階段或按下清除時重設。

操作者終端機

可停駐的操作者終端機預設為停用。若要啟用，請設定 gateway.terminal.enabled: true 並重新啟動閘道。終端機需要 operator.admin 連線，並會在使用中代理程式的工作區內開啟主機 PTY。新分頁會跟隨目前選取的聊天代理程式。

使用 Ctrl + 反引號切換停駐區。版面配置支援停駐於底部或右側、隨瀏覽器檢視區調整大小，並可保留多個 shell 分頁。如需 gateway.terminal.enabled 與選用的 gateway.terminal.shell 覆寫設定，請參閱閘道設定。

在工作階段側邊欄中探索到的 Codex 與 Claude Code 工作階段，可在同一個終端機面板內以其原生命令列介面開啟。在設定 › 聊天中，將開啟 Codex/Claude 工作階段的位置設為終端機，即可讓一般的資料列點擊動作開啟 codex resume 或 claude --resume；預設仍為唯讀的 OpenClaw 檢視器。資料列的右鍵選單或烤肉串選單一律會提供這兩個選項；當該工作階段符合資格時，檢視器標頭也會包含在終端機中開啟。

資格會依各工作階段及各主機判定。閘道本機工作階段會在閘道主機上啟動由提供者擁有的繼續命令。配對節點工作階段會在所屬節點上啟動允許清單中的提供者命令，且只轉送該 PTY 的輸出、輸入及調整大小事件；這不會暴露一般節點 shell，也不會接受瀏覽器提供的命令。未公布相符終端機繼續命令的節點，包括不支援雙向串流的嵌入式工作節點橋接器，仍可使用檢視器，並會顯示無法開啟終端機。

工作階段可在中斷連線後繼續存在：重新載入頁面、筆記型電腦進入睡眠或短暫網路中斷時，工作階段會在閘道上中斷連結，而不會遭到終止；同一個瀏覽器分頁重新連線時會重新連結，並重播最近的輸出。中斷連結的工作階段會在 gateway.terminal.detachedSessionTimeoutSeconds 後遭到終止（預設為 300 秒；0 會還原為中斷連線時終止）。terminal.list 會顯示可連結的工作階段，terminal.attach 會接管其中一個工作階段（類似 tmux 的接管方式），而 terminal.text 則會在不連結的情況下，以純文字讀取工作階段最近的輸出，供代理程式／工具使用。

終端機也可透過 /?view=terminal 以全螢幕、僅含終端機的文件形式使用。iOS 與 Android 應用程式會在其終端機畫面中嵌入此頁面，並重複使用已儲存的閘道認證資訊；可用性遵循相同的 gateway.terminal.enabled 與 operator.admin 閘門，且在所連線的閘道未提供終端機時，頁面會顯示通知。

瀏覽器面板

控制 UI 隨附可停駐的瀏覽器面板，可在任何一般網頁瀏覽器中呈現由閘道控制的瀏覽器（也就是代理程式透過瀏覽器工具操控的同一個瀏覽器），不需要原生 WebView。當所連線的閘道向 operator.admin 連線公布 browser.request 時，此面板便會出現；工作階段工作區欄中的地球按鈕可切換其顯示狀態。面板會顯示即時頁面快照，並提供分頁、可編輯的 URL 列、上一頁／下一頁／重新載入及在你的瀏覽器中開啟等功能；它可停駐於右側或底部，並將點擊、滾輪捲動及基本輸入轉送至遠端頁面。

兩種擷取模式可為代理程式封裝頁面內容：

• 註記（鉛筆）：在頁面上手繪標記。傳送至聊天會將筆畫合成至螢幕截圖、把圖片附加至使用中的聊天編輯器，並預先填入說明頁面 URL、標題及每個已標示區域的提示，讓代理程式確切知道你圈選了哪些部分。
• 檢查（指標）：將游標懸停以查看游標下方的元素（選取器、無障礙名稱、角色、大小）；按一下即可透過相同的編輯器流程，傳送該元素的詳細資訊及反白標示的螢幕截圖。檢查、滾輪捲動及上一頁／下一頁功能需要 browser.evaluateEnabled（預設開啟）。

macOS 應用程式會保留其原生連結瀏覽器側邊欄，用於開啟在儀表板中點擊的連結；瀏覽器面板也可在其中運作，並且是在其他所有平台上註記頁面的方式。

聊天行為

連線中斷與重新連線

工作階段建立後，閘道連線中斷並不會將你登出。儀表板會保持顯示，並在頂端列下方顯示浮動的琥珀色“閘道連線已中斷 — 正在重新連線…”膠囊提示，同時用戶端會以退避機制自動重試（從 800 ms 到最多 15 s）。即時更新與即時通訊／工作階段操作會暫停，直到連線恢復；膠囊提示中的 立即重試 會強制立即嘗試連線。聊天內容仍可編輯：一般文字與附件傳送會保留在目前分頁中以閘道／工作階段為範圍的瀏覽器儲存空間內，顯示為等待重新連線，並在閘道恢復後自動傳送。離線時，即時控制項與斜線命令仍無法使用。

若此瀏覽器已持有認證資訊（已設定的權杖／密碼或已核准的裝置權杖），首次開啟與重新載入時會在建立連線期間顯示小型動畫 OpenClaw 標誌，而不會短暫閃現登入閘門。只有在尚未儲存認證資訊，或閘道主動拒絕認證資訊（錯誤的權杖／密碼、已撤銷的配對）時，才會顯示登入閘門——這些狀態需要你提供輸入，而非繼續等待。

安裝 PWA 與網頁推播

控制 UI 隨附 manifest.webmanifest 與服務工作執行緒，因此現代瀏覽器可將其安裝為獨立 PWA。即使分頁或瀏覽器視窗未開啟，網頁推播也能讓閘道透過通知喚醒已安裝的 PWA。

如果頁面在 OpenClaw 更新後立即顯示 通訊協定不相符，請先使用 openclaw dashboard 重新開啟儀表板並強制重新整理。若仍然失敗，請清除儀表板來源的網站資料，或在瀏覽器的無痕視窗中測試；舊分頁或瀏覽器服務工作執行緒快取可能會讓更新前的控制 UI 套件繼續搭配較新的閘道執行。

若要固定金鑰（多主機部署、密鑰輪替或測試），可透過閘道程序的環境變數覆寫 VAPID 金鑰組：

• OPENCLAW_VAPID_PUBLIC_KEY
• OPENCLAW_VAPID_PRIVATE_KEY
• OPENCLAW_VAPID_SUBJECT（預設為 https://openclaw.ai）

控制 UI 使用下列受範圍限制的閘道方法來註冊及測試瀏覽器訂閱：

• push.web.vapidPublicKey 取得作用中的 VAPID 公開金鑰。
• push.web.subscribe 註冊 endpoint 以及 keys.p256dh/keys.auth。
• push.web.unsubscribe 移除已註冊的端點。
• push.web.test 將測試通知傳送至呼叫端的訂閱。

託管嵌入內容

助理訊息可使用 [embed ...] 短代碼在行內呈現託管的網頁內容。iframe 沙箱原則由 gateway.controlUi.embedSandbox 控制：

內建的 Canvas 外掛也提供 show_widget，可直接從工具呼叫呈現獨立完整的 SVG 或 HTML。瀏覽器會公布 inline-widgets 閘道能力，且重新載入聊天歷程時，產生的 Canvas 文件仍可使用。源自頻道的執行作業不會獲得此工具。

{  gateway: {    controlUi: {      embedSandbox: "scripts",    },  },}

絕對外部 http(s) 嵌入 URL 預設仍會遭到封鎖。若要允許 [embed url="https://..."] 載入第三方頁面，請設定 gateway.controlUi.allowExternalEmbedUrls: true。

聊天訊息寬度

聊天對話記錄使用與撰寫區對齊、置中且易於閱讀的框架。在該框架內，助理與工具輸出保持靠左對齊，而使用者訊息泡泡保持靠右對齊。寬螢幕部署可設定 gateway.controlUi.chatMessageMaxWidth，在不修補內建 CSS 的情況下覆寫對話記錄寬度：

{  gateway: {    controlUi: {      chatMessageMaxWidth: "min(1280px, 82%)",    },  },}

該值會在送達瀏覽器前進行驗證。支援的格式包括 960px 或 82% 等純長度與百分比，以及受限制的 min(...)、max(...)、clamp(...)、calc(...) 和 fit-content(...) 寬度運算式。

Tailnet 存取（建議）

openclaw gateway --tailscale serve

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

不安全的 HTTP

如果你透過純 HTTP（http://<lan-ip> 或 http://<tailscale-ip>）開啟儀表板，瀏覽器會在 非安全環境 中執行並封鎖 WebCrypto。根據預設，OpenClaw 會 封鎖 沒有裝置身分的控制 UI 連線。

文件記載的例外情況：

• 僅限 localhost 的不安全 HTTP 相容性搭配 gateway.controlUi.allowInsecureAuth=true
• 透過 gateway.auth.mode: "trusted-proxy" 成功完成控制 UI 操作者驗證
• 緊急用途的 gateway.controlUi.dangerouslyDisableDeviceAuth=true

**建議的修正方式：**使用 HTTPS（Tailscale Serve），或在 https://<magicdns>/（Serve）或 http://127.0.0.1:18789/（位於閘道主機上）於本機開啟 UI。

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

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

如需 HTTPS 設定指引，請參閱 Tailscale。

內容安全政策

Control UI 隨附嚴格的 img-src 政策：僅允許同源資產、data: URL，以及本機產生的 blob: URL。遠端 http(s) 與協定相對圖片 URL 會遭瀏覽器拒絕，且絕不會發出網路擷取要求。

實際行為如下：

• 透過相對路徑提供的頭像與圖片（例如 /avatars/<id>）仍會顯示，包括 UI 擷取後轉換成本機 blob: URL 的需認證頭像路由。
• 行內 data:image/... URL 仍會顯示。
• 由 Control UI 建立的本機 blob: URL 仍會顯示。
• GitHub 連結預覽頭像由閘道從 GitHub 的固定頭像主機擷取，並以受限的 data: URL 傳回；操作者的瀏覽器絕不會連絡遠端頭像主機。
• 頻道中繼資料輸出的遠端頭像 URL 會在 Control UI 的頭像輔助函式中遭移除，並以內建標誌／徽章取代，因此遭入侵或惡意的頻道無法強迫操作者的瀏覽器任意擷取遠端圖片。

此功能永遠啟用，且無法設定。

頭像路由認證

設定閘道認證後，Control UI 頭像端點需要與 API 其餘部分相同的閘道權杖：

• GET /avatar/<agentId> 僅向已認證的呼叫端傳回頭像圖片。GET /avatar/<agentId>?meta=1 依相同規則傳回頭像中繼資料。
• 對任一路由發出的未認證要求都會遭拒絕（與同層級的助理媒體路由一致），因此頭像路由不會在其他部分皆受保護的主機上洩漏代理程式身分。
• Control UI 擷取頭像時，會以 Bearer 標頭轉送閘道權杖，並使用已認證的 Blob URL，讓圖片仍可在儀表板中顯示。

若停用閘道認證（不建議在共用主機上這麼做），頭像路由也會與閘道其餘部分一樣變成不需認證。

助理媒體路由認證

設定閘道認證後，助理的本機媒體預覽會使用兩步驟路由：

• GET /__openclaw__/assistant-media?meta=1&source=<path> 需要一般的 Control UI 操作者認證；瀏覽器檢查可用性時，會以 Bearer 標頭傳送閘道權杖。
• 成功的中繼資料回應會包含一個短效的 mediaTicket，其範圍限定於該確切來源路徑。
• 瀏覽器顯示的圖片、音訊、影片與文件 URL 會使用 mediaTicket=<ticket>，而非使用中的閘道權杖或密碼。票證會很快到期，且無法授權其他來源。

這可維持媒體顯示與瀏覽器原生媒體元素的相容性，同時避免將可重複使用的閘道認證資訊放入可見的媒體 URL。

核准連結

操作者核准通知可深層連結至保留的 ${controlUiBasePath}/approve/{approvalId} 命名空間下提供的獨立核准文件（例如 /approve/<approvalId>，或在設定基底路徑時使用 /openclaw/approve/<approvalId>）。此 URL 在核准的生命週期內保持穩定，且可安全地在你自己的裝置間轉送：它只會識別核准，絕不會授權核准。

• 閘道會在外掛 HTTP 路由之前，為所有 HTTP 方法保留單區段的 /approve/<approvalId> 命名空間，因此外掛路由絕不可能遮蔽或攔截核准文件。
• 開啟核准文件需要與 Control UI 其餘部分相同的閘道認證（權杖／密碼、Tailscale Serve 身分，或受信任 Proxy 身分）；認證資訊絕不會成為核准 URL 的一部分。
• 停用 Control UI 提供服務時，對此命名空間的要求會傳回 404，而不會轉交給外掛處理常式。
• 在核准文件中登入僅對該頁面暫時有效：它不會覆寫同一瀏覽器中完整 Control UI 所儲存的閘道選擇或設定。

閘道會從 dist/control-ui 提供靜態檔案：

pnpm ui:build

選用的絕對基底（固定資產 URL）：

OPENCLAW_CONTROL_UI_BASE_PATH=/openclaw/ pnpm ui:build

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

pnpm ui:dev

接著將 UI 指向你的閘道 WS URL（例如 ws://127.0.0.1:18789）。

Control UI 空白頁面

如果瀏覽器載入空白儀表板，且 DevTools 未顯示有用的錯誤，可能是擴充功能或提早執行的內容指令碼阻止 JavaScript 模組應用程式求值。靜態頁面包含純 HTML 復原面板，若啟動後未註冊 <openclaw-app>，此面板便會顯示。

變更瀏覽器環境後，請使用面板的 Try again 動作，或在完成以下檢查後手動重新載入：

• 停用會注入所有頁面的擴充功能，特別是具有 <all_urls> 內容指令碼的擴充功能。
• 嘗試使用無痕視窗、全新的瀏覽器設定檔，或其他瀏覽器。
• 讓閘道保持執行，並在變更瀏覽器後驗證相同的儀表板 URL。

偵錯／測試：開發伺服器 + 遠端閘道

Control UI 是靜態檔案；WebSocket 目標可設定，且可與 HTTP 來源不同。若要在本機使用 Vite 開發伺服器，但閘道在其他位置執行，這項功能相當實用。

pnpm ui:dev

http://localhost:5173/?gatewayUrl=ws%3A%2F%2F<gateway-host>%3A18789

http://localhost:5173/?gatewayUrl=wss%3A%2F%2F<gateway-host>%3A18789#token=<gateway-token>

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

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

相關內容

• 儀表板 — 閘道儀表板
• 健康狀態檢查 — 閘道健康狀態監控
• 終端介面 — 終端使用者介面
• WebChat — 瀏覽器式聊天介面