它到底是什么

/voice 是 Claude Code CLI 的内置语音听写命令。启用后，你说话时的音频实时流传到 Anthropic 服务器完成转写，转写结果直接插入当前 prompt 输入框。语音和键盘输入可以在同一条消息里混用。

版本要求（来自官方文档原文）：

用 claude --version 查看当前版本。

账户要求： 必须使用 Claude.ai 账户登录。以下情况下 /voice 不可用：

• 直接使用 Anthropic API key（非 claude.ai 账户）
• Amazon Bedrock、Google Vertex AI、Microsoft Foundry
• 组织开启了 HIPAA 合规模式

转写不消耗 Claude 消息或 token，不计入 /usage 限额。

怎么触发 / 怎么使用

1. 命令变体

/voice          # 开关切换（保持当前模式）
/voice hold     # 启用 hold 模式（按住说话）
/voice tap      # 启用 tap 模式（点击开始，再点击发送）
/voice off      # 关闭语音听写

首次启用时，Claude Code 会运行麦克风检测。在 macOS 上会触发系统级麦克风权限弹窗。

2. Hold 模式（默认）

按住 Space 开始录音，松开结束并将转写文本插入光标位置。

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

注意：终端需要发送 key-repeat 事件，hold 检测才能工作。检测期间会短暂显示 keep holding…，录音激活后显示实时波形。

若想跳过 warmup 延迟，可切换到 tap 模式，或将触发键重绑定为 meta+k 之类的修饰键组合——修饰键在第一次按下时即刻开始录音。

3. Tap 模式

点一次 Space 开始录音，再点一次停止并自动提交（转写结果 ≥ 3 个词时）。短于 3 个词的结果只插入不提交，防止误触。

无空格语言的自动提交（v2.1.195 修复）：自动提交此前靠"数空格分词"判断 ≥3 词，导致不使用空格分词的语言（日文、中文、泰文等）转写完后永远不触发自动提交。v2.1.195 修复了这一点——这些语言现在也能正确自动提交。来源：Claude Code changelog v2.1.195 —— "Fixed voice dictation auto-submit never firing for languages written without spaces (Japanese, Chinese, Thai)"。

• 第一次点击只在 prompt 为空时才触发录音（不影响正常打空格）
• 录音在 15 秒静音或累计 2 分钟后自动停止

4. Hold 模式的自动提交

在 Hold 模式下，松开键后默认等待你手动按 Enter。在用户设置文件中加 autoSubmit: true 可改为松开即发送（要求转写结果 ≥ 3 个词）：

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

监控 / 控制 / 键位

默认触发键是 Space，对应 Chat context 的 voice:pushToTalk action。可在 ~/.claude/keybindings.json 重绑定：

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

space: null 在此仅为可读性，省略也不影响行为——自定义绑定会替换默认的 Space，而非叠加。

键位选择建议：

保存 / 配置 / 集成

持久化设置（写入用户 settings 文件，跨会话生效，无需每次运行 /voice）：

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

听写语言：跟随全局 language 配置项，默认英文。支持 20 种语言（含日文、韩文、俄文等；官方清单不含中文）。可在 /config 里改，或直接写 settings：

{
  "language": "japanese"
}

语言值支持 BCP 47 代码（如 ja）或语言名称字符串（如 "japanese"）。若 language 填了不支持的值，/voice 启用时会警告并自动 fallback 到英文转写（不影响 Claude 的文本回复语言）。

转写词典针对编程词汇做了优化，regex、OAuth、JSON、localhost 等开发术语可被正确识别。当前项目名和 git 分支名会被自动加入识别提示。

VS Code 扩展：同样支持语音听写，账户要求相同。不支持 VS Code Remote（SSH / Dev Containers / Codespaces），因为麦克风在本地而扩展运行在远端主机。

Agent view：在 agent view 的 dispatch 输入框或 peek panel reply 获得焦点时，hold 或 tap 触发键同样有效，可对后台 session 进行语音输入。

运行约束 / 限制

跟同类原语对比

经典使用场景

• 双手忙碌（翻阅代码或文档）时，tap 模式下不触碰键盘即可下达重构指令
• 在 hold 模式下先键入代码片段，再按住 Space 补充口述说明，两者合并成一条完整 prompt
• 用非英文母语的开发者配置 language 后，以母语描述需求、Claude 用母语回复
• Agent view 中对后台运行的 session 进行语音追加指令，无需切换焦点

常见坑

1. 按住 Space 只是打出空格，不触发录音：语音听写处于关闭状态。运行 /voice hold 启用。若启用后仍无反应（只出现一两个空格后无波形），说明终端禁用了 key-repeat——改用 tap 模式（/voice tap）或绑定修饰键组合。

2. Tap 模式点 Space 打出空格而非录音：Tap 模式第一次点击只在 prompt 为空时才触发录音。清空输入框后再试。

3. WSL 上安装 SoX 后仍报错：WSL 通过 PulseAudio 路由音频，须额外安装 PulseAudio 后端：

   sudo apt install sox libsox-fmt-pulse
   

   复制

   单独 apt install sox 只装 ALSA 后端，WSL 没有 /dev/snd 设备，无法录音。

4. macOS 终端未出现在隐私设置的麦克风列表中：无法直接添加，需重置权限状态：

   tccutil reset Microphone com.apple.Terminal
   # iTerm2 用 com.googlecode.iterm2
   

   复制

   完整退出（Cmd+Q）并重新启动终端，再运行 /voice 触发系统权限弹窗。

5. 连续启动失败后语音被自动暂停（Voice input is failing repeatedly and has been paused）：Claude Code 检测到多次连续启动失败后暂停新会话，直到有一次成功。通常是无音频设备（如无头服务器、被拒绝的权限）。修复底层原因后重新触发 /voice。

关闭 / 退出

/voice off

语音设置跨会话持久化，/voice off 只关闭当前及后续会话的语音功能。如要彻底清除，在 settings 文件中删除或将 enabled 改为 false。

来源

• Voice dictation — Claude Code Docs
• Commands — Claude Code Docs