語音聽寫

在 Claude Code CLI 中使用按住錄音或點擊錄音的語音聽寫功能來說出您的提示。

在 Claude Code CLI 中說出您的提示，而不是輸入它們。您的語音會即時轉錄到提示輸入中，因此您可以在同一條訊息中混合語音和輸入。使用 /voice 啟用聽寫，然後在說話時按住一個鍵或點擊一次開始，再點擊一次發送。

聽寫也適用於代理檢視。在調度輸入或窺視面板回覆聚焦時，按住或點擊您的推送通話鍵以聽寫到背景工作階段。

要求

語音聽寫會將您錄製的音頻串流傳輸到 Anthropic 的伺服器進行轉錄。音頻不在本地處理。它需要以下所有條件：

• Claude.ai 帳戶：語音轉文字服務僅在您使用 Claude.ai 帳戶進行身份驗證時可用，當 Claude Code 配置為直接使用 Anthropic API 金鑰、Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 時不可用。
• 未啟用 HIPAA 合規性的組織：當此限制適用時，/voice 會顯示 Voice mode is disabled by your organization's policy。
• 本地麥克風：語音聽寫在遠端環境中不起作用，例如網頁上的 Claude Code或 SSH 工作階段。
• 如果您在 WSL 中執行 Claude Code，則需要 WSLg：WSLg 在從 Microsoft Store 在 Windows 10 或 11 上安裝 WSL2 時包含。如果 WSLg 不可用，例如在 WSL1 上，改為在原生 Windows 中執行 Claude Code。

轉錄不會消耗 Claude 訊息或代幣，也不會計入 /usage 中顯示的限制。請參閱資料使用了解 Anthropic 如何處理您的資料。

音頻錄製在 macOS、Linux 和 Windows 上使用內建的原生模組。在 Linux 上，如果原生模組無法載入，Claude Code 會回退到 ALSA utils 中的 arecord 或 SoX 中的 rec。如果兩者都不可用，/voice 會列印您的套件管理員的安裝命令。

Claude Code VS Code 擴充功能也支援語音聽寫，具有相同的 Claude.ai 帳戶要求。它在 VS Code Remote 工作階段中不可用，包括 SSH、Dev Containers 和 Codespaces，因為麥克風在您的本地機器上，而擴充功能在遠端主機上執行。

啟用語音聽寫

執行 /voice 以啟用聽寫。第一次啟用時，Claude Code 會執行麥克風檢查。在 macOS 上，如果您的終端機從未被授予權限，這會觸發系統麥克風權限提示。

/voice
Voice mode enabled (hold). Hold space to record. Dictation language: en (/config to change).

/voice 接受一個可選的模式引數：

語音聽寫在工作階段之間保持。直接在您的使用者設定檔案中設定它，而不是執行 /voice：

{
  "voice": {
    "enabled": true,
    "mode": "tap"
  }
}

啟用語音聽寫時，當提示為空時，輸入頁尾會顯示 hold space to speak 提示。提示文字反映您目前的 voice:pushToTalk 快捷鍵繫結，如果您重新繫結聽寫鍵，則會更新。提示文字在兩種模式中都相同，如果您配置了自訂狀態行，則不會出現。

轉錄在兩種模式中都針對編碼詞彙進行了調整。常見的開發術語如 regex、OAuth、JSON 和 localhost 都能正確識別，您目前的專案名稱和 git 分支名稱會自動新增為識別提示。

按住錄音

按住模式是推送通話：錄製在您按住鍵時執行，在您鬆開時停止。這是預設模式。

按住 Space 開始錄製。Claude Code 通過監視來自您終端機的快速按鍵重複事件來偵測按住的鍵，因此在錄製開始前有一個簡短的預熱期。頁尾在預熱期間顯示 keep holding…，然後在錄製啟動後切換到即時波形。

前幾個按鍵重複字元在預熱期間輸入到輸入中，並在錄製啟動時自動移除。單個 Space 點擊仍會輸入一個空格，因為按住偵測只在快速重複時觸發。

您的語音在您說話時出現在提示中，在轉錄最終確定之前會變暗。鬆開 Space 停止錄製並最終確定文字。轉錄會插入到您的游標位置，游標保持在插入文字的末尾，因此您可以按任何順序混合輸入和聽寫。再次按住 Space 以附加另一個錄製，或先移動游標以在提示中的其他位置插入語音：

> refactor the auth middleware to ▮
  # hold Space, speak "use the new token validation helper"
> refactor the auth middleware to use the new token validation helper▮

預設情況下，鬆開鍵會插入轉錄並等待您按 Enter。在 voice 設定物件中設定 "autoSubmit": true 以在您鬆開鍵時自動發送提示，只要轉錄至少有三個單詞。

點擊錄音並發送

點擊模式使用單個按鍵切換錄製：點擊一次開始，說話，然後再點擊一次發送提示。沒有預熱，您不需要保持鍵被按住。

使用 /voice tap 啟用點擊模式。當提示輸入為空時，點擊 Space 開始錄製。頁尾在錄製時顯示即時波形。再次點擊 Space 停止。

Claude Code 插入轉錄，當轉錄至少有三個單詞時自動提交提示。較短的轉錄會被插入但不會被提交，因此意外點擊不會發送一個隨意的單詞。

三個單詞的閾值計算不使用空格書寫的語言中的單詞。自 v2.1.195 起，日文、中文和泰文轉錄計算個別單詞，因此它們在點擊模式和使用 autoSubmit 的保持模式中自動提交。較早的版本將沒有空格的轉錄計為一個單詞，並且從不自動提交。

第一次點擊只在提示輸入為空時開始錄製，因此您在撰寫訊息時仍然可以正常輸入空格。第二次點擊無論輸入內容如何都會停止錄製。錄製也會在 15 秒無聲或 2 分鐘總時間後自動停止。

變更聽寫語言

語音聽寫使用與控制 Claude 回應語言相同的language 設定。如果該設定為空，聽寫預設為英文。在 VS Code 擴充功能中，如果 language 為空，聽寫會在預設為英文之前使用 VS Code 的 accessibility.voice.speechLanguage 設定。

在 /config 中或直接在設定中設定語言。您可以使用 BCP 47 語言代碼或語言名稱：

{
  "language": "japanese"
}

如果您的 language 設定不在支援的清單中，/voice 會在啟用時警告您，並為聽寫回退到英文。Claude 的文字回應不受此回退的影響。

重新繫結聽寫鍵

聽寫鍵在 Chat 上下文中繫結到 voice:pushToTalk，預設為 Space。相同的繫結控制按住和點擊模式。在 ~/.claude/keybindings.json 中重新繫結它：

{
  "bindings": [
    {
      "context": "Chat",
      "bindings": {
        "meta+k": "voice:pushToTalk",
        "space": null
      }
    }
  ]
}

voice:pushToTalk 動作一次使用一個鍵。當您繫結自訂鍵時，它會取代預設的 Space 繫結，而不是新增第二個觸發器，因此此範例中的 "space": null 行是為了清晰起見，可以省略而不改變行為。

在按住模式中，避免繫結裸字母鍵，例如 v，因為按住偵測依賴於按鍵重複，字母在預熱期間輸入到提示中。使用 Space，或使用修飾符組合，例如 meta+k 以在第一次按鍵時開始錄製，無需預熱。點擊模式沒有預熱，因此大多數鍵都可以。

某些鍵不會傳遞到終端應用程式，根本無法繫結。例如，如果您嘗試繫結 Caps Lock，它會顯示錯誤。請參閱自訂鍵盤快捷鍵了解完整的快捷鍵語法和保留快捷鍵的清單。

疑難排解

語音聽寫未啟動或錄製時的常見問題：

• Voice mode requires a Claude.ai account：您使用 API 金鑰或第三方提供者進行了身份驗證。執行 /login 以使用 Claude.ai 帳戶登入。
• Voice mode is disabled by your organization's policy：您的組織的合規性配置停用了語音聽寫，如需求中所述。請聯絡您的組織管理員以確認您的組織是否可使用語音聽寫。
• Microphone access is denied：在系統設定中授予您的終端機麥克風權限。在 macOS 上，前往系統設定 → 隱私與安全 → 麥克風並啟用您的終端機應用程式，然後再次執行 /voice。在 Windows 上，前往設定 → 隱私與安全 → 麥克風並開啟桌面應用程式的麥克風存取，然後再次執行 /voice。如果您的終端機未列在 macOS 設定中，請參閱終端機未列在 macOS 麥克風設定中。
• Linux 上的 No audio recording tool found：原生音頻模組無法載入，且未安裝回退。使用錯誤訊息中顯示的命令安裝 SoX，例如 sudo apt-get install sox。
• Voice mode requires a microphone, but SoX could not open an audio capture device：SoX 已安裝，但主機沒有音頻擷取裝置，例如無頭伺服器或容器。在具有麥克風的機器上執行 Claude Code。自 v2.1.195 起，Linux 上的 Claude Code 在該情況下報告此訊息；較早的版本即使已安裝 SoX 也會要求您安裝它。
• Voice mode could not find a working audio recorder in WSL：WSLg 透過 PulseAudio 而非 ALSA 裝置路由音頻，因此 SoX 需要明確安裝其 PulseAudio 後端。執行 sudo apt install sox libsox-fmt-pulse。單獨安裝 sox 會拉入 ALSA 後端，這在 WSL 上無法錄製，因為沒有 /dev/snd 裝置。
• Voice input is failing repeatedly and has been paused：語音聽寫連續遇到多個啟動失敗，並停止嘗試新的工作階段，直到一個成功。失敗計數無論麥克風無法啟動或錄音機啟動後停止而未產生任何音頻。這通常表示此主機上的麥克風或音頻堆疊無法捕獲音頻，例如無頭伺服器、沒有音頻傳遞的遠端 shell 或被拒絕的麥克風權限。確認工作輸入裝置，修復上述項目中的根本原因，然後再次觸發語音。在 v2.1.202 之前，只有啟動失敗計入暫停。
• 在按住模式中按住 Space 時沒有任何反應：在按住時監視提示輸入。如果空格不斷累積，語音聽寫可能已關閉；執行 /voice hold 啟用它。如果只出現一個或兩個空格然後沒有任何反應，語音聽寫已開啟但按住偵測未觸發。按住偵測需要您的終端機發送按鍵重複事件，因此如果在作業系統層級停用了按鍵重複，它無法偵測按住的鍵。使用 /voice tap 切換到點擊模式以避免按鍵重複要求。
• 在點擊模式中點擊 Space 輸入空格而不是錄製：第一次點擊只在提示輸入為空時開始錄製。先清除輸入，或通過執行 /voice tap 檢查您是否處於點擊模式。
• No audio detected from microphone：錄製已開始但捕獲了無聲。確認正確的輸入裝置設定為系統預設值，其輸入級別未靜音或接近零。在 Windows 上，開啟設定 → 系統 → 聲音 → 輸入並選擇您的麥克風。在 macOS 上，開啟系統設定 → 聲音 → 輸入。
• Voice connection failed：您的錄製因為連線失敗而從未到達轉錄服務。檢查您的網路並重試。捕獲無音頻的錄製會報告 No audio detected from microphone 而不是此訊息。在 v2.1.200 之前，無聲麥克風可能會報告連線失敗，這暗示網路問題，而實際問題是輸入裝置。
• No speech detected：音頻到達轉錄服務但未識別任何單詞。靠近麥克風說話，減少背景噪音，並確認您的聽寫語言與您說話的語言相符。
• 轉錄是亂碼或使用了錯誤的語言：聽寫預設為英文。如果您用另一種語言聽寫，請先在 /config 中設定它。請參閱變更聽寫語言。

終端機未列在 macOS 麥克風設定中

如果您的終端機應用程式未出現在系統設定 → 隱私與安全 → 麥克風下，則沒有您可以啟用的切換。重設您的終端機的權限狀態，以便下一次 /voice 執行觸發新的 macOS 權限提示。

1. 重設您的終端機的麥克風權限

   執行 tccutil reset Microphone <bundle-id>，將 <bundle-id> 替換為您的終端機的識別碼：內建終端機為 com.apple.Terminal，或 iTerm2 為 com.googlecode.iterm2。對於其他終端機，使用 osascript -e 'id of app "AppName"' 查詢識別碼。

   注意

   您可以執行 tccutil reset Microphone 而不需要套件 ID，但它會撤銷 Mac 上每個應用程式的麥克風存取權限，包括 Zoom 或 Slack 等應用程式。每個應用程式在下次使用時都需要重新請求存取權限，因此不要在活躍通話期間執行它。

2. 退出並重新啟動您的終端機

   macOS 不會重新提示已在執行的程序。使用 Cmd+Q 退出終端機應用程式，而不只是關閉其視窗，然後再次開啟它。

3. 觸發新的提示

   啟動 Claude Code 並執行 /voice。macOS 會提示麥克風存取；允許它。

另請參閱

• 自訂鍵盤快捷鍵：重新繫結 voice:pushToTalk 和其他 CLI 鍵盤動作
• 設定設定：voice、language 和其他設定鍵的完整參考
• 互動模式：鍵盤快捷鍵、輸入模式和工作階段控制
• 命令：/voice、/config 和所有其他命令的參考