故障排查
按 现象 选择章节并依次检查。图片是操作示意图，用于说明排查路径与功能范围；实际界面以当前 App 与 macOS 为准。
开始前：收集这 5 项
Section titled “开始前：收集这 5 项”排查或反馈前先记下：
- macOS 版本（系统设置 → 通用 → 关于本机）
- VoiceHotkey 版本（设置 → 关于）
- 识别引擎名称（设置 → 输入模型）
- 是否开启仅本地模式（设置 → 通用 → 隐私）
- App 路径（在 Finder 中对 App 选「显示简介」看位置）
热键完全没反应
Section titled “热键完全没反应”典型表现：按下热键后没有录音浮层、菜单栏状态不变、系统也无任何提示。
- 菜单栏是否仍有 VoiceHotkey 图标（App 是否在运行）
- 辅助功能是否勾选了当前路径下的 VoiceHotkey
- 是否从
/Applications或~/Applications启动（而非下载目录） - 热键是否与其它软件 / 系统快捷键冲突
- 设置 → 快捷键页是否提示「需要辅助功能」
-
确认进程
点菜单栏图标应能弹出菜单。若无图标：从 Applications 再启动一次。 -
核对辅助功能
系统设置 → 隐私与安全性 → 辅助功能。- 列表中必须有 VoiceHotkey，且开关为开。
- 路径必须等于你正在运行的 App。
- 有多个旧条目时：全部删除 → 只添加当前 App → 退出并重开 VoiceHotkey。
-
固定安装路径
把 App 放进 Applications 后，只从该处启动。参见 安装与权限。 -
重录热键
设置 → 快捷键 → 语音输入 → 录入一个少冲突的组合（例如再加一个修饰键）。 -
排除快捷键冲突
暂时退出与默认热键冲突的工具：语音输入默认右 Command、命令默认鼠标中键（输入法、启动器、窗口管理）再试。
有录音但没有文字
Section titled “有录音但没有文字”典型表现：浮层或状态显示在听，结束后输入框仍空，或一直停在处理中。
- 麦克风权限是否开启、输入设备是否正确
- 输入模型是否已配置（云引擎凭证 / Apple 或本机资源是否可用）
- 仅本地模式是否挡住了当前云引擎
- 网络、服务商配额、Key 是否过期
- 光标是否在可输入的文本框里（部分安全输入框会拒绝注入）
-
确认真实录音准备状态
新安装默认真实 ASR，当前设置没有 Demo 开关。先核对麦克风权限与输入设备；旧配置或测试环境的演示提示见 第一次配置。 -
看菜单栏状态文案
菜单里常会提示：需麦克风、未配置引擎、仅本地拦截等。按提示逐项修。 -
麦克风
系统设置中打开 VoiceHotkey 的麦克风；用语音备忘录试一下系统能否录音，排除硬件问题。 -
引擎配置
设置 → 输入模型：换 Apple 本机 做对照。- Apple 能出字、云引擎不能 → 查 Key / 网络 / 配额。
- 全部不能 → 查权限、仅本地、光标焦点。
-
仅本地模式
若开启了 仅本地模式 却选了公网引擎，转写会失败。改引擎或临时关闭仅本地。 -
输出目标
设置 → 通用 → 输出动作：历史专用是内部模式，现行选单没有这个选项；该模式只保留记录，不插入或自动复制。若选择复制，请检查剪贴板。需要插入时选「插入到光标」并聚焦可编辑文本框。默认无可编辑焦点可回退复制到剪贴板；部分终端 / 安全输入框无法注入，可改试备忘录。
权限反复丢失
Section titled “权限反复丢失”典型表现：昨天还能用，今天热键又失效；辅助功能里像有记录却不生效。
原因（最常见）
Section titled “原因（最常见）”| 原因 | 说明 |
|---|---|
| 路径变了 | 从下载目录、不同文件夹或其它构建路径启动 |
| 签名/版本替换 | 覆盖安装后系统视为新 App |
| 重复条目 | 列表里多个 VoiceHotkey，系统绑错条目 |
- 只保留一份 App：放在
/Applications或~/Applications。 - 完全退出 VoiceHotkey（菜单栏 → 退出）。
- 系统设置 → 辅助功能：删除过时的 VoiceHotkey 条目。麦克风页核对当前 App 的授权开关。
- 从固定路径启动 App，重新授权（引导或设置 → 通用）。
- 以后只从这个路径打开；不要在多个安装路径之间来回切换。
润色 / 翻译没有变化
Section titled “润色 / 翻译没有变化”- 文本处理里是否开启了润色 / 使用了翻译热键
- 后处理模型是否可用（云端凭证 / 本机模型 / Apple 翻译语言资源）
- 仅本地模式是否拦截非 localhost API
- 润色失败时是否保留了原文；也要检查历史与状态提示
- 设置 → 文本处理：确认大模型润色已启用，翻译用的是 翻译热键 而非普通语音输入热键。
- 云端 LLM 核对凭证、模型与端点；本地 Spark 核对模型已安装。Apple 原生翻译需 macOS 26+ 与对应语言资源，不要求 LLM Key；不能在低版本系统中使用。
- 仅本地模式阻止公网 LLM；换本地模型 / 回环端点，或按需要暂时关闭该模式。App 自适应润色还需试用 / Pro。
- 仍失败：先保证纯语音输入有字，再开润色，缩小问题范围。
语音命令完全没反应
Section titled “语音命令完全没反应”- 设置 → 语音命令 顶部「启用语音命令」是否打开
- 命令热键是否与语音输入/翻译冲突，且辅助功能已授权
- 所需执行能力是否被关掉（例如「允许热键」）
- 用户词典条目是否启用、短语是否匹配（先精确再模糊）
当前没有内置口令目录；请创建并启用用户条目。自由口令与选区改写需要试用 / Pro 的可用意图模型。系统窗口动作需辅助功能，提醒 / 日程需对应完整访问。见 语音命令。
终端命令不执行
Section titled “终端命令不执行”当前版本没有 Shell 执行功能，也没有「允许终端命令」、Shell 确认或环境设置。旧 Shell 条目不受支持；不要通过修改试用 / Pro 或查找已移除的开关排查。请改用支持的用户词典动作、已有快捷指令或系统控制，见 终端命令现状。
许可功能受限或无法激活
Section titled “许可功能受限或无法激活”查看 设置 → 许可证 的方案。Free 可用基础润色与用户词典，但意图、选区改写、自适应润色、App 内文件转写与自定义历史需试用 / Pro。Free 与试用期间均显示「激活 Pro」表单，可随时激活；已激活 Pro 使用「更换密钥…」。
若设备超限，在联网的旧 Mac 上停用；解绑请求失败时本机停用不保证释放云端名额。网络 / 服务故障可触发本地验签回退，明确的吊销 / 无效 / 超限响应不会。详见 许可证与条款。
按场景快速对照
Section titled “按场景快速对照”- 安装路径 + 双权限
- 核对麦克风与输入设备
- 配置任一可用识别引擎
- 在备忘录试热键
- 确认仍从 Applications 启动新版本
- 清辅助功能旧条目并重授
- 看关于页版本是否为预期
- 云引擎需可访问对应 API 域名
- 或改 Apple / 已安装本机模型 / 本机回环服务
- 仅本地模式 阻止公网 ASR / LLM 并暂停更新；商业许可请求仍可联网