コンテンツにスキップ
VoiceHotkeyVoiceHotkey Docs

トラブルシューティング

症状 ごとにセクションを選んでください。各節にチェックリストと順番どおりの対処があります。破線の枠はスクリーンショット用プレースホルダ（public/screenshots/ts-*.svg）です。

始める前に: 次の 5 点を控える

Section titled “始める前に: 次の 5 点を控える”
  1. macOS のバージョン
  2. VoiceHotkey のバージョン（設定 → このアプリについて）
  3. 音声認識エンジン名
  4. ローカルのみ のオン / オフ
  5. アプリのパス（Finder → 情報を見る）

ホットキーが無反応

オーバーレイなし、メニューバーの状態変化なし、システムの反応もなし。

チェックリスト

Section titled “チェックリスト”
  • メニューバーアイコンがある（アプリ起動中）
  • 現在の アプリパスにアクセシビリティが付いている
  • /Applications または ~/Applications から起動している
  • ホットキーがほかのアプリと衝突していない
  • ホットキーページがアクセシビリティ警告を出していない

手順

Section titled “手順”
  1. プロセス — メニューバーアイコンからメニューが開くこと。無い場合はアプリケーションから再起動。
  2. アクセシビリティ — システム設定 → プライバシーとセキュリティ → アクセシビリティ。VoiceHotkey は 1 行、正しいパス、スイッチオン。重複を削除し、アプリを終了して再起動。
  3. 安定したパス — インストールと権限 を参照。
  4. 再割り当て — 設定 → ホットキー → あまり使わない組み合わせを録り直す。
  5. 衝突 — ⌥Space を使うほかのツールを終了して再試行。
プレースホルダ: 整理されたアクセシビリティ一覧
図 A · アクセシビリティ一覧（プレースホルダ · ts-01-accessibility-list.svg）

録音するがテキストが出ない

オーバーレイは聴取中を示すが、欄は空のまま、または処理が終わらない。

チェックリスト

Section titled “チェックリスト”
  • デモモードがオフ
  • マイクが許可され、入力デバイスが正しい
  • エンジンが設定済み（キー / Apple の準備完了）
  • ローカルのみがクラウドエンジンを遮断していない
  • ネットワーク / クォータ / キーの有効性
  • 通常のテキスト欄にキャレットがある（セキュアフィールドは挿入を妨げることがある）

手順

Section titled “手順”
  1. 設定 → 一般 — デモモード をオフにする。
  2. メニューバーの状態を読む — マイクが必要、エンジン未設定、ローカルのみで遮断、など。
  3. マイク — VoiceHotkey を有効にし、ボイスメモなどでハードウェアを確認。
  4. エンジン — 対照として Apple を試す。Apple は動くがクラウドが失敗 → キー / ネットワーク / クォータ。
  5. ローカルのみ — ローカルのみ がオンのとき公衆エンジンは失敗する。
  6. 出力 — 後処理の 出力アクション がキャレット挿入であること。Terminal が注入を妨げる場合はメモで試す。
プレースホルダ: メニューバーの状態
図 B · メニューバーの状態（プレースホルダ · ts-02-menubar-status.svg）
プレースホルダ: ローカルのみのトグル
図 C · ローカルのみ（プレースホルダ · ts-03-local-only.svg）

権限がすぐ外れる

昨日は動いたのに今日はホットキーが死んでいる。アクセシビリティが中途半端に見える。

よくある原因

Section titled “よくある原因”
原因 説明
パスが変わった ダウンロード、別フォルダ、別ビルドのパス
署名 / 上書き 上書きインストールが別アプリ扱い
行の重複 誤ったアクセシビリティ行が紐づいている

直し方

Section titled “直し方”
  1. アプリケーションにアプリを 1 つだけ置く。
  2. VoiceHotkey を 完全に終了 する。
  3. アクセシビリティとマイクから VoiceHotkey の行をすべて削除する。
  4. 固定パスから起動し直して再許可する。
  5. いつも同じパスから開く（デバッグ版とリリース版は別パス扱い）。

仕上げ / 翻訳が変わらない

Section titled “仕上げ / 翻訳が変わらない”
  • 仕上げがオン / 翻訳 用ホットキーを使っている
  • 後処理の LLM キーが設定済み
  • ローカルのみが API を遮断していない
  • 失敗時は生の書き起こしが挿入されることがある（想定どおり）
  1. 設定 → テキスト後処理: 仕上げをオン。翻訳は専用ホットキー。
  2. LLM プロバイダのキーを設定。
  3. ローカルのみをオフにして比較するか、Base URL を localhost に向ける。
  4. 仕上げを有効にする前に、素の音声入力が動くことを確認。

シェルコマンドが動かない

Section titled “シェルコマンドが動かない”
  • Trial または Pro（Free ではない）
  • 設定 → 音声コマンド → ターミナルコマンドを許可 がオン
  • 確認ダイアログをキャンセルしていない
  • 危険ブロックリストに引っかかっていない
  • 意図モデルがオンで設定済み

シェルコマンド と プラン を参照。

プレースホルダ: ライセンスページ
図 D · ライセンス（プレースホルダ · ts-04-license.svg）

よくあるシナリオ

Section titled “よくあるシナリオ”
  1. パス + 両方の権限
  2. デモモードをオフ
  3. 動くエンジンを 1 つ
  4. メモでテスト

まだ解決しないとき

Section titled “まだ解決しないとき”
  1. 初回セットアップ の通しテストをやり直す。
  2. 冒頭の 5 点を集める。
  3. お問い合わせ から Issue を立てる。
インストールと権限DMG、パス、アクセシビリティ、マイク。
初回セットアップデモモード、エンジン、ホットキー、テスト。