Mac 终端里听写没反应？先查安全键盘输入

听写在备忘录里可用，到了 Terminal 或 iTerm2 就失效时，先检查「安全键盘输入」（Secure Keyboard Entry），再动麦克风设置。安全输入可能影响全局快捷键与自动粘贴，但它只是一个可能原因，不代表终端里的每次失败都相同。

Ducduc 在自动插入前检查安全输入。已经完成的结果可在粘贴受阻时保存在复制卡片与历史记录里。如果录音一开始就被安全输入挡住，则并没有产生转写。先分清这一点，才能决定是找回文字，还是修复触发键。

本篇于 2026 年 10 月 17 日核对终端文档与 Ducduc 源码，不代表已测试每种终端、macOS 版本或 SSH 配置。

先按症状排查

症状	优先检查
所有 App 里触发键都没反应	辅助功能权限、实际配置的快捷键、fn 冲突
气泡随声音变化，但没有转录	识别语言、语音资源与麦克风输入
其他地方能用，终端在前台就不行	安全键盘输入，以及触发键是否到达 App
有转录，但出现复制卡片	卡片原因：安全输入、目标改变或无法验证插入

症状吻合时，先看 fn 快捷键冲突或语言模型设置。不要因为插入失败就重新安装识别模型。

安全键盘输入在限制什么？

macOS 的安全事件输入限制其他进程收到键盘事件。Apple 归档的技术说明 TN2150介绍系统范围的影响；iTerm2 菜单文档也说明安全键盘输入可能让其他程序的全局快捷键失效。

纯修饰键与普通按键的快捷键可能有不同表现。裸 fn 或 Command 与自定义组合键可能不同，但不应保证某个触发键在所有键盘和 macOS 版本里都能使用。

Apple 在终端安全键盘输入说明中介绍了这个选项。检查 Terminal → Secure Keyboard Entry，或 iTerm2 对应菜单项。密码提示或另一个 App 也可能持有安全输入；前台终端不一定就是持有者。

检查菜单，找回文字，再测试

1. 先完成密码或身份验证，聚焦普通输入位置，不要在密码提示里测试听写。
2. Apple 终端检查 Terminal → Secure Keyboard Entry（安全键盘输入），iTerm2 检查 iTerm2 → Secure Keyboard Entry。勾选说明该终端的选项已开启；其他 App 也可能另外启用安全输入。
3. Ducduc 已经产生文字时，点击 复制，或打开 听写历史。聚焦目标输入框，亲自用键盘粘贴，先不按 Enter。
4. 在备忘录中用普通短语测试实际配置的触发键。那里能用，就回到实际终端 prompt 再试一次；处处不能用，查辅助功能与触发键配置。
5. 验证完成后仍疑似卡在安全输入状态，可先保存工作，在合适时退出并重开可疑 App，再检查菜单。不要为了试快捷键强制退出尚有未保存工作的终端会话。

是否调整安全键盘输入，由你的工作需求决定；先理解它用于限制其他 App 观察按键。手动找回文字，让已经完成的转写不必依赖自动粘贴。触发键测试成功，也不能证明插入必然成功，这是两个阶段。

Claude Code 原生 /voice 使用终端的麦克风权限，Ducduc 使用自己的权限。/voice 报麦克风错误、Ducduc 却能用时，按 Claude Code 指南处理；改 Ducduc 的识别语言不会给终端授予麦克风权限。

Ducduc 无法安全粘贴时会怎样？

当前插入流程检查辅助功能、安全输入以及记录下来的目标。在真正发出粘贴按键前，还会再次检查。路由到其他 App 的 AI 指令也使用受保护的粘贴流程，激活另一个 App 不代表可以绕过安全输入。

情况	预期处理
安全输入开启	提供复制卡片，不自动粘贴
光标在密码框	不自动插入密码框
App、输入框或已知选区改变	提供复制卡片，避免粘到错误位置
回读确认粘贴没有落下	提供复制卡片
输入框无法回读	不能始终验证送达；文字没出现时到历史记录找

点击「复制」，结果进入剪贴板，大卡片关闭，出现小型「已复制」提示，再由你决定粘到哪里。复制卡片不等于丢字，不必因为首次粘贴被阻止就反复口述相同请求。

选中文字后的语音编辑，替换时更严格：需要可写的目标，以及仍然有效的选区。给编码工具的语音输入区分一般听写与 AI 指令路由。

确认光标在 Agent 输入框，还是普通 shell

同一个终端窗口，可能正在显示编程 Agent 输入框、普通 shell、REPL 或密码提示。同一句粘贴文字在其中的含义不同。下面是写给 Agent 的模拟示例：

解释为什么部署失败，先检查日志，不要重新部署。

在 Agent 输入框，发送前检查请求和“不重新部署”的约束都到了；普通 shell 提示下，不要把这句话当命令提交。可执行命令的引号、参数和路径需要逐字核对；文字整理得通顺，不代表 shell 语法已验证。

第一次送达测试可以不发送。成功标准是句子只出现一次，并在目标输入框里。长粘贴被 Agent 输入框折叠成占位符时，先看目标输入行为说明，再判断是否丢字。

剪贴板怎样恢复？

Ducduc 按一个文字块粘贴。合成的剪贴板操作会串行执行，第二次操作不能覆盖仍在进行中的粘贴：

1. 校验目标，保存剪贴板项目与数据类型。
2. 把听写文字放进剪贴板，并标记为临时内容。
3. 再次检查剪贴板所有权与目标，短暂延迟后只发送一次 ⌘V。
4. 等目标读取的时间窗口结束，只在 Ducduc 仍持有那次剪贴板变更时恢复快照。

这段时间里你复制了新内容，以新内容为准。不遵守临时标记的剪贴板管理器仍可能记录听写文字。目标 App 读取很慢时也可能晚于恢复窗口；定时恢复不是插入成功的证明。

点击「复制」是有意保留的复制，文字不标记为临时，也不自动恢复覆盖。处理机密文字时，这些限制需要与云端清稿分开看。隐私与数据流向指南说明后者。

SSH 和 tmux 会改变这个规则吗？

Ducduc 粘贴到的是本地终端模拟器。Shell 跑在哪里，不会改变 Mac 的安全输入检查。远端 sudo 或 SSH 密码交互是否产生影响，取决于本地终端怎样处理它。

需要 Mac 独立听写输入层时，可试用 Ducduc，先在备忘录，再在实际终端测试不敏感短句。有用的反馈包含 App 与 macOS 版本、触发键、录音有没有开始、复制卡片提示；不必附凭据或私密转写内容。