47 · Voice 语音模式：把提示词说出来，而不是打出来

📚 系列导航：上一篇 46 开发配置 把 Claude Code 当成「被开发的对象」那一套环境怎么搭讲清了。这一篇回到最日常的一个动作——怎么把提示词说出来，让它实时转成文字。/voice 一开，你按住空格说话，话就落进输入框；还能跟手打混着来。听着挺玄，其实开起来就一行命令，但有几条「能不能用」的硬门槛，不先看清你大概率会卡在第一步。

⚠️ 实验性功能，可能随版本变化。 本篇命令、参数、版本号均以官方文档为准，但语音听写仍在迭代，你看到时具体行为可能已有调整，以你本机 /voice 的实际提示为准。

都说「能动嘴就别动手」效率高，但说句实话，对程序员这个群体，语音输入长期是个伪需求——我们打字本来就快，满屏的变量名、函数名、snake_case，你拿嘴念给语音引擎听，它十有八九给你转成一堆同音错字，改起来比打字还累。用某主流输入法的语音功能写技术笔记，「useEffect」常被它听成「U se if act」，碰上几次也就关了再不开。

所以一开始听说 Claude Code 出了语音听写，很容易带着偏见去试——预判它又是个花架子。结果两点能改观这种看法：一是它专门针对编程词汇调过，regex、OAuth、JSON、localhost 这些它认得；二是它把你当前项目名和 git 分支名自动喂进去当识别提示，所以你念自己项目里那些「黑话」，命中率比通用输入法高一截。

这就不一样了。它不是要替代你打代码，而是替代你「打那一长段需求描述」——你瘫在椅子上把「重构一下 auth 中间件，改用新的 token 校验 helper」说出来，比一个字一个字戳进去，是真省事。这一篇就带你把它开起来、用顺，顺带把那几条「为啥我开不了」的坑挨个填平。

看完这一篇，你会拿到：

• 一句话讲明白语音听写是什么、它转写发生在哪（不在你本地）
• 一条最关键的「能不能用」红线——只认 Claude.ai 账户登录，用 API key 的根本开不了
• 平台支持情况一张表（Mac / Windows / Linux / WSL / 远程 / VS Code）说清
• 两种录音模式（按住 vs 点击）分别怎么用、各自适合什么场景
• 怎么把它设成开机默认、怎么改听写语言、怎么换触发键
• 一个能照着跑、给了预期输出的实战：从开启到说出第一句提示

---

01 先搞懂：语音听写到底是个啥，转写在哪发生

先给结论：语音听写就是「你说话，它实时转成文字，落进提示词输入框」——不是让你跟 Claude「对话聊天」，是把你敲键盘这个动作换成了说话。

类比：会议上的实时字幕。 你开线上会，打开实时字幕，你一边说，屏幕下方一边把你的话转成文字滚出来——你没在「跟字幕对话」，字幕只是把你的语音誊成文本。Claude Code 的语音听写就是这个角色：你按住键说话，话变成字进了输入框，之后这段文字怎么用，跟你手打进去的完全一样——你可以继续手打补几个字，再回车发给 Claude。

官方对它的描述很直白：

在 Claude Code CLI 中说出你的提示词，而不是输入它们。你的语音会实时转录到提示词输入中，所以你可以在同一条消息中混合使用语音和输入。

注意这句里藏着一个很贴心的设计——「混合使用语音和输入」。转写出来的文字插在你光标的位置，光标停在插入文本的末尾，所以你完全可以说一半、手打一半：用嘴说出那段啰嗦的需求描述，再用手补上一个精确的文件名或函数名。这是它比纯语音输入法好用的地方之一。

接下来这点至关重要，直接决定了下面一整节的「能不能用」：你的语音不在本地处理。官方写得很清楚：

语音听写将你录制的音频流传输到 Anthropic 的服务器进行转录。音频不在本地处理。

也就是说，你说的话会被传到 Anthropic 的服务器转成文字再传回来。这一条引出三个连带结论，你现在先记住，下一节展开：第一，它必须联网；第二，它必须用 Claude.ai 账户认证（服务器要知道你是谁）；第三，它在没有麦克风的远程环境里用不了（音频得从你本机采）。

最后给一个挺容易被忽略的好消息：转写不花钱、不占额度。官方明确——

转录不消耗 Claude 消息或令牌，也不计入 /usage 中显示的限制。

换句话说，你说多少话、转多少字，都不吃你的订阅额度（订阅与计费见第 06 篇）。这点盯着 /usage 就能验出来——开着语音连说带转写忙活半天，额度数字纹丝不动。所以别有「多用几次会不会很烧」的心理负担，它跟你发给 Claude 的消息是两码事。

💡 一句话总结：语音听写 = 把「打字」换成「说话」，转出来的文字跟手打的一样用，还能跟手打混着来；它的音频传到 Anthropic 服务器转写、不在本地，但转写本身不花钱、不占 /usage 额度。

---

02 第一条红线：只认 Claude.ai 账户登录，用 API key 的直接开不了

这一节最短，但最该先看——很多人卡在第一步，就卡在这。

上一节说了，转写要把音频传到 Anthropic 服务器，服务器得认得你。于是语音听写有一条硬门槛：你必须用 Claude.ai 账户登录。 官方把不支持的情况一条条点了名：

语音转文本服务仅在你使用 Claude.ai 账户进行身份验证时可用，当 Claude Code 配置为直接使用 Anthropic API 密钥、Amazon Bedrock、Google Vertex AI 或 Microsoft Foundry 时不可用。当你的组织启用了 HIPAA 合规性时，语音听写也不可用。

翻成人话——回想第 04 / 05 篇你怎么接入的 Claude Code：

• 如果你走的是订阅登录（Pro / Max 那种 Claude.ai 账户），✅ 能用语音。
• 如果你填的是 Anthropic API key，或接的是 Bedrock / Vertex / Foundry，❌ 语音直接用不了。
• 组织开了 HIPAA 合规，❌ 也用不了。

这不是 bug，是设计如此——语音转写这个服务挂在 Claude.ai 账户体系下，API key 那条路根本不通这个能力。

那怎么判断自己是哪种？最直接的办法是直接试：开 /voice，如果你用的是 API key，它会甩你一句明确的报错：

Voice mode requires a Claude.ai account

看到这句，别折腾麦克风权限了，根因就是认证方式不对。官方给的解法也干脆：运行 /login，改用 Claude.ai 账户登录。常年挂着公司 API key 的机器，第一次在上面敲 /voice 就会吃这个报错，很容易误以为是麦克风坏了去查半天——其实是账户类型压根不支持。这一条值得比踩坑早知道五分钟。

你的接入方式（见第 04、05 篇）	能用语音听写吗
Claude.ai 账户登录（Pro / Max 订阅）	✅ 能
Anthropic API key	❌ 报 requires a Claude.ai account
Amazon Bedrock / Google Vertex / Microsoft Foundry	❌ 不支持
组织启用了 HIPAA 合规	❌ 不支持

💡 一句话总结：语音听写只认 Claude.ai 账户登录——用 API key、Bedrock、Vertex、Foundry 或开了 HIPAA 的，一律开不了，报错就是那句 requires a Claude.ai account，解法是 /login 换登录方式。

---

03 第二条门槛：得有本地麦克风，平台支持一张表说清

账户这关过了，第二关是硬件和环境：转写虽然在云上，但音频得从你这台机器的麦克风采集。这一条决定了它在哪些环境能用、哪些环境天生用不了。

类比：你得真有一支话筒插在面前。 实时字幕再智能，也得先有麦克风把你的声音收进来——你坐在一台没接麦克风的服务器前对着空气说话，再好的转写引擎也是巧妇难为无米之炊。语音听写同理：它需要本地麦克风访问权限，所以凡是「你人不在那台机器跟前」的环境，基本都用不了。

官方把这条说得很清楚：

语音听写还需要本地麦克风访问权限，因此在远程环境中不起作用，例如网络上的 Claude Code 或 SSH 会话。

把各平台和环境整理成一张表，你对号入座：

平台 / 环境	支持情况	备注
macOS	✅ 内置原生模块	首次 /voice 触发系统麦克风权限提示
Windows	✅ 内置原生模块	设置里给终端开麦克风权限
Linux	✅ 原生模块，失败回退到 arecord / rec	都没有时 /voice 会打印安装命令
WSL	⚠️ 需要 WSLg	WSL2（Win10/11 商店版）自带 WSLg；WSL1 没有，得在原生 Windows 跑
SSH 会话	❌	麦克风在你本地，会话在远端
网络版 Claude Code	❌	远程环境，没本地麦克风（见第 11 篇）
VS Code 扩展	✅（同样要 Claude.ai 账户）	但 VS Code Remote（SSH / Dev Containers / Codespaces）❌

几个新手最容易栽的点，单独拎出来说：

远程一律不行，原因是同一个。 不管是 SSH、网络版 Claude Code（第 11 篇讲过的浏览器里那个），还是 VS Code 连着远程主机——只要「干活的进程在远端、麦克风在你本地」，语音就用不了。官方专门点了 VS Code 扩展这一条：

它在 VS Code Remote 会话中不可用，包括 SSH、Dev Containers 和 Codespaces，因为麦克风在你的本地机器上，而扩展在远程主机上运行。

WSL 是个特例，得有 WSLg。 WSLg 是微软给 WSL2 配的那套「能跑图形和音频」的组件，Win10/11 上从应用商店装的 WSL2 自带。如果你还在用 WSL1，没有 WSLg，语音用不了——官方建议直接在原生 Windows 里跑 Claude Code。

Linux 上没装录音工具时它会教你装。 Linux 优先用内置原生模块，加载不了会回退到 ALSA 的 arecord 或 SoX 的 rec；两个都没有，/voice 会直接打印出你那个发行版的安装命令（比如 sudo apt-get install sox），照着敲就行，不用你自己瞎找。

💡 一句话总结：语音转写在云上，但音频要从本地麦克风采——所以 Mac/Win/Linux 本机能用，SSH、网络版、VS Code Remote 这类「人不在机器跟前」的远程环境一律不行；WSL 得有 WSLg，Linux 缺录音工具时 /voice 会教你装。

---

04 两种录音模式：按住说，还是点一下说

门槛都过了，正式开起来。/voice 一开，你要先认识它的两种录音模式——这俩决定了你「怎么开始、怎么停、说完要不要自己回车」。

类比：对讲机 vs 录音笔。 对讲机是按住才说话，松手就停、对面就收到——这是「按住模式」；录音笔是按一下开始录、再按一下停，中间你不用一直摁着——这是「点击模式」。两种交互习惯，按你顺手的来。

先看两种模式的核心区别：

模式	怎么触发	怎么停	说完发送	适合
按住（hold） 默认	按住 Space	松开 Space	默认松手后等你按 Enter（可配自动发）	想精确控制录哪一段、边说边停
点击（tap）	点一下 Space 开始	再点一下 Space	转写 ≥3 个词自动发送	想「说完即走」、不愿一直摁着键

按住模式（默认）：像对讲机，按住才录

按住模式就是按键通话：按住 Space 开始录，松开停。这是默认模式，开了 /voice 不指定模式就是它。

这里有个细节你最好提前知道，否则第一次用会懵：按住模式有个短暂的「预热」。Claude Code 靠监测终端的「按键重复」事件来判断你是不是在按住，所以刚按下去会有一小下延迟，页脚显示 keep holding…，等录制真正激活才切成实时波形。官方解释：

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

翻成人话两点：一，预热那一下蹦出来的几个字符，录制激活后会自动删掉，别慌；二，你单点一下 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——给你留了手打补充和检查的余地。如果你嫌每次还要回车麻烦，可以在设置里开 autoSubmit（下一节讲），松手就自动发，前提是转写至少有三个词。

点击模式：像录音笔，点一下开、再点一下走

点击模式用单键切换：点一下 Space 开始，说，再点一下 Space——停止并自动发送。没有预热，你也不用一直摁着键。

用 /voice tap 开启它。要注意点击模式有个版本门槛比按住模式高——官方注明：

语音听写需要 Claude Code v2.1.69 或更高版本。点击模式需要 v2.1.116 或更高版本。

所以如果你 /voice tap 不好使，先 claude --version 看看版本够不够。

点击模式有两个防呆设计，挺贴心：

• 第一次点击只在输入框为空时才开始录音——所以你撰写消息时正常敲空格不会误触发录音。
• 转写不足三个词的，插入但不发送——防止你手滑点一下、蹦出个单字就被发出去。

另外它会自动停：15 秒没声音，或者总共录满两分钟，自动停止。

两种都用一阵下来，不少人会稳定在点击模式：按住模式那个预热的小延迟，对急性子有点别扭，老觉得「都开始说了它还没录」；点击模式点一下就走、说完再点一下自动发，更符合「想到一句说一句」的节奏。但要论「精确控制录哪一小段、边想边停」，按住模式更跟手——你试两天就知道自己是哪一派。

💡 一句话总结：两种模式——**按住（默认，对讲机式）**按住 Space 录、松手定稿、默认要你回车；**点击（录音笔式，需 v2.1.116+）**点一下开、再点一下停并自动发（≥3 词）；急性子选点击，要精控选按住。

---

05 三个调校：设成默认、改听写语言、换触发键

模式会用了，再把三个常用调校交给你——这三件事配一次，长期顺手。

让它开机就在：写进设置，别每次手敲 /voice

/voice 开启的状态会在会话之间持续，但如果你想一上来就是开的、连第一次 /voice 都省掉，直接写进你的用户设置文件（settings.json 的用户级 / 项目级区别见第 31 篇）：

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

enabled 控制开不开，mode 填 hold 或 tap 定默认模式。

前一节提到的「松手自动发」也在这个 voice 对象里配——加一行 autoSubmit：

{
  "voice": {
    "enabled": true,
    "mode": "hold",
    "autoSubmit": true
  }
}

开了 autoSubmit，按住模式松手后只要转写 ≥3 个词就自动发，不用再按 Enter。

改听写语言：默认是英语，说中文要先设

这条对咱们中文用户尤其关键。语音听写默认用英语——你要是直接对它说中文，大概率转出一坨乱码。官方说得很明白：听写用的是和控制 Claude 回复语言同一个 language 设置，这个设置为空时听写就回退英语。

它支持的听写语言是固定的一张表，目前没有中文（截至本文，支持列表为捷克、丹麦、荷兰、英、法、德、希腊、印地、印尼、意、日、韩、挪威、波兰、葡、俄、西、瑞典、土、乌克兰这些）；如果你同时有日语或韩语的需求，日语 ja、韩语 ko 倒是在列。所以如果你主要说中文，得有个心理预期：现版本它对中文的听写支持还没覆盖到——这点务必以你本机 /voice 启用时的实际提示为准，不在支持列表里它会警告你并回退英语。

设置语言在 /config 里改，或直接写设置，填语言名或 BCP 47 代码都行：

{
  "language": "japanese"
}

官方还补了一条：如果你的 language 不在支持列表里，/voice 启用时会警告你，并把听写回退成英语——但这只影响听写，Claude 的文字回复语言不受这个回退影响。

换触发键：不想用空格，绑别的

默认触发键是 Space（按住和点击共用这一个键）。想换，在 ~/.claude/keybindings.json 里把 voice:pushToTalk 绑到别的键（快捷键体系见第 14 篇）：

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

这里有个按住模式专属的坑，官方专门提醒了：

在按住模式中，避免绑定裸字母键如 v，因为按住检测依赖于按键重复，字母在预热期间输入到提示词中。

翻成人话：按住模式别绑单个字母键（比如光一个 v）——因为它靠「按键重复」检测按住，预热期间那个字母会被打进输入框。想绕开预热，绑一个修饰符组合（比如 meta+k）最香，组合键第一次按下就开始录、没有预热那一下延迟。点击模式没预热，绑啥键基本都行。

💡 一句话总结：三件长期受用的调校——voice.enabled/mode 写进设置让它开机就在（加 autoSubmit 松手自动发）；听写默认英语、要靠 language 设置改，但支持列表里目前没中文（日韩在）；换触发键改 voice:pushToTalk，按住模式别绑裸字母、优先修饰符组合。

---

06 动手：从开启到说出第一句提示

光看不练假把式。下面带你最小流程跑一遍——前提你已经是 Claude.ai 账户登录（第 02 节那条红线），且在本机（不是 SSH / 网络版）。全程不依赖你已有的任何复杂项目，随便进一个目录开 claude 就行。

第零步：确认版本够（在终端）

claude --version

预期：版本号 ≥ 2.1.69（想用点击模式则 ≥ 2.1.116）。低了先升级，否则 /voice 不认。

第一步：进会话，开启语音

/voice

预期：第一次开会触发麦克风权限检查——macOS 上会弹系统权限提示，点允许。然后页脚打印类似：

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

看到 Voice mode enabled = 开成功了。括号里 hold 是当前模式，Dictation language: en 告诉你现在听写按英语处理。

如果这里直接报 Voice mode requires a Claude.ai account——回第 02 节，你是用 API key 登录的，先 /login 换 Claude.ai 账户。

第二步：留意输入框页脚的提示

提示词为空时，输入框页脚会显示一行 hold Space to speak 这样的提示——这是在告诉你「现在按住空格就能说话」。

第三步：按住空格，说一句英文提示

按住 Space 不放，对着麦克风清楚地说一句英文（默认英语，先别说中文）。比如：

# 按住 Space，说出： list all files in the current directory

预期：你说话时，文字实时出现在输入框里（定稿前是暗的）；按住的头一下页脚显示 keep holding…（预热），随即切成实时波形。松开 Space，文字定稿，变成：

> list all files in the current directory▮

看到你说的话变成了输入框里的文字 = 听写真的跑通了。这时它默认不自动发，停在那儿等你。

第四步：（可选）手打补一句，再发

把光标留在末尾，手打补几个字——验证一下「语音 + 手打混用」：

> list all files in the current directory and show their sizes▮

预期：手打的部分无缝接在语音转写后面。按 Enter 发出去，Claude 正常响应。这一步证明了第 01 节说的——转写出来的文字跟手打的完全一样用。

第五步：试试点击模式（需 v2.1.116+）

/voice tap

清空输入框，点一下 Space（不用按住），说一句 ≥3 个词的英文，再点一下 Space。

预期：第二次点击后，转写文字插入并自动发送（满三个词）。没有预热那一下延迟——对比一下你就知道两种模式的手感差别了。

第六步：关掉（可选）

/voice off

预期：页脚提示语音已禁用，页脚那行 hold Space to speak 消失，Space 恢复成正常空格键。

跑通这几步，你就把「确认版本 → 开启授权 → 按住说话 → 语音手打混用 → 切点击模式 → 关掉」这条完整链路亲手走了一遍。以后无非是配进 settings 让它常驻、按需换语言或触发键——核心交互就这些。

💡 一句话总结：动手就六步——--version 确认版本 → /voice 开启并授权麦克风 → 按住 Space 说英文看它转成文字 → 手打补一句验证混用 → /voice tap 试点击模式 → /voice off 关掉；亲手跑通，比记一堆参数都管用。

---

07 小结

这一篇把 Claude Code 的语音听写从头讲到尾——核心就一句：把「打那一长段需求」从手打换成说话，转出来的字跟手打一样用。

把要点串起来回顾：

你关心的事	结论	关键点
它是什么	实时语音转文字，落进输入框	转写在 Anthropic 服务器、不在本地；不占 /usage 额度
我能不能用（认证）	只认 Claude.ai 账户	API key / Bedrock / Vertex / Foundry / HIPAA 都不行
我能不能用（环境）	本机能、远程不能	要本地麦克风；SSH、网络版、VS Code Remote 一律不行
怎么开、怎么录	/voice，两种模式	按住（默认，有预热）/ 点击（需 v2.1.116+，说完自动发）
怎么调顺	写进设置 + 改语言 + 换键	默认英语、支持列表暂无中文；触发键改 voice:pushToTalk

你现在应该能： 一句话说清语音听写是什么、它的音频去了哪（云上、不花额度）；先看准那条「只认 Claude.ai 账户」的红线，别再对着麦克风权限白查半天；分清哪些平台和环境能用（本机能、远程不能）；开起 /voice 并在按住 / 点击两种模式间挑顺手的；还会把它写进 settings 设成默认、按需改听写语言和触发键，并照着动手环节把整条链路亲手跑通。这套「能动嘴就少动手」的输入方式，是你在描述长需求时给自己减负的一个小开关——开不开是你的自由，但至少现在你知道它怎么开、什么时候开不了。

回到开头对语音输入的那点偏见——它确实替代不了你精准打代码，但替代「瘫着把一大段需求说出来」绰绰有余。这就够了：工具不必样样全能，在它擅长的那一格里帮你省下力气，就是好工具。

---

下一篇 48「综合实战：从零到上线串起所学」——前面四十七篇，零件一个个递到了你手上：装环境、提需求、配 CLAUDE.md、接 MCP、派 subagent、配 hook、走 git……单看每个你都会了，但把它们串成一条「从空目录到一个能上线的小项目」的完整流水线，你走过吗？ 下一篇就当一次毕业设计：拉着你从零起一个真实小项目，把这套手艺串起来跑一遍，让你亲眼看见这些零件咬合在一起是什么样子。