Claude Code Desktop SSH × WSL2 実践セットアップガイド【Windows編】¶
この記事のポイント¶
- WSL2の開発環境にClaude Code DesktopのGUI機能（ビジュアルdiff・並列セッション等）をフル接続するにはSSH設定が必要
- Windows × WSL2特有の落とし穴（ポート競合・ネットワークモード・バイナリ未同梱）を順番に潰していく
- 公開鍵認証を設定すれば、以降はパスワード入力なしでワンクリック接続が可能になる
クイックリファレンス¶
| Step | 作業内容 | 所要時間目安 |
|---|---|---|
| 1 | Claude Code Desktopのアップデート | 5分 |
| 2 | WSL2にOpenSSH Serverを導入 | 2分 |
| 3 | ネットワークモードをmirroredに変更 | 5分 |
| 4 | ポート競合の確認と解消 | 5分 |
| 5 | sshdを起動 | 1分 |
| 6 | PowerShellからSSH接続を確認 | 3分 |
| 7 | 公開鍵認証を設定（推奨） | 5分 |
| 8 | Claude Code Desktopから接続 | 3分 |
はじめに¶
Claude Code Desktopの Code タブは、ファイルシステムに直接アクセスしながらAIコーディングを行える機能だ。ビジュアルdiffレビュー、並列セッション、ファイル添付など、ターミナル版のClaude Code CLIにはないGUI機能を備えている。
ただし、Codeタブの「ローカル」モードはWindowsファイルシステム上で動作する。開発環境をWSL2に置いている場合、そのままではWSL2上のプロジェクトをCodeタブから扱えない。
ここでSSH機能の出番になる。本記事では、ローカルWSL2への接続を題材にしたハンズオン形式で、SSH機能のセットアップを一通り体験する。ここで得た知識（鍵認証・ポート設定・接続トラブルシュート）はそのままクラウドVMやリモートサーバーへの接続にも応用できる。
なぜローカルのWSL2にSSHで繋ぐのか¶
「ローカルの127.0.0.1にSSH接続する意味があるのか」という疑問は当然だ。技術的には「別マシンへのリモート接続」と同じ仕組みを使って、WSL2というLinux環境にClaude Code DesktopのGUIをフル接続する手段になる。
flowchart LR
subgraph windows ["Windows"]
A["Claude Code Desktop<br/>（GUI）"]
end
subgraph wsl2 ["WSL2 Linux"]
B["プロジェクト<br/>Docker / Node / Python 等"]
end
A -- "SSH経由で<br/>ファイル操作・コード実行" --> B具体的に何ができるようになるか：
| やりたいこと | SSHなし | SSH接続後 |
|---|---|---|
| WSL2上のコードをAIで編集 | ターミナル版CLI のみ | Desktop GUIで操作可能 |
| 変更のビジュアルdiff確認 | 不可 | 可能 |
| 複数タスクの並列セッション | 手動でtmux等 | GUIから並列起動 |
| ファイル添付でコンテキスト共有 | 不可 | 可能 |
| Docker/Linux固有ツールの利用 | CLIからは可能 | GUIからも可能 |
つまり「開発環境はWSL2にあるが、Claude Code DesktopのGUI機能を使いたい」というケースでの接続手段だ。ターミナル操作に抵抗がなくCLI版で十分という場合は、このセットアップは不要。
クラウドVM接続への応用
本記事はローカルWSL2への接続を扱うが、手順はクラウドVMやリモート開発サーバーへの接続とほぼ同じだ。ローカルで一通り検証してからリモートへ展開する予行演習としても有用。
全体フロー¶
以下のフローチャートで、セットアップの全体像と各分岐を把握できる。
flowchart TD
START([セットアップ開始]) --> A
A{"Claude Code Desktop<br/>最新版か？"}
A -->|No| A1["ヘルプ → 再起動して<br/>最新バージョンに更新"]
A1 --> A2{"resources/ に<br/>claude-ssh/ が<br/>存在するか？"}
A2 -->|No| A3["バイナリ未同梱<br/>アップデート待ち"]
A2 -->|Yes| B
A -->|Yes| B
B{"WSL2 に<br/>openssh-server<br/>あるか？"}
B -->|No| B1["sudo apt install<br/>openssh-server"]
B1 --> C
B -->|Yes| C
C{".wslconfig で<br/>mirrored 設定済み？"}
C -->|No| C1["設定追加 → wsl --shutdown"]
C1 --> D
C -->|mirrored| D
D{"ポート22の競合<br/>はあるか？"}
D -->|Yes| D1["Windows SSH停止<br/>or WSL2を別ポートに"]
D1 --> E
D -->|No| E
E["WSL2: sudo service ssh start"] --> F
F{"PowerShellから<br/>SSH接続できるか？"}
F -->|Yes| G
F -->|No| F1["エラーに応じて対処"]
F1 --> D
G["鍵認証設定（推奨）"] --> H
H["Claude Code Desktop<br/>SSH → 接続先を設定"] --> DONE([完了])
style START fill:#6366f1,color:#fff,stroke:none
style DONE fill:#22c55e,color:#fff,stroke:none
style A3 fill:#ef4444,color:#fff,stroke:none全体像を把握したところで、各ステップを順番に進めていく。
Step 1：Claude Code Desktopのアップデート¶
SSH機能は比較的新しいため、古いバージョンではSSHリモートサーバーのバイナリが同梱されていない場合がある。
更新手順：
- Claude Code Desktop を開く
- ヘルプ → 「再起動してバージョンX.X.XXXXに更新」 を選択
- 再起動後、再度ヘルプメニューを確認する
1回の更新では最新版にならないことがある
段階的にしかアップデートされないケースがあるため、「ヘルプ」メニューに新しい更新が表示されなくなるまで繰り返す。
バイナリの存在確認：
dir "$env:LOCALAPPDATA\AnthropicClaude\app-*\resources\claude-ssh\"
claude-ssh-linux-amd64 などのファイルが存在すれば準備完了。フォルダ自体が存在しない場合は、さらなるアップデートが必要になる。
アプリの準備ができたら、次はWSL2側の環境を整備する。
Step 2：WSL2にOpenSSH Serverを導入¶
WSL2のターミナルで以下を実行する。
sudo apt update
sudo apt install openssh-server
インストール後、設定ファイルの構文チェックを行う。
sudo sshd -t
エラーが出なければ設定は正常だ。SSHサーバー自体の準備はこれで完了するが、実際に接続するにはネットワーク設定の調整が必要になる。
Step 3：WSL2のネットワークモードをmirroredに変更¶
このステップはWSL2全体のネットワーク構成を変更するため、影響範囲を理解した上で実施する。
NATモードとmirroredモードの違い¶
WSL2のデフォルトはNATモードで、WSL2は独自の仮想ネットワーク（例：172.x.x.x）を持ち、Windowsとは別のIPアドレスが割り当てられる。mirroredモードにすると、WindowsのネットワークインターフェースがそのままWSL2にミラーリングされ、両者が同じIPアドレスを共有する。
flowchart LR
subgraph nat ["NATモード（デフォルト）"]
W1["Windows<br/>192.168.1.x"] --- NAT["NAT変換"] --- L1["WSL2<br/>172.x.x.x"]
end
subgraph mirrored ["mirroredモード"]
W2["Windows<br/>192.168.1.x"] --- M["ミラーリング"] --- L2["WSL2<br/>192.168.1.x"]
endなぜmirroredモードが必要か¶
NATモードではClaude Code Desktopからの接続でエラーが発生しやすい。 mirroredモードにすると 127.0.0.1 で直接WSL2に到達できるようになり、接続が安定する。Microsoft公式も「新しい機能と互換性の向上のためmirroredモードの使用を推奨」としている。
mirroredモードの注意点¶
変更前に以下を確認しておきたい。
| 項目 | 影響 |
|---|---|
| ポート競合 | WindowsとWSL2でポートが共有されるため、同じポート番号を両方で使用できない（次のStep 4で対処） |
| Docker Desktop | 基本的に互換性あり。ただしコンテナの --network host モードで挙動が変わる報告あり |
| VPN利用時 | 企業VPN接続中にWSL2のネットワーク接続が不安定になるケースが報告されている |
| IPv6 | localhostの ::1 はサポートされない。IPv4の 127.0.0.1 を使用する |
| Windows要件 | Windows 11 22H2以降が必要 |
元に戻すのは簡単
問題が発生した場合は、.wslconfig から networkingMode = mirrored の行を削除（またはコメントアウト）して wsl --shutdown するだけでNATモードに戻せる。
設定手順¶
Windows側で .wslconfig を編集する：
notepad "$env:USERPROFILE\.wslconfig"
以下を記述して保存する。
[wsl2]
networkingMode = mirrored
変更を反映する。
wsl --shutdown
その後、WSL2を再起動する。mirroredモードになっていることは、WSL2側で ip a を実行してWindowsと同じIPアドレスが表示されることで確認できる。
切り替えが完了したら、次はポート競合の問題に対処する。
Step 4：ポート競合の確認と解消¶
mirroredモードでは、WindowsとWSL2がポートを共有する。Windows側でOpenSSH Serverが動作している場合、ポート22が競合してWSL2のsshdが起動できない。
競合の確認（PowerShell）：
netstat -ano | findstr ":22 "
結果が表示される場合、ポート22は既に使用されている。
パターンA：Windows側のSSH Serverを停止する（推奨）¶
Windows側のSSHサーバーを使用していない場合はこちらが簡単だ。
# 管理者権限のPowerShellで実行
Stop-Service sshd
Set-Service sshd -StartupType Disabled
この場合、WSL2のsshdはデフォルトのポート22で起動できる。
パターンB：WSL2のsshdを別ポートで動かす¶
Windows側のSSH Serverを維持したい場合は、WSL2側のポートを変更する。
sudo sed -i 's/#Port 22/Port 2222/' /etc/ssh/sshd_config
ポート競合を解消できたら、sshdを起動する。
Step 5：sshdを起動する¶
sudo service ssh start
起動確認を行う。
sudo service ssh status
sshd is running と表示されれば正常だ。
起動直後に停止する場合の診断：
sudo /usr/sbin/sshd -D -d
フォアグラウンド＋デバッグモードで起動し、エラーメッセージを直接確認できる。Address already in use と出た場合はStep 4に戻ってポート競合を解消する。
sshdの正常起動を確認できたら、Windows側からの疎通テストに進む。
Step 6：PowerShellからSSH接続を確認¶
Claude Code Desktopの接続前に、まずコマンドラインで疎通を確認する。この段階で問題を切り分けておくと、Step 8のトラブルシュートが容易になる。
# ポート22の場合
ssh WSLユーザー名@127.0.0.1
# ポート2222の場合
ssh -p 2222 WSLユーザー名@127.0.0.1
ユーザー名に注意
WindowsのユーザーとWSL2のユーザーは異なる場合がある。WSL2側のユーザー名は whoami コマンドで確認できる。
初回接続時のホスト鍵確認には yes と入力する。
パスワードが不明な場合は、WSL2側で再設定する。
sudo passwd $(whoami)
よくあるエラーと対処¶
| エラー | 原因 | 対処 |
|---|---|---|
Connection reset | sshdが起動していない | Step 5を確認 |
Connection timed out | ポート競合 or Firewall | Step 4を確認 |
Permission denied | ユーザー名 or パスワードの誤り | ユーザー名確認 + passwd |
Host key verification failed | known_hostsに古いエントリ | ssh-keygen -R 127.0.0.1 |
パスワード認証での接続が確認できたら、公開鍵認証の設定に進む。
Step 7：公開鍵認証を設定する（推奨）¶
パスワード認証でも動作するが、公開鍵認証を設定しておくと毎回のパスワード入力が不要になる。
鍵の生成（Windows PowerShell）：
ssh-keygen -t ed25519
実行すると3つの質問が表示される。
Enter file in which to save the key (C:\Users\ユーザー名/.ssh/id_ed25519):
何も入力せずEnterを押す。 デフォルトの保存先がそのまま使われる。ここにファイル名やパスを入力すると意図しない場所に保存されるため注意。
Enter passphrase (empty for no passphrase):
パスフレーズの設定。空のままEnterでスキップ可能。
Enter same passphrase again:
同様にEnter。
パスフレーズを設定するか？
パスフレーズは鍵ファイル自体を暗号化する追加のパスワードで、鍵ファイルが漏洩した場合の保険になる。ただしSSH接続のたびにパスフレーズの入力を求められるため、ローカルWSL2への接続用途であればパスフレーズなし（空Enter）で問題ない。 リモートサーバーへの接続に使う鍵であれば設定を推奨する。
鍵が正しく生成されたか確認する：
dir "$env:USERPROFILE\.ssh\id_ed25519.pub"
ファイルが表示されれば正常だ。「存在しないため検出できません」と表示される場合は、鍵生成時のファイル名の質問でデフォルト以外を入力した可能性がある。その場合は ssh-keygen -t ed25519 からやり直す。
公開鍵をWSL2に登録する¶
WSL2のターミナル側で作業するほうが確実だ。まずPowerShellで公開鍵の内容をコピーする。
cat "$env:USERPROFILE\.ssh\id_ed25519.pub"
表示された ssh-ed25519 AAAA... で始まる1行をコピーし、WSL2のターミナルで以下を実行する。
mkdir -p ~/.ssh
echo "ここにコピーした公開鍵を貼り付ける" >> ~/.ssh/authorized_keys
chmod 700 ~/.ssh
chmod 600 ~/.ssh/authorized_keys
パスワード認証でも一時的に使える
Claude Code Desktopは初回接続時にパスワード入力ダイアログを表示する。入力後はセッション中キャッシュされるため、しばらくは再入力不要。ただしセッションが切れるたびに再入力が必要になるため、公開鍵認証の設定を推奨する。
パスワードなしで接続できることを確認する。
ssh WSLユーザー名@127.0.0.1
ここまでで下準備は完了だ。最後にClaude Code Desktop側の設定を行う。
Step 8：Claude Code Desktopから接続¶
- Claude Code Desktop を開く
- Code タブを選択
- 接続方式のドロップダウンから SSH を選択
- 「SSH接続を追加」ダイアログが表示される
入力項目：
| フィールド | 入力例 | 説明 |
|---|---|---|
| 名前 | wsl | 任意の識別名 |
| SSHホスト | WSLユーザー名@127.0.0.1 | ユーザー名@ホスト の形式。WSL2側のユーザー名を使う |
| SSHポート | 2222 | ポートを変更した場合に指定。デフォルト22なら空欄でよい |
| IDファイル（秘密鍵） | ~/.ssh/id_ed25519 | デフォルトは ~/.ssh/id_rsa。ed25519で生成した場合は変更が必要 |
- 「SSH接続を追加」ボタンをクリック
- 初回接続時は「ワークツリーを信頼する」の確認に同意
- リモートフォルダーを選択して作業開始
IDファイルのデフォルトに注意
IDファイルのデフォルト値は ~/.ssh/id_rsa になっている。Step 7で ssh-keygen -t ed25519 で鍵を生成した場合は ~/.ssh/id_ed25519 に変更する必要がある。パスワード認証で接続する場合は空欄のままでよい。
パスワード認証のキャッシュ
初回にパスワード認証で接続が成功すると、しばらくはセッションがキャッシュされ、IDファイルの設定が正しくなくてもアクセスできてしまう場合がある。公開鍵認証が確実に機能しているか確認するには、Claude Code Desktopを完全に終了・再起動してから接続を試すのが確実だ。
Claude Code Desktopは接続情報を内部的に保持するため、Windows側の ~/.ssh/config を手動で編集する必要はない。
Tips¶
WSL2のsshdは再起動のたびに停止する¶
WSL2ではsystemdが有効でない限り、再起動のたびにsshdを手動で起動する必要がある。自動起動を設定する場合は、.bashrc に以下を追加する方法がある。
# ~/.bashrc の末尾に追加
if ! pgrep -x sshd > /dev/null; then
sudo service ssh start > /dev/null 2>&1
fi
sudoのパスワード入力を省略するには、visudoで設定する。
sudo visudo
# 以下を追加（ユーザー名は自身のものに変更）
username ALL=(ALL) NOPASSWD: /usr/sbin/service ssh start
接続がうまくいかないときのデバッグ¶
SSH接続の詳細ログを確認するには -v オプションを使用する。
ssh -v WSLユーザー名@127.0.0.1
問題の切り分けに有効な情報が出力される。
SSH接続でできること：活用アイデア5選¶
SSH接続をセットアップしたら、以下のような使い方が考えられる。
- WSL2上のDockerコンテナをGUIからデバッグ — コンテナのログ確認・ファイル編集・docker compose操作をDesktopのビジュアルdiff付きで行える
- 外出先からTailscale経由で自宅PCの開発を継続 — メッシュVPNとtmuxを組み合わせれば、カフェや移動中でもセッションを中断せずに作業できる
- クラウドVMのGPUインスタンスでML実験を管理 — AWS EC2やGCPのGPUマシンに接続し、学習スクリプトの修正・実行・結果確認をDesktop上で完結させる
- 本番サーバーの設定ファイルをビジュアルdiffで安全に編集 — nginx.confやsystemdユニットファイルの変更差分を目視確認してからデプロイできる
- 複数環境への並列セッションで横断的にリファクタリング — 開発・ステージング・本番それぞれにSSH接続を登録し、GUIから切り替えながら同一の修正を適用する
まとめ¶
Windows × WSL2でのClaude Code Desktop SSH接続は、ネットワークモード変更・ポート競合解消・バイナリ確認という3つの関門を越える必要がある。手順は多いが、一度構築すればSSHドロップダウンからワンクリックで接続できる。
SSH機能自体がまだ新しいため、接続中に予期しないエラーが発生する可能性がある。その場合はStep 6に戻ってPowerShellからの疎通確認で問題を切り分けるのが最も効率的だ。
Next Step：リモートサーバーへの応用¶
本記事ではローカルWSL2をターゲットにしたが、SSH機能の本領はインターネット経由のリモート接続にある。
応用パターン¶
| パターン | 概要 | 接続先の例 |
|---|---|---|
| クラウドVM | AWS EC2・GCPなどのLinuxインスタンスに直接接続 | ubuntu@<EC2ホスト名> |
| Tailscale経由の自宅PC | メッシュVPNで外出先から自宅WSL2に接続 | user@100.x.x.x（Tailscale IP） |
| Dev Container | Docker上の開発コンテナにSSHで接続 | dev@localhost:2222 |
| 踏み台サーバー経由 | ProxyJumpで多段SSH | 社内ネットワーク等 |
リモート側の制約¶
Claude Code DesktopのSSH機能は、接続先に専用バイナリ（~/.claude/remote/server 等）を自動デプロイして動作する。接続先には以下の条件がある。
| 項目 | 要件 |
|---|---|
| OS | Linux（x86_64）。claude-ssh-linux-amd64 バイナリが転送される |
| シェル | bash または sh（POSIX互換）。fish shellだと $! 構文の非互換で起動に失敗する報告あり |
| 権限 | ~/.claude/remote/ ディレクトリへの書き込み権限 |
| ネットワーク | Anthropic APIへのアウトバウンド通信が必要（API通信はリモート側から発生） |
| ARM対応 | ARM64（Raspberry Pi、Graviton等）は公式情報では未確認 |
SSH機能はまだ新しい
2026年2月時点でSSH機能は追加されたばかりであり、シェル互換性など既知の不具合が複数報告されている。GitHub Issues（anthropics/claude-code）で最新状況を確認することを推奨する。