文档索引

在此获取完整文档索引：https://code.claude.com/docs/llms.txt 使用此文件发现所有可用页面，然后再进一步探索。

语音听写

在 Claude Code CLI 中使用按住录音或点击录音的语音听写来说出你的提示。

在 Claude Code CLI 中用语音代替打字说出你的提示。你的语音会实时转录到提示输入中，因此你可以在同一条消息中混合语音和打字。使用 /voice 启用听写，然后按住某个键说话或点击一次开始、再次点击发送。

要求

语音听写将你录制的音频流式传输到 Anthropic 的服务器进行转录。音频不在本地处理。语音转文字服务仅在你使用 Claude.ai 账户认证时可用，在 Claude Code 配置为直接使用 Anthropic API 密钥、Amazon Bedrock、Google Vertex AI 或 Microsoft Foundry 时不可用。转录不消耗 Claude 消息或令牌，不计入 /usage 中显示的限制。有关 Anthropic 如何处理你的数据，请参阅数据使用。

语音听写还需要本地麦克风访问，因此在Web 上的 Claude Code 或 SSH 会话等远程环境中无法工作。在 WSL 中，语音听写需要 WSLg 进行音频访问。在 Windows 10 或 11 上从 Microsoft Store 安装 WSL2 时，WSLg 已包含在内。如果 WSLg 不可用（例如在 WSL1 上），请在原生 Windows 中运行 Claude Code。

音频录制在 macOS、Linux 和 Windows 上使用内置的原生模块。在 Linux 上，如果原生模块无法加载，Claude Code 会回退到 ALSA 工具中的 arecord 或 SoX 中的 rec。如果两者都不可用，/voice 会为你的包管理器打印安装命令。

Claude Code VS Code 扩展也支持语音听写，同样需要 Claude.ai 账户。它在 VS Code Remote 会话中不可用，包括 SSH、Dev Container 和 Codespaces，因为麦克风在你的本地机器上而扩展在远程主机上运行。

启用语音听写

运行 /voice 启用听写。首次启用时，Claude Code 会进行麦克风检查。在 macOS 上，如果从未授予过，这会触发终端的系统麦克风权限提示。

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

/voice 接受可选的模式参数：

语音听写跨会话持久化。直接在用户设置文件中设置，而不是运行 /voice：

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

当语音听写启用时，提示为空时输入页脚会显示 hold Space to speak 提示。该提示反映你当前的 voice:pushToTalk 绑定，如果你重新绑定听写键则会更新。两种模式下的提示文本相同，如果你配置了自定义状态行则不会显示。

两种模式的转录都针对编码词汇进行了调优。常见的开发术语如 regex、OAuth、JSON 和 localhost 都能正确识别，你当前的项目名称和 git 分支名称会自动添加为识别提示。

按住录音

按住模式是按键说话：按住键时录制运行，松开时停止。这是默认模式。

按住 Space 开始录制。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。在 voice 设置对象中设置 "autoSubmit": true，当松开键时自动发送提示，前提是转录至少有三个单词。

点击录音并发送

点击模式通过单次按键切换录制：点击一次开始，说话，然后再次点击发送提示。没有预热，你不需要按住键。

使用 /voice tap 启用点击模式。提示输入为空时，点击 Space 开始录制。录制时页脚显示实时波形。再次点击 Space 停止。当转录至少有三个单词时，Claude Code 插入转录并自动提交提示。较短的转录会被插入但不会提交，因此误触不会发送一个孤立的词。

第一次点击仅在提示输入为空时才开始录制，因此你仍然可以在编写消息时正常输入空格。第二次点击无论输入内容如何都会停止录制。录制也会在 15 秒静音或总共两分钟后自动停止。

更改听写语言

语音听写使用与控制 Claude 响应语言相同的 language 设置。如果该设置为空，听写默认为英语。在 VS Code 扩展中，如果 language 为空，听写使用 VS Code 的 accessibility.voice.speechLanguage 设置，然后默认为英语。

在 /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 密钥或第三方提供商认证。运行 /login 使用 Claude.ai 账户登录。
• Microphone access is denied：在系统设置中授予终端麦克风权限。在 macOS 上，前往 System Settings -> Privacy & Security -> Microphone 并启用你的终端应用，然后再次运行 /voice。在 Windows 上，前往 Settings -> Privacy & security -> Microphone 并为桌面应用开启麦克风访问，然后再次运行 /voice。如果你的终端未列在 macOS 设置中，请参阅终端未列在 macOS 麦克风设置中。
• Linux 上 No audio recording tool found：原生音频模块无法加载且未安装回退工具。使用错误消息中显示的命令安装 SoX，例如 sudo apt-get install 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：语音听写连续遇到多次启动失败，已停止尝试新会话直到有一个成功。这通常意味着此主机上的麦克风或音频栈无法捕获音频，例如无头服务器、没有音频透传的远程 shell 或被拒绝的麦克风权限。确认有可用的输入设备，修复上面条目中的根本原因，然后再次触发语音。
• 在按住模式中按住 Space 没有任何反应：按住时观察提示输入。如果空格不断累积，语音听写可能已关闭；运行 /voice hold 启用它。如果只出现一两个空格然后没有了，语音听写已开启但按住检测未触发。按住检测需要你的终端发送按键重复事件，因此如果在操作系统级别禁用了按键重复，则无法检测按住的键。使用 /voice tap 切换到点击模式以避免按键重复要求。
• 在点击模式中点击 Space 输入空格而非录音：第一次点击仅在提示输入为空时才开始录制。先清除输入，或通过运行 /voice tap 检查你是否在点击模式。
• No audio detected from microphone：录制已开始但捕获的是静音。确认正确的输入设备设置为系统默认，且其输入级别未静音或接近零。在 Windows 上，打开 Settings -> System -> Sound -> Input 并选择你的麦克风。在 macOS 上，打开 System Settings -> Sound -> Input。
• No speech detected：音频到达了转录服务但未识别出任何单词。靠近麦克风说话，减少背景噪音，确认你的听写语言与你说的语言匹配。
• 转录混乱或语言错误：听写默认为英语。如果你用其他语言听写，请先在 /config 中设置。参见更改听写语言。

终端未列在 macOS 麦克风设置中

如果你的终端应用未出现在 System Settings -> Privacy & Security -> Microphone 下，没有可以启用的切换开关。重置终端的权限状态，使下次 /voice 运行触发全新的 macOS 权限提示。

1. 重置终端的麦克风权限

   运行 tccutil reset Microphone <bundle-id>，将 <bundle-id> 替换为你的终端标识符：内置 Terminal 使用 com.apple.Terminal，iTerm2 使用 com.googlecode.iterm2。对于其他终端，使用 osascript -e 'id of app "AppName"' 查找标识符。

   ⚠️

   Warning

   你可以不带 bundle ID 运行 tccutil reset Microphone，但这会撤销你 Mac 上每个应用的麦克风访问权限，包括 Zoom 或 Slack 等应用。每个应用在下次使用时都需要重新请求访问权限，因此不要在活跃通话期间运行。

2. 退出并重新启动终端

   macOS 不会重新提示已运行的进程。使用 Cmd+Q 退出终端应用，而不仅仅是关闭窗口，然后重新打开。

3. 触发全新提示

   启动 Claude Code 并运行 /voice。macOS 提示麦克风访问权限；允许它。

另请参阅

• 自定义键盘快捷键：重新绑定 voice:pushToTalk 和其他 CLI 键盘操作
• 配置设置：voice、language 和其他设置键的完整参考
• 交互模式：键盘快捷键、输入模式和会话控制
• 命令：/voice、/config 和所有其他命令的参考