開発ツールの通信をTUNで扱う仕組み

ターミナルから実行するGitやnpmは、ブラウザーのようにOSのシステムプロキシ設定を必ず参照するわけではありません。そのため、ブラウザーでは接続できるのに、git fetchやnpm installだけがタイムアウトすることがあります。Gitの設定や環境変数にプロキシを個別指定すれば解決できますが、ツールやシェルごとに設定が増え、不要になった設定が残る原因にもなります。

Clash系クライアントでmihomoコアを使う場合、TUNモードは仮想ネットワークインターフェースを作り、アプリケーションのIP通信をコアへ渡します。Gitやnpmがプロキシ設定を参照しなくても、接続先のドメインやIPアドレスに応じてルールを適用できます。ただし、TUNを有効にすればどの通信も自動的にプロキシ経由になるわけではありません。ルールがDIRECTを選ぶ場合や、対象の通信がトンネルに入らない場合もあります。

  • システムプロキシ：対応アプリがOSのHTTPまたはSOCKSプロキシ設定を参照します。簡単ですが、ターミナルツールが設定を無視することがあります。
  • ツールごとのプロキシ：Gitの設定やnpmの設定、環境変数で接続先を指定します。動作範囲が明確な一方、複数の設定を整合させる必要があります。
  • TUN：ネットワーク層で通信を取り込みます。個別設定を減らせますが、クライアントの権限、経路設定、DNS、除外ルールの確認が必要です。

有効化の前に確認する設定と安全な手順

まず利用中のクライアント名とコアを確認します。TUNの設定項目はClash Verge、Clash Verge Rev、Clash for Windowsなどで異なり、同じ画面名や同じ機能があるとは限りません。また、TUN設定を解釈するのはクライアントではなく実際に動作しているコアです。mihomo向けの設定項目を旧Clashコアにそのまま追加すると、起動時にエラーになることがあります。

  1. 現在のプロファイルとローカルオーバーライドをバックアップします。サブスクリプションURL、ノードの認証情報、コントローラーのシークレットは公開リポジトリに保存しないでください。
  2. クライアントのバージョン情報やログで、利用中のコアがmihomoであることと、そのバージョンを確認します。バージョン番号やメニューの位置はクライアントごとに異なります。
  3. 他のVPN、仮想ネットワークツール、別のプロキシクライアントを一時停止します。複数のアプリが同じ経路やシステムプロキシを制御していると、接続経路の判断が難しくなります。
  4. クライアントのTUN設定を開き、有効化します。初回は管理者権限やOSのネットワーク拡張の許可を求められる場合があります。権限要求の内容を確認してから許可してください。
  5. クライアントを再起動し、ログでTUNインターフェースと経路の作成に成功したことを確認します。その後、通常の端末からGitやnpmの通信をテストします。

mihomoの設定ファイルを直接管理する場合、次は既存の設定に統合するための最小例です。トップレベルに同じ名前のtun:セクションがすでにある場合は、重複して追加せず既存の項目を確認してください。クライアントが設定を生成する方式では、画面のTUN設定が優先されることもあります。

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

auto-routeはルート設定を自動化し、strict-routeはTUN経由の経路をより厳密に扱います。ネットワーク構成やOSによって、必要な値や動作は異なります。リモート作業中にルートを誤ると、SSHや社内ネットワークへの接続を失う可能性があるため、変更前に復旧手段を確保し、項目を一つずつ試してください。

OS別の導入ポイントとGit・npmの確認

OS主な確認事項問題があるとき
WindowsクライアントのTUNまたはサービスモード、管理者権限、他のVPNアダプターとの競合クライアントのログ、ネットワークアダプター、Windowsファイアウォールの状態を確認する
macOSクライアントが要求するネットワーク拡張やVPN構成の許可、Apple SiliconとIntelに合ったアプリ「システム設定」のVPNやプライバシー関連の許可を確認し、クライアントを再起動する
Linuxディストリビューション、TUNデバイス、ネットワーク管理権限、既存のルーティング/dev/net/tunの有無、サービスログ、ルートとDNS設定を確認する

Windowsでは、TUNドライバーやサービスの導入に管理者権限が必要になる場合があります。クライアントの画面でTUNが有効に見えても、ログに「permission denied」「device unavailable」などが記録されていれば、通信を取り込めていない可能性があります。管理者として一度起動して確認し、不要な常時昇格を避けたい場合は、クライアントが案内するサービス方式を検討してください。

macOSでは、TUNを使うクライアントがOSのVPN構成やネットワーク拡張の許可を必要とすることがあります。許可の名称や場所はmacOSのバージョンとクライアントによって異なるため、OS設定でクライアント名やVPNを検索してください。許可後も動作しない場合は、クライアントの状態表示だけで判断せず、ログでインターフェースの作成と経路の適用を確認します。

Linuxでは、カーネルがTUNを利用できることに加え、起動ユーザーに必要な権限があるか確認します。コンテナ内でmihomoを動かす場合は、ホスト側のネットワーク名前空間やコンテナの権限も関係します。ネットワーク管理権限を安易に付与するのではなく、利用しているパッケージやサービスの手順に従い、必要最小限の権限で検証してください。

Gitとnpmを同じ条件でテストする

TUNのルールが機能しているか、接続先を確認できるリポジトリやパッケージを使ってテストします。まず一つの通信だけ実行し、クライアントの接続画面やログで対象ドメイン、適用ルール、選択されたプロキシグループを確認してください。例として、一般公開リポジトリの読み取り専用URLを使って次のように確認できます。

git ls-remote https://example.com/team/project.git
npm view example-package version

example.comとexample-packageは形式を示すための例です。実際のテストにはアクセス権があり、接続が許可されたリポジトリとパッケージを使ってください。GitがSSH形式のURLを使っている場合、HTTPSのテスト結果だけでSSH接続の経路も正常とは判断できません。SSHの接続先ポートや組織の認証方式を別途確認しましょう。

すでにGitやnpmへ個別プロキシを登録している場合は、TUNのテスト中にその設定が接続を上書きしていないか確認します。Gitではgit config --show-origin --get-regexp 'http\..*proxy|https\..*proxy'、npmではnpm config get proxyとnpm config get https-proxyを使って、設定値と設定元を確認できます。認証情報を含む値は画面共有やログへの貼り付けを避けてください。

ルール・DNS・Dockerの通信を整える

TUNに通信が入っても、最終ルートはルールで決まります。たとえばGitのホスト名が意図せずDIRECTに一致すれば、TUNを有効にしても直接接続になります。クライアントの接続履歴で対象のドメインとルール名を確認し、必要な宛先だけを適切なプロキシグループへ振り分けてください。広い範囲のIPアドレスを一律にプロキシへ送ると、社内Git、ローカル開発サーバー、クラウドの管理画面まで影響することがあります。

開発ツールでは名前解決も重要です。DNS問い合わせが失敗すると、プロキシ接続自体が確立する前にGitやnpmがエラーを返すことがあります。設定を変える前に、ログで名前解決の失敗か、接続タイムアウトかを区別してください。fake-ipを利用している場合でも、ローカルドメインや社内ネットワークで使う名前が適切に解決されるかを確認します。DNS設定の変更は、動作中の設定をバックアップしてから行いましょう。

Dockerの通信はホストのターミナルと同じ経路とは限りません。Docker Desktopでは、コンテナの通信が仮想化されたネットワークを経由し、ホストのTUNやルールとの関係がOSやDockerの構成によって変わります。Linuxではブリッジやネットワーク名前空間によって、コンテナからの通信がホストの通常プロセスと異なる経路を通る場合があります。ホストからのgit ls-remoteが成功しても、コンテナ内のgitやnpmが成功するとは限りません。

  • ホストの端末とコンテナ内で同じ宛先へ接続し、どちらだけが失敗するかを記録する。
  • コンテナのDNS設定、ネットワークモード、ビルド時と実行時のプロキシ設定を分けて確認する。
  • Dockerのビルド引数や環境変数に認証情報を含める場合、イメージの履歴やログに残らない方法を選ぶ。
  • コンテナからホストのプロキシポートへ接続する場合、127.0.0.1がコンテナ自身を指す点に注意し、環境に合った接続先を確認する。

接続できないときの切り分けとFAQ

エラー文だけで原因を断定せず、通信が止まる段階を確認します。たとえば、DNS解決エラーは名前解決やDNSルール、接続タイムアウトは経路やファイアウォール、認証エラーはGitやレジストリの認証情報を優先して調べます。テストごとに、時刻、実行コマンド、接続先、クライアントのルール表示、エラー全文を記録してください。サブスクリプションURL、アクセストークン、秘密鍵、認証情報は共有前に必ず伏せます。

  1. クライアントが起動し、mihomoコアが正常に動作していることを確認する。
  2. TUNの有効状態だけでなく、ログにインターフェースとルートの作成成功が記録されているか確認する。
  3. 接続画面でGitまたはnpmの接続先が表示され、想定したルールとプロキシグループが適用されているか確認する。
  4. 同じ接続先を別のノードで試す前に、個別プロキシ設定、DNS、ファイアウォール、ネットワーク切り替えの影響を一つずつ調べる。
  5. 変更した設定を戻して再テストし、症状が改善した項目だけを最終設定に残す。

よくある質問

TUNを有効にすればGitのプロキシ設定は削除できますか？

必ず削除できるとは限りません。まずTUNとルールでGitの通信が意図した経路を通ることを確認し、個別設定が不要な場合だけ整理します。設定を削除する前に、git config --show-originで保存元を確認し、組織指定のプロキシや認証設定を誤って消さないでください。

ブラウザーは動くのにnpmだけ失敗するのはなぜですか？

ブラウザーがシステムプロキシを使う一方、npmは独自設定や環境変数を参照している可能性があります。npm config get proxy、npm config get https-proxyで値を確認し、接続画面でレジストリのホスト名がどのルールに一致したかを調べてください。認証やレジストリのURLが正しいかも別途確認します。

TUNを有効にした後、社内サイトやSSHが使えなくなりました。

社内宛てのルートやDNS、SSHの宛先が、意図しないプロキシルールに一致している可能性があります。まずTUNを一時停止して通信が戻るか確認し、接続ログで適用されたルールを調べます。社内のプライベートIP範囲やドメインを設定に追加する場合は、組織のネットワーク要件に沿ってください。

Dockerコンテナだけ接続できない場合はどうすればよいですか？

ホストとコンテナのネットワーク経路、DNS、Dockerのプロキシ設定を分けて確認します。コンテナ内で同じ宛先をテストし、ホスト側の接続ログに通信が現れるか調べてください。Docker DesktopとLinuxではネットワーク構成が異なるため、ホストで成功した設定をコンテナにもそのまま適用できるとは限りません。

複数の開発ツールを個別に設定したくない場合、TUNはターミナル通信を一か所で扱う選択肢になります。一方で、TUNはシステムのルートやDNSにも関係するため、最初はGitなど一つの通信を対象にログを確認し、正常動作を確かめてからnpmやDockerへ広げるのが安全です。クライアントや対応OSを選ぶ場合は、ダウンロードページで現在の対応状況を確認してください。