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

> 📚 **系列导航**：上一篇 [46 开发配置](46-dev-config.md) 把 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` 文字就定下来，插在你光标处。想接着说就再按住一次追加。看官方这个例子，特别直观：

```text
> 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 篇）：

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

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

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

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

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

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

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

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

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

```json
{
  "language": "japanese"
}
```

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

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

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

```json
{
  "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` 就行。

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

```bash
claude --version
```

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

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

```text
/voice
```

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

```text
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` 不放，对着麦克风清楚地说一句**英文**（默认英语，先别说中文）。比如：

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

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

```text
> list all files in the current directory▮
```

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

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

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

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

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

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

```text
/voice tap
```

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

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

**第六步：关掉**（可选）

```text
/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……单看每个你都会了，**但把它们串成一条「从空目录到一个能上线的小项目」的完整流水线，你走过吗？** 下一篇就当一次毕业设计：拉着你从零起一个真实小项目，把这套手艺**串起来跑一遍**，让你亲眼看见这些零件咬合在一起是什么样子。
