使用 OpenClaw WebChat：原生 macOS/iOS 聊天介面設定指南

每次開發聊天介面，最煩的就是要在前端處理複雜的 WebSocket 連線，還要擔心 Session 狀態在不同裝置間對不起來。如果你也受夠了在瀏覽器裡調試那些笨重的 Web UI，WebChat 提供的原生體驗絕對是更好的選擇。

這套 macOS/iOS 的 SwiftUI 聊天介面會直接與 Gateway WebSocket 通訊，讓你省去中間層的麻煩，直接與核心邏輯對接。

WebChat (Gateway WebSocket UI)

狀態：macOS/iOS SwiftUI 聊天 UI 直接與 Gateway WebSocket 通訊。

這是什麼

• 針對 Gateway 的原生聊天 UI（不需要內嵌瀏覽器，也不用跑本地靜態伺服器）。
• 使用與其他 Channel 相同的 Session 和路由規則。
• 確定性路由：回覆總是會傳回 WebChat。

快速開始

1. 啟動 Gateway。
2. 打開 WebChat UI（macOS/iOS App）或 Control UI 的聊天分頁。
3. 確保已配置 Gateway Auth（預設是必須的，即使是在 loopback 環境）。

運作原理（行為）

• UI 會連線到 Gateway WebSocket 並使用 chat.history、chat.send 與 chat.inject。
• 為了穩定性，chat.history 是有範圍限制的：Gateway 可能會截斷過長的文字欄位、省略大型 Metadata，並將過大的項目替換為 [chat.history omitted: message too large]。
• chat.inject 會直接將 Assistant 筆記附加到對話紀錄中並廣播給 UI（不會執行 Agent）。
• 中止的執行（Aborted runs）可以讓部分 Assistant 輸出在 UI 中保持可見。
• 當存在緩衝輸出時，Gateway 會將中止的部分 Assistant 文字持久化到對話紀錄中，並為這些項目標記中止 Metadata。
• 歷史紀錄總是從 Gateway 獲取（不會監控本地檔案）。
• 如果連不到 Gateway，WebChat 會進入唯讀模式。

Control UI 代理工具面板

• Control UI 的 /agents 工具面板有兩個獨立視圖：
  • Available Right Now 使用 tools.effective(sessionKey=...)，顯示當前 Session 在執行時實際能用的工具，包含核心工具、Plugin 以及 Channel 擁有的工具。
  • Tool Configuration 使用 tools.catalog，專注於 Profile、覆寫（Overrides）和目錄語義。
• 執行時的可用性是受 Session 範圍限制的。在同一個 Agent 上切換 Session 可能會改變 Available Right Now 列表。
• 設定編輯器並不代表執行時的可用性；實際存取權限仍遵循 Policy 優先順序（allow/deny，以及每個 Agent 和 Provider/Channel 的覆寫設定）。

遠端使用

• 遠端模式透過 SSH 或 Tailscale 建立 Gateway WebSocket 隧道。
• 你不需要運行獨立的 WebChat 伺服器。

設定參考 (WebChat)

完整設定請參考：Configuration

WebChat 選項：

• gateway.webchat.chatHistoryMaxChars：chat.history 回應中文字欄位的最大字數。當對話條目超過此限制時，Gateway 會截斷長文字，並可能用佔位符替換過大的訊息。客戶端也可以在單次 chat.history 請求中發送 maxChars 來覆寫此預設值。

相關全域選項：

• gateway.port, gateway.bind: WebSocket 主機與 Port。
• gateway.auth.mode, gateway.auth.token, gateway.auth.password: WebSocket 認證（Token 或密碼）。
• gateway.auth.mode: "trusted-proxy": 針對瀏覽器客戶端的反向代理認證（參考 Trusted Proxy Auth）。
• gateway.remote.url, gateway.remote.token, gateway.remote.password: 遠端 Gateway 目標。
• session.*: Session 儲存與主要 Key 的預設值。

下一步

• 設定指南
• 受信任代理認證

AI Setup Assistant