跳到內容
VoiceHotkeyVoiceHotkey Docs

故障排查

按 現象 選擇章節。每一節都是可勾選的檢查順序；設定相關截圖由 UI 複刻生成（ts-03/ts-04 為 WebP）；系統/選單列（ts-01/ts-02）亦為可自動生成的介面示意 WebP。

開始前：收集這 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、命令 ⌃⌥C（輸入法、啟動器、視窗管理）再試。

介面示意：輔助功能列表清理舊條目
圖 A · 輔助功能列表：只保留目前路徑（介面示意 · ts-01-accessibility-list.webp）

有錄音但沒有文字

Section titled “有錄音但沒有文字”

典型表現：浮層或狀態顯示在聽，結束後輸入框仍空，或一直停在處理中。

檢查清單

Section titled “檢查清單”
  • 示範模式是否已關閉
  • 麥克風權限是否開啟、輸入設備是否正確
  • 輸入模型是否已配置（雲引擎 Key / Apple 是否可用）
  • 僅本機模式是否擋住了目前雲引擎
  • 網路、供應商配額、Key 是否過期
  • 游標是否在可輸入的文字框裡（部分安全輸入框會拒絕注入）

分步處理

Section titled “分步處理”

  1. 關閉示範模式
    設定 → 通用 → 示範模式 設為關。示範模式不走真實麥克風轉寫。

  2. 看選單列狀態文案
    選單裡常會提示：需麥克風、未配置引擎、僅本機攔截等。按提示逐項修。

  3. 麥克風
    系統設定中打開 VoiceHotkey 的麥克風；用語音備忘錄試一下系統能否錄音，排除硬體問題。

  4. 引擎配置
    設定 → 輸入模型：換 Apple 本機 做對照。

    • Apple 能出字、雲引擎不能 → 查 Key / 網路 / 配額。
    • 全部不能 → 查權限、僅本機、游標焦點。

  5. 僅本機模式
    若開啟了 僅本機模式 卻選了公網引擎，轉寫會失敗。改引擎或臨時關閉僅本機。

  6. 輸出目標
    設定 → 文字處理 → 輸出動作：確認不是「僅歷史」；試「插入到游標」。部分終端 / 安全輸入框無法注入，可改試備忘錄。

介面示意：選單列狀態提示
圖 B · 選單列狀態提示（介面示意 · ts-02-menubar-status.webp）
介面預覽：僅本機模式開關
圖 C · 僅本機模式（UI 複刻 · ts-03-local-only.webp）

權限反覆丟失

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 · 許可證 / 方案（UI 複刻 · ts-04-license.webp）

按場景快速對照

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

仍無法解決

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