{/* TRANSLATED — 已翻译为中文 */}

> ## 文档索引
> 在此获取完整文档索引：https://code.claude.com/docs/llms.txt
> 使用此文件发现所有可用页面，然后再进一步探索。

# 语音听写

> 在 Claude Code CLI 中使用按住录音或点击录音的语音听写来说出你的提示。

在 Claude Code CLI 中用语音代替打字说出你的提示。你的语音会实时转录到提示输入中，因此你可以在同一条消息中混合语音和打字。使用 `/voice` 启用听写，然后按住某个键说话或点击一次开始、再次点击发送。

<Note>
  语音听写需要 Claude Code v2.1.69 或更高版本。点击模式需要 v2.1.116 或更高版本。使用 `claude --version` 检查你的版本。
</Note>

## 要求

语音听写将你录制的音频流式传输到 Anthropic 的服务器进行转录。音频不在本地处理。语音转文字服务仅在你使用 Claude.ai 账户认证时可用，在 Claude Code 配置为直接使用 Anthropic API 密钥、Amazon Bedrock、Google Vertex AI 或 Microsoft Foundry 时不可用。转录不消耗 Claude 消息或令牌，不计入 `/usage` 中显示的限制。有关 Anthropic 如何处理你的数据，请参阅[数据使用](/en/data-usage)。

语音听写还需要本地麦克风访问，因此在[Web 上的 Claude Code](/en/claude-code-on-the-web) 或 SSH 会话等远程环境中无法工作。在 WSL 中，语音听写需要 WSLg 进行音频访问。在 Windows 10 或 11 上从 Microsoft Store 安装 WSL2 时，WSLg 已包含在内。如果 WSLg 不可用（例如在 WSL1 上），请在原生 Windows 中运行 Claude Code。

音频录制在 macOS、Linux 和 Windows 上使用内置的原生模块。在 Linux 上，如果原生模块无法加载，Claude Code 会回退到 ALSA 工具中的 `arecord` 或 SoX 中的 `rec`。如果两者都不可用，`/voice` 会为你的包管理器打印安装命令。

Claude Code [VS Code 扩展](/en/vs-code)也支持语音听写，同样需要 Claude.ai 账户。它在 VS Code Remote 会话中不可用，包括 SSH、Dev Container 和 Codespaces，因为麦克风在你的本地机器上而扩展在远程主机上运行。

## 启用语音听写

运行 `/voice` 启用听写。首次启用时，Claude Code 会进行麦克风检查。在 macOS 上，如果从未授予过，这会触发终端的系统麦克风权限提示。

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

`/voice` 接受可选的模式参数：

| 命令          | 效果                                        |
| :------------ | :------------------------------------------ |
| `/voice`      | 开关切换，保持当前模式                      |
| `/voice hold` | 以[按住模式](#按住录音)启用                 |
| `/voice tap`  | 以[点击模式](#点击录音并发送)启用           |
| `/voice off`  | 禁用                                        |

语音听写跨会话持久化。直接在[用户设置文件](/en/settings)中设置，而不是运行 `/voice`：

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

当语音听写启用时，提示为空时输入页脚会显示 `hold Space to speak` 提示。该提示反映你当前的 `voice:pushToTalk` 绑定，如果你[重新绑定听写键](#重新绑定听写键)则会更新。两种模式下的提示文本相同，如果你配置了[自定义状态行](/en/statusline)则不会显示。

两种模式的转录都针对编码词汇进行了调优。常见的开发术语如 `regex`、`OAuth`、`JSON` 和 `localhost` 都能正确识别，你当前的项目名称和 git 分支名称会自动添加为识别提示。

## 按住录音

按住模式是按键说话：按住键时录制运行，松开时停止。这是默认模式。

按住 `Space` 开始录制。Claude Code 通过监视终端的快速按键重复事件来检测按住的键，因此在录制开始前有一个短暂的预热。预热期间页脚显示 `keep holding…`，录制激活后切换为实时波形。

预热期间前几个按键重复字符会输入到输入框中，录制激活时会自动移除。单次 `Space` 点击仍然输入空格，因为按住检测仅在快速重复时触发。

<Tip>
  要跳过预热，使用 `/voice tap` 切换到[点击模式](#点击录音并发送)，或[重新绑定到修饰键组合](#重新绑定听写键)如 `meta+k`。修饰键组合在首次按键时即开始录制。
</Tip>

你的语音在说话时出现在提示中，在转录最终确定前以淡色显示。松开 `Space` 停止录制并最终确定文本。转录插入到你的光标位置，光标保持在插入文本的末尾，因此你可以按任何顺序混合打字和听写。再次按住 `Space` 追加另一段录音，或先移动光标将语音插入提示的其他位置：

```
> refactor the auth middleware to ▮
  # 按住 Space，说"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 插入转录并自动提交提示。较短的转录会被插入但不会提交，因此误触不会发送一个孤立的词。

第一次点击仅在提示输入为空时才开始录制，因此你仍然可以在编写消息时正常输入空格。第二次点击无论输入内容如何都会停止录制。录制也会在 15 秒静音或总共两分钟后自动停止。

## 更改听写语言

语音听写使用与控制 Claude 响应语言相同的 [`language` 设置](/en/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 的文本响应不受此回退影响。

## 重新绑定听写键

听写键绑定在 `Chat` 上下文中的 `voice:pushToTalk`，默认为 `Space`。同一绑定控制按住和点击两种模式。在 [`~/.claude/keybindings.json`](/en/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` 如果你尝试绑定会显示错误。有关完整的按键绑定语法和保留快捷键列表，请参阅[自定义键盘快捷键](/en/keybindings)。

## 故障排除

语音听写未激活或未录制时的常见问题：

* **`Voice mode requires a Claude.ai account`**：你使用 API 密钥或第三方提供商认证。运行 `/login` 使用 Claude.ai 账户登录。
* **`Microphone access is denied`**：在系统设置中授予终端麦克风权限。在 macOS 上，前往 System Settings -> Privacy & Security -> Microphone 并启用你的终端应用，然后再次运行 `/voice`。在 Windows 上，前往 Settings -> Privacy & security -> Microphone 并为桌面应用开启麦克风访问，然后再次运行 `/voice`。如果你的终端未列在 macOS 设置中，请参阅[终端未列在 macOS 麦克风设置中](#终端未列在-macos-麦克风设置中)。
* **Linux 上 `No audio recording tool found`**：原生音频模块无法加载且未安装回退工具。使用错误消息中显示的命令安装 SoX，例如 `sudo apt-get install 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 上，打开 Settings -> System -> Sound -> Input 并选择你的麦克风。在 macOS 上，打开 System Settings -> Sound -> Input。
* **`No speech detected`**：音频到达了转录服务但未识别出任何单词。靠近麦克风说话，减少背景噪音，确认你的[听写语言](#更改听写语言)与你说的语言匹配。
* **转录混乱或语言错误**：听写默认为英语。如果你用其他语言听写，请先在 `/config` 中设置。参见[更改听写语言](#更改听写语言)。

### 终端未列在 macOS 麦克风设置中

如果你的终端应用未出现在 System Settings -> Privacy & Security -> Microphone 下，没有可以启用的切换开关。重置终端的权限状态，使下次 `/voice` 运行触发全新的 macOS 权限提示。

<Steps>
  <Step title="重置终端的麦克风权限">
    运行 `tccutil reset Microphone <bundle-id>`，将 `<bundle-id>` 替换为你的终端标识符：内置 Terminal 使用 `com.apple.Terminal`，iTerm2 使用 `com.googlecode.iterm2`。对于其他终端，使用 `osascript -e 'id of app "AppName"'` 查找标识符。

    <Warning>
      你可以不带 bundle ID 运行 `tccutil reset Microphone`，但这会撤销你 Mac 上每个应用的麦克风访问权限，包括 Zoom 或 Slack 等应用。每个应用在下次使用时都需要重新请求访问权限，因此不要在活跃通话期间运行。
    </Warning>
  </Step>

  <Step title="退出并重新启动终端">
    macOS 不会重新提示已运行的进程。使用 Cmd+Q 退出终端应用，而不仅仅是关闭窗口，然后重新打开。
  </Step>

  <Step title="触发全新提示">
    启动 Claude Code 并运行 `/voice`。macOS 提示麦克风访问权限；允许它。
  </Step>
</Steps>

## 另请参阅

* [自定义键盘快捷键](/en/keybindings)：重新绑定 `voice:pushToTalk` 和其他 CLI 键盘操作
* [配置设置](/en/settings)：`voice`、`language` 和其他设置键的完整参考
* [交互模式](/en/interactive-mode)：键盘快捷键、输入模式和会话控制
* [命令](/en/commands)：`/voice`、`/config` 和所有其他命令的参考