Claude Code 语音输入可把你说的话实时转成提示词，适合按住说话或轻点发送两种用法；前提是 v2.1.69+、Claude.ai 账号和本地麦克风可用。若没有反应，先看是否启用 /voice、权限是否拒绝、WSL 是否有 WSLg，必要时用 /voice tap、/voice hold 或重绑 voice:pushToTalk 验证。

Claude Code 语音输入怎么配置与排查 #

语音听写需要 Claude Code v2.1.69 或更高版本。Tap 模式需要 v2.1.116 或更高版本。用 claude --version 检查。

在 Claude Code CLI 里直接说提示词，不用全打字。你的语音会实时转成输入框里的文本，可以和键盘输入混着用。先用 /voice 开启，再选择按住说话的 hold 模式，或者轻点开始、再轻点发送的 tap 模式。

使用前提 #

Voice dictation 会把录制的音频流式传到 Anthropic 服务器做转写，不会在本地处理。语音转文字服务只在你使用 Claude.ai 账号认证时可用；如果 Claude Code 配置的是 Anthropic API key、Amazon Bedrock、Google Vertex AI 或 Microsoft Foundry，就不能用。

转写不会消耗 Claude 消息或 tokens，也不计入 /usage 里显示的限制。数据处理方式见 data usage。

语音听写还需要本地麦克风访问权限，所以在这些环境里不能用：

• 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 utils 的 arecord，或者 SoX 的 rec。如果这两者都没有，/voice 会打印适合你包管理器的安装命令。

Claude Code 的 VS Code extension 也支持语音输入，要求同样是 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 支持可选模式参数：

语音输入会跨会话保存。你也可以直接在 user settings file 里配置，而不是每次运行 /voice：

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

启用后，如果提示词输入框是空的，底部会显示 hold Space to speak 提示。这个提示会跟随你当前的 voice:pushToTalk 绑定变化；如果你重新绑定了听写按键，它也会更新。两个模式下提示文案相同。若你配置了 custom status line，这个提示不会出现。

两种模式的转写都针对编程词汇做了优化。regex、OAuth、JSON、localhost 这类开发术语能正确识别，当前项目名和 git 分支名也会自动作为识别提示。

Hold to record #

Hold 模式就是 push-to-talk：按住键时录音，松开就停。这是默认模式。

按住 Space 开始录音。Claude Code 通过观察终端发出的快速按键重复事件来判断是否“按住”，所以录音开始前会有一个短暂预热。底部会先显示 keep holding…，等录音真正开始后切换成实时波形。

预热期间，前一两个重复字符可能会先输入到提示词里；一旦录音激活，这些字符会自动删掉。单独按一下 Space 仍然只是输入一个空格，因为按住检测只会在快速重复时触发。

如果你想跳过预热，可以用 /voice tap 切到 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，并且转写内容至少有三个词，松开按键时会自动发送提示词。

Tap to record and send #

Tap 模式是单次按键切换：按一下开始录音，说完后再按一下发送。没有预热，也不需要一直按住。

用 /voice tap 启用 tap 模式。提示词输入框为空时，按 Space 开始录音，底部会显示实时波形。再按一次 Space 停止。Claude Code 会在转写内容至少有三个词时自动插入并提交提示词；如果少于三个词，只会插入，不会发送，这样误触不会把一个零散词发送出去。

第一次按键只有在输入框为空时才会开始录音，所以你在正常写消息时仍然可以像平时一样输入空格。第二次按键会无视输入框内容直接停止录音。录音还会在 15 秒静默后，或总时长达到两分钟后自动停止。

怎么更改听写语言 #

Voice dictation 使用和 Claude 回复语言相同的 language setting。如果这个设置为空，听写默认是英语。在 VS Code extension 中，如果 language 为空，会先使用 VS Code 的 accessibility.voice.speechLanguage，然后再回退到英语。

你可以在 /config 里设置语言，也可以直接改 settings。既可以写 BCP 47 语言代码，也可以写语言名：

{
  "language": "japanese"
}

如果你的 language 不在支持列表里，/voice 在启用时会警告，并把听写回退到英语。这个回退不会影响 Claude 的文字回复。

怎么重绑听写按键 #

听写按键绑定到 Chat 上下文里的 voice:pushToTalk，默认是 Space。hold 和 tap 两种模式共用同一个绑定。你可以在 ~/.claude/keybindings.json 里修改：

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

voice:pushToTalk 一次只用一个键。自定义绑定会替换默认的 Space，不是额外再加一个触发键，所以示例里的 "space": null 只是为了说明清楚，删掉也不会改变行为。

在 hold 模式里，不要把它绑定到单独的字母键，比如 v。因为 hold 检测依赖键重复，预热期间这个字母会先打进提示词。更稳妥的做法是继续用 Space，或者改成像 meta+k 这样的修饰键组合，这样第一次按下就会开始录音，没有预热。tap 模式没有预热，所以大多数按键都能用。

有些按键不会被终端应用传递，因此根本不能绑定。比如你尝试绑定 Caps Lock，系统会报错。完整的按键语法和保留快捷键列表，见 customize keyboard shortcuts。

排查语音输入不生效怎么解决 #

语音输入无法启动或无法录音时，常见问题如下：

• Voice mode requires a Claude.ai account：你现在是用 API key 或第三方 provider 登录的。运行 /login 切换到 Claude.ai 账号。
• Microphone access is denied：在系统设置里给终端授予麦克风权限。macOS 打开 System Settings → Privacy & Security → Microphone，把终端应用勾上，然后再运行一次 /voice。Windows 打开 Settings → Privacy & security → Microphone，开启 desktop apps 的麦克风访问，然后再运行 /voice。如果 macOS 的设置里根本找不到终端，见下方“macOS 麦克风设置中找不到终端应用”。
• Linux 上出现 No audio recording tool found：内置音频模块没有加载成功，而且也没装任何回退工具。按报错里的命令安装 SoX，例如 sudo apt-get install sox。
• WSL 中出现 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，或者麦克风权限被拒绝。先确认输入设备可用，再按上面的报错逐项修复，然后重新触发语音输入。
• 在 hold 模式下按住 Space 没反应：按住时观察提示词输入框。如果空格不断累积，说明语音模式没开，运行 /voice hold 即可。如果只出现一两个空格然后停止，说明语音模式已开，但 hold 检测没有触发。hold 检测要求终端能发出键重复事件，如果操作系统关闭了 key-repeat，就检测不到。此时改用 /voice tap 可以绕开这个要求。
• tap 模式下按 Space 只是输入空格：第一次按键只有在输入框为空时才会开始录音。先清空输入框，或者确认自己当前就是 /voice tap 模式。
• No audio detected from microphone：录音已经开始，但抓到的是静音。确认系统默认输入设备选对了，并且输入音量不是静音或接近零。Windows 打开 Settings → System → Sound → Input 选择麦克风，macOS 打开 System Settings → Sound → Input。
• No speech detected：音频已经到达转写服务，但没有识别出词。离麦克风近一点，降低背景噪音，并确认你的 dictation language 和你正在说的语言一致。
• 转写内容乱码或语言不对：听写默认是英语。如果你在说别的语言，先在 /config 里设置语言。见 怎么更改听写语言。

macOS 麦克风设置中找不到终端应用 #

如果终端应用没有出现在 System Settings → Privacy & Security → Microphone 里，就没有可以手动切换的开关。你需要重置这个终端的权限状态，让下一次 /voice 重新触发 macOS 的权限弹窗。

先运行 tccutil reset Microphone <bundle-id>，把 <bundle-id> 换成你的终端标识：内置 Terminal 用 com.apple.Terminal，iTerm2 用 com.googlecode.iterm2。其他终端可以用 osascript -e 'id of app "AppName"' 查标识。

你也可以不带 bundle ID 运行 tccutil reset Microphone，但这会撤销 Mac 上所有应用的麦克风权限，包括 Zoom、Slack 这类应用。它们下次使用时都要重新申请权限，不要在通话中执行。

macOS 不会对已经在运行的进程重新弹权限框。请用 Cmd+Q 退出终端应用，不要只关窗口，然后重新打开。

启动 Claude Code 后运行 /voice，在弹出的麦克风权限请求里选择允许。

常见问题 #

语音输入为什么只支持 Claude.ai 账号？ #

因为语音转文字服务会把音频流式传到 Anthropic 服务器，只有 Claude.ai 账号认证时可用。API key、Bedrock、Vertex AI 和 Microsoft Foundry 都不支持。

为什么按住 Space 没有开始录音？ #

先看输入框里空格是在一直累积，还是只出现一两个后就停了。前者通常说明 /voice 没开启；后者说明 hold 检测没触发，常见原因是系统关闭了键重复。你可以改用 /voice tap，或者把按键重绑成修饰键组合。

WSL 里怎么让 Claude Code 语音输入可用？ #

需要 WSLg 才能拿到音频输入。WSL2 从 Microsoft Store 安装时通常自带 WSLg；如果是 WSL1，或者没有 WSLg，就要改在原生 Windows 里运行 Claude Code。若是 WSL 中 SoX 报找不到录音器，通常还要装 sox libsox-fmt-pulse。