Claude Code官方文档语音输入Voice

Claude Code 语音输入（Voice Dictation）- CLI 中按键录音转文本

在 Claude Code CLI 中使用按住录音或点击录音的语音听写功能来说出你的提示词，转录后插入到输入框中。

· 阅读约 12 分钟

语音听写

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

在 Claude Code CLI 中说出你的提示词，而不是输入它们。你的语音会实时转录到提示词输入中，所以你可以在同一条消息中混合使用语音和输入。使用 /voice 启用听写，然后要么在说话时按住一个键，要么点击一次开始，再点击一次发送。

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

要求

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

语音听写还需要本地麦克风访问权限，因此在远程环境中不起作用，例如网络上的 Claude Code 或 SSH 会话。在 WSL 中，语音听写需要 WSLg 来访问音频，这包含在 Windows 11 上的 WSL2 中。在 Windows 10 或 WSL1 上，改为在本机 Windows 中运行 Claude Code。

音频录制在 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 hold在按住模式中启用
/voice tap在点击模式中启用
/voice off禁用

语音听写在会话之间持续。直接在你的用户设置文件中设置它，而不是运行 /voice：

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

启用语音听写时，当提示词为空时，输入页脚会显示 hold Space to speak 提示。提示文本在两种模式中都相同，如果你配置了自定义状态行，则不会显示。

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

按住录音

按住模式是按键通话：当你按住键时录制运行，释放时停止。这是默认模式。

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

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

💡 要跳过预热，使用 /voice tap 切换到点击模式，或重新绑定到修饰符组合，如 meta+k。修饰符组合在第一次按键时开始录制。

你的语音在你说话时出现在提示词中，在转录最终确定之前会变暗。释放 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 插入转录并在转录至少有三个单词时自动提交提示词。较短的转录被插入但不提交，所以意外点击不会发送一个杂散的单词。

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

更改听写语言

语音听写使用与控制 Claude 响应语言相同的language 设置。如果该设置为空，听写默认为英语。在 VS Code 扩展中，如果 language 为空，听写在默认为英语之前使用 VS Code 的 accessibility.voice.speechLanguage 设置。

支持的听写语言：

语言代码
捷克语cs
丹麦语da
荷兰语nl
英语en
法语fr
德语de
希腊语el
印地语hi
印度尼西亚语id
意大利语it
日语ja
韩语ko
挪威语no
波兰语pl
葡萄牙语pt
俄语ru
西班牙语es
瑞典语sv
土耳其语tr
乌克兰语uk

在 /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
      }
    }
  ]
}

设置 "space": null 移除默认绑定。如果你想要两个键都活跃，则省略它。

在按住模式中，避免绑定裸字母键如 v，因为按住检测依赖于按键重复，字母在预热期间输入到提示词中。使用 Space，或使用修饰符组合如 meta+k 在第一次按键时开始录制，无需预热。点击模式没有预热，所以大多数键都可以。

某些键不会传递到终端应用程序，根本无法绑定。例如，如果你尝试绑定 Caps Lock，会显示错误。有关完整的快捷键语法和保留快捷键列表，请参阅自定义键盘快捷键。

故障排除

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

  • Voice mode requires a Claude.ai account：你使用 API 密钥或第三方提供商进行了身份验证。运行 /login 以使用 Claude.ai 账户登录。
  • Microphone access is denied：在系统设置中授予你的终端麦克风权限。在 macOS 上，转到系统设置 → 隐私和安全 → 麦克风并启用你的终端应用，然后再次运行 /voice。在 Windows 上，转到设置 → 隐私和安全 → 麦克风并为桌面应用打开麦克风访问，然后再次运行 /voice。如果你的终端未在 macOS 设置中列出，请参阅下面的”终端未在 macOS 麦克风设置中列出”。
  • Linux 上的 No audio recording tool found：本机音频模块无法加载，没有安装回退。使用错误消息中显示的命令安装 SoX，例如 sudo apt-get install sox。
  • 在按住模式中按住 Space 时没有任何反应：在按住时观察提示词输入。如果空格不断累积，语音听写可能已关闭；运行 /voice hold 启用它。如果只出现一两个空格然后没有任何反应，语音听写已打开但按住检测未触发。按住检测需要你的终端发送按键重复事件，所以如果在操作系统级别禁用了按键重复，它无法检测按住的键。使用 /voice tap 切换到点击模式以避免按键重复要求。
  • 在点击模式中点击 Space 输入空格而不是录制：第一次点击仅在提示词输入为空时开始录制。先清除输入，或通过运行 /voice tap 检查你是否处于点击模式。
  • No audio detected from microphone：录制开始但捕获了静音。确认正确的输入设备设置为系统默认值，其输入级别未静音或接近零。在 Windows 上，打开设置 → 系统 → 声音 → 输入并选择你的麦克风。在 macOS 上，打开系统设置 → 声音 → 输入。
  • 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 而不带 bundle ID，但这会撤销 Mac 上每个应用的麦克风访问权限，包括 Zoom 或 Slack 等应用。每个应用在下次使用时都需要重新请求访问权限，所以不要在活跃通话期间运行它。

2. 退出并重新启动你的终端

macOS 不会重新提示已在运行的进程。使用 Cmd+Q 退出终端应用，而不仅仅是关闭其窗口，然后再次打开它。

3. 触发新的提示

启动 Claude Code 并运行 /voice。macOS 提示输入麦克风访问权限；允许它。

另请参阅

本文翻译自 Anthropic Claude Code 官方文档，最近一次同步：2025-05-01。