Claude Codeを快適に使うClash Verge設定・ターミナル接続ガイド

Claude CodeとClash Vergeの役割を分けて理解する

Claude Codeをターミナルから利用するとき、ログイン画面が開かない、認証後に接続が切れる、パッケージの取得だけ失敗する、といった問題が起こることがあります。これらはClaude Code本体の障害とは限りません。ターミナルアプリ、OSのプロキシ設定、Clash Vergeのローカルポート、mihomoカーネルのルール、DNS解決という複数の層を順番に通過するため、どこで通信が止まったかを分けて確認する必要があります。

Clash Vergeは、サブスクリプションを読み込み、mihomoカーネルを起動し、ローカルのHTTPまたはSOCKSプロキシを提供するクライアントです。一方、Claude Codeはターミナル上で動く開発ツールであり、シェルの環境変数や認証情報を使って外部サービスへ接続します。Clash Vergeを起動しただけでは、すべてのターミナル通信が自動的にプロキシを通るとは限りません。

確認する層	主な役割	代表的な確認方法
Clash Verge	設定、サブスクリプション、システムプロキシ、TUNの管理	現在のプロファイルと接続ログを確認
mihomo	DNS、ルール照合、プロキシ接続、ローカルポートの待ち受け	カーネルログとポート状態を確認
ターミナル	Claude Codeやcurlなどのコマンドを実行	環境変数とコマンドの終了コードを確認
認証情報	ログインセッションやAPI関連の資格情報を保持	トークンを表示せず、認証状態だけを確認

Clash Vergeでサブスクリプションとモードを整える

Clash Vergeを初めて設定する場合は、サービス提供元のClashまたはmihomo向けサブスクリプションURLを用意します。Clash VergeのProfiles、または設定一覧にあるURL追加の入口から登録し、取得した設定を選択して有効化します。ブラウザーで開けるURLでも、返される内容がHTMLのログインページやJSONエラーなら、Clash設定として解析できません。更新に失敗する場合は、URLの有効期限、User-Agent制限、DNS、取得プロキシを順に確認します。

Claude Codeのような開発ツールを利用するときは、通常「Rule」モードから始めるのが扱いやすいでしょう。Ruleモードでは、ルールに一致したドメインだけをプロキシへ送れるため、国内サービスや社内ネットワークへの接続を必要以上に変更しません。Globalモードは切り分けには便利ですが、すべての通信が同じプロキシを通るため、社内Git、パッケージレジストリ、ローカル開発サーバーに影響することがあります。

モード	向いている場面	注意点
Rule	日常利用、開発作業、ドメインごとの分流	必要なドメインがルールから漏れることがある
Global	特定ドメインのルール漏れを調べる短時間のテスト	社内サービスやローカル接続もプロキシへ送る可能性がある
Direct	Clashを使わない状態との比較	外部サービスの接続確認には向かない場合がある

ルールモードで通信できない場合は、最初からすべてを手動で書き換えるのではなく、一時的にGlobalへ切り替えて比較します。Globalで成功し、Ruleで失敗するなら、プロファイル内のルールまたはルールプロバイダーが原因です。どちらでも失敗するなら、ノード、DNS、証明書、認証、またはサービス側の状態を確認します。

ターミナルにプロキシ環境変数を設定する

Clash Vergeのローカルポートは、設定画面のGeneral、Settings、またはカーネル設定に表示されます。環境によって異なりますが、よく使われる混合ポートは127.0.0.1:7890です。実際のポートが7897や別の番号になっていることもあるため、例をそのままコピーせず、Clash Vergeに表示される値を使ってください。9090などのExternal Controllerポートは管理API用であり、ターミナルのHTTPプロキシとして指定してはいけません。

macOSまたはLinuxのbash、zshでは、次のように環境変数を設定できます。ここでは混合ポートが7890である場合を示しています。

export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
export ALL_PROXY=socks5://127.0.0.1:7890

curl -I --connect-timeout 10 https://example.com

HTTP_PROXYとHTTPS_PROXYには、ClashのHTTPまたはmixedポートを指定します。SOCKS5を使う場合はALL_PROXYを設定します。ツールによって環境変数名の大文字・小文字の扱いが異なるため、必要に応じて小文字も設定してください。

export http_proxy="$HTTP_PROXY"
export https_proxy="$HTTPS_PROXY"
export all_proxy="$ALL_PROXY"

env | grep -i proxy

プロキシを外した状態に戻すには、シェルを閉じるか、次のコマンドを実行します。

unset HTTP_PROXY HTTPS_PROXY ALL_PROXY
unset http_proxy https_proxy all_proxy

実際に接続をテストしてClaude Codeを起動する

ここでは、Clash Vergeの起動状態、プロキシ、DNS、ターミナルの順番で確認します。一度に複数の設定を変えると、どの変更が有効だったか分からなくなるため、各手順の後に通信結果を記録してください。

Clash Vergeで対象のプロファイルを選択し、mihomoカーネルがRunningまたは稼働中になっていることを確認します。
Generalなどの画面で、mixed-portの番号とシステムプロキシの状態を確認します。
Ruleモードを選び、必要なら一時的にGlobalモードへ切り替えて比較します。
ターミナルに環境変数を設定し、curl -I https://example.comでHTTPレスポンスを確認します。
Clash Vergeの接続一覧またはログを開き、curlの通信が表示されることを確認します。
接続テストが成功してから、Claude Codeを起動してログインまたは認証操作を行います。

curlがConnection refusedを返す場合は、指定したポートでmihomoが待ち受けていないか、Clash Vergeが停止している可能性があります。Could not resolve hostなら、DNS解決またはシェルのネットワーク設定を確認します。HTTPステータスが返るのにClaude Codeだけが失敗する場合は、プロキシ経路ではなく認証状態、Node.jsの実行環境、サービス側のアクセス制限などを調べます。

Node.jsやパッケージマネージャーを使う作業では、シェルに設定したプロキシがすべてのツールへ同じように適用されるとは限りません。npm、Git、Python、Dockerなどは独自の設定ファイルや独自の環境変数を持つ場合があります。Claude Codeの起動だけ成功しても、拡張機能や依存パッケージの取得で失敗するなら、失敗したコマンドを単独で実行し、どのツールがどの設定を参照しているか確認してください。

接続ログを読むポイント

対象ドメインがログにない：ターミナルがプロキシ環境変数を参照していない、または別のネットワーク経路を使っています。
ドメインはあるがタイムアウトする：選択中のノード、ルール、DNS、上流ネットワークを確認します。
短時間で何度も切断される：ノードの品質、TLS処理、QUICやUDP経路、ローカルのスリープ復帰を確認します。
403や401が返る：通信経路ではなく、認証状態、アカウント、地域、User-Agentなどのサービス側条件を確認します。

TUNを使うべき場面と使わない場面

システムプロキシに対応したターミナルと開発ツールだけを利用するなら、まずHTTPまたはSOCKSの環境変数で十分なことがあります。TUNは仮想ネットワークインターフェースを作り、システムプロキシを参照しないアプリケーションの通信も取り込む仕組みです。DNSの処理や自動ルート設定を含むため、便利である一方、権限、VPN、他のセキュリティソフトとの競合が増えます。

Claude Codeがターミナルから通常のHTTPS接続を行うだけなら、TUNを最初から有効にする必要はありません。環境変数を参照しない補助プロセス、コンテナ、特定のランタイム、GUIアプリの通信まで同じルールで制御したい場合に、TUNを検討してください。TUNを有効にする前に、Clash Vergeのシステム権限、DNS hijack、自動ルート、Strict Routeの各項目を確認します。

ログインエラーと通信不安定さを切り分ける

ブラウザーで認証ページを開く方式では、ブラウザー側のログインセッションとターミナル側のClaude Codeの認証状態が別になることがあります。ブラウザーでログイン済みだからといって、ターミナルが自動的に認証済みになるとは限りません。認証画面が表示されないときは、Clash Vergeの接続ログに認証関連のドメインが出ているか、ターミナルに表示されたURLが途中で切れていないか、既定ブラウザーが正しく起動しているかを確認します。

ログイン後に「接続が閉じられた」「応答を待機中のままになる」といった状態が続く場合は、まずGlobalモードで短時間だけ比較します。Globalで改善するならRuleモードのルール漏れが疑われます。Globalでも改善しないなら、別のノード、別のネットワーク、DNS設定、時刻設定、セキュリティソフトのHTTPS検査を順に確認してください。PCの日時が大きくずれていると、TLS証明書や認証セッションの検証に失敗することがあります。

複数のターミナルを開いている場合、古いターミナルには変更前の環境変数が残っています。設定を変更した後は新しいターミナルを開くか、unsetしてから再設定してください。また、シェルの起動ファイルにプロキシを常時記述すると、Clash Vergeを終了した後も存在しない127.0.0.1ポートへ接続し続けることがあります。常用設定にする前に、一時的なシェルセッションで動作を確認するのがおすすめです。

ポートエラー：Clash Vergeの実際のmixed-portと環境変数の番号が一致しているか確認します。
ルールエラー：Globalで成功するかを試し、対象ドメインとルールプロバイダーを調べます。
DNSエラー：mihomoのDNSログ、OSのDNS設定、TUNのDNS hijackを個別に確認します。
認証エラー：通信経路が正常でも、アカウントや認証セッションの問題は残ります。
頻繁な切断：ノードの遅延だけでなく、パケットロス、アイドル切断、Wi-Fiの省電力も確認します。