---
read_when:
    - 處理語音喚醒或 PTT 路徑
summary: Mac 應用程式中的語音喚醒與按鍵通話模式，以及路由詳細資訊
title: 語音喚醒 (macOS)
x-i18n:
    generated_at: "2026-04-30T03:21:15Z"
    model: gpt-5.5
    provider: openai
    source_hash: 0273c24764f0baf440a19f31435d6ee62ab040c1ec5a97d7733d3ec8b81b0641
    source_path: platforms/mac/voicewake.md
    workflow: 16
---

# 語音喚醒與按住說話

## 模式

- **喚醒詞模式**（預設）：永遠開啟的語音辨識器會等待觸發詞（`swabbleTriggerWords`）。符合時會開始擷取、顯示帶有部分文字的覆蓋層，並在靜音後自動送出。
- **按住說話（按住右 Option）**：按住右 Option 鍵即可立即擷取，不需要觸發詞。按住時會顯示覆蓋層；放開後會完成並在短暫延遲後轉送，讓你可以微調文字。

## 執行階段行為（喚醒詞）

- 語音辨識器位於 `VoiceWakeRuntime`。
- 只有當喚醒詞和下一個字之間有**有意義的停頓**（約 0.55 秒間隔）時才會觸發。覆蓋層/提示音可以在命令開始前的停頓時就啟動。
- 靜音視窗：語音持續時為 2.0 秒；如果只聽到觸發詞則為 5.0 秒。
- 強制停止：120 秒，避免工作階段失控。
- 工作階段之間的防抖：350 毫秒。
- 覆蓋層透過 `VoiceWakeOverlayController` 驅動，並使用已提交/暫存的著色。
- 送出後，辨識器會乾淨地重新啟動，以聆聽下一個觸發詞。

## 生命週期不變條件

- 如果語音喚醒已啟用且權限已授予，喚醒詞辨識器應保持聆聽中（明確的按住說話擷取期間除外）。
- 覆蓋層可見性（包括透過 X 按鈕手動關閉）絕不能阻止辨識器恢復。

## 黏住的覆蓋層失敗模式（先前）

先前，如果覆蓋層卡住並保持可見，而你手動關閉它，語音喚醒可能看起來像是「失效」，因為執行階段的重新啟動嘗試可能會被覆蓋層可見性阻擋，且後續沒有排程重新啟動。

強化：

- 喚醒執行階段重新啟動不再被覆蓋層可見性阻擋。
- 覆蓋層關閉完成會透過 `VoiceSessionCoordinator` 觸發 `VoiceWakeRuntime.refresh(...)`，因此手動按 X 關閉一律會恢復聆聽。

## 按住說話細節

- 快捷鍵偵測使用全域 `.flagsChanged` 監視器來偵測**右 Option**（`keyCode 61` + `.option`）。我們只觀察事件（不攔截）。
- 擷取管線位於 `VoicePushToTalk`：立即啟動語音辨識、將部分結果串流到覆蓋層，並在放開時呼叫 `VoiceWakeForwarder`。
- 按住說話開始時，我們會暫停喚醒詞執行階段，以避免音訊 tap 互相競爭；放開後會自動重新啟動。
- 權限：需要麥克風與語音辨識；看到事件需要輔助使用/輸入監控核准。
- 外接鍵盤：有些鍵盤可能不會如預期公開右 Option；如果使用者回報漏偵測，請提供備用快捷鍵。

## 使用者可見設定

- **語音喚醒**切換：啟用喚醒詞執行階段。
- **按住 Cmd+Fn 說話**：啟用按住說話監視器。在 macOS < 26 上停用。
- 語言與麥克風選擇器、即時音量計、觸發詞表格、測試器（僅限本機；不轉送）。
- 如果裝置中斷連線，麥克風選擇器會保留上次選取項目、顯示中斷連線提示，並暫時退回系統預設值，直到裝置返回。
- **音效**：偵測到觸發詞和送出時播放提示音；預設為 macOS「Glass」系統音效。你可以為每個事件選擇任何可由 `NSSound` 載入的檔案（例如 MP3/WAV/AIFF），或選擇**無音效**。

## 轉送行為

- 啟用語音喚醒時，轉錄文字會轉送到作用中的 Gateway/agent（與 Mac 應用程式其餘部分使用的本機與遠端模式相同）。
- 回覆會傳送到**上次使用的主要提供者**（WhatsApp/Telegram/Discord/WebChat）。如果傳送失敗，錯誤會被記錄，且該次執行仍可透過 WebChat/工作階段記錄檢視。

## 轉送酬載

- `VoiceWakeForwarder.prefixedTranscript(_:)` 會在送出前加上機器提示。喚醒詞與按住說話路徑共用此邏輯。

## 快速驗證

- 開啟按住說話切換，按住 Cmd+Fn，說話，放開：覆蓋層應顯示部分結果，然後送出。
- 按住期間，選單列耳朵應保持放大（使用 `triggerVoiceEars(ttl:nil)`）；放開後會恢復。

## 相關

- [語音喚醒](/zh-TW/nodes/voicewake)
- [語音覆蓋層](/zh-TW/platforms/mac/voice-overlay)
- [macOS 應用程式](/zh-TW/platforms/macos)
