TUI（終端機 UI）

快速開始

1. 啟動 Gateway。

openclaw gateway

2. 開啟 TUI。

openclaw tui

3. 輸入訊息並按 Enter。

遠端 Gateway：

openclaw tui --url ws://<host>:<port> --token <gateway-token>

Gateway 使用密碼驗證時，改用 --password。

畫面說明

• 標頭：連線 URL、當前 agent、當前工作階段。
• 聊天記錄：使用者訊息、助理回覆、系統通知、工具卡片。
• 狀態列：連線/執行狀態（connecting、running、streaming、idle、error）。
• 頁尾：連線狀態 + agent + 工作階段 + 模型 + think/fast/verbose/reasoning + token 計數 + deliver。
• 輸入區：含自動完成的文字編輯器。

運作概念：agent + 工作階段

• Agent 是唯一的 slug（如 main、research）。Gateway 公開可用列表。
• 工作階段屬於當前 agent。
• 工作階段金鑰存為 agent:<agentId>:<sessionKey>。
  • 輸入 /session main 時，TUI 會展開為 agent:<currentAgent>:main。
  • 輸入 /session agent:other:main 時，明確切換到該 agent 工作階段。
• 工作階段範圍：
  • per-sender（預設）：每個 agent 有多個工作階段。
  • global：TUI 始終使用 global 工作階段（選擇器可能為空）。
• 當前 agent + 工作階段始終顯示在頁尾。

傳送與傳遞

• 訊息傳送給 Gateway；預設不傳遞給 provider。
• 啟用傳遞：
  • /deliver on
  • 或設定面板
  • 或啟動時加上 openclaw tui --deliver

選擇器與覆蓋層

• 模型選擇器：列出可用模型並設定工作階段覆寫。
• Agent 選擇器：選擇不同的 agent。
• 工作階段選擇器：僅顯示當前 agent 的工作階段。
• 設定：切換 deliver、工具輸出展開、thinking 可見性。

鍵盤快速鍵

• Enter：傳送訊息
• Esc：中止執行中的回合
• Ctrl+C：清除輸入（按兩次退出）
• Ctrl+D：退出
• Ctrl+L：模型選擇器
• Ctrl+G：Agent 選擇器
• Ctrl+P：工作階段選擇器
• Ctrl+O：切換工具輸出展開/收合
• Ctrl+T：切換 thinking 可見性（重新載入歷史）

斜線指令

核心：

• /help
• /status
• /agent <id>（或 /agents）
• /session <key>（或 /sessions）
• /model <provider/model>（或 /models）

工作階段控制：

• /think <off|minimal|low|medium|high>
• /fast <status|on|off>
• /verbose <on|full|off>
• /reasoning <on|off|stream>
• /usage <off|tokens|full>
• /elevated <on|off|ask|full>（別名：/elev）
• /activation <mention|always>
• /deliver <on|off>

工作階段生命週期：

• /new 或 /reset（重設工作階段）
• /abort（中止執行中的回合）
• /settings
• /exit

其他 Gateway 斜線指令（如 /context）會轉發到 Gateway 並顯示為系統輸出。詳見 斜線指令。

本機 shell 指令

• 在行首加上 ! 可執行本機 shell 指令。
• TUI 會在每次工作階段首次使用時提示一次是否允許本機執行；拒絕後該工作階段的 ! 功能停用。
• 指令在 TUI 工作目錄中以全新、非互動式 shell 執行（不保留 cd/env）。
• 本機 shell 指令的環境中包含 OPENCLAW_SHELL=tui-local。
• 單獨的 ! 會作為一般訊息傳送；前置空白不會觸發本機執行。

工具輸出

• 工具呼叫顯示為含參數 + 結果的卡片。
• Ctrl+O 切換收合/展開檢視。
• 工具執行中，部分更新會串流到同一張卡片。

終端機顏色

• TUI 使用終端機預設前景色顯示助理本文，深淺色終端機都能正常閱讀。
• 如果終端機使用淺色背景且自動偵測有誤，請在啟動 openclaw tui 前設定 OPENCLAW_THEME=light。
• 要強制使用原始深色配色，設定 OPENCLAW_THEME=dark。

歷史與串流

• 連線時，TUI 載入最近的歷史記錄（預設 200 則訊息）。
• 串流回應會即時更新，直到最終定稿。
• TUI 同時監聽 agent 工具事件以呈現更豐富的工具卡片。

連線細節

• TUI 以 mode: "tui" 向 Gateway 註冊。
• 重新連線時顯示系統訊息；事件間隙會在記錄中標示。

選項

• --url <url>：Gateway WebSocket URL（預設為設定檔或 ws://127.0.0.1:<port>）
• --token <token>：Gateway token（需要時）
• --password <password>：Gateway 密碼（需要時）
• --session <key>：工作階段金鑰（預設：main，scope 為 global 時為 global）
• --deliver：傳遞助理回覆給 provider（預設關閉）
• --thinking <level>：覆寫傳送時的 thinking 層級
• --timeout-ms <ms>：Agent 逾時（毫秒）（預設為 agents.defaults.timeoutSeconds）

注意：設定 --url 時，TUI 不會退回到設定檔或環境憑證。請明確傳入 --token 或 --password。缺少明確憑證為錯誤。

疑難排解

傳送訊息後沒有輸出：

• 在 TUI 中執行 /status 確認 Gateway 已連線且為 idle/busy。
• 檢查 Gateway 記錄：openclaw logs --follow。
• 確認 agent 可執行：openclaw status 和 openclaw models status。
• 如果預期訊息出現在聊天頻道中，請啟用傳遞（/deliver on 或 --deliver）。
• --history-limit <n>：載入的歷史記錄條目數（預設 200）

連線疑難排解

• disconnected：確認 Gateway 正在執行且 --url/--token/--password 正確。
• 選擇器中沒有 agent：檢查 openclaw agents list 和路由設定。
• 工作階段選擇器為空：可能在 global scope 下或尚未建立任何工作階段。