Claude CodeでLinuxのAlt+V画像貼り付けが効かないときの対処

LinuxのClaude Codeで Alt+V を押しても何も起きないのは、不具合というより既定の割り当てがそうなっているためです。画像貼り付け(chat:imagePaste)の既定は、WindowsとWSLが Alt+V、LinuxとmacOSは Ctrl+V だけです。端末が Ctrl+V を自分の貼り付けに使っていると、Linuxには画像を貼るキーが残りません。

直す方法は2つあります。~/.claude/keybindings.json に alt+v を足すか、画像をファイルで渡すかです。この記事では、まず原因がキーなのかクリップボードなのかを切り分け、そのあとで設定を足します。

なぜLinuxではAlt+Vが空振りするのか

GitHubのissue #92312が、この食い違いを報告しています。報告者の環境はUbuntu 24.04(GNOME、Wayland)、Claude Code 2.1.261、VTEベースの端末です。クリップボードに画像がある状態で Alt+V を押しても、[Image #1] のチップは出ず、ヒントもエラーも出ません。

キーバインド一覧の表では、chat:imagePaste の既定は次のように書かれています。

issueの報告者は、WSLにだけ両方のキーを割り当てる分岐があることを指摘し、同じ扱いをLinuxとmacOSにも広げるよう求めています。報告によると、GNOME Terminal、Tilix、Konsole、ddtermは Ctrl+V を端末の貼り付けに割り当てる設定にでき、その設定にするとLinuxでは画像を貼るキーが残りません。

つまり、Linuxで Alt+V が効かないのは「押し方が悪い」のでも「クリップボードが壊れている」のでもなく、そもそもそのキーに何も結び付いていないからです。

キーの問題か、クリップボードの問題かを切り分ける

画像が貼れない原因は、キーが届いていない場合と、キーは届いているがクリップボードの画像を読めていない場合の2通りです。後者にキーバインドを足しても直りません。先に切り分けます。

キーがアプリまで届いているかは、端末で押した順に出るバイトを見れば分かります。showkey -a が入っていれば、起動してから Ctrl+V と Alt+V を押して比べます。入っていなければ、cat -v を起動して Alt+V を押し、Enterを押すと内容が見えます。

showkey -a
# Ctrl+V → 0x16 が出れば、アプリまで届いている
# Alt+V  → 0x1b 0x76(ESC と v)が出れば、Alt+V も届く

Ctrl+V を押しても何も表示されなければ、端末が先に処理しています。Alt+V で 0x1b 0x76 が出るなら、Claude Code側で alt+v を割り当てれば受け取れる状態です。出ない場合は、端末がAltを別の用途に使っているため、次の節の「それでも効かないとき」に進みます。

keybindings.jsonでAlt+Vを足す

Claude Codeは /keybindings で設定ファイルを作成して開きます。保存先は ~/.claude/keybindings.json です。ファイルの変更は自動で検出され、Claude Codeを再起動する必要はありません。

Chat コンテキストに alt+v を足します。修飾キーの書き方は、alt がWindowsとLinuxではAltキー、macOSではOptionキーを指します。

{
  "$schema": "https://www.schemastore.org/claude-code-keybindings.json",
  "$docs": "https://code.claude.com/docs/en/keybindings",
  "bindings": [
    {
      "context": "Chat",
      "bindings": {
        "alt+v": "chat:imagePaste"
      }
    }
  ]
}

ctrl+v はそのまま残ります。ここで足しているのは alt+v だけで、WSLの既定と同じ「両方のキーが画像貼り付けに結び付く」状態になります。

保存したら、クリップボードに画像をコピーして、プロンプトで Alt+V を押します。[Image #1] のチップが出れば成功です。チップはカーソルの位置に入るので、その前後に質問を書けば、画像を位置で指して尋ねられます。

記述に誤りがあっても、画面にエラーは出ません。Claude Codeは設定の検証結果をデバッグログに書きます。効かないときは --debug を付けて起動し、次のような警告を探します。

claude --debug

検証の対象には、JSONの構文エラー、ctl+k のような綴り違いの修飾キー、存在しないコンテキスト名、未知のアクション名、同じコンテキスト内の重複があります。たとえば "alt + v" のように + の隣に空白を入れると、キーの連続入力(chord)として読まれ、発火しません。キー文字列は alt+v と詰めて書きます。

それでも効かないとき

Altキーが端末に取られている

Alt+V も端末やデスクトップ環境のショートカットと衝突することがあります。上の showkey -a で 0x1b 0x76 が出ないなら、その可能性があります。別の修飾キーの組み合わせを選べば、同じ設定で回避できます。

{
  "bindings": [
    {
      "context": "Chat",
      "bindings": {
        "alt+v": "chat:imagePaste",
        "ctrl+alt+v": "chat:imagePaste"
      }
    }
  ]
}

2つ目はあくまで例で、どの組み合わせが空いているかは端末とデスクトップ環境で変わります。端末の設定画面でショートカット一覧を見て、空いている組み合わせを選んでください。

Ctrl+Shift+Vは動くが、文書化されていない

issueの報告者の環境では、画像を貼れた唯一のキーは Ctrl+Shift+V でした。端末が Ctrl+Shift+V を Ctrl+V と同じバイトとしてアプリに渡すため、偶然届いていると報告者は説明しています。この挙動はキーバインド一覧には載っておらず、端末の種類や設定で変わるので、頼りにするのは避けたほうが無難です。

画像をファイルで渡す

キーに頼らない方法も2つあります。画像のドラッグ&ドロップと、プロンプトにパスを書く方法です。common-workflowsの手順には、次の3つが挙げられています。

1. 画像をClaude Codeのウィンドウにドラッグ&ドロップする
2. コピーした画像を Ctrl+V で貼る(Windows・WSLは Alt+V)
3. 「Analyze this image: /path/to/your/image.png」のようにパスを書く

3つ目は貼り付けの経路を通らないので、キーやクリップボードのどちらが原因でも使えます。スクリーンショットを一度ファイルとして保存し、そのパスをプロンプトに書けば済みます。

Waylandでxclipが入っていると画像が貼れない報告もある

issue #88898は、Waylandでxclipがインストールされていると、画像ではなくテキストが貼られるという報告です。キーの割り当てとは別の原因で、Alt+V を足しても変わりません。Ctrl+V でも Alt+V でも画像にならないときは、こちらの症状に当たっていないかを確かめてください。

既定が変わるまでの見通し

issue #92312は、Alt+V を全OSで chat:imagePaste に割り当てるよう求めています。理由は、既定のキーがOSで違うと、あるOSで覚えたキーが別のOSでは無反応になるからです。報告者が引いている先例が、WSLで両方のキーを割り当てる分岐です。#50985で、端末が Ctrl+V を横取りするためにWSLへ Alt+V を足すよう求めたところ、issueはstale botに閉じられたものの、WSLの両方割り当ては入っている、と報告者は書いています。

このissueはopenです。コメントは報告者自身の2件で、2026年9月18日のコメントは、2.1.276の時点でLinuxの Alt+V を変える変更履歴の項目がないと述べています。Linuxの既定が変わった場合は、キーバインド一覧の chat:imagePaste の行と変更履歴に記載が出るはずなので、そこで確かめられます。それまでは keybindings.json への追記が、既定を待たずに使える方法です。

ここでの設計判断は、報告者と同じ側に立てます。設定で変えられるのは事実ですが、keybindings.json に書けると知らない人には、Linuxの Alt+V が無反応なのは何の手がかりもない状態です。既定として割り当てるかどうかが、発見のしやすさを決めます。

WindowsやWSL2の画像貼り付けとの違い

同じ「画像が貼れない」でも、症状ごとに原因は別の場所にあります。

WindowsとWSLでは Alt+V が既定なので、押して無反応という症状自体が別物です。Linuxの無反応は「キーが何にも結び付いていない」のが本体で、keybindings.json の1行で解消できる点が違います。

まとめ

Linuxで Alt+V が効かないのは、既定が Ctrl+V のみだからです。切り分けは、クリップボードに image/png があるか、showkey -a でキーがアプリまで届くかの2点で済みます。キーが端末に奪われているなら、Chat コンテキストに "alt+v": "chat:imagePaste" を足します。それでも届かないときは、パスをプロンプトに書く方法が、キーにもクリップボードにも依存しない最後の手段です。