跳转到内容
VoiceHotkeyVoiceHotkey Docs

故障排查

按 现象 选择章节。每一节都是可勾选的检查顺序；虚线框为截图占位（public/screenshots/ts-*.svg）。

开始前：收集这 5 项

Section titled “开始前：收集这 5 项”

排查或反馈前先记下：

  1. macOS 版本（系统设置 → 通用 → 关于本机）
  2. VoiceHotkey 版本（设置 → 关于）
  3. 听写引擎名称（设置 → 听写模型）
  4. 是否开启仅本地模式（设置 → 通用 → 隐私）
  5. App 路径（在 Finder 中对 App 选「显示简介」看位置）

热键完全没反应

Section titled “热键完全没反应”

典型表现：按下热键后没有录音浮层、菜单栏状态不变、系统也无任何提示。

检查清单

Section titled “检查清单”
  • 菜单栏是否仍有 VoiceHotkey 图标（App 是否在运行）
  • 辅助功能是否勾选了当前路径下的 VoiceHotkey
  • 是否从 /Applications 或 ~/Applications 启动（而非下载目录）
  • 热键是否与其它软件 / 系统快捷键冲突
  • 设置 → 热键页是否提示「需要辅助功能」

分步处理

Section titled “分步处理”

  1. 确认进程
    点菜单栏图标应能弹出菜单。若无图标：从 Applications 再启动一次。

  2. 核对辅助功能
    系统设置 → 隐私与安全性 → 辅助功能。

    • 列表中必须有 VoiceHotkey，且开关为开。
    • 路径必须等于你正在运行的 App。
    • 有多个旧条目时：全部删除 → 只添加当前 App → 退出并重开 VoiceHotkey。

  3. 固定安装路径
    把 App 放进 Applications 后，只从该处启动。参见 安装与权限。

  4. 重录热键
    设置 → 热键 → 语音输入 → 录入一个少冲突的组合（例如再加一个修饰键）。

  5. 排除快捷键冲突
    暂时退出与默认热键冲突的工具：听写默认 ⌃⌥Space、命令默认 ⌥Space（输入法、启动器、窗口管理）再试。

截图占位：辅助功能列表清理旧条目
图 A · 辅助功能列表：只保留当前路径（占位 · ts-01-accessibility-list.svg）

有录音但没有文字

Section titled “有录音但没有文字”

典型表现：浮层或状态显示在听，结束后输入框仍空，或一直停在处理中。

检查清单

Section titled “检查清单”
  • 演示模式是否已关闭
  • 麦克风权限是否开启、输入设备是否正确
  • 听写模型是否已配置（云引擎 Key / Apple 是否可用）
  • 仅本地模式是否挡住了当前云引擎
  • 网络、服务商配额、Key 是否过期
  • 光标是否在可输入的文本框里（部分安全输入框会拒绝注入）

分步处理

Section titled “分步处理”

  1. 关闭演示模式
    设置 → 通用 → 演示模式 设为关。演示模式不走真实麦克风转写。

  2. 看菜单栏状态文案
    菜单里常会提示：需麦克风、未配置引擎、仅本地拦截等。按提示逐项修。

  3. 麦克风
    系统设置中打开 VoiceHotkey 的麦克风；用语音备忘录试一下系统能否录音，排除硬件问题。

  4. 引擎配置
    设置 → 听写模型：换 Apple 本机 做对照。

    • Apple 能出字、云引擎不能 → 查 Key / 网络 / 配额。
    • 全部不能 → 查权限、仅本地、光标焦点。

  5. 仅本地模式
    若开启了 仅本地模式 却选了公网引擎，转写会失败。改引擎或临时关闭仅本地。

  6. 输出目标
    设置 → 文本后处理 → 输出动作：确认不是「仅历史」；试「插入到光标」。部分终端 / 安全输入框无法注入，可改试备忘录。

截图占位：菜单栏状态提示
图 B · 菜单栏状态提示（占位 · ts-02-menubar-status.svg）
截图占位：仅本地模式开关
图 C · 仅本地模式（占位 · ts-03-local-only.svg）

权限反复丢失

Section titled “权限反复丢失”

典型表现：昨天还能用，今天热键又失效；辅助功能里像有记录却不生效。

原因（最常见）

Section titled “原因（最常见）”
原因 说明
路径变了 从下载目录、不同文件夹、或 make run 的临时包启动
签名/版本替换 覆盖安装后系统视为新 App
重复条目 列表里多个 VoiceHotkey，系统绑错条目

修复步骤

Section titled “修复步骤”
  1. 只保留一份 App：放在 /Applications 或 ~/Applications。
  2. 完全退出 VoiceHotkey（菜单栏 → 退出）。
  3. 系统设置 → 辅助功能 / 麦克风：删除所有 VoiceHotkey 相关条目。
  4. 从固定路径启动 App，重新授权（引导或设置 → 通用）。
  5. 以后只从这个路径打开；开发调试时注意 debug/release 包路径不同也会触发重授。

润色 / 翻译没有变化

Section titled “润色 / 翻译没有变化”
  • 文本后处理里是否开启了润色 / 使用了翻译热键
  • 后处理大模型是否配置了 Key
  • 仅本地模式是否拦截非 localhost API
  • 失败时是否其实插入了「原文」（属预期回退）
  1. 设置 → 文本后处理：确认润色风格不是关掉，翻译用的是 翻译热键 而非普通听写热键。
  2. 配置与听写独立的 LLM 提供商 Key（可与意图模型共用提供商钥匙串）。
  3. 关闭仅本地模式做一次对照，或把 Base URL 指到本机网关。
  4. 仍失败：先保证裸听写有字，再开润色，缩小问题范围。

语音命令完全没反应

Section titled “语音命令完全没反应”
  • 设置 → 语音命令 顶部「启用语音命令」是否打开
  • 命令热键是否与听写/翻译冲突，且辅助功能已授权
  • 「允许快捷键」是否被关掉（仅词典快捷键会失败）
  • 用户词典条目是否启用、短语是否匹配（先精确再模糊）

见 语音命令。

终端命令不执行

Section titled “终端命令不执行”
  • 「启用语音命令」总开关是否打开
  • 是否在试用或 Pro（Free 无终端命令）
  • 设置 → 语音命令 是否开启「允许终端命令」（不在「通用」页）
  • 确认框是否点了取消
  • 命令是否命中危险模式黑名单
  • 若靠意图生成：意图模型是否开启且配置成功；若靠用户词典：条目是否为终端类型且已启用

见 终端命令 与 方案对比。

截图占位：许可证页
图 D · 许可证 / 方案（占位 · ts-04-license.svg）

按场景快速对照

Section titled “按场景快速对照”
  1. 安装路径 + 双权限
  2. 关闭演示模式
  3. 配置任一可用听写引擎
  4. 在备忘录试热键

仍无法解决

Section titled “仍无法解决”
  1. 再走一遍 第一次配置 的「端到端试一次」。
  2. 准备好文首 5 项信息。
  3. 到 联系与反馈 提交（GitHub Issues 等）。
安装与权限DMG、路径、辅助功能与麦克风。
第一次配置演示模式、引擎、热键与自测。