macOS companion app

WebChat（macOS）

macOS 選單列 App 將 WebChat UI 內嵌為原生 SwiftUI 檢視。它會連線至閘道，並預設使用所選代理程式的主要工作階段（main，或當 session.scope 為 global 時使用 global）。

完整聊天視窗是原生分割檢視：

工作階段側邊欄：可搜尋的工作階段清單，包含已釘選、閘道支援的群組及最近使用區段。在各區段中，衍生的子工作階段會巢狀顯示於其父工作階段下；收合的父工作階段會彙整執行中、失敗及未讀的後代工作階段。快顯功能表支援工作階段資訊、重新命名、釘選、分支、標示已讀／未讀、封存／還原、複製工作階段金鑰及刪除。主要的新工作階段動作（或 Shift-Cmd-N）會立即透過 sessions.create 建立工作階段；相鄰的選項彈出式視窗可選取代理程式，並要求建立可選擇基底參照的受管理工作樹。
視窗工具列：內容用量環（權杖與工作階段成本，並附有精簡動作）、模型控制項，以及工作階段動作選單。模型依提供者分組，預設提供者排在最前面，而已釘選與最近使用的模型則保留於頂端。控制項可繼承或覆寫模型的思考層級、選擇工具呼叫的詳細程度，以及切換快速回應。選單可重新命名目前的工作階段或從中建立分支，並更新其釘選、已讀或封存狀態。工作階段⋯（Shift-Cmd-S）會開啟「使用中／已封存」管理器，用於閘道搜尋、群組管理、工作階段檢查、重新命名、釘選、封存及還原。選取模式可將釘選、取消釘選、封存或刪除套用至多個使用中的工作階段，同時讓個別失敗項目保持可見。選單中的個別勾選標記可顯示或隱藏助理推理與工具活動；兩者預設皆為開啟，並會跨啟動記憶設定。
對話記錄與撰寫器：助理訊息會以附有頭像的純文字呈現，使用者訊息則以強調色對話泡泡呈現。待處理的代理程式問題會呈現為原生卡片，包含單選或複選選項、可輸入自由文字的其他答案、到期倒數，以及共用的終止狀態。空白聊天會提供桌面版入門提示。輸入 / 會開啟由 commands.list 支援的斜線命令自動完成，並可使用方向鍵／Tab／Return／Escape 鍵盤導覽。在訊息上按一下右鍵，即可複製其可見的 Markdown，而不包含隱藏的推理。遭截斷的助理訊息也會提供開啟完整訊息，以載入可選取文字的 Markdown 閱讀器。使用聆聽可透過閘道執行 TTS，並以本機語音作為備援。
語音控制項：撰寫器可啟動或停止現有的 macOS 對話模式，而不會取代其選單列浮層。對話模式啟用時，撰寫器會顯示其聆聽／思考／說話狀態、即時音訊活動，以及可展開的滾動對話記錄。在「對話」按鈕上按一下右鍵，即可選擇 System Default 或已連線的麥克風；這與語音喚醒及按鍵說話使用相同的麥克風選擇。若所選麥克風中斷連線，使用中的對話工作階段會退回使用系統預設值，並在下次啟動對話模式時再次嘗試該選項。當對話模式未占用音訊擷取時，另一個麥克風動作可錄製語音留言。

選單列中的錨定式精簡聊天面板會維持精簡的單欄版面配置，並在行內提供相同的模型、思考、詳細程度及快速控制項，另包含入門提示、對話模式、語音留言及聆聽。助理推理與工具活動在此精簡介面中仍會隱藏。

多個閘道視窗

開啟 Settings → Gateways，即可新增或移除可重複使用的閘道設定檔。每個設定檔包含私人網路 ws:// 或安全的 wss:// 端點，以及其選用的權杖或密碼；認證資訊會儲存在 macOS 鑰匙圈中。安全設定檔會維護各自受到系統信任閘門保護的首次使用憑證釘選，且不會從主要閘道繼承 gateway.remote.tlsFingerprint。移除設定檔也會關閉其開啟的視窗，並關閉其次要連線。

選擇 File → New Gateway Window… 或按下 Cmd-N，然後選取其中一個已儲存的設定檔。選擇器會記住最近使用的設定檔。每次選取都會建立新的獨立視窗，因此同一個閘道可出現在多個視窗中，並具有不同的使用中工作階段及導覽狀態。

每個已儲存的設定檔都擁有一個共用的閘道連線、裝置驗證範圍、對話記錄快取、離線寄件匣及路由租約。該設定檔的視窗會重複使用這些資源，同時維持獨立導覽。不同設定檔的視窗會維持連線並同時執行聊天。

選單列 App 所設定的閘道仍是 Mac 節點功能與對話模式的擁有者。其他閘道視窗僅供操作者使用，因此第二個閘道無法在未告知的情況下重新指定全域麥克風或裝置控制項。聆聽／TTS 與一般聊天動作會使用視窗本身的閘道連線。

快速聊天列

按下 Option-Space（⌥Space），或從選單列選單選擇快速聊天，即可開啟主要工作階段的浮動撰寫器。可使用 Settings → General → Quick Chat shortcut 中的錄製器變更全域快捷鍵。

快速聊天會顯示目標代理程式（頭像或表情符號，並以代理程式名稱作為預留位置），並傳送至該代理程式的主要工作階段。Return 接受傳送後，聊天列會維持開啟，並向下展開以顯示串流傳回的 Markdown 回覆與最近的對話記錄。聊天列輸入欄仍是撰寫器。按下 Command-Return 可傳送並在完整聊天視窗中開啟同一目標；按下 Shift-Return 可換行；按下 Escape 可關閉整個聊天列與回覆區域。按一下外部也會將其關閉。若缺少相關的 macOS 權限，附加的提示列會提供 Grant 與 Not now 動作。

使用麥克風按鈕將語音聽寫至撰寫器。部分語音結果會即時取代聽寫範圍，同時保留撰寫器中已有的文字。再次按下該按鈕、Return 或 Escape 即可停止；傳送、隱藏快速聊天或使其失去焦點也會釋放麥克風。首次使用時會要求 macOS 麥克風與語音辨識存取權。快速聊天使用 Apple 語音，且可能使用其網路服務；只有被動式語音喚醒需要裝置端辨識。

精簡模型控制項會顯示目標工作階段目前的模型與推理層級。模型選擇會更新該工作階段，因此會在其中持續保留；推理選擇則僅套用於目前快速聊天介面傳送的每則訊息。聊天列隱藏時，本機選擇會重設。切換代理程式或選擇最近的工作階段時，會保留明確選擇，但重新載入新目標工作階段的底層模型狀態。

按一下歷史記錄按鈕，即可從最近更新的五個工作階段中選擇，或返回傳送新訊息給 <agent>。選擇最近的工作階段後，訊息會傳送至該確切工作階段，並將預留位置變更為在 <session> 中回覆。隱藏快速聊天會將此暫時目標重設為所選代理程式的主要工作階段；從頭像選單切換代理程式也會將其清除。

Command-Return 會開啟收到該次傳送之代理程式的對話，即使工作階段範圍為全域亦同。

相機按鈕會開啟選單，提供 Capture Window… 或 Capture Area…。視窗擷取會標示每個可見視窗；區域擷取會在拖曳區域時調暗每個顯示器，並顯示即時尺寸。選取的螢幕截圖會連同任何輸入的文字作為其說明，傳送至所選代理程式。首次使用時會要求 macOS 螢幕錄製存取權。按下 Escape、按一下空白處，或按一下但未拖曳出有效區域，都會取消操作。

使用文件文字按鈕，可從目前聚焦 App 的聚焦視窗附加文字。快速聊天會將結果顯示為可移除的情境標籤，而不會把擷取的文字放入撰寫器；傳送時會將標籤中的文字附加至送出的訊息，然後將其清除。這需要 macOS 輔助使用權限。每次關閉快速聊天時，附加的文字也會清除，因此某次顯示的情境不會洩漏至後續傳送。

回覆完成後，選擇貼到 <app>，即可將其可見的助理文字（不含隱藏推理）複製到一般剪貼簿，並貼入先前位於最前方的 App。這需要 macOS 輔助使用權限。此動作會取代目前的剪貼簿內容，然後隱藏快速聊天。

可使用 Settings → General → Quick Chat 完全停用此功能；同一區段也包含快捷鍵錄製器。

本機模式：直接連線至本機閘道 WebSocket。
遠端模式：使用已設定的直接 ws:///wss:// 路由，或由 App 管理的 SSH 通道作為資料平面。

啟動與偵錯

手動：Lobster 選單 ->「開啟聊天」。
測試時自動開啟：
bash
```
dist/OpenClaw.app/Contents/MacOS/OpenClaw --chat
```
（--webchat 可作為舊版別名使用。）
日誌：./scripts/clawlog.sh（子系統 ai.openclaw，類別 WebChatSwiftUI）。

連接方式

資料平面：閘道 WS 方法 chat.history、chat.message.get、chat.send、chat.abort、chat.inject，以及 question.list 與 question.resolve，另有事件 chat、agent、presence、tick、health；問題卡片會追蹤 question.requested 與 question.resolved 事件，並在重新連線後從 question.list 重新整理。
chat.history 會傳回經顯示正規化的對話記錄：行內指令標籤會從可見文字中移除；純文字工具呼叫 XML 承載內容（<tool_call>、<function_call>、<tool_calls>、<function_calls>，包括遭截斷的區塊）與洩漏的模型控制權杖也會移除；純靜默權杖的助理資料列（例如完全符合 NO_REPLY/no_reply）會省略；過大的資料列則可替換為截斷預留位置。
工作階段：如上所述，預設使用主要工作階段；UI 可在工作階段之間切換。
工作階段群組：sessions.groups.list、sessions.groups.put、sessions.groups.rename 及 sessions.groups.delete 擁有群組目錄。成員資格是透過 sessions.patch 更新的工作階段 category。
未讀狀態：工作階段啟用且其即時歷史記錄成功載入後，App 會清除該工作階段的未讀標記。歷史記錄載入失敗時不會清除；暫時性的修補失敗會在下次啟用時重試。
初始設定會使用專用工作階段，使首次執行設定保持獨立。
離線快取：App 會為每個閘道保留最近聊天工作階段與對話記錄的小型唯讀快取（~/Library/Application Support/OpenClaw/chat-cache.sqlite）：冷啟動會立即呈現最後已知的對話記錄，並在閘道回應後重新整理；中斷連線時仍可瀏覽最近的聊天（在連線恢復前，傳送功能會維持停用）。

安全性介面

遠端模式僅透過 SSH 轉送閘道 WebSocket 控制連接埠。

已知限制

UI 針對聊天工作階段最佳化，而非完整的瀏覽器沙箱。