Claude Codeをv2rayNで使う方法｜国内向け端末プロキシ設定

Claude Codeをターミナルから利用するとき、ブラウザーだけがプロキシを通っていても、開発ツールの通信まで同じ経路になるとは限りません。Claude Codeはターミナル上でAPIへ接続するため、v2rayNのノードを選択しただけでは十分ではなく、ローカルプロキシの待受ポートとシェルの環境変数を正しく指定する必要があります。設定が不足すると、ログイン画面が開かない、認証後に接続が切れる、パッケージのインストールだけ失敗する、という症状が起きます。

この記事では、Windowsのv2rayNを中心に、Claude Codeを国内環境から試す際の一般的な端末プロキシ設定を説明します。特定のノードや契約サービスを推奨するものではありません。利用するサービスの規約、認証方式、組織のネットワークポリシーを確認したうえで、正規のアカウントと許可された接続経路を使用してください。v2rayNでは、まず通常のWebアクセスが安定していることを確認し、その後にClaude Code専用の環境変数を設定すると、原因を切り分けやすくなります。

Claude Codeとv2rayNの通信経路を理解する

v2rayNは、選択したVMessやVLESSなどのノードをXrayまたは対応するコアへ渡し、端末上にローカルのHTTPプロキシやSOCKSプロキシを開きます。Claude Codeは通常、ターミナルから起動されたプロセスとして動作するため、ブラウザーのプロキシ設定やWindowsのシステムプロキシを自動的に引き継ぐとは限りません。Claude Codeを起動するプロセスが参照する環境変数に、v2rayNのローカルアドレスを指定することが重要です。

よく使われる初期値は、HTTPプロキシが127.0.0.1:10809、SOCKSプロキシが127.0.0.1:10808です。ただし、この番号は固定ではありません。v2rayNの「設定」→「パラメータ設定」→「コア設定」または「ポート設定」に表示される実際の値を確認してください。別のアプリが同じポートを使用している場合、v2rayNは起動に失敗するか、設定画面に表示されたポートで待ち受けられないことがあります。

Claude Codeの通信で最初に試す環境変数はHTTPS_PROXYです。HTTPSでAPIへ接続するプログラムがHTTPプロキシへ接続する構成は一般的で、URLは通常http://127.0.0.1:10809のように書きます。SOCKSを使う場合は、アプリケーション側がSOCKS URLを解釈できるかを確認し、ALL_PROXY=socks5://127.0.0.1:10808を試します。HTTP用ポートにsocks5://を指定する、またはSOCKS用ポートにhttp://を指定する、といった形式の混同は接続失敗の原因です。

v2rayNとClaude Codeの事前確認

設定を始める前に、v2rayN単体の接続状態を確認します。メイン画面で有効なサブスクリプショングループを選び、ノードを「アクティブサーバーに設定」します。続いて「システムプロキシを有効化」を使う場合は、ブラウザーで通常のHTTPSサイトを開き、システムプロキシが機能しているか確認します。システムプロキシを使わない場合でも、Claude Code用のローカルポートが開いているかを確認できれば問題ありません。

サブスクリプションの更新に失敗したまま、古いノードを使い続けないでください。v2rayNの「購読グループ」から対象を更新し、更新日時、ノード数、選択中のノード名を確認します。VLESSとVMessは別のプロトコルであり、アドレスやポートだけを手動で変更しても接続できるとは限りません。TLS、SNI、Realityの公開鍵、短いID、flow、WebSocketパスなどは、配布された設定と一致している必要があります。

Claude Code側では、利用するアカウントの認証方式を先に整理します。ブラウザー認証を使う構成では、ログイン後に表示されるコードやリダイレクト処理がターミナルへ戻る必要があります。環境変数でAPIキーや認証トークンを渡す構成では、キーをコマンド履歴、画面共有、公開ログへ残さないようにします。認証情報が無効な場合と、プロキシへ到達できない場合では対処が異なるため、エラー全文を保存し、キーそのものは記録しないでください。

• v2rayNでアクティブなノードが設定されている。
• ローカルHTTPまたはSOCKSポートの番号が確認できる。
• ブラウザーまたは別のHTTPクライアントで基本通信を確認している。
• Claude Codeの認証方式と必要なアカウント権限を把握している。
• ターミナルで使うシェルがPowerShell、コマンドプロンプト、bashのどれか分かっている。

ターミナルへプロキシを設定する手順

ここではWindowsのPowerShellで、現在開いているターミナルだけにプロキシを設定します。この方法なら、設定を解除するまでの範囲が明確で、ほかのアプリへ意図せず影響を与えにくくなります。まずv2rayNを起動してノードを有効にし、設定画面でHTTP待受ポートを確認してください。以下の10809は例です。

1. ノードを有効化

   v2rayNのメイン画面で利用するノードを選択し、「アクティブサーバーに設定」を実行します。必要に応じて「システムプロキシを有効化」も確認します。

2. ポートを確認

   「設定」→「パラメータ設定」→「ポート設定」を開き、HTTPポートとSOCKSポートが実際に待ち受けている番号を記録します。

3. 環境変数を設定

   PowerShellで$env:HTTPS_PROXY="http://127.0.0.1:10809"を実行し、Claude Codeを同じウィンドウから起動します。

4. 認証を実行

   Claude Codeのログインまたは認証コマンドを実行し、ブラウザー認証が必要な場合は同じ端末の案内に従います。

5. 通信を確認

   簡単な質問を送信し、v2rayNのログに新しい接続が表示されるか、応答が最後まで返るかを確認します。

PowerShellの環境変数は、そのウィンドウから起動した子プロセスに引き継がれます。別のPowerShellを開いた場合は設定が消えるため、Claude Codeを起動する前に再実行してください。設定を解除するにはRemove-Item Env:HTTPS_PROXYを実行します。SOCKSを試す場合は、対応状況を確認したうえで$env:ALL_PROXY="socks5://127.0.0.1:10808"を設定し、HTTP用とSOCKS用の変数を混在させないようにします。

コマンドプロンプトでは書式が異なります。現在のウィンドウだけに設定する場合は、次のように実行します。

set HTTPS_PROXY=http://127.0.0.1:10809
claude

macOSやLinuxのbash、zshでは、起動前に次の形式を使います。端末のシェル設定ファイルへ恒久的に追加する場合は、共有端末や業務端末で認証情報とプロキシの利用範囲を確認してください。

export HTTPS_PROXY="http://127.0.0.1:10809"
export HTTP_PROXY="http://127.0.0.1:10809"
claude

URLにユーザー名やパスワードを含める形式は、シェル履歴やプロセス情報へ認証情報が残る可能性があるため、ローカルプロキシでは通常必要ありません。プロキシ認証を有効にしている場合は、v2rayN側の待受設定と利用するクライアントの対応仕様を確認し、キーやパスワードをそのまま記事、スクリーンショット、サポートログへ貼り付けないでください。

開発作業に合わせたルーティングと確認方法

Claude Code本体のAPI通信だけでなく、実行する開発ツールが別の接続を行うことがあります。たとえば依存パッケージの取得、ドキュメントの参照、認証ページの表示、外部APIの呼び出しは、それぞれ異なるプロセスやライブラリを使う可能性があります。そのため、Claude Codeの応答が返ることは、すべての開発通信が同じプロキシを通っている証明にはなりません。

ルーティングは、開発作業の種類に応じて分けます。プロキシ対象のAPIや認証関連ドメインは、選択したプロキシアウトバウンドへ送ります。一方、社内サーバー、localhost、LAN上のGitサービス、データベース、開発用コンテナのアドレスは、通常は直通にします。すべての通信を一律にプロキシへ送ると、社内アドレスへ到達できなくなったり、ローカル開発サービスの名前解決が壊れたりすることがあります。

DNSの扱いにも注意が必要です。ドメイン名をv2rayN側で判定したい場合、XrayコアのDNS設定、ルーティングのdomainStrategy、TUNを使用するかどうかが互いに影響します。Claude CodeのためだけにFakeDNSやTUNを有効化する必要はありません。まずはHTTPプロキシを環境変数で指定する構成から始め、DNS漏れや社内サービスへの影響を確認したうえで、必要な場合だけTUNや詳細な分流を検討してください。

ログインエラーと通信切れを切り分ける

ログイン画面が開かない場合は、認証情報を再発行する前に、Claude Codeを起動したターミナルがプロキシ環境変数を継承しているか確認します。PowerShellではWrite-Output $env:HTTPS_PROXY、bashではprintf '%s\n' "$HTTPS_PROXY"を実行します。値が空なら、別のターミナルから起動した、環境変数の名前を誤記した、引用符の書式が不正だった、という可能性があります。

ログイン後にすぐ切断される場合は、ノードの瞬間的な接続ではなく、長時間のHTTPS通信、接続再利用、ストリーミング応答が安定しているかを確認します。v2rayNのログに再接続が連続している場合は、ノードの切り替え、コアのエラー、回線のパケット損失を確認します。v2rayN側に接続記録がない場合は、Claude Codeが別の環境変数を参照している、またはその変数をサポートしない通信ライブラリを使っている可能性があります。

proxy connection refused
connect ECONNREFUSED 127.0.0.1:10809
socket hang up
request timed out
401 Unauthorized
403 Forbidden

ECONNREFUSEDは指定したローカルポートで待受がない、v2rayNが終了している、ポート番号が違う、といった状態を示します。socket hang upやrequest timed outは、リモートノード、トランスポート、回線品質、長時間接続のいずれも候補になります。401や403は認証または権限の問題であることが多く、プロキシが正常に動作していても発生します。エラーの種類を混同せず、v2rayNのログとClaude Codeの出力を同じ時刻で照合してください。

認証情報と設定を安全に維持する

環境変数は便利ですが、端末上のすべてのプロセスから見えるとは限らないため、共有端末では特に注意が必要です。認証トークンをシェル設定ファイルへ平文で保存する場合は、ファイルのアクセス権、バックアップ、画面共有、ログ収集の範囲を確認します。使用後は一時的な環境変数を解除し、不要になったキーはサービス側で失効させてください。

v2rayNの設定を更新する際は、ノードのプロトコルを自己判断で変更しないことも重要です。VLESSのReality設定をVMessとして入力する、TLSを無効にして試す、サーバー名を空欄にする、といった変更は、通信を安定させるどころか接続を壊したり、意図しない経路を作ったりします。サブスクリプション由来の設定は、まず配布元の内容をそのまま使い、必要な例外だけをルーティング側で管理します。

毎回の起動で手動設定するのが面倒な場合でも、最初からシステム全体へ恒久設定する必要はありません。Claude Code専用の起動スクリプトやプロジェクトごとの開発手順に限定し、会社のネットワーク、ローカルAPI、パッケージレジストリなどが影響を受けないか確認してください。設定を変更した日時、使用したローカルポート、ノードの識別名、発生したエラーだけを記録すると、次回の更新後も再現性を保ちやすくなります。