開発者向けClash TUN設定術｜Git・npmなどCLI通信をまとめてプロキシ

ブラウザは通るのに Git や npm が失敗する理由

ブラウザでは問題なくサイトを開けるのに、ターミナルから git clone や npm install を実行するとタイムアウトする。この差は、ブラウザと CLI が同じプロキシ設定を使うとは限らないことから生まれます。Clash のシステムプロキシ設定は、OS のプロキシ設定を参照するアプリには有効ですが、すべてのコマンドラインツールがその設定を自動で引き継ぐわけではありません。Git、Node.js、Docker、Python のツールは、それぞれ独自のプロキシ設定や環境変数を参照することがあります。

こうした環境で役立つのが TUN モードです。TUN は仮想ネットワークインターフェースを作り、OS のルーティングを通る通信を Clash に渡します。アプリごとにプロキシ対応状況が違っていても、対象の通信をネットワーク層で扱えるため、CLI や一部の開発ツールをまとめてプロキシ経由にしやすくなります。ただし、TUN をオンにすれば必ずすべての通信が捕捉されるわけではありません。権限、ルート設定、DNS、他の VPN との競合、コンテナや仮想マシンのネットワーク境界も影響します。

まずは「ブラウザが使えるか」ではなく、実際に失敗するターミナルで通信を再現し、Clash の接続一覧やログに宛先が現れるかを確認しましょう。ログに github.com や registry.npmjs.org が見えているなら、捕捉後のルールやプロキシグループが候補です。該当通信がまったく表示されないなら、TUN の起動状態、OS 側のルート、Docker や WSL のような別ネットワーク環境を先に調べるのが効率的です。

TUN を有効にする前に確認したいこと

TUN はネットワーク経路に関わる機能なので、最初に使っているクライアントとコアを確認します。Clash Verge、Clash Verge Rev、Mihomo Party などでは、画面の構成や項目名がバージョンによって異なります。設定に「TUN」「仮想インターフェース」「サービスモード」などの項目があるかを探し、現在のコアが TUN をサポートする Mihomo 系であることも確かめてください。古いクライアントやコアでは、説明と実際の操作が一致しないことがあります。

次に、OS の権限を確認します。Windows では仮想アダプターの作成やルート設定に管理者権限が必要になる場合があります。macOS ではネットワーク拡張や VPN 構成の追加について、システムの許可が求められることがあります。Linux では TUN デバイスへのアクセス権や、実行ユーザーに許されたネットワーク機能が関係します。画面上で TUN を有効にしたつもりでも、OS の確認ダイアログを閉じた、またはサービスが起動できていないために、実際には有効になっていない例があります。

企業や学校の端末では、管理ポリシーが仮想インターフェースや追加 VPN の利用を制限している場合があります。許可のない端末で設定を回避しようとせず、管理者に確認してください。また、別の VPN クライアント、エンドポイント保護ソフト、DNS フィルターが常駐していると、既定ルートや名前解決を取り合うことがあります。トラブル時は、組織のルールに反しない範囲で競合の有無を確認し、複数のトンネルを同時に動かした状態だけで原因を判断しないようにします。

初回は既存の設定をバックアップし、TUN 以外の項目を変更せずに試すのがおすすめです。DNS の拡張設定やプロセス単位のルーティングまで同時に触ると、失敗したときに原因が分からなくなります。変更前の状態と、TUN を有効にした後の状態を比較できるよう、クライアント名、コアのバージョン、OS、発生時刻を記録しておくと、ログの読み直しにも役立ちます。

Clash の TUN を段階的に有効化する

設定画面で TUN を有効にする前に、Clash が正常に起動し、プロファイルの読み込みエラーがないことを確認します。プロキシグループが選択でき、通常のブラウザ通信が期待どおり処理される状態を作ってください。そのうえで設定から TUN を有効化し、必要な OS の許可や管理者確認を完了してから、コアを再起動するか設定を反映します。メニュー名はクライアントにより違いますが、重要なのはトグルの表示だけでなく、接続状態やログで TUN インターフェースが実際に動作していることです。

設定ファイルを直接編集する場合は、利用中の Mihomo バージョンが対応するキーを公式ドキュメントで確認してください。たとえば、次のような構成が使われることがありますが、バージョンやクライアントの管理方法によって扱いが異なります。購読プロファイルを直接編集すると、更新時に変更が消えることもあるため、オーバーレイやクライアントが用意する追加設定の仕組みを優先してください。

Illustrative Mihomo TUN fragment — verify supported options for your core

tun:
  enable: true
  stack: mixed
  auto-route: true
  auto-detect-interface: true

dns:
  enable: true

コード断片の値をそのまま貼り付けることが目的ではありません。特に DNS の構成、スタック方式、ルート自動設定の挙動は環境に左右されます。すでに別の DNS サービスを使っている場合や、社内ネットワークで独自の名前解決が必要な場合は、既存の方針と衝突しないか確かめてから変更します。YAML のインデントミスや未対応のキーがあるとコアが設定を読み込めず、TUN が起動しない原因になります。編集後はクライアントの設定検証やログを確認し、起動エラーがないことを確かめましょう。

TUN を有効にしたら、まず短い通信テストを一つ実行し、その直後に Clash の接続一覧を開きます。宛先が表示され、意図したルールとプロキシグループが選ばれていることを確認してください。ここで予想外の DIRECT が選ばれる場合は、TUN の故障と決めつけず、ルールの順序や最終ルールを調べます。Clash のルールは上から順に評価され、先に一致したルールが採用されるため、広い条件が開発ツール向けのルールより上にあると、意図した出口へ届きません。

Git・npm・Docker の接続を個別に検証する

TUN が動いているかを調べるときは、Git、npm、Docker をまとめて一度に試すのではなく、ツールごとに確認します。各ツールは別のプロセスやネットワーク名前空間を使い、TUN の対象範囲も異なるためです。ターミナルで curl -I https://github.com のような短いリクエストを行い、Clash のログに接続が記録されるか見ます。応答の成否だけではなく、接続先、判定ルール、選択されたポリシーを合わせて確認してください。

Git の場合、HTTPS のリモートと SSH のリモートでは通信経路が異なります。https:// のリポジトリ取得は通常 HTTPS 通信として確認できますが、[email protected]:... のような SSH 接続は、HTTP プロキシ設定をそのまま使いません。HTTPS では成功するのに SSH だけ失敗するなら、まずリモート URL の形式と SSH クライアント側の経路を切り分けます。Git に独自のプロキシ設定が残っていないかも確認し、設定済みの値が TUN と異なる動作を生んでいないか調べましょう。

npm では、レジストリへの接続と、パッケージ本体を取得する tarball の接続が別のホストになることがあります。npm config get registry で利用中のレジストリを確認し、必要なら npm view などの軽い問い合わせで試験します。パッケージ一覧の取得は成功してインストールだけ止まるときは、Clash のログで追加の配信ホストがないかを確認してください。ミラーを使っている場合は、公式レジストリとミラーを無計画に混在させず、それぞれの接続先とルールを把握します。

Docker では、ホストのターミナルとコンテナ内の通信を別々に考える必要があります。Linux の Docker Engine は独立したネットワーク名前空間を使うため、ホストの TUN がコンテナの通信を常に同じ形で捕捉するとは限りません。Docker Desktop も仮想マシンを介するため、ホスト側で成功してもコンテナ内の docker pull が失敗することがあります。まずホストから同じレジストリへ接続し、次にコンテナ内から再試行して、どちらの段階でログが途切れるか比べてください。コンテナに環境変数を渡す方法を使う場合は、認証情報やプロキシ URL をイメージやログへ不用意に残さないよう注意が必要です。

TUN を使わず、ツール側で明示的にプロキシを設定する方法もあります。環境変数の HTTP_PROXY、HTTPS_PROXY、ALL_PROXY は便利ですが、すべてのアプリが同じ変数を尊重するわけではありません。Clash の mixed-port と SOCKS ポートを取り違えたり、HTTP プロキシ用の形式を SOCKS 接続先に指定したりすると、接続拒否やハンドシェイクエラーになります。利用するポートとプロトコルはクライアント設定で確認し、変数が子プロセスやコンテナにも渡っているかを検証してください。

通信が通らないときの切り分けと安全な運用

接続失敗の症状は、発生する段階ごとに分けると判断しやすくなります。Clash の接続一覧に該当通信が出ないなら、TUN が有効か、対象アプリが別ネットワーク内にいないか、OS のルートが期待どおりかを確認します。接続は見えるのにタイムアウトするなら、選択されたプロキシグループ、ノードの状態、ルールの一致先を調べます。名前解決だけ失敗する場合は DNS の設定やキャッシュ、TLS エラーの場合はシステム時刻、証明書検査、プロキシ経路の影響も候補になります。

すでに環境変数や Git、npm のプロキシ設定を使っている場合は、TUN と同時に有効にしたときだけ問題が出ないかも確認します。ツールの明示的なプロキシ設定が別のポートを指していると、TUN による経路と期待が食い違うことがあります。原因を特定するために設定を一つずつ比較し、必要のない古い値は記録したうえで整理してください。複数のプロキシ設定を無条件に重ねるのではなく、「TUN に任せる通信」と「ツールが直接プロキシを使う通信」を意図的に分けると、後から管理しやすくなります。

ルールは最初から開発サービスのすべてを広いドメイン指定で囲うのではなく、実際の失敗ログに現れたホストを起点に整えます。GitHub 本体とリリース配信、npm レジストリとパッケージ CDN は、接続先が分かれる場合があります。必要なルールを追加したら、ルールの位置が広範な GEOIP や MATCH より前にあるかを確認し、意図したポリシーへ到達しているかをログで再確認します。購読更新で設定が置き換わるクライアントでは、編集内容の保存場所も確認してください。

TUN は通信を扱う範囲が広いため、動作確認が終わった後もログや設定ファイルを安全に管理することが大切です。共有用のログを作る前に、購読 URL、アクセストークン、社内ホスト名、ユーザー名などを取り除きます。プロキシの認証情報をシェル履歴や Docker イメージに残さないことも重要です。また、利用が許可されているネットワークとサービスの範囲を守り、企業や学校の制限を回避する目的で設定を使わないでください。

よくある質問

システムプロキシをオンにしているのに Git が通らないのはなぜですか？

システムプロキシを参照しない Git の実行環境や、プロキシ設定が別に保存されている構成が考えられます。まず Git のリモートが HTTPS か SSH かを確認し、失敗した操作の間に Clash の接続ログへ宛先が表示されるか調べてください。ログに通信がなければ TUN やネットワーク境界を、通信があるならルールと選択された出口を確認します。

TUN と環境変数のプロキシ設定はどちらを使うべきですか？

対象アプリが環境変数に対応し、接続先を明示的に制御したい場合は、ツール側の設定が分かりやすいことがあります。複数の CLI がシステムプロキシを無視し、まとめて扱いたい場合は TUN が便利です。両方を使う場合は、プロキシの二重適用やポートの取り違えがないか、対象ごとに接続ログを確認してください。

ホストでは成功するのに Docker コンテナ内だけ失敗するのはなぜですか？

コンテナや Docker Desktop の仮想マシンは、ホストとは別のネットワーク経路を使うことがあります。ホストからの通信とコンテナ内の通信を別々に試し、Clash にどちらが記録されるかを比べましょう。コンテナにプロキシ環境変数を渡す場合は、イメージやログに認証情報が残らないように管理してください。

YAML を変更したら TUN が起動しなくなりました。何を確認しますか？

まずインデント、キーの綴り、利用中のコアが対応する設定かを確認し、クライアントの検証結果と起動ログを読みます。購読設定を直接編集している場合は、更新によって変更が戻っていないかも確認してください。原因が分からないときはバックアップへ戻し、一項目ずつ変更して再検証するのが安全です。

OS のシステムプロキシだけに頼る方法は手軽ですが、CLI ごとの対応差や Docker のネットワーク境界で設定が分散しやすく、手動の環境変数設定はポートやプロトコルの管理が増えます。Clash V.CORE なら、TUN と接続ログ、ルールの確認を一つの流れで進めやすく、Git・npm などの通信を段階的に検証できます。自分の OS と利用規約に合う方法を選び、開発用プロキシ環境を整えたい方はダウンロードから確認してください。