Mac 上 Claude Code 语音输入：设置与排障

Claude Code /voice 有哪些限制？

Claude Code 原生听写适合直接向它的输入框说话。选择前先检查认证方式、录音模式、语言，以及麦克风在哪台机器。需要中英混说、跨 App 输入，或让识别音频留在 Mac 时，再考虑独立听写 App。

本文由 Ducduc 制作者编写，2026 年 10 月 21 日核对官方文档，并以公开 Ducduc v0.3.8 为产品边界。我们没有做同一音频集的对比，因此不按速度或准确率排名。

Voice mode 和 Dictation 是一回事吗？

听写把语音变成文字 prompt；双向语音对话还会读出回答。Anthropic 的语音模式说明区分了这两种操作。Claude Code 听写不等于对话式语音模式。本文介绍 CLI 的 /voice 输入，不把 Claude 桌面或手机 App 的每个麦克风入口混在一起。

在 Mac 开始听写，检查后再发送

在本地终端打开 Claude Code，以 Claude.ai 账号认证，执行 /voice hold。
macOS 询问时，允许这个终端访问麦克风。权限属于实际录音的 App。
用 /config 设置口述语言，在输入框按住 Space，看到听音指示后说一条无敏感信息的测试要求，再松开。
检查转写后才按 Enter。可合并下文设置明确关闭 autoSubmit；点击录音模式的发送行为不同。

只需系统听写时，也可先查看 Apple 的 Mac 听写指南，在实际终端输入框试用。能否插入仍取决于目标控件；应因具体工作流需要选择独立工具，而非默认原生听写不存在。

原生录音、发送与使用条件

下表依据 Anthropic 语音文档：

问题	官方说明
谁能使用？	需要 Claude.ai 认证；直接 API Key 或第三方提供方配置不适用
在哪里识别？	音频流发送到 Anthropic 转写
能在远程录音吗？	需要本地麦克风；不支持 SSH、云会话和 VS Code Remote
转写占 `/usage` 额度吗？	转写不占；发送 prompt 是后续 Agent 交互
停止就会发送吗？	按住模式通常等 Enter，`autoSubmit` 可改变行为；点击模式会发送至少三个词的转写
点击录音最长多久？	静音 15 秒或总录音两分钟后停止

原生听写要先检查再发送，可以把下面的 voice 对象合并进用户设置 ~/.claude/settings.json，保留其他已有设置。这会选择按住模式并关闭自动提交：

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

Claude Code 语音输入没反应时怎么查

现象	先检查什么
不认识 `/voice`，或要求 Claude.ai 账号	核对实际认证与提供方，不要为了听写移除工作需要的配置
按住 Space 一直添加空格	确认已开启按住模式；长按识别依赖重复按键事件
点击 Space 只输入空格	点击录音仅在输入框为空时开始；它也可能自动提交成稿
麦克风被拒绝，或录音无声	分别检查终端的麦克风权限、macOS「声音 → 输入」设备
提示语音连接失败	检查转写服务连接；录到了静音属于另一类问题
使用 SSH 或 VS Code Remote	原生听写需要本地麦克风，可考虑本地输入文字再粘贴

这些步骤依据 Anthropic 官方排障，不是我们的实测数据。组织策略由管理员控制。截至本次核对，官方语言列表没有中文，另见中文输入指南。日语、韩语、法语、德语和西班牙语均在列表内，适合时可先试原生听写。

独立 Mac 输入层改变什么

Ducduc 在 macOS 14 或更新版本提供文字输入：本机识别、整理转写、安全时插入。它不运行编程任务，也不替 Claude Code 提供认证。

你的需要	Ducduc 路径	要检查的边界
prompt、邮件和笔记共用一个键	在聚焦的输入框普通听写	输入框需接受插入，部分目标要手动粘贴
中文要求夹杂英文术语	选择中文（含中英混说），加入项目词汇	对照原稿与成稿，精确标识符仍可能错
远程编程会话	在 Mac 听写，粘贴到本地 SSH 客户端	传递的是文字，不转发麦克风；本地终端决定能否送达
转写文字不经过云端清稿	Ducduc 离线模式与本地 Ollama 模型	下载模型、关闭 Ollama 云功能，并保持本地服务运行
口述要求整理成 prompt	开启在 AI 编码工具里写成 prompt	清稿旨在保留原意，不补齐没说出的需求

Ducduc 免费安装不需要账号，内置云端清稿有每周额度。以当前方案条款为准；转写不计某项额度，不代表后续 Agent 工作都免费。

示例：Mac 终端连接远端机器

下面是模拟工作流，不代表已逐一测试每种 SSH 客户端和服务器。假设 Claude Code 跑在远端，你用 Mac 上的 iTerm2 连接：

照常连接远程会话，聚焦 Claude Code 的输入框，确认不是普通 shell 或密码提示。
在 Mac 启动 Ducduc，口述一句短要求，例如「解释失败的测试，不要修改任何文件」。
结束录音，在同一输入框等待。检查文字是否出现，并保留“不改文件”的约束。
出现复制卡片时，复制结果，自己粘贴到目标 prompt；检查后再按 Enter。

关键在于录音发生在哪里。远端 CLI 没有麦克风，仍可能收到本地终端粘贴的文字。这不能保证终端暴露了足够的辅助功能信息，或接受每次粘贴；送达问题见安全输入排障。

粘贴折叠与文字缺失不同

如果已安装的终端界面显示折叠粘贴预览，仅凭折叠不能判断丢字，应在发送前检查草稿。当前终端配置文档已不再说明本文此前引用的「800 个字符或三行」阈值，因此不把它当成当前通用规则。

怀疑丢字时，先对照 Ducduc 历史与输入框。历史完整而粘贴折叠，先检查目标预览；原始转写不完整，查识别；出现复制卡片，查送达。在确认失败阶段前重录整段，可能反而产生重复指令。

分开看音频、清稿文字与 Agent 会话

Ducduc 的语音识别在本机运行。默认清稿把文字发送到 Ducduc 服务及其配置的模型提供方，远程 BYOK 模型直接收到文字。下载本地 Ollama 模型、关闭其云功能并开启 Ducduc 离线模式后，可以把清稿留在 Mac；仅有 localhost 地址不能证明推理在本机。macOS 14–15 缺少语言资源时，识别可能被阻止，不会因此悄悄上传音频。

本地听写不会把 Claude Code 变成本地服务。发送 prompt 后，仍按 Agent 自己的配置和政策处理。先读Ducduc 数据流向；确实需要这个边界时，再配置本地清稿。

用一次短试用做选择

原生 /voice 的语言、认证和宿主条件适合时，可以先用原生。需要独立 Mac 输入流程时，下载 Ducduc，在实际使用的终端或编辑器里试一句不敏感的短要求，检查词语、约束、位置与发送行为。这四项比没有测量依据的“更准确”更能帮助你选择。