安装与权限

完成安装并正确授权后，全局热键与听写才能稳定工作。本页按真实安装顺序展开；虚线框图为 截图占位，可用 App / 系统设置实拍替换 public/screenshots/ 下对应 SVG。

系统要求

• macOS 14 或更高
• Apple Silicon 或 Intel
• 可选：听写 / 大模型 API Key（BYOK）
• 正式听写需要：麦克风 + 辅助功能
• 使用 Apple 系统语音 时还需：系统设置 → 隐私与安全性 → 语音识别

1. 下载安装包

1. 打开 Releases
   浏览器访问
   VoiceHotkey-releases · Latest。

2. 下载 DMG
   资源列表中选择与当前架构匹配的 .dmg（通常为通用 / 标明 macOS 的构建）。不要下载 Source code 压缩包当作安装包。

3. 打开磁盘映像
   双击下载好的 DMG，等待出现安装窗口。

图 1 · Releases 页下载 DMG（占位 · 文件 install-01-releases.svg）

2. 安装到固定路径

1. 拖入应用程序
   将 VoiceHotkey.app 拖到 应用程序（Applications） 文件夹。
   也可拖到用户目录下的应用程序：~/Applications。

2. 弹出 DMG（可选）
   安装完成后可推出磁盘映像，下载的 DMG 可保留作备份。

3. 记住启动路径
   之后请 始终从同一路径 启动，例如：

   • /Applications/VoiceHotkey.app
   • 或 ~/Applications/VoiceHotkey.app

图 2 · DMG 窗口：拖入 Applications（占位 · install-02-dmg.svg）

图 3 · Finder 中确认 App 路径（占位 · install-03-path.svg）

不要从「下载」目录长期运行

从 ~/Downloads 或解压临时目录直接打开 App，路径/签名一变，macOS 会把 辅助功能 当成另一个应用，表现为：热键失灵、权限「明明开了却无效」。请安装到 Applications 后再授权。

3. 首次打开

1. 启动 App
   在 Launchpad / Finder 中打开 VoiceHotkey。若出现「无法验证开发者」，按系统提示在 隐私与安全性 中允许打开（已公证构建通常更顺畅）。

2. 看菜单栏
   屏幕右上角应出现麦克风样式的菜单栏图标。没有图标时：检查是否被菜单栏折叠，或 App 是否已退出。

3. 走完引导（Onboarding）
   首次启动会弹出 快速设置（欢迎 → 权限 → 方案说明 → 完成）。
   可在引导里直接申请权限，也可稍后在系统设置中处理。

图 4 · 菜单栏图标（占位 · install-07-menubar.svg）

图 5 · 引导中的权限步骤（占位 · install-06-onboarding.svg）

4. 授予辅助功能

辅助功能用于：全局热键、把文字插入光标、注入快捷键。没有它，按热键通常完全没反应。

1. 打开 系统设置 → 隐私与安全性 → 辅助功能。
2. 点击列表左下角 +（或开关旁的锁/编辑），添加 VoiceHotkey.app。
3. 确认列表中的路径是你正在运行的那个（/Applications/... 或 ~/Applications/...）。
4. 打开开关为 开启。
5. 若列表里有多个「VoiceHotkey」或灰色旧条目：删掉旧项，只保留当前路径下的一项，然后 完全退出 App 再打开。

图 6 · 系统设置 · 辅助功能（占位 · install-04-accessibility.svg）

从 App 内跳转

设置 → 通用（或引导页）通常提供打开辅助功能设置的按钮；授权后回到 App，菜单栏状态应不再提示「需辅助功能」。

5. 授予麦克风

真实听写需要麦克风。演示模式下可不录音，正式使用请授权。

1. 打开 系统设置 → 隐私与安全性 → 麦克风。
2. 找到 VoiceHotkey 并打开开关。
3. 首次录音时，系统也可能弹出授权对话框——请选 允许。
4. 若使用外置麦 / 耳机麦，在 系统设置 → 声音 → 输入 中确认输入设备正确；App 通用 页若提供麦克风选择，保持与系统一致或选自动。

5b. 语音识别（仅 Apple 引擎）

使用 Apple Speech / SpeechAnalyzer 时，系统还会要求 语音识别 权限（SFSpeechRecognizer）。云引擎（豆包、Whisper 等）一般 不 依赖此项。

1. 打开 系统设置 → 隐私与安全性 → 语音识别。
2. 允许 VoiceHotkey。
3. 若某语言不可用，在系统设置中下载对应语言包，或换引擎。

图 7 · 系统设置 · 麦克风（占位 · install-05-microphone.svg）

6. 权限核对清单

授权完成后，在 App 内快速确认：

检查项	期望
菜单栏图标	可见且可点开菜单
设置 → 通用 · 权限区	辅助功能、麦克风已授权；Apple 引擎时语音识别也已授权
热键试按	出现录音浮层 / 状态变化（演示模式也会有反馈）
安装路径	与辅助功能列表中的条目一致

仍异常时见 故障排查。

下一步

第一次配置关闭演示模式、选择听写引擎、确认热键并试打字。

热键与录音短按 / 长按、快速发送与取消。