voiceEnabled/voice設定でClaude Codeの音声入力を使う

Claude Code CLIの音声入力は、/voiceで都度オンにする使い方のほかに、settings.jsonへ書いて常時有効にする使い方があります。voiceEnabledは書けますが、v2.1.92でvoiceオブジェクトに置き換わった旧形式です。新しく書くならvoice.enabledを使います。この記事では設定ファイルの書き方、hold/tapの選び方、動かないときの症状別の見分け方を扱います。

voiceEnabledは旧形式、新規はvoiceオブジェクトで書く

/voiceを実行すると、Claude Codeがvoiceオブジェクトを設定ファイルへ書き込みます。手で書くのは、新しいマシンのセットアップや、チームで同じ設定を配りたいときです。

{
  "voice": {
    "enabled": true,
    "mode": "tap",
    "autoSubmit": false
  }
}

modeはholdかtapで、enabledがtrueのままmodeを省くとholdになります。autoSubmitはhold modeにだけ効く項目で、tap modeでは指定しても意味がありません。設定の置き場所は「Any file」と定義されているので、ユーザー設定のほかプロジェクト設定にも書けます。

旧形式のvoiceEnabledは、v2.1.92でvoiceオブジェクトが入ったときに非推奨になりました。trueかfalseの1項目だけで、モードと自動送信は指定できません。それでも読み込まれるため、古い設定ファイルは動き続けます。両方が書かれているときはvoice.enabledが優先されます。

起動時のオプションに音声入力用のものはありません。v2.1.287のclaude --helpの出力にvoiceを含む行はなく、有効にする入口は/voiceと設定ファイルの2つです。

使えるかどうかを決める3つの条件

音声入力は、録音を文字起こしのためにAnthropicのサーバーへ送る仕組みで、ローカルでは処理されません。必要なのは次の3点です。

組織の管理者が音声入力を止めている場合は、/voiceが「Voice mode is disabled by your organization's policy」と表示します。この場合は上の3条件を満たしても使えません。

文字起こしはClaudeのメッセージ数やトークンを消費せず、/usageの集計にも入りません。録音にはmacOS・Linux・Windowsとも内蔵のネイティブモジュールを使います。Linuxでモジュールを読み込めないときは、ALSAのarecordかSoXのrecに切り替わります。どちらも無ければ、/voiceがパッケージマネージャー向けのインストールコマンドを出します。

VS Code拡張機能も同じClaude.aiアカウントの条件で使えます。SSH・Dev Containers・Codespacesを含むVS Code Remoteでは使えません。マイクが手元のマシンにあり、拡張機能はリモートホストで動くからです。

holdとtapの動きの違い

/voice holdか/voice tapでモードを選べ、/voice offで無効にできます。引数なしの/voiceは、現在のモードのままオンとオフを切り替えます。有効にするときにマイクの確認が走り、macOSではシステムのマイク許可ダイアログが出ます。

hold modeでは、ウォームアップ中に入ったキーリピートの文字が録音開始時に自動で消えます。Spaceを1回だけ押した場合は、ふつうにスペースが入ります。ウォームアップを避けたいなら、tap modeにするか、meta+kのような修飾キーの組み合わせに付け替えます。修飾キーの組み合わせは最初の押下で録音が始まります。

tap modeの送信条件は、文字起こしが3語以上あることです。短い結果は入力欄に入るだけで送信されません。うっかりタップした1語が送られる事故を避ける仕組みです。日本語・中国語・タイ語はスペースで区切られませんが、単語単位で数えるので、tap modeでもhold modeのautoSubmitでも自動送信されます。

hold modeの既定は、キーを離すと文字起こしを入力欄へ入れてEnterを待つ動きです。キーを離した時点で送りたいなら、voiceオブジェクトに"autoSubmit": trueを足します。条件はtap modeと同じ3語以上です。

録音の途中でやめたいときはEscかCtrl+Cを押します。マイクが止まり、文字起こしは捨てられて、入力欄は録音前の状態に戻ります。文字起こしの処理中に押しても同じです。この押下では、EscはClaudeの応答を中断せず、Ctrl+Cも入力欄を消したり終了操作に数えられたりしません。

tap modeの録音は、無音が15秒続くか合計2分で自動的に止まります。

話した内容は、確定するまで薄い色でプロンプトに表示され、カーソル位置に挿入されます。音声と手入力を混ぜて使えます。

音声入力キーを付け替える

音声入力のキーはChatコンテキストのvoice:pushToTalkで、既定はSpaceです。holdとtapの両方が同じ割り当てを使います。変更は~/.claude/keybindings.jsonで行います。

{
  "bindings": [
    {
      "context": "Chat",
      "bindings": {
        "meta+k": "voice:pushToTalk",
        "space": null
      }
    }
  ]
}

このアクションが使うキーは同時に1つです。別のキーを割り当てると既定のSpaceは置き換わるので、"space": nullの行は省いても動きは変わりません。hold modeでvのような文字キーに付け替えるのは避けます。ウォームアップ中にその文字が入力欄へ打ち込まれるからです。tap modeにはウォームアップがないので、多くのキーが使えます。Caps Lockはターミナルにキーとして届かないため、割り当てるとエラーになります。

Spaceは入力欄に文字を打つ場面でだけ録音を始めます。トランスクリプト表示ではSpaceが会話のページ送りに、vimモードのINSERT以外ではコマンドになるため、録音は始まりません。meta+kのような修飾キーの組み合わせなら、これらの画面からでも始められます。キーバインド全般の書き方はClaude Codeショートカット一覧にあります。

録音の言語はlanguage設定と共通

文字起こしの言語に専用の設定はなく、Claudeの返答言語を決めるlanguageが共用されます。空なら英語です。VS Code拡張では、languageが空のときaccessibility.voice.speechLanguageが先に参照され、それも無ければ英語になります。

{
  "language": "japanese"
}

"japanese"のような言語名のほか、"ja"のようなBCP 47の言語コードでも書けます。文字起こしが対応するのは日本語を含む20言語です。対応外の値を入れると、/voiceを有効にするときに警告が出て、文字起こしだけが英語に戻ります。返答の言語は変わりません。/configから選ぶこともできます。

languageは返答言語と一緒に動くので、返答は英語のまま音声入力だけ日本語にする、という分け方はできません。言語設定全体の関係は、姉妹記事のClaudeの言語設定ガイドにあります。

文字起こしはコーディング用語に合わせて調整されています。regex・OAuth・JSON・localhostなどは正しく認識され、現在のプロジェクト名とgitブランチ名も認識のヒントに加わります。

音声入力を有効にしてから最初の3セッションは、入力欄が空のときフッターにhold space to speakのヒントが出ます。キーを付け替えていれば、そのキーの表示に変わります。カスタムのステータスラインを設定している場合、このヒントは出ません。

エージェントビューのバックグラウンドセッションにも使える

エージェントビューでは、詳細確認パネルの返信欄と、画面下部の送信欄にフォーカスがあるときに、同じキーで音声入力できます。バックグラウンドで動いているセッションへの返信を、キーボードに持ち替えずに出せます。この対応が入ったのはv2.1.145です。

症状から原因を探す

/voiceの実行時や録音中に出るメッセージで、原因を切り分けられます。

• Voice mode requires a Claude.ai account: APIキーか外部プロバイダーで認証しています。/loginでClaude.aiアカウントに切り替えます
• Microphone access is denied: OSの設定でターミナルアプリにマイクを許可してから、もう一度/voiceを実行します。Windowsでは「設定」→「プライバシーとセキュリティ」→「マイク」で許可します
• Voice mode requires SoX for audio recording(Linux): ネイティブモジュールを読み込めず、代わりのSoXも入っていません。エラーに出るコマンド(例: sudo apt-get install sox)で入れます
• Voice mode could not find a working audio recorder in WSL: WSLgは音声をPulseAudio経由で扱います。sudo apt install sox libsox-fmt-pulseでPulseAudio用のバックエンドを入れます。soxだけではALSA用が入り、/dev/sndのないWSLでは録音できません
• Voice mode requires a microphone, but SoX could not open an audio capture deviceと出ます。SoXはあっても、マイクがありません。ヘッドレスサーバーやコンテナが典型です。v2.1.195より前は、SoXが入っていてもインストールを求められました
• No audio detected from microphone: 録音は始まったものの無音でした。システムの既定の入力デバイスと、入力レベルがミュートや0付近でないかを見ます。Windowsの入力デバイスは「設定」→「システム」→「サウンド」→「入力」で選びます
• No speech detected: 音声は届いたのに言葉として認識されませんでした。マイクに近づけて雑音を減らし、話している言語とlanguageが一致しているかを確かめます
• Voice connection failed: 文字起こしのサービスまで録音が届いていません。ネットワークを確認します。v2.1.200より前は、マイクが無音でもこのメッセージが出て、ネットワークの問題に見えることがありました
• Voice stream error: WebSocket upgrade rejected with HTTP <status>: サーバーが接続を断りました。400番台は、サインインの期限切れか、間に入ったプロキシやボット対策のサービスが応答していることを示すのが通例です。/loginでサインインし直し、VPNやプロキシがあれば確認します。録音中に拒否が届いたときは、400番台以外だと一度だけ再試行してからこのメッセージが出ます。400番台は再試行されません
• Voice input is failing repeatedly and has been paused: 10秒以内に3回失敗すると、最初の失敗から10秒が過ぎるまで音声入力が止まります。上の項目で根本原因を直してから、もう一度試します

エラーが出ないのに録音が始まらないときは、hold modeでSpaceを押し続けながら入力欄を見ます。

macOSで、システム設定の「プライバシーとセキュリティ」→「マイク」にターミナルアプリが並んでいないときは、切り替えるスイッチがありません。権限の状態をリセットして、次の/voiceで許可のダイアログを出し直します。

<bundle-id>を省いてtccutil reset Microphoneだけを実行すると、ZoomやSlackを含むMac上の全アプリのマイク権限が取り消されます。通話中には実行しません。

まとめ

新しく書く設定はvoiceオブジェクトで、voiceEnabledは既存ファイルに残っている場合の読み替え先として覚えておけば足ります。キーを押し続けにくいなら/voice tap、押し続けのまま送信まで済ませたいならautoSubmit付きのhold modeです。/voiceコマンド自体の使い方はClaude Codeの/voiceコマンドで音声入力を使う — hold/tap/offに、設定ファイル全体の構成はClaude Code設定ガイドにあります。全体像はClaude Code完全ガイド、claude.ai側の音声モードとの違いはClaude音声モードと画面共有の使い方で確認できます。