语音输入

在 Claude Code CLI 里用语音输入提示：要求、/voice 开启、按住说话与点按说话两种模式、取消录音、听写语言、重绑定按键和排障。

在 Claude Code CLI 里可以说出提示而不是打字。你的语音被实时转写进提示输入框，所以同一条消息里可以混用语音和打字。用 /voice 启用听写，然后要么按住一个键说话，要么点一下开始、再点一下发送。听写在智能体视图里也能用：当 dispatch 输入框或 peek 面板的回复框获得焦点时，按住或点按你的说话键，就能向后台会话听写。

要求

语音听写把你录下的音频流式传到 Anthropic 的服务器转写，音频不在本地处理。它需要以下全部：

Claude.ai 账号：语音转文字服务只在用 claude.ai 账号认证时可用；Claude Code 配置为直接使用 Anthropic API key、Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 时不可用。
本地麦克风：语音听写在云端会话或 SSH 会话里不工作。
在 WSL 里运行 Claude Code 时需要 WSLg：在 Windows 10 或 11 上从 Microsoft Store 安装的 WSL2 自带 WSLg；WSLg 不可用（例如 WSL1）时，改在原生 Windows 里运行 Claude Code。

转写不消耗 Claude 消息或 token，也不计入 /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 hold`	以按住模式启用
`/voice tap`	以点按模式启用
`/voice off`	禁用

语音听写跨会话保持。你也可以不运行 /voice，直接在用户设置文件里设置：

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

启用语音听写后的前三个会话里，提示为空时输入页脚会显示 hold space to speak 提示。该提示反映你当前的 voice:pushToTalk 绑定，并在你重绑定听写键时更新；两种模式下提示文字相同，配置了自定义状态行时不显示。

两种模式下，转写都针对编码词汇做了调优：regex、OAuth、JSON 和 localhost 这类常见开发术语能被正确识别，你当前的项目名和 git 分支名会自动作为识别提示加入。

按住说话

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

按住 Space 开始录音。Claude Code 通过观察终端发来的快速按键重复事件来检测按住的键，所以录音开始前有短暂的预热：预热时页脚显示 keep holding…，录音生效后显示 listening…。录音期间，提示光标变成随你麦克风音量升降的条，除非你打开了 prefersReducedMotion。

预热期间，开头的一两个按键重复字符会输入进输入框，并在录音激活时自动移除。单次点按 Space 仍然输入空格，因为按住检测只在快速重复时触发。

按住或点按 Space 只在按键本来会输入到提示里的地方启动听写：在转录查看器里，Space 用来翻页；在 vim 模式的非 INSERT 状态下它是一个命令。像 meta+k 这样重绑定的修饰键组合从不输入文本，所以在这些地方它也能启动听写。

提示：要跳过预热，用 /voice tap 切换到点按模式，或者重绑定为 meta+k 这样的修饰键组合；修饰键组合在第一次按键时就开始录音。

你的语音在你说话时出现在提示里，在转写最终确定之前显示为暗色。松开 Space 停止录音并确定文本。转写被插入到光标位置，光标停在插入文本的末尾，所以你可以按任何顺序混用打字和听写：再次按住 Space 追加另一段录音，或先移动光标，把语音插入提示的别处：

> refactor the auth middleware to ▮
  # 按住空格，说 "use the new token validation helper"
> refactor the auth middleware to use the new token validation helper▮

默认情况下，你松开键时 Claude Code 插入转写并等你按 Enter。在 voice 设置对象里设 "autoSubmit": true，则在转写至少有三个词时，松开键就自动发送提示。

点按录音并发送

点按模式用一次按键切换录音：点一下开始，说话，再点一下发送提示。没有预热，也不需要一直按住键。

用 /voice tap 启用点按模式。提示输入框为空时，点按 Space 开始录音，录音期间页脚显示 ● REC · tap to send，再点按 Space 停止。转写至少有三个词时，Claude Code 插入转写并自动提交提示；更短的转写会被插入但不提交，所以误触不会发出一个孤立的词。

三个词的阈值对不用空格书写的语言也按词计数：日语、中文和泰语的转写数的是单个词，所以它们在点按模式以及带 autoSubmit 的按住模式下会自动提交。

第一次点按只在提示输入框为空时才开始录音，所以你撰写消息时仍能正常输入空格；第二次点按无论输入内容如何都会停止录音。录音在静默 15 秒或总共两分钟后也会自动停止。

取消录音

按 Esc 或 Ctrl+C 取消听写而不是确定它：Claude Code 停止麦克风，丢弃转写，并把提示恢复到录音开始前的内容。已完成录音的转写仍在处理期间，这两个键同样能取消；你在处理期间编辑或提交的提示保持你留下的样子。取消的这一次按键不做别的事：Esc 不会中断 Claude 的响应，Ctrl+C 不会清空提示，也不会算作退出 Claude Code 所需的两次按键中的第一次。

更改听写语言

语音听写使用与控制 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
      }
    }
  ]
}

voice:pushToTalk 动作一次只用一个键。绑定自定义键时，它会替换默认的 Space 绑定而不是增加第二个触发器，所以这个例子里的 "space": null 一行只是为了清晰，省略它行为不变。

在按住模式里，避免绑定 v 这样的单个字母键，因为按住检测依赖按键重复，而字母在预热期间会输入进提示。用 Space，或用 meta+k 这样的修饰键组合，在第一次按键就开始录音而无预热。点按模式没有预热，所以大多数键都行。

有些键不会被送到终端应用，根本无法绑定，例如试图绑定 Caps Lock 会显示错误。完整的键绑定语法和保留快捷键列表见自定义键盘快捷键页。

排障

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

Voice mode requires a Claude.ai account：你用 API key 或第三方提供商认证。运行 /login 用 claude.ai 账号登录。
Voice mode is disabled by your organization's policy：你组织的管理员策略关闭了语音听写；联系组织管理员确认你的组织是否提供语音听写。
Microphone access is denied：在系统设置里给你的终端授予麦克风权限。macOS 上，进入 System Settings → Privacy & Security → Microphone，启用你的终端应用，再运行 /voice；Windows 上，进入 Settings → Privacy & security → Microphone，为桌面应用打开麦克风访问，再运行 /voice。如果你的终端没有列在 macOS 设置里，见下面「终端没有列在 macOS 麦克风设置里」。
Linux 上的 Voice mode requires SoX for audio recording：原生音频模块加载不了，也没有安装回退。按错误消息里显示的命令安装 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：语音听写在 10 秒内遇到三次失败。Claude Code 暂停听写，直到距这些失败中的第一次已过 10 秒。这通常表示这台主机上的麦克风或音频栈无法采集音频，例如无头服务器、没有音频透传的远程 shell，或被拒绝的麦克风权限。确认有可用的输入设备，按上面的条目修复根本原因，然后再次触发语音（v2.1.202 之前，只有启动失败才计入暂停）。
按住模式下按住 Space 没反应：按住时观察提示输入框。如果空格不断累积，语音听写很可能是关的，运行 /voice hold 启用它；如果只出现一两个空格然后没有动静，说明语音听写已开但按住检测没有触发。按住检测要求你的终端发送按键重复事件，所以操作系统层面关闭了按键重复时它检测不到按住的键；用 /voice tap 切换到点按模式可避免对按键重复的要求。
点按模式下点按 Space 输入了空格而不是录音：第一次点按只在提示输入框为空时才开始录音。先清空输入，或运行 /voice tap 确认你处于点按模式。
No audio detected from microphone：录音开始了但捕获到的是静音。确认正确的输入设备被设为系统默认，且它的输入电平没有静音或接近零。Windows 上打开 Settings → System → Sound → Input 选择你的麦克风；macOS 上打开 System Settings → Sound → Input。
Voice connection failed：你的录音因为连接失败从未到达转写服务。检查网络并重试。没有采集到音频的录音会报告 No audio detected from microphone 而不是这条消息（v2.1.200 之前，静音的麦克风可能报告连接失败，在真正的问题是输入设备时提示网络问题）。
Voice stream error: WebSocket upgrade rejected with HTTP <status>：某个服务器以所示的 HTTP 状态拒绝了你的连接，所以这不是网络中断。400 范围内的状态通常表示登录过期，或有代理或机器人防护服务代替转写服务应答。运行 /login 刷新登录；状态持续时，检查你网络路径上的 VPN 或代理。如果拒绝到达时你仍在录音，Claude Code 对 400 范围之外的状态会重试一次再显示这条消息，对 400 范围内的状态不重试。（v2.1.229 到 v2.1.231，原生构建不显示此消息：Claude Code 继续录音，按住模式的页脚仍显示 listening…，在你停止录音后才报告 Voice connection failed。）
No speech detected：音频到达了转写服务但没有识别出词。靠近麦克风说话、降低背景噪音，并确认你的听写语言与你说的语言一致。
转写乱码或语言不对：听写默认英语。如果你用另一种语言听写，先在 /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，macOS 提示麦克风访问，允许它。

另见

自定义键盘快捷键：重绑定 voice:pushToTalk 和其他 CLI 键盘动作。
全部设置：voice、language 及其他设置键。
交互模式：键盘快捷键、输入模式和会话控制。
命令：/voice、/config 和所有其他命令的参考。