Claude Codeをターミナルから利用するとき、ブラウザーや一般的なデスクトップアプリで通信できていても、Claude Codeのリクエストだけが失敗することがあります。これは、v2rayNのシステムプロキシ設定と、ターミナルで起動したプロセスのプロキシ設定が別に扱われるためです。v2rayNでローカルポートを確認し、シェルの環境変数へ正しいプロキシURLを指定することで、開発ツールの通信経路を明確にできます。
v2rayNでノードを接続した後、HTTPプロキシまたはSOCKSプロキシの待受ポートを確認し、Claude Codeを起動するシェルへHTTP_PROXY、HTTPS_PROXY、必要に応じてNO_PROXYを設定します。設定後は環境変数、ポート待受、実際のAPI通信を順番に確認すると、認証エラーとプロキシ接続エラーを切り分けやすくなります。
v2rayNの接続とターミナルの通信は別に考える
v2rayNは、選択したノードを使ってローカルマシン上にHTTPプロキシやSOCKSプロキシの待受口を作ります。ブラウザーがそのポートを利用するように設定されていれば、ブラウザーの通信はプロキシを経由します。しかし、ターミナルから起動するClaude Code、パッケージマネージャー、Gitクライアント、各種CLIツールは、必ずしもOSのシステムプロキシ設定を自動的に読み取るとは限りません。
この違いを理解しないまま「v2rayNは接続中なのにClaude Codeが使えない」と判断するのは早すぎます。確認すべき経路は、v2rayNがノードへ接続しているか、ローカルポートが待ち受けているか、シェルの環境変数がそのポートを指しているか、Claude Codeが利用するAPIへのTLS接続が成立するか、という4段階です。どこで止まっているかによって、修正する場所が変わります。
v2rayNの設定画面では、バージョンや表示モードにより項目名が少し異なる場合がありますが、通常は「設定」からローカルプロキシのポートを確認できます。HTTPポートが10809、SOCKSポートが10808という構成はよく使われます。ただし、これは固定値ではありません。別のアプリケーションが同じポートを使用している場合や、過去に値を変更した場合は、画面に表示されている番号を優先してください。
HTTPとSOCKSのどちらを選ぶか
ターミナル用の設定では、まずHTTPプロキシを試すのが分かりやすい方法です。多くのHTTPS対応CLIツールは、HTTPS_PROXYにHTTPプロキシのURLを指定し、CONNECTメソッドで暗号化された接続を中継します。プロキシURLがHTTPであることと、最終的なAPI通信が暗号化されることは矛盾しません。ここで指定するHTTPは、ローカルのプロキシ入口の方式を表します。
SOCKS5を使う場合は、たとえばsocks5://127.0.0.1:10808を指定します。DNS解決もプロキシ側へ任せたい構成では、クライアントが対応していればsocks5h://127.0.0.1:10808を検討できます。ただし、すべてのCLIや内部ライブラリがSOCKS URLを同じように解釈するとは限りません。接続できない場合は、まずv2rayNのHTTPポートを使う構成へ戻し、問題の範囲を狭めてください。
HTTPS_PROXY=http://127.0.0.1:10809のように指定します。HTTPS APIへのCONNECT中継を使うため、CLIとの相性を確認しやすい方式です。
適合:初回設定、原因切り分け
socks5://127.0.0.1:10808を指定します。アプリケーションがSOCKSを正しくサポートしているかを確認する必要があります。
適合:既存のCLIがSOCKS対応済み
ブラウザーなどには反映されても、ターミナルのプロセスへ伝わるとは限りません。Claude Codeの検証には環境変数を明示する方が確実です。
適合:GUIアプリ中心の利用
WindowsとUnix系シェルへ環境変数を設定する
環境変数は、Claude Codeを実際に起動する同じターミナルで設定してください。PowerShellで設定しても、別に開いたコマンドプロンプトやIDE内蔵ターミナルへ自動的に反映されるとは限りません。特にVisual Studio Codeなどの統合ターミナルをすでに開いている場合は、設定変更後にターミナルをいったん閉じて、新しいセッションで確認するのが安全です。
v2rayNを接続
v2rayNで利用するノードを選択し、「システムプロキシ」を有効にします。続けて「設定」内のHTTPポートを確認し、ここでは例として
10809を使います。PowerShellを設定
$env:HTTP_PROXY="http://127.0.0.1:10809"と$env:HTTPS_PROXY="http://127.0.0.1:10809"を実行します。必要なら$env:NO_PROXY="127.0.0.1,localhost"も追加します。値を確認
echo $env:HTTPS_PROXYを実行し、ポート番号の誤りや余分な空白がないことを確認します。URLの末尾にパスを追加する必要は通常ありません。Claude Codeを起動
同じPowerShellウィンドウでClaude Codeを起動します。別ウィンドウで実行する場合は、そのセッションにも同じ環境変数を設定してください。
コマンドプロンプトを利用する場合は、次のように設定します。
set HTTP_PROXY=http://127.0.0.1:10809
set HTTPS_PROXY=http://127.0.0.1:10809
set NO_PROXY=127.0.0.1,localhostbashやzshなどのシェルでは、変数名を大文字で指定する構成が一般的です。小文字のhttp_proxyやhttps_proxyしか参照しないツールもあるため、挙動が不明な場合は大文字と小文字の両方を同じ値にして確認できます。ただし、シェルの設定ファイルへ恒久的に保存する前に、現在のセッションで動作を確かめてください。
export HTTP_PROXY="http://127.0.0.1:10809"
export HTTPS_PROXY="http://127.0.0.1:10809"
export NO_PROXY="127.0.0.1,localhost"Windows PowerShell
- HTTP
$env:HTTP_PROXY- HTTPS
$env:HTTPS_PROXY- 確認
echo $env:HTTPS_PROXY
設定したウィンドウからClaude Codeを起動します。
bash・zsh
- HTTP
export HTTP_PROXY- HTTPS
export HTTPS_PROXY- 確認
printenv HTTPS_PROXY
新しいシェルでは環境変数が引き継がれない場合があります。
Claude Codeの認証設定とプロキシ設定を混同しない
Claude Codeを利用するには、プロキシ経路とは別に、サービス側の認証情報や利用環境に応じたAPI設定が必要です。ANTHROPIC_API_KEYなどの認証用環境変数は、誰がAPIを利用できるかを決める情報です。一方、HTTPS_PROXYは、通信をどの経路で外部へ送るかを決めます。プロキシが正常でも認証情報が無効なら認証エラーになり、認証情報が正しくてもプロキシへ接続できなければタイムアウトになります。
APIキーをコマンド履歴へ直接書く方法は避けてください。共有端末、画面録画、シェル履歴、ログ収集機能に残る可能性があります。キーを設定する場合は、利用しているシェルの環境変数機能や、公式に案内されている認証フローを使い、不要になったセッションでは値を解除します。v2rayNのノード情報、UUID、APIキーを同じ設定ファイルへまとめて保管する必要もありません。
また、APIの接続先を変更するための環境変数と、単に通信を中継するプロキシ環境変数も区別してください。通常のネットワーク経路だけを変更したい場合は、まずHTTP_PROXYとHTTPS_PROXYを設定します。接続先URLや互換APIの設定を変更する変数は、利用するサービスや社内ゲートウェイの仕様が明確な場合だけ使用してください。目的が異なる変数を同時に追加すると、エラーの原因を特定しにくくなります。
設定後にポート、名前解決、API通信を確認する
環境変数を設定したら、いきなり大きなコードベースで作業を開始せず、短い確認から進めます。まずv2rayNのログでノードが接続状態になっていることを確認し、次にローカルポートが開いているかを調べます。WindowsではPowerShellのTest-NetConnection 127.0.0.1 -Port 10809を使えます。TcpTestSucceeded : Trueなら、そのポートへTCP接続できていますが、外部APIまで到達できることを保証する結果ではありません。
次に、設定したプロキシを経由してHTTPS接続が成立するかを確認します。利用するコマンドやURLは、環境のポリシーと対象サービスの公式案内に従ってください。接続テストでタイムアウトする場合は、v2rayNのノード、HTTPポート、ファイアウォール、シェルの環境変数を確認します。証明書検証エラーの場合は、システム時刻、TLSを途中で置き換えるソフトウェア、プロキシURLの書式を調べます。
| 症状 | 確認する場所 | 最初に行う対処 |
|---|---|---|
| 接続がタイムアウトする | v2rayNのノード状態、HTTPポート、HTTPS_PROXY | ブラウザーではなく、同じターミナルから環境変数の値とポートを確認する |
| プロキシ接続拒否 | 127.0.0.1のポート待受 | v2rayNを起動し、設定画面に表示された実際のポートへ修正する |
| 401・認証失敗 | 認証情報と利用権限 | プロキシではなくAPIキーやログイン状態の設定を確認する |
| 一部のローカル通信だけ失敗 | NO_PROXYと社内・LANアドレス | localhostや社内ドメインを必要に応じて除外する |
| 名前解決に失敗する | DNS方式、SOCKS対応、ネットワーク制限 | まずHTTPプロキシへ切り替え、同じ宛先で再テストする |
結論：GUIで成功してもCLIの成功とは限らない
ブラウザーが開けることはv2rayNのノードが使える証拠になりますが、Claude Codeが同じ経路を使っている証拠にはなりません。ターミナル内のHTTPS_PROXYと、実際に起動したプロセスのログを確認して初めて、CLI側の通信経路を判断できます。
開発作業で安定して使うための運用ポイント
日常的にClaude Codeを使う場合は、毎回手動で長いコマンドを入力するより、用途別の起動方法を用意すると入力ミスを減らせます。ただし、プロキシ設定をシェルの全環境へ恒久的に適用すると、プロキシを必要としない社内サーバー、ローカル開発環境、パッケージレジストリまで経由することがあります。まずは専用のターミナルセッションで試し、問題がなければ必要最小限の範囲だけへ適用してください。
NO_PROXYには、少なくとも127.0.0.1とlocalhostを入れておくと、ローカルAPI、開発用サーバー、コンテナ管理ツールとの接続を切り分けやすくなります。社内ネットワークのドメインやプライベートアドレスを除外するかどうかは、組織のネットワーク設計に合わせます。除外しすぎると必要な外部通信まで直接接続になり、逆に除外しなさすぎるとローカルサービスがプロキシへ送られて失敗することがあります。
ネットワークを切り替えた後に接続できなくなった場合は、最初にv2rayNの現在のノード状態とローカルポートを確認し、その後にターミナルを再起動します。Wi-Fiから別の回線へ移動しただけで、環境変数の値が変わるわけではありません。一方、v2rayNが終了した、ポート番号が変更された、ノードが再接続中である、といった状態なら、古いプロキシURLを保持したターミナルからは通信できません。
- v2rayNのノードを変更したら、まずブラウザーとターミナルを別々に確認する。
- HTTPポートとSOCKSポートを混同せず、指定したスキームと番号を一致させる。
- 認証エラーをプロキシ障害と決めつけず、APIキーやログイン状態を分けて確認する。
- 接続テストを何度も自動実行せず、ログと時刻を残して一つずつ変更する。
- 共有端末ではプロキシURL、認証情報、ノード情報を履歴や設定ファイルへ不用意に残さない。