主题
语音听写
在 Claude Code CLI 中用语音口述提示词，支持按住录音和点按录音两种模式。
是什么
语音听写让你在 Claude Code CLI 里用说话代替打字来输入提示词。你的语音会被实时转写进输入框，因此可以在同一条消息里混用语音和打字。用 /voice 启用后，既可以按住某个键说话，也可以点按一次开始、再点按一次发送。
该功能会把录制的音频流式传到 Anthropic 服务器进行转写（不在本地处理），转写不消耗 Claude 消息或 token，也不计入 /usage 中显示的额度。
怎么工作
- 运行
/voice启用听写；首次启用会做麦克风检查，在 macOS 上会触发终端的系统麦克风权限弹窗。 - hold 模式（默认）为按住说话：按住
Space开始录音，松开停止并定稿；语音边说边以暗色显示在输入框，定稿后插入光标处。 - tap 模式为点按切换：输入框为空时点按
Space开始，再点按一次停止；转写满 3 个词以上时自动提交，过短则只插入不发送。 - 转写针对编程词汇做了优化（如
regex、OAuth、JSON、localhost），并自动把当前项目名和 git 分支名作为识别提示。 - tap 模式下录音会在静音 15 秒或满 2 分钟后自动停止。
- 听写键绑定为
Chat上下文中的voice:pushToTalk，默认Space，hold 与 tap 模式共用此绑定。 - 听写语言复用控制 Claude 回复语言的
language设置；为空时默认英语。
怎么配置 / 用法
启用与模式切换：
/voice # 切换开/关，保持当前模式
/voice hold # 启用 hold 模式
/voice tap # 启用 tap 模式
/voice off # 关闭在用户设置文件中持久化启用并指定模式：
json
{
"voice": {
"enabled": true,
"mode": "tap"
}
}hold 模式下设置 "autoSubmit": true 可在松键时自动发送（转写需至少 3 个词）。
设置听写语言（可用 BCP 47 代码或语言名）：
json
{
"language": "japanese"
}什么时候用
- 想用说话代替打字来快速输入较长的提示词时。
- 希望在同一条消息里混用语音和打字时。
- 用 modifier 组合键（如
meta+k）绑定时可省去 hold 模式的预热延迟。 - 需要用非英语口述（支持 cs/da/nl/en/fr/de/el/hi/id/it/ja/ko/no/pl/pt/ru/es/sv/tr/uk）时。
限制 / 坑
- 需 Claude Code v2.1.69 及以上；tap 模式需 v2.1.116 及以上（
claude --version查看）。 - 仅在用 Claude.ai 账号登录时可用；直连 Anthropic API key、Amazon Bedrock、Google Vertex AI、Microsoft Foundry 或组织启用 HIPAA 合规时均不可用。
- 需本地麦克风，不能在 Claude Code on the web、SSH 等远程环境使用；VS Code 扩展在 Remote/SSH/Dev Containers/Codespaces 下也不可用。
- WSL 中需 WSLg 提供音频访问；WSL1 等无 WSLg 时需改用原生 Windows 运行。
- hold 模式依赖终端的 key-repeat 事件检测按键，有短暂预热；OS 禁用 key-repeat 时无法触发，需改用 tap 模式。
硬事实速查（11 条）
- 启用命令为
/voice，参数hold/tap/off；默认 hold 模式。 - 音频流式上传到 Anthropic 服务器转写，不在本地处理，不消耗消息/token，不计入
/usage。 - Linux 上原生音频模块加载失败时回退到 ALSA 的
arecord或 SoX 的rec；macOS/Linux/Windows 均用内置原生模块录音。 - hold 模式下转写满 3 个词且设
"autoSubmit": true时松键自动发送，否则等待Enter。 - tap 模式下转写满 3 个词自动提交；首次点按仅在输入框为空时开始录音。
- 听写键
voice:pushToTalk默认Space，一次只用一个键；自定义键会替换默认绑定。 - hold 模式不要绑定单字母键（如
v），因预热期会把字母打进输入框；Caps Lock等键无法绑定。 - 支持 20 种听写语言；
language设置不在支持列表时启用时会告警并回退英语，不影响文本回复。 - VS Code 扩展中若
language为空，会先用 VS Code 的accessibility.voice.speechLanguage再回退英语。 - WSL 录音需
sudo apt install sox libsox-fmt-pulse（WSLg 走 PulseAudio，单装 sox 仅带 ALSA 后端无法录音）。 - tap 模式录音在静音 15 秒或满 2 分钟后自动停止。