Claude Code をターミナルから使うとき、ブラウザでは問題なく通信できるのに、インストール、ログイン、モデル呼び出しの段階でタイムアウトや接続拒否が発生することがあります。主な原因は、ターミナルのプロセスが OS のシステムプロキシを自動的に参照するとは限らないこと、Clash Verge の待受ポートと環境変数の指定が一致していないこと、そして TUN モードと手動プロキシ設定を重ねていることです。
この記事では、Clash Verge と mihomo を使って Claude Code の通信経路を確認し、Windows・macOS・Linux のターミナルから安定して接続するための設定を整理します。Claude Code 本体の認証方式や利用可能なサービスは時期やアカウントによって変わるため、ここでは特定のサービス仕様を固定せず、HTTPS 通信を Clash に正しく渡すための共通設定を中心に説明します。
Claude Code の通信で最初に確認すること
Claude Code はターミナル上で動作する CLI ツールです。ブラウザのように Windows や macOS のプロキシ画面を必ず読み取るとは限らず、Node.js、curl、npm、Git などが参照する環境変数を使って通信する場合があります。そのため、Clash Verge で「システムプロキシ」をオンにしただけでは、すべての Claude Code 通信がプロキシ経由になるとは限りません。
まず Clash Verge の「設定」から混在ポートを確認します。バージョンや設定ファイルによって異なりますが、Clash Verge では 127.0.0.1:7897 が混在ポートとして使われる構成があります。実際の値は必ずアプリ画面、または現在読み込んでいる設定ファイルで確認してください。混在ポートは HTTP プロキシと SOCKS5 接続の両方を受け付けますが、環境変数ではプロトコルの書き方を分ける必要があります。
| 確認項目 | 見る場所 | 確認内容 |
|---|---|---|
| Clash の起動状態 | Clash Verge のホーム画面 | mihomo コアが実行中か |
| 混在ポート | 設定またはポート表示 | 例:127.0.0.1:7897 |
| プロキシグループ | 「プロキシ」ページ | 実際に利用するノードまたは自動選択グループ |
| 接続モード | ホーム画面または設定 | Rule、Global、Direct のどれか |
| ターミナル側の設定 | 環境変数 | HTTP_PROXY と HTTPS_PROXY の値 |
Rule モードを使用する場合は、Claude Code が接続するホスト名に対して意図したポリシーが適用されることも確認します。接続先をすべてプロキシへ送る必要がある環境では一時的に Global モードで検証し、接続できた後に Rule モードへ戻して対象ドメインのルールを調整すると、原因を切り分けやすくなります。
システムプロキシとターミナル環境変数の違い
システムプロキシは、OS のネットワーク設定を参照するアプリに対して有効です。一方、ターミナルで起動したコマンドは、プロセス自身がシステムプロキシを読むとは限りません。curl、wget、npm、Python、Go などは、実装やバージョンによって HTTP_PROXY、HTTPS_PROXY、ALL_PROXY などを優先します。
Claude Code の導入前に、まずターミナルで Clash のプロキシを明示してください。HTTPS の URL に接続するときも、一般的な HTTP CONNECT プロキシを指定する構成では HTTPS_PROXY の値を http:// から始めます。これは「HTTPS を HTTP で送る」という意味ではなく、ローカルの HTTP プロキシへ CONNECT 要求を出すという意味です。
一時的に環境変数を設定する
macOS と Linux の zsh、bash では次のように設定できます。ポート番号は自分の Clash Verge の表示値に置き換えてください。
export HTTP_PROXY=http://127.0.0.1:7897
export HTTPS_PROXY=http://127.0.0.1:7897
export ALL_PROXY=socks5://127.0.0.1:7897
export NO_PROXY=localhost,127.0.0.1,::1大文字の変数に加えて、小文字の変数しか見ないツールにも対応したい場合は、次のように同じ値を設定します。
export http_proxy="$HTTP_PROXY"
export https_proxy="$HTTPS_PROXY"
export all_proxy="$ALL_PROXY"
export no_proxy="$NO_PROXY"Windows PowerShell では、現在開いているセッションだけに適用するために次を実行します。
$env:HTTP_PROXY="http://127.0.0.1:7897"
$env:HTTPS_PROXY="http://127.0.0.1:7897"
$env:ALL_PROXY="socks5://127.0.0.1:7897"
$env:NO_PROXY="localhost,127.0.0.1,::1"この方法の利点は、設定の影響範囲が現在のターミナルだけに限定されることです。動作確認が終わる前にシェルの起動ファイルへ書き込むと、Git、npm、社内サイトなど別の通信までプロキシへ送られる可能性があります。まず一時設定で確認し、安定してから永続化してください。
実際に接続をテストする手順
設定を変更した後は、いきなり Claude Code の認証を繰り返すのではなく、下位層から順番にテストします。これにより、Clash の問題、DNS の問題、環境変数の問題、サービス側の認証問題を分けて判断できます。
- Clash Verge を起動し、mihomo コアが停止していないことを確認する。
- 「プロキシ」ページで利用するノードまたはポリシーグループを選択する。
- 混在ポートの番号を確認し、ターミナルの環境変数へ同じ番号を設定する。
- Clash Verge のログ画面を開いたまま、ターミナルから接続テストを実行する。
- 接続が確認できたら、Claude Code のインストールまたはログインを再試行する。
HTTPS の疎通だけを確認する場合は、次のコマンドを使います。接続先は利用中のサービスが案内する公式ホストへ置き換えてください。
curl -v --proxy http://127.0.0.1:7897 https://example.com/レスポンスが返り、Clash Verge のログに接続先のドメインと選択したポリシーが表示されれば、少なくともターミナルからローカルプロキシまでは到達しています。Connection refused なら待受ポートが違うか mihomo が停止しています。Could not resolve host なら DNS 解決を確認します。TLS handshake の途中で止まる場合は、ノードの経路、システム時刻、セキュリティソフトの HTTPS 検査を確認してください。
次に、Claude Code を起動する同じターミナルで環境変数が見えているか確認します。
echo $HTTPS_PROXY
env | grep -i proxyPowerShell では次を使います。
$env:HTTPS_PROXY
Get-ChildItem Env: | Where-Object { $_.Name -match "PROXY" }Claude Code のエラーが認証失敗や権限不足である場合、プロキシ設定だけでは解決しません。まず HTTP ステータス、レスポンス内容、Clash の接続ログを確認し、通信が成功した後にアカウントや API キーの問題を調べてください。
TUN モードを使う場合の設定と注意点
環境変数を設定しても一部の CLI がプロキシを参照しない場合や、複数の開発ツールをまとめてプロキシ経由にしたい場合は、Clash Verge の TUN モードが候補になります。TUN は仮想ネットワークインターフェースを作成し、アプリケーションがプロキシを意識しているかどうかに関係なく、IP パケットを mihomo へ渡します。
Clash Verge で TUN を有効にする前に、サービスモードや管理者権限が必要か確認してください。Windows では仮想ネットワークドライバーとルーティング変更のため、サービスモードのインストールが必要になる構成があります。macOS や Linux でも権限確認が求められる場合があります。TUN をオンにしても、プロキシグループが Direct のままなら通信は直結するため、モードとルールの両方を確認することが重要です。
tun:
enable: true
stack: mixed
auto-route: true
auto-detect-interface: true
dns-hijack:
- any:53上記は mihomo 系設定でよく使われる項目の例です。実際の設定画面では、GUI のスイッチが同等の値を生成することがあります。手動で YAML を編集する場合は、現在の mihomo が対応しているフィールドかどうかを確認してください。古い Clash 系コア向けの設定をそのまま貼り付けると、起動エラーやフィールド非互換になることがあります。
TUN と環境変数を同時に使うこと自体が常に誤りというわけではありませんが、二重経路になりやすいため、切り分け時はどちらか一方に限定するのが安全です。TUN の動作確認を行うときは、いったん HTTP_PROXY と HTTPS_PROXY を解除して、TUN だけで接続できるか試します。
unset HTTP_PROXY HTTPS_PROXY ALL_PROXY
unset http_proxy https_proxy all_proxyPowerShell では次のように解除できます。
Remove-Item Env:HTTP_PROXY,Env:HTTPS_PROXY,Env:ALL_PROXY -ErrorAction SilentlyContinue
Remove-Item Env:http_proxy,Env:https_proxy,Env:all_proxy -ErrorAction SilentlyContinueサービス別の分岐と失敗時の確認方法
Claude Code が利用する接続先は、ログイン方式、契約プラン、環境変数、利用する API 互換サービスによって変わります。したがって、特定のドメインだけを固定して許可するのではなく、まず Clash のログに実際の接続先を表示させ、そのドメインがどのルールへ一致したかを確認してください。ルールが意図せず DIRECT に一致しているなら、必要なドメインに対するルールをプロバイダー設定の適切な位置へ追加します。
| 症状 | 確認する場所 | 対処の方向 |
|---|---|---|
| インストール時だけ失敗する | npm の設定、HTTPS_PROXY、レジストリ URL | npm が別のプロキシやレジストリを使っていないか確認 |
| ログイン画面が開かない | ブラウザとターミナルの経路 | システムプロキシと CLI の環境変数を分けて検証 |
| モデル要求がタイムアウトする | Clash の接続ログ、ノードの遅延 | Rule を確認し、別ノードまたは Global で比較 |
| 証明書エラーが出る | OS 時刻、Node.js、セキュリティソフト | 時刻を同期し、HTTPS インターセプトを確認 |
| TUN で社内サイトが開かない | DNS と LAN 除外ルール | 社内ドメイン、プライベート IP、ローカル DNS を適切に除外 |
環境変数でプロキシを指定する場合、認証情報を URL に直接書き込まないでください。プロキシのユーザー名やパスワードがシェル履歴、プロセス一覧、CI ログに残る可能性があります。また、Claude Code の API キーやアクセストークンも公開リポジトリへ保存せず、必要に応じて OS の資格情報管理機能や安全な環境変数管理を利用してください。
最終的な構成は、軽い検証ならターミナルの HTTP_PROXY と HTTPS_PROXY、複数アプリをまとめて捕捉するなら TUN、という使い分けが分かりやすいでしょう。どちらを選ぶ場合も、Clash の待受ポート、プロキシグループ、DNS、そして実際のログを順番に確認すれば、Claude Code の接続エラーを感覚だけで追いかけずに切り分けられます。