跳到內容
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 的工具（輸入法、啟動器、窗口管理）再試。

截圖佔位：輔助功能列表清理舊條目
圖 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 “終端命令不執行”
  • 是否在試用或 Pro（Free 無終端命令）
  • 設定 → 語音命令 是否開啟「允許終端命令」
  • 確認框是否點了取消
  • 命令是否命中危險模式黑名單
  • 意圖模型是否開啟且配置成功

見 終端命令 與 方案對比。

截圖佔位：許可證頁
圖 D · 許可證 / 方案（佔位 · ts-04-license.svg）

按場景快速對照

Section titled “按場景快速對照”
  1. 安裝路徑 + 雙權限
  2. 關閉演示模式
  3. 配置任一可用聽寫引擎
  4. 在備忘錄試熱鍵

仍無法解決

Section titled “仍無法解決”
  1. 再走一遍 第一次配置 的「端到端試一次」。
  2. 準備好文首 5 項信息。
  3. 到 聯繫與反饋 提交（GitHub Issues 等）。
安裝與權限DMG、路徑、輔助功能與麥克風。
第一次配置演示模式、引擎、熱鍵與自測。