Claude Codeをv2rayNで使う方法｜ターミナル接続設定ガイド

Claude Codeをターミナルから使うとき、ブラウザーでは正常に通信できるのに、認証画面が開かない、ログイン後にCLIへ戻れない、パッケージ取得がタイムアウトする、といった問題が起きることがあります。原因はClaude Codeそのものではなく、ターミナルがシステムプロキシを自動参照しないこと、v2rayNのローカルポートと環境変数が一致していないこと、または認証用ドメインだけが別の経路へ送られていることにあります。

この記事では、Windows上のv2rayN 7.xとXrayコアを例に、Claude Codeから利用するためのプロキシ方式を整理します。既存のノードを選択し、v2rayNのHTTPプロキシを確認し、PowerShellで一時的に環境変数を設定して接続を検証します。設定を恒久化する場合の注意点、npmやGitなど別の開発ツールへ影響を広げない方法、認証エラーと通信エラーを分けて調べる手順も説明します。

Claude Codeがv2rayNを自動で使うとは限らない

v2rayNで「システムプロキシ」を有効にすると、Windowsのプロキシ設定を参照するブラウザーやデスクトップアプリは、通常HTTPまたはHTTPS通信をローカルのv2rayNへ送信できます。しかし、ターミナルで動作するCLIは、必ずしもWindowsのシステムプロキシを読み取るとは限りません。Node.jsを基盤にしたツールでは、起動時の環境変数 HTTP_PROXY、HTTPS_PROXY、ALL_PROXY などを参照して通信経路を決めることがあります。

Claude Codeの通信をv2rayNへ渡すには、まずプロキシの入口を明示するのが確実です。HTTPSで接続するサービスであっても、クライアントからローカルプロキシへ送る指定は一般に http://127.0.0.1:10809 のようなHTTPプロキシ形式を利用できます。これは接続先がHTTP通信になるという意味ではありません。ローカルのHTTPプロキシがHTTPSのCONNECT要求を受け、v2rayNが選択したノードへ暗号化された通信を中継します。

SOCKSポートを使う場合は、ツール側がSOCKSプロキシに対応しているかを確認してください。HTTPS_PROXY=socks5://127.0.0.1:10808 と設定しても、利用しているHTTPライブラリがSOCKS形式を処理できなければ接続できません。最初の検証では、v2rayNのHTTPポート10809を優先し、CLI側の対応状況を増やさないことが重要です。

v2rayNで先に確認する設定

ターミナルの設定を変更する前に、v2rayN単体でノードが使える状態か確認します。サブスクリプションの更新に失敗している、選択中のノードがタイムアウトしている、Xrayコアの起動に失敗している場合、環境変数を正しく設定してもClaude Codeは通信できません。ブラウザーでHTTPSサイトを開けるか、v2rayNのログにDNS失敗やTLSハンドシェイク失敗がないかを確認してください。

• コア：v2rayN 7.xで選択中のXrayコアが起動していることを確認します。サブスクリプションのノードに対応するコアを選びます。
• ローカルポート：「設定」→「パラメーター設定」またはローカルプロキシ設定で、HTTP待受が10809、SOCKS待受が10808になっているか確認します。
• アドレス：通常は 127.0.0.1 を使います。LAN内へ公開する必要がなければ、待受アドレスを 0.0.0.0 に変更しないでください。
• システムプロキシ：ブラウザー確認には有効ですが、Claude Codeの環境変数設定の代わりになるとは限りません。
• ルーティング：認証やAPI通信に関係するドメインが、意図せず直接接続へ送られていないか確認します。

PowerShellでClaude Codeへプロキシを設定する

最初は現在開いているPowerShellだけに設定します。この方法なら、設定を閉じた後に元へ戻り、他のターミナルやサービスへ影響を与えません。v2rayNのHTTPポートが10809ではない場合は、実際に表示されている番号へ置き換えてください。ポート番号を推測したまま進めると、CLI側では単に接続タイムアウトとして見えることがあります。

1. ノードを接続する

   v2rayNを起動し、更新済みのサブスクリプションから利用可能なノードを選択します。ブラウザーでHTTPSページを開き、先にノードの基本接続を確認してください。

2. HTTPポートを確認する

   v2rayNの「設定」→「パラメーター設定」を開き、HTTPプロキシの待受アドレスとポートを確認します。例としてアドレスは127.0.0.1、ポートは10809です。

3. 環境変数を設定する

   PowerShellで次のコマンドを実行します。大文字・小文字は通常区別されませんが、複数のプロキシ変数を同じ入口へそろえると、ライブラリごとの差を減らせます。

4. CLIを起動する

   同じPowerShellウィンドウからClaude Codeを起動します。別のウィンドウで起動すると、そのセッションには環境変数が引き継がれないため注意してください。

5. 接続結果を確認する

   認証画面、プロジェクトの読み込み、簡単なコマンド実行の順に確認します。失敗した時刻とv2rayNのログ時刻を照合し、要求がローカルコアへ到達したかを調べます。

$env:HTTP_PROXY="http://127.0.0.1:10809"
$env:HTTPS_PROXY="http://127.0.0.1:10809"
$env:ALL_PROXY="http://127.0.0.1:10809"
$env:NO_PROXY="127.0.0.1,localhost"

claude

NO_PROXY は、ローカルアドレスをプロキシへ送らないための例です。社内開発サーバーや特定のローカルドメインを直接接続したい場合は、環境に合わせて追加します。ただし、広すぎるパターンを設定すると、外部サービスまで直接接続になる可能性があります。まずは 127.0.0.1,localhost だけにして、必要性を確認してから増やしてください。

Claude CodeがNode.jsの実行環境から起動される構成では、npmの取得通信が別の設定を参照することがあります。依存パッケージのインストールだけ失敗する場合は、Claude Codeの問題と決めつけず、同じターミナルでパッケージマネージャーを実行した時の挙動も確認します。認証用通信とパッケージ取得の両方が同じタイミングで失敗するなら、まずv2rayNのポート、ノード、ルーティングを優先して調べます。

ターミナルから実際の経路を検証する

環境変数の存在だけでは、通信が成功したことは分かりません。まずPowerShellからローカルポートへ接続できるか確認し、次にプロキシ経由のHTTPS要求をテストします。外部サービスのURLや応答内容は環境により変わるため、ここではTLS接続とHTTPステータスを観察する基本的な方法を使います。

Test-NetConnection 127.0.0.1 -Port 10809

curl.exe -I -x http://127.0.0.1:10809 https://example.com

TcpTestSucceeded : True なら、少なくともPowerShellから10809へTCP接続できます。これはノードの認証やClaude Codeの認証成功を意味しません。次の curl.exe で応答ヘッダーが返れば、HTTPプロキシがCONNECT要求を受けて外部HTTPS接続を確立できる可能性が高くなります。Windows PowerShellでは、別名の影響を避けるため curl ではなく curl.exe と明示するのが安全です。

ローカルポートへの接続が失敗する場合は、Claude Codeを再インストールする前に、v2rayNのコア状態とポート競合を確認します。v2rayNのログに bind、address already in use、または待受ポートに関するエラーがあれば、環境変数ではなくローカルインバウンドの問題です。一方、ローカルポートは開いているのに外部要求だけが失敗する場合は、選択ノード、DNS、ルーティング、TLSの順に切り分けます。

認証エラーとルーティングを切り分ける

ブラウザー認証では、ログインページを開く通信、認証後にCLIへ戻る通信、CLIがセッション状態を確認する通信が別々に発生することがあります。ログインページだけ表示され、完了後にCLIが認証済みにならない場合は、認証リダイレクト先やコールバック通信が直接接続へ回っていないか確認してください。ブラウザーはv2rayNを使っていても、CLIは別セッションとして動作するため、両方の経路が一致しているとは限りません。

• 認証画面が開かない：環境変数が設定された同じターミナルから起動したか、10809が待受中かを確認します。
• ログイン後にCLIへ戻らない：ブラウザー側とCLI側でプロキシ経路が分かれていないか、認証用のローカルコールバックが NO_PROXY に含まれているかを確認します。
• 認証後にすぐ切断される：v2rayNのログでTLSエラー、リセット、DNS失敗、タイムアウトを確認します。ノードを一時的に変更して比較すると、アカウント問題と経路問題を分けやすくなります。
• パッケージ取得だけ失敗する：npmなどが独自のプロキシ設定を持っていないか確認します。Claude Codeの環境変数だけで、別のツールの設定まで自動的に変更されるとは限りません。

日常運用で安定させるポイント

Claude Codeを継続利用するなら、毎回異なるノードやポートを試すより、動作確認済みのプロファイルを1つ基準にすると障害の再現性が高まります。v2rayNでは、普段使うノード、HTTPポート、ルーティングモード、DNS設定を記録し、変更した項目を一度に増やさないようにします。特にTUNモードと環境変数を同時に切り替えると、CLIがHTTPプロキシを使ったのか、TUNが通信を捕捉したのか判別しにくくなります。

1. 通常はシステムプロキシまたはCLIの環境変数のどちらを主経路にするか決めます。
2. Claude Codeの検証では、HTTPプロキシ10809を優先し、接続ログを保存します。
3. 動作後にTUNを試す場合は、環境変数を一時的に解除して、経路の違いを比較します。
4. 認証トークンやセッション情報をコマンド履歴へ直接入力しないようにします。
5. ノード変更後は、ローカルポート、DNS、外部HTTPS、Claude Codeの順に再確認します。

PowerShellの一時設定を解除する場合は、次のように実行します。現在のウィンドウだけが対象なので、別のターミナルで設定した値には影響しません。

Remove-Item Env:HTTP_PROXY -ErrorAction SilentlyContinue
Remove-Item Env:HTTPS_PROXY -ErrorAction SilentlyContinue
Remove-Item Env:ALL_PROXY -ErrorAction SilentlyContinue
Remove-Item Env:NO_PROXY -ErrorAction SilentlyContinue

最終的に重要なのは、「v2rayNは接続済み」「ブラウザーは開ける」「CLIの環境変数がある」「CLIの要求が同じノードから出ている」という4つを別々に確認することです。どれか1つを確認しただけで全経路が正常とは判断できません。まず一時的なHTTPプロキシ設定でClaude Codeの認証と簡単な実行を確認し、その後に必要なルールや恒久設定を追加する流れが、最も安全で戻しやすい方法です。