安裝與權限

完成安裝並正確授權後，全域熱鍵與語音輸入才能穩定運作。本頁按真實安裝順序展開；下圖為 自動生成的介面示意（系統設定 / 安裝 / 選單列 HTML 複刻 + Releases 實頁截圖）；可用本機實拍替換 public/screenshots/ 下對應 PNG。

系統要求

• 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.webp）

2. 安裝到固定路徑

1. 拖入應用程式
   將 VoiceHotkey.app 拖到 應用程式（Applications） 資料夾。
   也可拖到使用者目錄下的應用程式：~/Applications。

2. 退出 DMG（可選）
   安裝完成後可退出磁碟映像，下載的 DMG 可保留作備份。

3. 記住啟動路徑
   之後請 始終從同一路徑 啟動，例如：

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

圖 2 · DMG 視窗：拖入 Applications（介面示意 · install-02-dmg.webp）

圖 3 · Finder 中確認 App 路徑（介面示意 · install-03-path.webp）

不要從「下載」資料夾長期執行

從 ~/Downloads 或解壓臨時目錄直接開啟 App，路徑/簽名一變，macOS 會把 輔助功能 當成另一個應用程式，表現為：熱鍵失靈、權限「明明開了卻無效」。請安裝到 Applications 後再授權。

3. 首次開啟

1. 啟動 App
   在 Launchpad / Finder 中開啟 VoiceHotkey。若出現「無法驗證開發者」，按系統提示在 隱私與安全性 中允許開啟（已公證建置通常更順暢）。

2. 看選單列
   螢幕右上角應出現麥克風樣式的選單列圖示。沒有圖示時：檢查是否被選單列摺疊，或 App 是否已退出。

3. 走完引導（Onboarding）
   首次啟動會彈出 快速設定（歡迎 → 權限 → 方案說明 → 完成）。
   可在引導裡直接申請權限，也可稍後在系統設定中處理。

圖 4 · 選單列圖示（介面示意 · install-07-menubar.webp）

圖 5 · 引導中的權限步驟（介面示意 · install-06-onboarding.webp）

4. 授予輔助功能

輔助功能用於：全域熱鍵、把文字插入游標、注入快捷鍵。沒有它，按熱鍵通常完全沒反應。

1. 開啟 系統設定 → 隱私與安全性 → 輔助功能。
2. 點按列表左下角 +（或開關旁的鎖/編輯），新增 VoiceHotkey.app。
3. 確認列表中的路徑是你正在執行的那個（/Applications/... 或 ~/Applications/...）。
4. 將開關設為 開啟。
5. 若列表裡有多個「VoiceHotkey」或灰色舊條目：刪掉舊項，只保留目前路徑下的一項，然後 完全退出 App 再開啟。

圖 6 · 系統設定 · 輔助功能（介面示意 · install-04-accessibility.webp）

從 App 內跳轉

設定 → 通用（或引導頁）通常提供開啟輔助功能設定的按鈕；授權後回到 App，選單列狀態應不再提示「需輔助功能」。

5. 授予麥克風

真實語音輸入需要麥克風。示範模式下可不錄音，正式使用請授權。

1. 開啟 系統設定 → 隱私與安全性 → 麥克風。
2. 找到 VoiceHotkey 並開啟開關。
3. 首次錄音時，系統也可能彈出授權對話框——請選 允許。
4. 若使用外接麥克風 / 耳機麥克風，在 系統設定 → 聲音 → 輸入 中確認輸入設備正確；App 通用 頁若提供麥克風選擇，保持與系統一致或選自動。

5b. 語音辨識（僅 Apple 引擎）

使用 Apple Speech / SpeechAnalyzer 時，系統還會要求 語音辨識 權限（SFSpeechRecognizer）。雲端引擎（豆包、Whisper 等）一般 不 依賴此項。

1. 開啟 系統設定 → 隱私與安全性 → 語音辨識。
2. 允許 VoiceHotkey。
3. 若某語言不可用，在系統設定中下載對應語言套件，或換引擎。

圖 7 · 系統設定 · 麥克風（介面示意 · install-05-microphone.webp）

6. 權限核對清單

授權完成後，在 App 內快速確認：

檢查項	期望
選單列圖示	可見且可點開選單
設定 → 通用 · 權限區	輔助功能、麥克風已授權；Apple 引擎時語音辨識也已授權
熱鍵試按	出現錄音浮層 / 狀態變化（示範模式也會有反饋）
安裝路徑	與輔助功能列表中的條目一致

仍異常時見 故障排查。

下一步

第一次配置關閉示範模式、選擇辨識引擎、確認熱鍵並試打字。

快捷鍵與錄音短按 / 長按、快速發送與取消。