Claude Codeに画像が貼り付けられない・読み込めない時の対処法 — Mac/Windows/WSL2/SSH別 2026年版
Claude Codeで画像ペーストが効かない・文字列になる原因を公式ドキュメントベースで整理。MacはCtrl+V（Cmd+VはiTerm2限定）、WindowsはAlt+V、WSL2のクリップボード越境不可、SSHリモート開発での回避策まで環境別に解説する。
エンジニアのゆとです。
エラー画面のスクショをそのままClaude Codeに見せたくて、いつもの癖でCmd+Vを押したら何も起きなかったことがある。もう一度押しても反応なし。「画像対応してるって聞いたのに」としばらく首をかしげて、結局ターミナルの種類でショートカットが違うことに気づくまで無駄に時間を溶かした。調べてみると、同じところで詰まっている人はかなり多くて、しかもMac・Windows・WSL2・SSH越しのリモート開発でそれぞれ原因が別物だった。
この記事では、公式ドキュメント（Common workflows / Terminal configuration）の記述をベースに、環境別の正しい貼り付け方と、貼り付けたのに反応しない・文字列になる・複数枚で失敗するといった個別症状の原因を整理する。既存の解説記事はMacかWindowsどちらか一方に絞ったものが多く、WSL2とSSHリモートまで含めて1枚の表で見比べられる記事が見当たらなかったので、そこも含めてまとめた。
結論 — 症状別の対処表
まず自分の環境と症状に近いものを探してほしい。
| 症状 | 環境 | 原因 | 対処 |
|---|---|---|---|
Cmd+Vを押しても何も起きない | Mac（Terminal.app等） | Cmd+VはiTerm2以外では画像貼り付けに対応していない | Ctrl+Vを使う |
Ctrl+Vを押しても何も起きない | Windows | Windows版はCtrl+VではなくAlt+Vが画像貼り付けの割り当て | Alt+Vを使う |
| クリップボードに画像はあるはずなのに反応しない | WSL2 | WindowsとLinuxのクリップボードは別物で、そのままでは越境できない | 画像をファイル保存してパス指定、または後述のスクリプト/拡張機能を使う |
| SSH先のリモートサーバーでClaude Codeを動かしている | SSHリモート | ローカルのクリップボードはSSH越しにそのままでは飛ばない | scpでファイル転送するか、後述のトンネル経由ツールを使う |
| 貼り付けたら画像ではなく文字列やパスが入力欄に入る | 共通 | コピー元が画像データではなくファイルパス文字列をクリップボードに入れている | 画像そのものをコピーし直す（ファイルをドラッグ&ドロップに切り替えるのも手） |
| 複数枚貼り付けると失敗する・エラーになる | 共通 | 画像サイズの合計がAPIリクエスト上限に達している | 各画像を2,000px以下に縮小するか、枚数を減らして複数ターンに分ける |
なぜ環境によってこんなにバラバラなのか
そもそもの話として、CLIツールが「画像をペーストできる」というのは特別な仕組みに乗っかっている。ターミナルというのはもともとテキストしかやり取りしない前提のインターフェースで、画像データをそのままキーボード入力のように送る標準的な方法は存在しない。Claude Codeは各ターミナルアプリが持つ拡張的なペースト処理（クリップボード内の画像データを検知して一時ファイル化する機能）に依存しており、その拡張処理をどのキー割り当てで呼び出すかがアプリごとに違う。
つまり「画像が貼り付けられない」という同じ症状でも、原因は大きく3層に分かれる。
- キー割り当ての違い — Mac/Windowsでそもそも押すべきキーが違う
- クリップボードの越境問題 — WSL2やSSHのように、OS・マシンをまたぐとクリップボードの中身がそもそも届かない
- クリップボードの中身の問題 — コピー元が画像データではなくパス文字列を入れているだけ
この3層を切り分けずに「Ctrl+Vを押しても直らない」とだけ考えると、的外れな対処法を試して時間を溶かすことになる。以降、環境ごとに分けて書く。
Macで貼り付けられない場合
公式ドキュメントには次のように明記されている。
Copy an image and paste it into the CLI with Ctrl+V. On macOS, Cmd+V also works in iTerm2.
翻訳すると「Ctrl+Vで貼り付ける。macOSではCmd+VもiTerm2でだけ動く」ということになる。つまりmacOSの基本ショートカットはCtrl+Vであって、Cmd+VはあくまでiTerm2限定の追加対応にすぎない。標準のTerminal.appや、VS Code統合ターミナルではCmd+Vは画像貼り付けとしては機能しない（テキストのペーストとしてはCmd+Vが使えるので、なおさら「反応しない」ことに気づきにくい）。
自分がハマったのもここで、普段の癖でCmd+Vを押して「画像も貼れるんじゃなかったのか」と思っていたが、単に使っているターミナルとショートカットの組み合わせが悪かっただけだった。まずCtrl+Vを試し、それでも動かない場合だけ次の項目を確認する。
- クリップボードに本当に画像データが入っているか（スクリーンショットを撮った直後か、画像を右クリックして「コピー」しているか）
- 使っているターミナルアプリ自体がクリップボード経由の画像貼り付けに対応しているか
- iTerm2の場合、
/terminal-setupを実行した直後はアプリの再起動が必要になることがある
Windowsで貼り付けられない場合
Windowsでは逆にCtrl+VではなくAlt+Vが画像貼り付けの割り当てになる。Win+Shift+Sでスクリーンショットを撮ってクリップボードに入れたあと、Ctrl+Vを押しても何も起きないのは仕様であって不具合ではない。
この「WindowsでCtrl+Vが効かない」という点は、以前はAnthropicのGitHubリポジトリに機能要望としてIssueが立っていたが、現在はクローズ済みになっている。Alt+Vという専用の割り当てが用意されたことで、この要望自体は解決した形だ。ただし日本語で検索するとまだ「Windowsは画像貼り付け非対応」という古い情報が上位に残っていることがあるので、まずはAlt+Vを試してから他の原因を疑うといい。
WSL2上でClaude Codeを動かしている場合は、Windows側のショートカットがそのまま使えるとは限らない。次の項目で詳しく扱う。
WSL2でクリップボードが越境しない問題
WSL2は仮想化されたLinux環境で、WindowsホストとはOSレベルで別のマシンとして動いている。クリップボードもこの境界の内側にあるため、Windows側でコピーした画像がWSL2内のClaude Codeにそのまま届くとは限らない。Alt+Vを押しても無反応、あるいはテキストとしてのパスしか貼り付かない、という報告が多いのはこのためだ。
現実的な回避策は3つある。
- 画像を保存してパス指定する — 最も確実な方法。スクリーンショットを一度ファイルとして保存し、Claude Codeに
/mnt/c/Users/xxx/Pictures/screenshot.pngのようなパスをそのまま伝える - PowerShellスクリプトでWSL側にコピーする — Snipping Toolの自動保存機能をオンにしておき、保存先を監視してWSL側のパスに変換・配置するスクリプトをショートカット登録する。毎回スクショから2アクションで渡せるようになる
- クリップボード連携ツールや拡張機能を使う — VS Code上でWSL2のリモート開発をしている場合、クリップボードの画像を検知してWSL側にブリッジする拡張機能を使う選択肢もある
どれも「Windows側のクリップボードとWSL2側のファイルシステムは別物」という前提に立った回避策で、WSL2の仕様そのものを変えるものではない。頻繁に画像を渡す作業が多いなら、2か3のどちらかを一度セットアップしておくと以降がかなり楽になる。
SSH越しのリモート開発で画像を渡す場合
VPS上やリモートサーバー上のClaude CodeにSSHで接続して作業している場合は、また別の壁がある。ローカルマシンのクリップボードにある画像は、SSH接続だけでは自動的にリモート側に飛ばない。ローカルとリモートは完全に別のマシンなので、当然といえば当然だが、見落として「なぜかリモートだけ画像が貼れない」と悩むケースをよく見かける。
一番シンプルな回避策は、ローカルでスクリーンショットを撮ったあとにscpでリモートに転送し、リモート側でファイルパスを指定する方法だ。
scp ~/Desktop/screenshot.png user@remote-host:/tmp/screenshot.pngもう少し手間をかけてもいいなら、SSHのリバーストンネル経由でローカルのクリップボードデーモンとリモート側のクライアントを繋ぎ、あたかもローカルで貼り付けているかのように扱えるツールも公開されている。仕組みとしては、ローカル側で常駐させたデーモンがwl-paste/xclip/pngpasteなどOS標準のクリップボードツールから画像を取得してBase64化し、SSHの-Rオプションで開けたポートを通じてリモート側のクライアントに渡す、という構成になっている。毎回scpするのが面倒なくらい画像のやり取りが多い場合は検討する価値がある。
いずれの方法でも、Claude Code自体の設定を変える必要はない。あくまで「画像データをリモートのファイルシステムまでどう運ぶか」というSSHインフラ側の話だと理解しておくと、Claude Codeのバグを疑って時間を無駄にせずに済む。
ドラッグ&ドロップは万能ではない
クリップボード経由のペーストがどうしても環境依存で不安定な場合、Finder（Mac）やエクスプローラー（Windows）から画像ファイルを直接ターミナルウィンドウにドラッグ&ドロップする方法もある。多くの環境ではこれが一番安定して動く。
ただし注意点がある。ターミナルアプリによっては、ドロップされた画像ファイルを画像データとしてではなく、単なるファイルパスの文字列として入力欄に挿入するものがある。この場合はClaude Code側が画像として認識してくれないので、貼り付け後に[Image #1]のような表示になっているかを確認する癖をつけるといい。パスの文字列がそのままテキストとして入っているだけなら、それはそれで問題なく動く（Claude Codeはファイルパスを渡されれば画像として読みに行く）ので、慌てて貼り直す必要はない。
対応形式とサイズ制限
地味に見落としやすいのがサイズ・形式の制限で、これが原因で「複数枚貼り付けたら急に失敗する」ことがある。
- 対応形式: JPEG、PNG、GIF、WebP（UIキャプチャや文字が入ったスクショはPNG推奨）
- 画像が1枚だけの場合: 長辺8,000pxまで
- 画像が複数枚ある場合: 1枚あたり長辺2,000pxまで
- APIリクエスト全体のサイズ上限: 30MB
つまり、高解像度ディスプレイでフルスクリーンのスクリーンショットを何枚も一気に貼り付けると、1枚あたりの上限（複数枚時は2,000px）にすぐ引っかかる。エラーが出た場合は、比較に本当に必要な画像だけに絞るか、スクリーンショットを撮る範囲を最初から狭めておくと安定する。全部一度に見せる必要がないなら、ターンを分けて1〜2枚ずつ渡すほうが結果的に速い。
それでも直らない時のチェックリスト
一通り試しても改善しない場合は、次の順番で切り分けるとよい。
- クリップボードに画像データそのものが入っているか確認する（スクリーンショット直後か、画像を選択して「コピー」しているか。ファイルを「切り取り」しただけだとパスしか入らないことがある）
- 使っているOSに合ったキーを押しているか確認する（Mac:
Ctrl+V、iTerm2ならCmd+Vも可 / Windows:Alt+V） - WSL2やSSHリモートで作業していないか確認する。していれば、そもそもクリップボードが物理的に届いていない前提でファイル経由に切り替える
- 貼り付け後に入力欄が
[Image #1]のような表示になっているか確認する。パス文字列のままならそれでも動くので慌てない - 複数枚で失敗するなら、画像サイズ（複数枚時は長辺2,000px）とAPIリクエスト30MB上限を疑う
- ここまでで解決しない場合は、いったんファイルパス指定（
このスクショを見て: /path/to/image.png）に切り替える。原因の切り分けをあきらめてでも作業を先に進めたいときの最終手段として一番確実
テキストの改行や貼り付けで別のつまずきがある場合は、そちらは原因が完全に別なので分けて確認したほうがいい。
FAQ
画像を貼り付けたあと、Claude Codeが認識しているか確認する方法は？
入力欄に[Image #1]のような表示が出ていれば認識されている。Claudeが返答の中でその画像を参照する際も同じ表記になり、Cmd+Click（Mac）またはCtrl+Click（Windows/Linux）でデフォルトのビューアで開ける。
複数の画像を同時に貼り付けて比較させることはできる？
できる。[Image #1]、[Image #2]と番号が振られていくので、「Image #1とImage #2の違いを教えて」のように番号で指示すればいい。ただし前述の通り、複数枚時は1枚あたり長辺2,000pxの制限がかかる点に注意する。
VS Code統合ターミナルでも同じ方法で貼り付けられる？
基本的には同じCtrl+V（WindowsはAlt+V）で動くが、VS Code統合ターミナル特有の入力処理の制限に引っかかることがある。テキストの大きい貼り付けで文字が欠落する問題と根が近いので、うまくいかない場合はドラッグ&ドロップかファイルパス指定に切り替えたほうが早い。
画像ではなくファイルパスを直接渡す方法にはどんなメリットがある？
クリップボードの状態に左右されず、確実に同じファイルを参照できる点が大きい。リポジトリ内のデザインモックアップやログ画像を何度も参照する場合、パス指定のほうが再現性が高く、会話のログも読みやすく保たれる。
まとめ
Claude Codeの画像貼り付けが効かない問題は、突き詰めると「キー割り当ての勘違い」「クリップボードがそもそも物理的に届いていない」「クリップボードの中身が画像データではない」という3つの原因のどれかに集約される。
まずは自分の環境がMac・Windows・WSL2・SSHリモートのどれに当てはまるか、そして症状が「無反応」なのか「文字列になる」のかを切り分けること。それさえできれば、ここに書いた対処法のどれかで大抵は解決する。うまくいかない場合の最終手段として、ファイルパス指定に切り替える選択肢を常に持っておくと、原因調査に時間を溶かさずに作業を先に進められる。
