掌握 Menu Bar 狀態邏輯：讓你的 Agent 動態一目瞭然
你是不是也遇過這種情況：開發了一個在背景執行的工具，但每次都要切換回終端機或主視窗，才知道它到底是在跑腳本、讀檔案，還是單純卡住了？這種資訊不透明的感覺真的很煩，開發者需要的是一種不用打斷工作流，就能秒懂工具狀態的方式。
這份文件會帶你了解我們如何透過 Menu Bar 的圖示與狀態列，精準呈現 Agent 的工作狀態。
需要準備的東西
Section titled “需要準備的東西”- 基礎的 Swift 開發環境
- 可接收
ControlChannel.handleAgentEvent的權限 - 串接
node.list的裝置權限
要在 Menu Bar 實作狀態顯示，你需要理解核心的 Session 邏輯與視覺對應關係。
1. 搞定 Session 優先級
Section titled “1. 搞定 Session 優先級”Agent 同時處理多個任務時，狀態列會根據以下規則決定顯示內容：
- Main Session 優先：只要
mainsession 在忙，圖示就會立即顯示它的狀態。 - 最近活動原則：如果
main閒置，則顯示最近一個有動作的 non-main session。 - 穩定性：我們不會在任務執行中途隨意切換顯示對象，只有當目前 session 進入閒置，或
main開始活動時才會切換。
2. Activity 與圖示對應
Section titled “2. Activity 與圖示對應”根據不同的 ActivityKind，圖示會切換對應的 glyph：
exec→ 💻read→ 📄write→ ✍️edit→ 📝attach→ 📎- 其他預設 → 🛠️
3. 視覺狀態實作
Section titled “3. 視覺狀態實作”在 Swift 中，我們使用 IconState enum 來管理四種主要狀態：
| 狀態 | 視覺表現 |
|---|---|
idle | 正常的生物圖示 (Normal critter) |
workingMain | 帶有 glyph 的標籤、全色調、腳部「工作中」動畫 |
workingOther | 帶有 glyph 的標籤、暗淡色調、無動畫 |
overridden | 強制使用選定的 glyph 與色調（除錯用） |
4. 處理事件輸入
Section titled “4. 處理事件輸入”所有狀態都來自 agent 事件。你需要解析 stream 欄位：
stream: "job"：檢查data.state（started, streaming, done, error）。stream: "tool"：檢查data.phase（start, result），並提取toolName與參數。
圖示頻繁閃爍
Section titled “圖示頻繁閃爍”如果工具執行速度極快，圖示可能會因為狀態切換太快而閃爍。 解決方案：在處理 tool results 時加入 TTL（存活時間）緩衝機制，避免狀態在短時間內反覆切換。
找不到 Health Status
Section titled “找不到 Health Status”當 Agent 正在工作時，Health status 會自動隱藏。 解決方案：這是正常邏輯。只有當所有 session 都進入閒置（idle）狀態時，健康摘要才會重新出現在狀態列中。
Debug 模式不生效
Section titled “Debug 模式不生效”如果你手動設定了圖示覆蓋，但圖示沒有變化。
解決方案：檢查 @AppStorage("iconOverride") 的儲存值，確認是否已映射到 IconState.overridden。
在發布前，請確保通過以下測試：
- 觸發 main session 任務：確認圖示立即切換，且狀態列顯示 main 標籤。
- 在 main 閒置時觸發其他 session：確認顯示 non-main 狀態且保持穩定直到結束。
- 其他 session 執行時啟動 main：圖示必須立即切換到 main。
- 快速工具呼叫：確保圖示不會閃爍。
- 閒置驗證：確認所有任務結束後，健康狀態列會重新出現。
想要更快速地完成設定嗎？可以直接詢問 AI Setup Assistant。
OpenClaw Expert
還是卡住了？
如果這篇文件沒有解決你的情境，直接問 OpenClaw Expert，拿到可執行步驟。