實作 Voice Wake 與 Push-to-Talk 功能

開發語音互動功能最煩人的就是誤觸和延遲。有時候你只是想快速下個指令，卻得在那邊等半天，或是明明手動關掉了介面，背景卻還在偷偷錄音，搞得系統狀態一團亂。

要讓語音體驗變得直覺，關鍵在於處理好「監聽」與「傳送」之間的切換邏輯。我們來看看如何透過 VoiceWakeRuntime 與 VoicePushToTalk 來搞定這些細節。

需要準備的東西

只要 5 分鐘，你就能設定好最基礎的語音路徑：

啟用 Voice Wake：在設定中開啟 Voice Wake，系統會啟動 VoiceWakeRuntime 監聽 swabbleTriggerWords。當偵測到關鍵字且後方有約 0.55s 的停頓時，就會觸發錄音。
設定 Push-to-Talk：開啟「Hold Cmd+Fn to talk」開關。這會啟動全域監控，按住右側 Option 鍵（keyCode 61）即可跳過觸發詞直接說話。
觀察狀態回饋：錄音時 Menu Bar 的 ears 圖示會放大，這代表 triggerVoiceEars(ttl:nil) 正在運作。放開按鍵或說完話後，圖示會恢復正常。
檢查自動傳送：語音結束後，VoiceWakeForwarder 會自動加上機器人提示（machine hint）並將 transcript 送往 WhatsApp 或 Discord 等你上次使用的 Gateway。

如果你在測試過程中遇到問題，通常是以下幾種狀況：

手動關閉 Overlay 後 Voice Wake 沒反應：這在舊版本是個 Bug。現在手動點擊 X 關閉介面後，VoiceSessionCoordinator 會強制執行 VoiceWakeRuntime.refresh(...)，確保監聽程式會重新啟動。
外接鍵盤無法觸發 Push-to-Talk：有些外接鍵盤不會送出標準的右側 Option 事件（keyCode 61）。如果遇到這種情況，請在設定中改用備用快捷鍵。
錄音突然中斷：請檢查是否觸發了 120s 的硬性時間限制，或是說話過程中的停頓超過了 2s（若只有觸發詞而沒說內容，停頓限制則是 5s）。
麥克風抓不到聲音：如果原本的麥克風斷線，系統會顯示斷線提示並暫時切換到系統預設裝置，直到你原本選用的裝置重新連上為止。

有任何設定上的疑問嗎？直接問問 AI Setup Assistant 吧。

OpenClaw Expert

如果這篇文件沒有解決你的情境，直接問 OpenClaw Expert，拿到可執行步驟。