Claude Media
Claude Code WSL2セットアップ — パスとNode.js、sandboxの落とし穴

Claude Code WSL2セットアップ — パスとNode.js、sandboxの落とし穴

Claude CodeをWSL2で使うときのセットアップ手順と、パスの取り違え・ブラウザーログイン・sandbox有効化まで、WSL特有のつまずきをまとめます。

WSL1とWSL2のどちらで動いているかを先に見る

公式のsetupページは、WSL1を「WSL2が使えない場合」の選択肢として載せています。ただしサンドボックスは非対応で、後述の既知の不具合も残っています。Desktopアプリ側のWSLセッションに至っては、WSL1は対象外です。

選択肢

Windowsでの3つの動かし方

  • ネイティブWindows

    PowerShellかCMDにインストールして使います。サンドボックスは非対応で、コマンドはサンドボックスなしで実行されます。

  • WSL2

    Linux用のインストーラーをWSLのターミナルで実行します。サンドボックスに対応するのはこの形だけです。

  • WSL1

    WSL2が使えないときの選択肢です。サンドボックスは非対応で、下記のExec format errorを踏みます。

PowerShellでwsl -l -vを実行すると、ディストリビューションごとのバージョンがVERSION列に出ます。

WSL1のままclaudeを実行するとcannot execute binary file: Exec format errorが出ることがあります。バイナリのプログラムヘッダーがWSL1のローダーで扱えない形式になった、既知の不具合です。GitHub issue #38788で追跡されています。もっとも確実な対処はWSL2への変換です。

wsl --set-version <ディストリビューション名> 2

WSL1のまま使うなら、動的リンカ経由でバイナリを呼ぶ関数を~/.bashrcに足す回避策があります。ホームディレクトリの場所が違う場合は、パスを読み替えます。

claude() {
  /lib64/ld-linux-x86-64.so.2 "$(readlink -f "$HOME/.local/bin/claude")" "$@"
}

追記したらsource ~/.bashrcで読み込み直します。回避策なので恒久対応にはなりません。原因の詳細はWSL1 Exec format errorの原因とWSL2移行にまとめています。

WSL2にClaude Codeをインストールする

WSLディストリビューションのターミナルを開き、Linux用のインストールコマンドを実行します。PowerShellやCMDからではなく、必ずWSLのターミナル内で実行します。Git for Windowsは、WSLの構成では要りません。

curl -fsSL https://claude.ai/install.sh | bash

Windowsをネイティブで使うか、WSL2でLinux環境として使うかの判断基準はClaude Code Windowsインストールにまとめています。

npmで入れて「node: not found」になるとき

npm経由で入れた場合に限って、WSL側でWindowsのnpmやnodeを拾う事故が起きます。公式インストーラーで入れたなら、この節は読み飛ばせます。

プラットフォームの不一致をnpmが報告したら、Windows側のnpmを拾っています。npm config set os linuxを先に実行してから、npm install -g @anthropic-ai/claude-code --forceを実行します。sudoは付けません。

claudeの実行時にexec: node: not foundと出る場合も、Windows側のNode.jsを掴んでいる状態です。which npmとwhich nodeを実行し、結果が/mnt/c/で始まっていればWindows側のバイナリです。Linux側なら/usr/から始まります。LinuxディストリビューションのパッケージマネージャーかnvmでNode.jsを入れ直します。切り分けの詳細は「node: not found」エラーの原因で扱っています。

nvmをWSLとWindowsの両方に入れていると、WSLはWindows側のPATHを既定で取り込むため、Windows側のnvmが優先されます。バージョンの切り替えが効かない原因として最も多いのは、WSLのシェルでnvmが読み込まれていないことです。~/.bashrcか~/.zshrcに次の3行を足します。

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"

読み込んでもWindows側のパスが優先されるなら、Linux側のNode.jsのパスを先頭に足します。

export PATH="$HOME/.nvm/versions/node/$(node -v)/bin:$PATH"

appendWindowsPath = falseでWindows側のPATH取り込みを切る方法は、Windowsの実行ファイルをWSLから呼べなくなるので避けてください。Windows側のNode.jsをアンインストールする対処も、Windowsで開発を続けるなら避けます。

ログイン時にブラウザーが開かない・戻ってこない

WSL2・SSH・コンテナ内でClaude Codeを起動すると、ブラウザーが別ホストで開くことがあります。ログイン後のリダイレクトがClaude Codeのローカルのコールバックサーバーに届かないため、ブラウザーにはログインコードが表示されます。コードをターミナルのPaste code here if promptedというプロンプトに貼り付ければ、認証は完了します。

ブラウザーが自動で開かないときは、cキーでログインURLをクリップボードにコピーし、Windows側のブラウザーに貼ります。BROWSER環境変数にWindows側ブラウザーのパスを設定する方法もあります。

export BROWSER="/mnt/c/Program Files/Google/Chrome/Application/chrome.exe"
claude

コードを貼り付けても効かないときは、ターミナルごとの別の貼り付け操作を試します。Windows Terminalなら右クリックかShift+Insertが多く、claude auth loginで代替する方法もあります。このコマンドは、貼り付けたコードを標準入力から読み取ります。事前にログインだけ済ませたい場合にも使え、v2.1.289の--helpに出るオプションは--claudeai(既定)・--console・--email・--ssoの4つです。ブラウザーの指定はBROWSER環境変数が受け持ちます。アカウント作成からログイン方式全体はClaudeログイン完全ガイドを参照してください。

検索結果が少ないときはプロジェクトの置き場所を疑う

検索結果が少ない症状は、Windows側とLinux側のファイルシステムをまたぐ読み取りが原因です。プロジェクトをWindows側(/mnt/c/)に置くと、クロスファイルシステムのディスク読み取りが遅くなります。その結果、期待より少ない件数しかヒットしないことがあります。検索自体は動くので、エラーは出ません。

claude doctorも手がかりになりません。この症状のときも、Searchの行は正常と表示されます。macOS上のv2.1.289で実行した出力は次のとおりです。

$ claude doctor
Claude Code doctor
 
Running: native (2.1.289)
Platform: darwin-arm64
Search: OK (bundled)
Auto-updates: enabled

対処は3つあります。

  • 検索を具体的にする。「auth-serviceパッケージでJWTの検証ロジックを探して」のように、ディレクトリやファイル種別を絞る
  • プロジェクトをLinux側(/home/配下)に置き直す
  • WSLをやめて、ネイティブWindowsで動かす

迷ったらpwdでプロジェクトのパスが/mnt/c/で始まるか、/home/配下かを見ます。Windows側のファイルシステムを指していれば、この節の症状が当てはまります。バックグラウンドタスクが空きメモリ十分でも「low memory」で止まる場合は、パスとは別原因のWSL2のlow memory誤検知を参照してください。

sandboxモードをWSL2で有効にする

sandboxモードは、コマンドごとにファイル書き込みとネットワークアクセスを制限する機能です。WSL2ではLinuxと同じくbubblewrapとsocatに依存します。

手順

WSL2でsandboxを使えるようにする

  1. 1

    依存パッケージを入れる

    UbuntuやDebian系のディストリビューションでは、次のコマンドです。

    sudo apt-get install bubblewrap socat
  2. 2

    Claude Codeを再起動して/sandboxを開く

    再起動しないと、/sandboxパネルが追加したパッケージを検知しません。必須の依存が足りないと、パネルにはDependenciesタブだけが出ます。このタブには、ripgrep・bubblewrap・socat・seccompフィルターのうち不足しているものが並びます。seccompフィルターだけが欠けている場合は、他のタブと並んでこのタブが出ます。タブが出なければ、依存は揃っています。

  3. 3

    Ubuntu 24.04以降ではAppArmorを確認する

    既定のAppArmorポリシーが、bubblewrapのユーザー名前空間の作成を止めていることがあります。sysctl kernel.apparmor_restrict_unprivileged_usernsを実行します。0が返るか、No such file or directoryが出るなら、この手順は不要です。1が返ったら、bwrap専用のプロファイルを追加します。

    sudo tee /etc/apparmor.d/bwrap > /dev/null <<'EOF'
    abi <abi/4.0>,
    include <tunables/global>
     
    profile bwrap /usr/bin/bwrap flags=(unconfined) {
      userns,
      include if exists <local/bwrap>
    }
    EOF
    sudo systemctl reload apparmor

    このプロファイルが効くのはbwrap自体だけで、サンドボックスの中で動くコマンドには及びません。

WSL1のままだと、Sandboxing requires WSL2と表示されます。WSL2に上げるか、サンドボックスなしで使います。

依存が足りないままだと、既定ではサンドボックスなしでコマンドが走ります。sandbox.failIfUnavailableをtrueにすると、サンドボックスを起動できないときはClaude Codeの起動そのものを止められます。

Windows側の実行ファイルを呼ぶときの設定

WSL2では、cmd.exeやpowershell.exe、/mnt/c/配下の実行ファイルの起動を、Unixソケット経由でWindows側に橋渡しします。サンドボックス化されたコマンドからこれらを起動できるかどうかは、Unixソケット関連の設定次第です。ソケットを塞ぐにはseccompフィルターの導入が前提になります。起動を許可するなら、すべてのUnixソケットを開くallowAllUnixSocketsを使います。特定のコマンドだけサンドボックスの外で動かすならexcludedCommandsです。

air-gapped環境のようにbubblewrapとsocatをPATHの外へ置く組織は、sandbox.socatPathで管理設定にパスを固定する方法も検討してください。個人・チーム・企業のレイヤー別にどこまで許可するかは、Claude Codeセキュリティ・権限ガイドで扱っています。sandbox有効なのに無サンドボックスで走る症状はWSL2のsandbox失敗の確認にまとめています。

sandboxの中でlocalhostとSSHがどう見えるか

Linux側と同様にWSL2でも、サンドボックス内のコマンドのlocalhostは、そのコマンド専用です。自分で起動したサーバーには届きますが、ホスト側で動いているサーバーには届きません。allowLocalBindingを設定しても効きません。ホストのサーバーに繋ぐコマンドは、excludedCommandsでサンドボックスの外へ出します。

SSHリモートへのgit操作は、WSL2では接続先を許可すれば通ります。それでも繋がらなければ、次の3点を見ます。

  • 接続先がポート22で許可されているか。ポートなしのallowedDomainsエントリーは22番を含みます
  • 社内プロキシがポート22を通すか
  • 鍵がファイルとして読めるか。ssh-agentのソケットが塞がれることがあり、~/.sshへのdenyReadがあると鍵ファイルも隠れます

DesktopのWSLセッションとCLI直起動の違い

Claude Code DesktopアプリのCodeタブにも、WSL2のディストリビューション内でセッションを開始する機能があります。どちらを使うかは、必要な機能で決まります。

くらべる

DesktopのWSLセッションとWSLターミナルのCLI

GUIで使う

DesktopのWSLセッション

使えるのは、並行セッション・サイドチャット・差分レビュー・ブランチとプルリクエストの状態・worktreeです。統合ターミナル・コネクタとプラグイン・セッションのフォーク・ファイルブラウザーペイン・@によるファイル候補は、まだ使えません。必要なのはWSL2と、ディストリビューション内のgitです。

設定を直接触る

WSLターミナルのCLI

機能の制限がなく、settings.jsonも直接調整できます。WSLでは、画像の貼り付けにCtrl+VとAlt+Vの両方が既定で割り当てられています。

DesktopのWSLセッションでは、フォルダーを信頼するかどうかを、ディストリビューションとフォルダーの組み合わせごとに決めます。あるディストリビューションで信頼したフォルダーは、別のディストリビューションでも、Windows上の同じパスでも信頼されません。ディストリビューションで初めてセッションを開くときは、Claude Codeが中でセットアップするため、起動が少し遅くなります。

通常のフォルダーピッカーから\\wsl.localhost\...のフォルダーを開くと、そのディストリビューション内で開き直されます。「エディタで開く」を選ぶと、Remote - WSL拡張機能経由でVS Codeがそのディストリビューションに接続した状態で開きます。拡張機能そのものの使い方はClaude Code VS Code拡張機能の使い方を参照してください。組織管理下のデバイスでは、管理者の設定によってWSLセッション自体が使えないことがあります。

まとめ

サンドボックスを使うならWSL2、プロジェクトはLinux側のファイルシステム、Node.jsはWSL側で管理する、という3点が分かれ目です。症状が出たときは、wsl -l -vのバージョン、pwdが示すプロジェクトのパス、which nodeの出力、/sandboxのDependenciesタブの順に見ると切り分けが早くなります。個別のエラーからの切り分けはClaude Codeでよくあるエラー10選にもあります。

参照した一次ソース

この記事の記述は、次の一次ソースと照合しています。更新時に参照先が変わった場合は一覧も更新します。

  1. code.claude.com/docs/ja/setup
  2. code.claude.com/docs/ja/troubleshoot-install
  3. code.claude.com/docs/ja/troubleshooting
  4. code.claude.com/docs/ja/sandboxing
  5. code.claude.com/docs/ja/desktop-wsl
  6. code.claude.com/docs/ja/keybindings
  7. code.claude.com/docs/ja/authentication
  8. code.claude.com/docs/ja/settings-reference
  9. code.claude.com/docs/ja/cli-reference
この記事を共有:XはてブLinkedIn