Claude CodeでiTerm2のOption keyとクリップボードを有効化する

iTerm2でOption+EnterやOption+Pが反応しないのは、iTerm2が既定でOptionキーを修飾キーとして送らないためです。Apple Terminalと違い、/terminal-setupはiTerm2のOptionキー設定までは自動化しません。設定画面での手動切り替えが必要です。一方で、クリップボードへの書き込み権限は/terminal-setupが自動で有効にします。2つは別々の設定なので、症状から切り分けます。

iTerm2で自動になる設定と手動の設定

iTerm2では、Shift+Enterの改行と画像の貼り付けは設定しなくても動きます。残りの3つは設定が要ります。

後ろの3行は、以降の節で手順を示します。

どちらの設定が足りないかを症状で切り分ける

症状によって、触る場所が違います。

Optionキー側が原因かどうかは、Claude Codeを使わずに確かめられます。iTerm2でcat -vを実行して、Option+Pを押します。

cat -v
# Option+P を押す。Ctrl+C で終了

Esc+が効いていれば、^[pと表示されます。Escキーに続けてpを送った入力が、そのまま見えている状態です。別の文字が出るなら、Optionキーが文字入力に使われています。

Optionキーが必要なショートカットとその理由

Claude Codeは、一部のショートカットにOptionキーを使います。Option+Enterでの改行や、Option+Pでのモデル切り替えが代表例です。macOSのほとんどのターミナルは、既定ではOptionを修飾キーとして送りません。この設定は「Use Option as Meta Key」と呼ばれることが多く、MetaはOptionやAltの歴史的なUnix名です。

設定が有効でないと、Option+Enterは普通のEnterと同じ動作になり、Option+Pを押してもモデルピッカーは開きません。Apple Terminalでは初回起動時のセットアッププロンプトを承諾すると、この設定が自動で入ります。iTerm2は自動化の対象外なので、次の手順で自分で切り替えます。

Option+T(拡張思考モードの切り替え)だけは例外で、OptionをメタキーにしていないmacOSでも動きます。設定前に「Option+Tだけ効いて他は効かない」状態になっていても、故障ではありません。Opus 5.5・Sonnet 5.5・Fableの各モデルは常に拡張思考で動くため、これらのモデルではOption+Tを押しても何も変わりません。

Left/Right OptionをEsc+に設定する手順

プロファイルの設定を1か所変えると、iTerm2がOptionを押した組み合わせを「Escに続けてそのキー」として送るようになります。

この設定はProfiles配下にあります。複数のプロファイルを使い分けているなら、Claude Codeを起動しているプロファイルで変更したかを確かめてください。

Esc+にしたあとの単語移動と削除

単語単位の操作は、src/utils/foo.tsのようなパスを編集するときに差が出ます。v2.1.261以降では_や.、/が区切りになるので、Alt+Bを繰り返すと、カーソルはts、foo、utils、srcの先頭の順に止まります。Alt+Fは現在の単語の末尾へ進み、単語と単語の間にいるときは次の単語の末尾へ進みます。Alt+Dの削除範囲も同じ考え方です。

パス全体を消したいときはCtrl+Wが向いています。1回で--flag=valueのような塊も消えます。直前の単語だけを消すなら、macOSではOption+Deleteです。iTerm2ではCmd+BackspaceがCtrl+Uに割り当てられていて、カーソルから行頭までを削除します。

クリップボード権限は/terminal-setupで開く

iTerm2は既定で、ターミナルアプリからのクリップボードアクセスをブロックしています。/copyで応答をシステムクリップボードへ送るには、この許可が必要です。手動で設定するなら、Settings → General → Selectionの「Applications in terminal may access clipboard」をオンにします。

Claude Code側では、この手順を/terminal-setupが代行します。

/terminal-setup

iTerm2の中で実行すると、上記の許可が自動で有効になります。コマンドはtmuxの中から実行しても、iTerm2を検出します。反映にはiTerm2アプリ自体の再起動が必要です。

/copyの使い方(コードブロックだけを選ぶ操作や、SSH越しにwキーでファイルへ書き出す操作など)はClaude Code copyコマンドでコードブロックだけを送るにあります。

クリップボードの画像を貼り付けるキー

画像の貼り付けは、/copyとは逆向きの操作です。クリップボードにある画像を入力欄へ入れるキーは、環境で異なります。

貼り付けた画像は、入力欄に[Image #N]として入ります。プロンプトの中でこの番号を指して、画像を参照できます。WSLでCtrl+Vがターミナルに横取りされるときは、Alt+Vを使います。/copyの許可設定は、この貼り付けとは関係しません。

Apple Terminal・VS Codeとの自動化範囲の違い

同じmacOSでも、ターミナルによって/terminal-setupが自動化する範囲は異なります。

Apple Terminalの/terminal-setupは、Optionのメタキー化に加えて、プロファイルの音声ベルも切ります。スクリーンリーダーモードではベルの設定は変更されません。v2.1.211より前は、スクリーンリーダーモードでもベルが切られていました。以前の実行でベルが消えたなら、Settings → Profiles → Advancedの「Audible bell」で戻せます。

VS Codeでの/terminal-setupは、Shift+Enterのキー割り当てを書き込みます。あわせてterminal.integrated.gpuAccelerationを"off"にします。ホストのターミナルの設定ファイルを書き換えるため、tmuxやscreenの中ではなく、ホスト側のターミナルで直接実行します。iTerm2のShift+Enterは、/terminal-setupなしで改行になります。

VS Codeの統合ターミナルでOption+Enterなどを使うには、設定ファイルに次の1行を足します。

{
  "terminal.integrated.macOptionIsMeta": true
}

GhosttyやKittyなど他のターミナルでは、設定ファイルでOption-as-AltまたはOption-as-Metaに相当する項目を探します。名称と場所はアプリごとに違いますが、考え方はiTerm2と同じです。

tmux配下で変わる点と変わらない点

tmuxの中でClaude Codeを使っても、iTerm2側のOptionキー設定とクリップボード設定はそのまま有効です。一方、通知とプログレス表示を外側のターミナルへ届けるには、allow-passthroughなど別の設定が必要です。こちらはClaude Code tmux設定にあります。

通知をmacOSの通知センターに転送する

Claude Codeは、権限確認やタスク完了で離席中と判断すると、通知イベントを出します。既定でデスクトップ通知が出るのは、Ghostty・Kitty・iTerm2の3つだけです。GhosttyとKittyは追加設定なしでOSの通知センターへ転送されますが、iTerm2では転送を有効にする作業が要ります。

Ghostty・Kitty・iTerm2以外のターミナルでは、デスクトップ通知は出ません。その場合は設定のpreferredNotifChannelを"terminal_bell"にすると、ターミナルのベルが鳴ります。音やコマンドを自分で決めたいときは、Notificationフックを使います。フックは組み込みの通知を置き換えず、並行して動きます。

デスクトップ通知は、SSH越しのセッションでもローカルマシンへ届きます。それでも出ないときは、macOS本体で、ターミナルアプリに通知の権限が付いているかを見ます。tmux配下なら、前述のallow-passthroughも要ります。

よくあるつまずき

• プロファイル違い: Claude Codeを起動しているプロファイルとは別のプロファイルだけをEsc+にしている
• 再起動忘れ: /terminal-setupを実行しても/copyが届かないなら、iTerm2アプリの再起動が済んでいない可能性があります
• tmuxを先に疑う: Optionキーとクリップボードは、まずiTerm2本体の設定で決まります。cat -vの確認で、tmuxを挟まずに切り分けられます
• Alt+B/Alt+F/Alt+Dが動かない: まずOptionをEsc+にしているか確かめます。区切り文字(_・.・/)で止まる動きはv2.1.261以降の挙動で、claude --versionで確認できます。keybindingFlavor設定は同版で非推奨になり、今は効果がありません

まとめ

Optionキーのショートカットが効かないなら、iTerm2のProfiles → Keys → Generalで、Left/Right OptionをEsc+にします。/copyが届かないなら、/terminal-setupを実行してiTerm2を再起動します。通知が出ないときは、Notification Center Alertsの転送を確かめます。

Shift+Enterが改行にならないときの対処はterminal-setupコマンドでShift+Enterが効かないときの対処、Option+P以外のショートカットはClaude Codeショートカット一覧にあります。