Claude Media
Claude CodeがIDEに自動接続できないときの環境変数2つ
Claude CodeTips

Claude CodeがIDEに自動接続できないときの環境変数2つ

IDEが動いているのに見つからない症状で、接続先を上書きするCLAUDE_CODE_IDE_HOST_OVERRIDEと、lockfile検証を飛ばすCLAUDE_CODE_IDE_SKIP_VALID_CHECKの使い分け。

読了目安 約10分

IDEは起動していて拡張機能も入っているのに、Claude Codeが「IDEが見つからない」と言う。そのときに試せる環境変数が CLAUDE_CODE_IDE_HOST_OVERRIDE と CLAUDE_CODE_IDE_SKIP_VALID_CHECK の2つです。前者は接続先のホストアドレスを手動で指定し、後者はIDEが書き出したlockfileの検証を飛ばします。

ただし、この2つは最初に触る変数ではありません。自動接続が働く条件を満たしているか、WSL2のネットワークが邪魔をしていないかを先に切り分けると、多くの場合は変数なしで片づきます。この記事では、切り分けの順番と2変数の使い分けをまとめます。

2つの環境変数は何を変えるのか

環境変数リファレンスの記載は、それぞれ1行です。

変数設定値働き
CLAUDE_CODE_IDE_HOST_OVERRIDE設定値ホストアドレス働きIDE拡張機能への接続先アドレスを上書きする。既定では、WSLからWindowsへの経路を含め、正しいアドレスを自動検出する
CLAUDE_CODE_IDE_SKIP_VALID_CHECK設定値1働き接続時にIDEのlockfileエントリの検証を飛ばす。IDEが動いているのに自動接続が見つけられないときに使う

どちらも「自動検出がうまく働かないときの手動の逃げ道」です。症状が違えば効く変数も違います。

くらべる

症状から選ぶ2変数

IDE は見つかるが届かない

HOST_OVERRIDE

IDEが別のホスト側で動いている構成向けです。WSL2からWindows側のIDEへ向かう場合が典型です。

IDE が候補に出てこない

SKIP_VALID_CHECK

lockfileはあるのに、検証で弾かれて候補から外れているときの切り分けに使います。

lockfileは、IDE側が起動のたびに書き出すファイルです。VS Code拡張もJetBrainsプラグインも、ランダムな認証トークンを ~/.claude/ide/<port>.lock に書き、CLIはそのトークンを X-Claude-Code-Ide-Authorization ヘッダーに載せて接続します。ポートはIDEが毎回割り当て、固定はできません。このlockfileの「検証」が何を見ているかは、リファレンスの1行に書かれていません。

変数を触る前に確認する4つのこと

起動場所はIDEの統合ターミナルか

自動接続の既定の動作は、IDEの統合ターミナルから claude を起動したときに接続する、というものです。外部ターミナルから起動した場合は、/ide を実行して手動で接続します。JetBrainsのトラブルシューティングにも、自動接続を期待するなら統合ターミナルから起動したかを確かめるよう書かれています。

外部ターミナルで毎回 /ide を打ちたくないなら、起動時に --ide を付ける方法があります。有効なIDEがちょうど1つあるときに、起動時に自動接続するフラグです。IDEが複数起動していると接続されない点に注意してください。

claude --ide

外部ターミナルでの自動接続は既定で無効

autoConnectIde は外部ターミナルからの自動接続を制御する設定で、既定は false です。true にすると、外部ターミナルから起動しても実行中のIDEに自動接続します。この設定はグローバル設定(~/.claude.json)に書くもので、settings.json に書いても無視されます。

{
  "autoConnectIde": true
}

1回のセッションだけ上書きしたい場合は、環境変数 CLAUDE_CODE_AUTO_CONNECT_IDE が使えます。false で自動接続を止め、true で強制的に接続を試みます。tmuxが親ターミナルを隠して自動検出が失敗するケースが、挙げられている例です。この変数は autoConnectIde より優先されます。

つまり「見つからない」の前に、そもそも自動接続を試す条件にいるかを見る必要があります。3つの入口を並べると次のとおりです。

入口効く場面
統合ターミナルから起動効く場面既定で自動接続
autoConnectIde / CLAUDE_CODE_AUTO_CONNECT_IDE効く場面外部ターミナルやtmux経由でも自動接続させたい
/ide / --ide効く場面その場で手動接続

拡張機能・プラグインは入っているか

JetBrainsでは、/ide が「No available IDEs detected」と返す原因として、プラグインの未導入・無効、IDEの再起動漏れが挙がっています。プラグインが入っていないIDEをClaude Codeが見つけた場合、/ide が導入してくれて、IDEの再起動を求められます。

JetBrains Remote Developmentでは、プラグインの入れ先に注意が要ります。手元のクライアント側ではなく、リモートホスト側のSettings → Plugin (Host)に入れる必要があります。クライアント側にだけ入れていると、プラグインを入れたはずなのにIDEが見つからない状態になります。

VS Codeでも、拡張機能の自動インストールは autoInstallIdeExtension(既定 true)で制御されます。止めたい場合は CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL=1 です。名前が似ていますが、これは拡張機能の導入を飛ばす変数で、接続の検証を飛ばす SKIP_VALID_CHECK とは別物です。

設定ディレクトリが食い違っていないか

lockfileの置き場所は、CLAUDE_CONFIG_DIR が設定されていると $CLAUDE_CONFIG_DIR/ide/ に変わります。IDEとCLIで設定ディレクトリが違えば、CLIが見る場所にlockfileが無い、という状況は理屈の上で起こり得ます。複数アカウントを CLAUDE_CONFIG_DIR で使い分けている環境では、この点も確認の対象です。ドキュメントに失敗例として載っているわけではないため、あくまで切り分けの観点です。

CLAUDE_CODE_IDE_HOST_OVERRIDEを使う場面

WSL2からWindows側のIDEに届かない

この変数が最も効きそうなのは、WSL2の中で claude を動かし、IDEはWindows側で動かしている構成です。既定ではWSLからWindowsへの経路を含めて自動検出するため、通常は指定不要です。

JetBrainsのドキュメントは、WSL2で「No available IDEs detected」が出る主な原因を、WSL2のNATネットワークまたはWindows FirewallがWSL2とWindows上のIDEの間の通信を塞いでいることとしています。WSL1はホストのネットワークをそのまま使うため、影響を受けません。

この場合、JetBrainsのドキュメントが勧める対処は変数ではなくネットワーク側です。

  1. Windows Firewallに、WSL2のサブネット内の通信を許可するルールを追加する(既存のネットワークモードを保てるため、推奨されている)
  2. .wslconfig に networkingMode=mirrored を書き、wsl --shutdown でWSLを再起動する(Windows 11 22H2以降が条件。Windows 10では1を使う)
hostname -I

ファイアウォールのルールは、このコマンドで得たIPアドレスの先頭2区画を使い、172.21.123.45 なら 172.21.0.0/16 のサブネットで作ります。JetBrainsの設定には、ループバック以外からの接続を受け付けるAccept connections from all network interfacesもあります。この設定はWSL2の既定のNATだけでなく、リモートIDEの構成でCLIがループバックから届かないときのためにも用意されています。ただし有効にすると、暗号化のない ws:// の通信とトークンがローカルネットワークに流れるため、ループバックで通せないときに限るよう注意されています。WSL2ではミラーモードが先に勧められています。

それでも届かないときに接続先を指定する

ファイアウォールとネットワークモードを見直しても届かないとき、接続先を直接渡すのが CLAUDE_CODE_IDE_HOST_OVERRIDE です。値はWSL2から見たWindowsホストのアドレスにします。

CLAUDE_CODE_IDE_HOST_OVERRIDE=<Windowsホストのアドレス> claude

アドレスの調べ方、ポートの扱い、値に使える書式は、リファレンスに載っていません。ポートはIDEが起動のたびに割り当てるので、ポートまで指定する変数ではないはずですが、これは推測です。IDE側もループバックだけで待ち受けていると、アドレスを指定しても届きません。VS Code拡張はループバック(127.0.0.1)限定で待ち受ける設計と説明されているため、VS CodeとWSL2の組み合わせでは、この変数だけでは解決しない可能性があります。JetBrainsはネットワークインターフェースの待ち受け設定を持つので、組み合わせて使う余地があります。

CLAUDE_CODE_IDE_SKIP_VALID_CHECKを使う場面

IDEは動いていて、拡張機能も入っていて、統合ターミナルから起動しているのに候補に出てこない。リファレンスがこの変数の使う場面として書いているのは、まさにこの状態です。

CLAUDE_CODE_IDE_SKIP_VALID_CHECK=1 claude --ide

使い方の流れは、次のとおりです。

手順

SKIP_VALID_CHECK で切り分ける手順

  1. 1

    通常の起動で再現させる

    変数なしで claude を起動し、/ide で「No available IDEs detected」が出ることを確かめます。

  2. 2

    変数を付けて1回だけ起動する

    CLAUDE_CODE_IDE_SKIP_VALID_CHECK=1 を付けて起動し直し、接続できるかを見ます。

  3. 3

    結果で原因を絞る

    接続できたなら、lockfileの検証で弾かれていたことになります。IDEの完全な再起動や、残っている古いlockfileの整理を試します。接続できなければ、別の原因を探します。

「検証を飛ばして繋がる」のは症状の回避であって、検証に引っかかった理由の解消ではありません。検証の目的も副作用も書かれていないので、常用するより、原因を絞るための1回きりの確認に使うのが無難です。古いlockfileが原因なら、IDEを完全に終了してから開き直すと、起動のたびに新しいlockfileが書き出されます。

恒久的に設定したいとき

シェルの export のほか、設定ファイルの env ブロックにも書けます。env に書いた値は、シェル由来の値を置き換えるのが原則です。

{
  "env": {
    "CLAUDE_CODE_IDE_HOST_OVERRIDE": "<Windowsホストのアドレス>"
  }
}

ただしWSL2のホスト側アドレスは、一般的なWSL2の挙動として再起動で変わることがあります。アドレスを固定値で書くと、次の起動で外れる恐れがあります。チーム共有の設定ファイルに書くのも避けたほうがよく、手元の .claude/settings.local.json か、シェルの export に留めると事故が減ります。SKIP_VALID_CHECK を env に常駐させるのは、前節の理由から勧められません。

接続できたかを確かめる

接続できると、/ide の結果として Connected to IntelliJ IDEA. のような確認メッセージが出ます(JetBrainsの場合)。接続中は、エディタで選択した範囲とアクティブなファイルのパスが、プロンプトごとにコンテキストへ加わります。会話には ⧉ Selected N lines from <file> の行が出ます。

IDEの診断情報は、モデルから mcp__ide__getDiagnostics として呼べます。VS CodeではProblemsパネルの内容を、JetBrainsではエディタに出ているエラーと警告を返します。接続が確立されたかどうかは、この表示で判断できます。

機密ファイルが選択状態で送られるのが気になる場合は、.env などに Read のdenyルールを置くと、選択範囲とアクティブファイルの通知がClaudeに届かなくなります。

IDEごとの対応範囲

この2変数が前提にしているのは、VS Code系とJetBrains(IntelliJ IDEA、PyCharm、Android Studio、WebStorm、PhpStorm、GoLandなど)の連携です。EclipseとVisual Studioの対応状況はClaude CodeはEclipse非対応とClaude CodeはVisual Studio 2026に統合できるかにまとめています。VS Code側で拡張機能そのものが応答しない場合は、VS Code拡張機能が応答しないときの切り分け手順が入口になります。RiderとWSLでパスが食い違う場合はRiderでWSLのパスがIDEと食い違うときの対処、プラグインの導入手順はClaude CodeのJetBrainsプラグインが入口になります。JetBrainsの2つの選択肢の違いはJetBrainsのClaude AgentとClaude Codeプラグインの違いで扱っています。環境変数全体の一覧はClaude Codeの設定項目一覧にあります。

まとめ

IDEが見つからないときは、統合ターミナルか、autoConnectIde か、プラグインの導入か、CLAUDE_CONFIG_DIR の食い違いか、WSL2のネットワークかの順に見ます。それでも残る症状に、接続先を渡す CLAUDE_CODE_IDE_HOST_OVERRIDE と、lockfileの検証を飛ばす CLAUDE_CODE_IDE_SKIP_VALID_CHECK を当てます。後者は原因を絞る1回きりの確認用、前者はWSL2でファイアウォールとミラーモードを試した後の手段と考えると、使い分けが決まります。

この記事を共有:XはてブLinkedIn

関連する記事

Claude Code をもっと見る →