> ## Documentation Index
> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 語音聽寫

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

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

<Note>
  語音聽寫需要 Claude Code v2.1.69 或更高版本。點擊模式需要 v2.1.116 或更高版本。使用 `claude --version` 檢查您的版本。
</Note>

聽寫也適用於[代理檢視](/zh-TW/agent-view#peek-and-reply)。在調度輸入或窺視面板回覆聚焦時，按住或點擊您的推送通話鍵以聽寫到背景工作階段。

<h2 id="requirements">
  要求
</h2>

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

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

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

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

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

<h2 id="enable-voice-dictation">
  啟用語音聽寫
</h2>

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

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

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

| 命令            | 效果                                  |
| :------------ | :---------------------------------- |
| `/voice`      | 切換開啟或關閉，保持目前模式                      |
| `/voice hold` | 在[按住模式](#hold-to-record)中啟用         |
| `/voice tap`  | 在[點擊模式](#tap-to-record-and-send)中啟用 |
| `/voice off`  | 停用                                  |

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

```json theme={null}
{
  "voice": {
    "enabled": true,
    "mode": "tap"
  }
}
```

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

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

<h2 id="hold-to-record">
  按住錄音
</h2>

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

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

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

<Tip>
  若要跳過預熱，使用 `/voice tap` 切換到[點擊模式](#tap-to-record-and-send)，或[重新繫結到修飾符組合](#rebind-the-dictation-key)，例如 `meta+k`。修飾符組合在第一次按鍵時開始錄製。
</Tip>

您的語音在您說話時出現在提示中，在轉錄最終確定之前會變暗。鬆開 `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` 以在您鬆開鍵時自動發送提示，只要轉錄至少有三個單詞。

<h2 id="tap-to-record-and-send">
  點擊錄音並發送
</h2>

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

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

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

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

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

<h2 id="change-the-dictation-language">
  變更聽寫語言
</h2>

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

<Accordion title="支援的聽寫語言">
  | 語言   | 代碼   |
  | :--- | :--- |
  | 捷克文  | `cs` |
  | 丹麥文  | `da` |
  | 荷蘭文  | `nl` |
  | 英文   | `en` |
  | 法文   | `fr` |
  | 德文   | `de` |
  | 希臘文  | `el` |
  | 印地文  | `hi` |
  | 印尼文  | `id` |
  | 義大利文 | `it` |
  | 日文   | `ja` |
  | 韓文   | `ko` |
  | 挪威文  | `no` |
  | 波蘭文  | `pl` |
  | 葡萄牙文 | `pt` |
  | 俄文   | `ru` |
  | 西班牙文 | `es` |
  | 瑞典文  | `sv` |
  | 土耳其文 | `tr` |
  | 烏克蘭文 | `uk` |
</Accordion>

在 `/config` 中或直接在設定中設定語言。您可以使用 [BCP 47 語言代碼](https://en.wikipedia.org/wiki/IETF_language_tag)或語言名稱：

```json theme={null}
{
  "language": "japanese"
}
```

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

<h2 id="rebind-the-dictation-key">
  重新繫結聽寫鍵
</h2>

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

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

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

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

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

<h2 id="troubleshooting">
  疑難排解
</h2>

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

* **`Voice mode requires a Claude.ai account`**：您使用 API 金鑰或第三方提供者進行了身份驗證。執行 `/login` 以使用 Claude.ai 帳戶登入。
* **`Voice mode is disabled by your organization's policy`**：您的組織的合規性配置停用了語音聽寫，如[需求](#requirements)中所述。請聯絡您的組織管理員以確認您的組織是否可使用語音聽寫。
* **`Microphone access is denied`**：在系統設定中授予您的終端機麥克風權限。在 macOS 上，前往系統設定 → 隱私與安全 → 麥克風並啟用您的終端機應用程式，然後再次執行 `/voice`。在 Windows 上，前往設定 → 隱私與安全 → 麥克風並開啟桌面應用程式的麥克風存取，然後再次執行 `/voice`。如果您的終端機未列在 macOS 設定中，請參閱[終端機未列在 macOS 麥克風設定中](#terminal-not-listed-in-macos-microphone-settings)。
* **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。{/* min-version: 2.1.195 */}自 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 或被拒絕的麥克風權限。確認工作輸入裝置，修復上述項目中的根本原因，然後再次觸發語音。
* **在按住模式中按住 `Space` 時沒有任何反應**：在按住時監視提示輸入。如果空格不斷累積，語音聽寫可能已關閉；執行 `/voice hold` 啟用它。如果只出現一個或兩個空格然後沒有任何反應，語音聽寫已開啟但按住偵測未觸發。按住偵測需要您的終端機發送按鍵重複事件，因此如果在作業系統層級停用了按鍵重複，它無法偵測按住的鍵。使用 `/voice tap` 切換到點擊模式以避免按鍵重複要求。
* **在點擊模式中點擊 `Space` 輸入空格而不是錄製**：第一次點擊只在提示輸入為空時開始錄製。先清除輸入，或通過執行 `/voice tap` 檢查您是否處於點擊模式。
* **`No audio detected from microphone`**：錄製已開始但捕獲了無聲。確認正確的輸入裝置設定為系統預設值，其輸入級別未靜音或接近零。在 Windows 上，開啟設定 → 系統 → 聲音 → 輸入並選擇您的麥克風。在 macOS 上，開啟系統設定 → 聲音 → 輸入。
* **`No speech detected`**：音頻到達轉錄服務但未識別任何單詞。靠近麥克風說話，減少背景噪音，並確認您的[聽寫語言](#change-the-dictation-language)與您說話的語言相符。
* **轉錄是亂碼或使用了錯誤的語言**：聽寫預設為英文。如果您用另一種語言聽寫，請先在 `/config` 中設定它。請參閱[變更聽寫語言](#change-the-dictation-language)。

<h3 id="terminal-not-listed-in-macos-microphone-settings">
  終端機未列在 macOS 麥克風設定中
</h3>

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

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

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

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

  <Step title="觸發新的提示">
    啟動 Claude Code 並執行 `/voice`。macOS 會提示麥克風存取；允許它。
  </Step>
</Steps>

<h2 id="see-also">
  另請參閱
</h2>

* [自訂鍵盤快捷鍵](/zh-TW/keybindings)：重新繫結 `voice:pushToTalk` 和其他 CLI 鍵盤動作
* [設定設定](/zh-TW/settings)：`voice`、`language` 和其他設定鍵的完整參考
* [互動模式](/zh-TW/interactive-mode)：鍵盤快捷鍵、輸入模式和工作階段控制
* [命令](/zh-TW/commands)：`/voice`、`/config` 和所有其他命令的參考