跳到內容
VoiceHotkeyVoiceHotkeyVoiceHotkey Docs

故障排查

圖片採用英文標示，說明操作流程與資料路徑；實際介面以目前 App 與 macOS 為準。

按 現象 選擇章節並依次檢查。圖片是操作流程圖，用於說明排查路徑與功能範圍；實際介面以目前 App 與 macOS 為準。

開始前：收集這 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. 排除快捷鍵衝突 暫時退出與預設熱鍵衝突的工具：語音輸入預設 右 Command、命令預設 滑鼠中鍵（輸入法、啟動器、視窗管理）再試。

操作流程圖：核對路徑並清理輔助使用舊項目
核對路徑並清理輔助使用舊項目（操作流程圖）

有錄音但沒有文字

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

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

檢查清單

Section titled “檢查清單”
  • 麥克風權限是否開啟、輸入裝置是否正確
  • 輸入模型是否已配置（雲引擎憑證 / Apple 或本機資源是否可用）
  • 僅本機模式是否擋住了目前雲引擎
  • 網路、服務商配額、Key 是否過期
  • 游標是否在可輸入的文字欄位里（部分安全輸入框會拒絕注入）

分步處理

Section titled “分步處理”

  1. 確認真實錄音準備狀態 新安裝預設真實 ASR，目前設定沒有 Demo 開關。先核對麥克風權限與輸入裝置；舊配置或測試環境的示範提示見 第一次配置。

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

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

  4. 引擎配置 設定 → 輸入模型：換 Apple 做對照，並確認所需語言資源可用。

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

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

  6. 輸出目標 設定 → 一般 → 輸出動作：歷史專用是內部模式，現行選單沒有這個選項；這個模式只保留記錄，不插入或自動複製。若選擇複製，請檢查剪貼簿。需要插入時選「插入到游標」並聚焦可編輯文字欄位。預設無可編輯焦點可回退複製到剪貼簿；部分終端 / 安全輸入框無法注入，可改試備忘錄。

操作流程圖：按狀態提示排查錄音與輸出
按狀態提示排查錄音與輸出（操作流程圖）
操作流程圖：僅本機模式範圍與授權聯網例外
僅本機模式範圍與授權聯網例外（操作流程圖）

權限反覆丟失

Section titled “權限反覆丟失”

典型表現：昨天還能用，今天熱鍵又失效；輔助使用里像有記錄卻不生效。

原因（最常見）

Section titled “原因（最常見）”
原因 說明
路徑變了 從下載目錄、不同資料夾或其它構建路徑啟動
簽名/版本替換 覆蓋安裝後系統視為新 App
重復項目 清單裡多個 VoiceHotkey，系統綁錯項目

修復步驟

Section titled “修復步驟”
  1. 只保留一份 App：放在 /Applications 或 ~/Applications。
  2. 完全退出 VoiceHotkey（選單列 → 退出）。
  3. 系統設定 → 輔助使用：刪除過時的 VoiceHotkey 項目。麥克風頁核對目前 App 的授權開關。
  4. 從固定路徑啟動 App，重新授權（引導或設定 → 一般）。
  5. 以後只從這個路徑打開；不要在多個安裝路徑之間來回切換。

潤色 / 翻譯沒有變化

Section titled “潤色 / 翻譯沒有變化”
  • 文字處理里是否開啟了潤色 / 使用了翻譯熱鍵
  • 後處理模型是否可用（雲端憑證 / 本機模型 / Apple 翻譯語言資源）
  • 僅本機模式是否攔截非 localhost API
  • 潤色失敗時是否保留了原文；也要檢查歷史與狀態提示
  1. 設定 → 文字處理：確認大模型潤色已啟用，翻譯用的是 翻譯熱鍵 而非普通語音輸入熱鍵。
  2. 雲端 LLM 核對憑證、模型與端點；本機 Spark 核對模型已安裝。Apple 原生翻譯需 macOS 26+ 與對應語言資源，不要求 LLM Key；不能在低版本系統中使用。
  3. 僅本機模式阻止公網 LLM；換本機模型 / 迴環端點，或按需要暫時關閉該模式。App 自適應潤色還需試用 / Pro。
  4. 仍失敗：先保證純語音輸入有字，再開潤色，縮小問題範圍。

語音命令完全沒反應

Section titled “語音命令完全沒反應”
  • 設定 → 語音命令 頂部「啟用語音命令」是否打開
  • 命令熱鍵是否與語音輸入/翻譯衝突，且輔助使用已授權
  • 所需執行能力是否被關掉（例如「允許熱鍵」）
  • 使用者詞典項目是否啟用、短語是否匹配（先精確再模糊）

目前沒有內建指令片語目錄；請創建並啟用使用者項目。自由指令片語與選區改寫需要試用 / Pro 的可用意圖模型。系統視窗動作需輔助使用，提醒 / 日程需對應完整訪問。見 語音命令。

終端命令不執行

Section titled “終端命令不執行”

目前版本沒有 Shell 執行功能，也沒有「允許終端命令」、Shell 確認或環境設定。舊 Shell 項目不受支援；不要通過修改試用 / Pro 或查找已移除的開關排查。請改用支援的使用者詞典動作、已有快捷指令或系統控制，見 終端命令現狀。

授權功能受限或無法啟用

Section titled “授權功能受限或無法啟用”

查看 設定 → 授權 的方案。Free 可用基礎潤色與使用者詞典，但意圖、選區改寫、自適應潤色、App 內檔案轉寫與自訂歷史需試用 / Pro。Free 與試用期間均顯示「啟用 Pro」表單，可隨時啟用；已啟用 Pro 使用「更換金鑰…」。

若裝置超限，在聯網的舊 Mac 上停用；解綁請求失敗時本機停用不保證釋放雲端名額。網路 / 服務故障可觸發本機驗簽回退，明確的吊銷 / 無效 / 超限回應不會。詳見 授權與條款。

操作流程圖：授權門檻、啟用入口與裝置名額
授權門檻、啟用入口與裝置名額（操作流程圖）

按場景快速對照

Section titled “按場景快速對照”
  1. 安裝路徑 + 雙權限
  2. 核對麥克風與輸入裝置
  3. 配置任一可用辨識引擎
  4. 在備忘錄試熱鍵

仍無法解決

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