macOSクリップボード画像をSSH/devcontainer内のClaude CodeでCtrl+V貼り付けする方法

pasting_images_from_mac_clipboard_to_remote_ssh_or_devcontainer_claude_code_with_ctrl_v.md

macOSクリップボード画像をSSH/devcontainer内のClaude CodeでCtrl+V貼り付けする方法

概要

macOSでスクリーンショットを撮影した画像を、SSH接続したリモートLinuxやdevcontainer内で実行しているClaude CodeにCtrl+Vで直接貼り付ける方法を説明します。

背景・課題

なぜ通常は動作しないのか

[macOS]
  スクリーンショット → macOSクリップボード (NSPasteboard)
      ↓ SSH/Docker
[Linux Remote/Container]
  Claude Code → Linux X11クリップボード → ❌ 存在しない
      ↓
  "No image found in clipboard"

問題点:

• LinuxのクリップボードはX11またはWaylandのディスプレイサーバーが管理
• SSH/devcontainerでは通常X11が動作していない（$DISPLAYなし、xclipなし）
• macOSとLinuxのクリップボードは完全に分離されている

Claude Codeの内部動作

Claude CodeはLinux環境では以下の順で動作します：

1. X11/Waylandサーバーへの接続を試みる
2. クリップボードデータの読み取り
3. X11が存在しない場合 → "No image found in clipboard"

注: Claude Codeの内部実装の詳細は非公開ですが、動作から判断すると、X11/Waylandのクリップボードシステムに依存していることが確認されています（GitHub issue #3186, #1361などより）。

解決策：XQuartz + X11転送

XQuartz（macOS用X11サーバー）を使い、macOS ↔ Linux間でX11プロトコルを転送することで、クリップボードを統合します。

仕組み

[macOS]
  NSPasteboard (macOSクリップボード)
      ↕ 自動統合
  XQuartz (X11サーバー)
      ↓ X11プロトコル転送
  SSH/Docker X11 Forwarding
      ↓
[Linux Remote/Container]
  DISPLAY=host.docker.internal:0 (または localhost:10.0)
      ↓
  xclip → X11プロトコル → macOS XQuartz
      ↓
  Claude Code → xclip経由でクリップボード読み取り → 画像取得成功！

重要なポイント:

• XQuartzがmacOSクリップボードとX11クリップボードを自動統合
• Linux側からはmacOS上のX11サーバーに接続
• 追加のスクリプトや手動同期が不要

セットアップ手順

1. macOS側：XQuartzのインストールと設定

インストール

# Homebrewでインストール
brew install --cask xquartz

XQuartz設定

# XQuartz起動
open -a XQuartz

XQuartzアプリのメニューから設定：

1. XQuartz → Preferences → Security

   • ✅ "Allow connections from network clients" を有効化

2. XQuartz → Preferences → Pasteboard

   • ✅ "Update Pasteboard when CLIPBOARD changes" を有効化
   • ✅ "Update CLIPBOARD when Pasteboard changes" を有効化

設定変更後、XQuartzを再起動：

killall XQuartz
open -a XQuartz

xhost設定（毎回必要）

XQuartz→アプリケーション→Terminalで起動するxtermで実行

# ネットワーク接続を許可
xhost +localhost

# 出力例：
# localhost being added to access control list

確認コマンド:

# XQuartz起動確認（-listen tcp が含まれていればOK）
ps aux | grep XQuartz | grep -v grep

# xhost設定確認
xhost
# 出力例：
# access control enabled, only authorized clients can connect
# INET:localhost
# INET6:localhost

2a. devcontainer用設定

devcontainer.json

.devcontainer/devcontainer.json に以下を追加：

{
  "name": "your-project",
  "build": {
    "dockerfile": "Dockerfile"
  },

  // X11転送設定
  "containerEnv": {
    "DISPLAY": "host.docker.internal:0"
  },

  // xclipインストール, DockerfileにいれておいてもOK
  "postCreateCommand": "sudo apt-get update && sudo apt-get install -y xclip",

}

重要: macOSではhost.docker.internal:0を使用します（docker.for.mac.host.internal:0も同義）。

Dockerfile

既存のDockerfileにxclipを追加：

# 既存の設定...

# X11クライアントツール
RUN apt-get update && apt-get install -y \
    xclip \
    && rm -rf /var/lib/apt/lists/*

2b. SSH用設定

SSH設定ファイル

~/.ssh/config に以下を追加：

Host your-remote-server
    HostName your-server-hostname
    User your-username
    ForwardX11 yes
    ForwardX11Trusted yes

DISPLAYはXQuartzのxtermでecho $DISPLAYで確認。

DISPLAY=:0 ssh user@remote-server

または、接続時にオプション指定：

DISPLAY=:0 ssh -Y user@remote-server  # -Y は ForwardX11Trusted

リモートLinux側の設定

# xclipインストール
sudo apt-get update
sudo apt-get install -y xclip

# SSH接続後にDISPLAY確認
echo $DISPLAY
# → localhost:10.0 のような値が表示されればOK

動作確認・テスト手順

前提条件チェック

# macOS側
open -a XQuartz
xhost +localhost

# devcontainer/SSH接続後、Linux側で実行
echo $DISPLAY
# → devcontainer: host.docker.internal:0
# → SSH: localhost:10.0 のような値が表示されること

which xclip
# → /usr/bin/xclip などのパスが表示されること

テスト1: テキストクリップボード

# === Linux側（devcontainer/SSH内）===
echo "test from linux" | xclip -selection clipboard -i

# === macOS側のターミナルで確認 ===
pbpaste
# → "test from linux" が表示されればOK

逆方向のテスト：

# === macOS側 ===
echo "test from mac" | pbcopy

# === Linux側 ===
xclip -selection clipboard -o
# → "test from mac" が表示されればOK

テスト2: 画像クリップボード

# === macOS側 ===
# スクリーンショットを撮影
# Cmd+Ctrl+Shift+4 で範囲選択

# === Linux側で確認 ===
# クリップボードのMIMEタイプ確認
xclip -selection clipboard -t TARGETS -o
# → image/png が含まれていればOK

# 画像をファイルに保存
xclip -selection clipboard -t image/png -o > /tmp/test.png
ls -lh /tmp/test.png
# → ファイルサイズが表示されればOK

# 確認
imgcat /tmp/test.png

テスト3: Claude Codeで貼り付け

# === macOS側 ===
# スクリーンショット撮影（Cmd+Ctrl+Shift+4）

# === Linux側（devcontainer/SSH内）===
# DISPLAY環境変数が設定されていることを確認
echo $DISPLAY

# Claude Code起動
claude

# プロンプト内で Ctrl+V を押す
# → 画像が貼り付けられれば成功！

完全な動作フロー

1. macOSでスクリーンショット (Cmd+Ctrl+Shift+4)
   → macOS NSPasteboard
   ↓
2. XQuartz Pasteboard統合（自動）
   → X11 CLIPBOARD selection
   ↓
3. X11プロトコル転送
   → SSH: X11 Forwarding経由
   → Docker: host.docker.internal:0経由
   ↓
4. Linux側でX11クライアント（xclip）が接続
   → macOS XQuartzのX11サーバーにアクセス
   ↓
5. Claude Codeがxclip経由で画像取得
   → Ctrl+V で貼り付け成功！

参考リンク

• XQuartz公式サイト
• SSH X11 Forwarding
• Docker for Mac networking

まとめ

XQuartzを使用することで、macOSとSSH/devcontainer間のクリップボードを完全に統合でき、ローカルと同じ感覚でスクリーンショットの貼り付けが可能になります。初回セットアップは若干手間ですが、一度設定すればシームレスに動作します。