開発者向けClash TUN設定｜Git・npm・Dockerの通信をターミナルで整える

ターミナル通信の仕組みを整理する

ブラウザーではサイトを開けるのに、Gitのcloneやnpmのパッケージ取得だけが失敗する場合、GUIクライアントのシステムプロキシ設定だけでは説明できないことがあります。コマンドラインツールは、OSのプロキシ設定を参照するもの、環境変数を読むもの、独自の設定を優先するものがあるためです。さらにDockerでは、ホスト上のDockerデーモンとコンテナ内のプロセスが別々に通信します。

TUNモードは仮想ネットワークインターフェースを使い、通常のアプリケーションが送るIP通信をmihomoへ取り込みます。そのため、プロキシ設定に対応していないプログラムも処理対象にできるのが利点です。ただし、TUNを有効にしただけで通信先がすべてプロキシ経由になるわけではありません。最終的な経路はmodeとrules、プロキシグループの選択、DNS設定に従います。

一方、Gitやnpmで明示的なプロキシを設定すると、アプリケーションがlocalhostの待ち受けポートへ接続します。この通信までTUNに取り込まれると、設定やルールによっては二重に処理されることがあります。最初は「TUNだけ」と「明示的プロキシだけ」を分けて試し、どちらで問題が解消するかを記録してください。

方式	主な対象	確認する点
システムプロキシ	OS設定を利用するブラウザーやアプリ	対象アプリがOSの設定を参照しているか
環境変数・アプリ設定	Git、npmなど設定に対応するツール	HTTPとHTTPSの指定、例外設定、認証情報
TUN	仮想インターフェースを通るIP通信	権限、ルート、DNS、ルールの判定
Docker	デーモン、ビルド、コンテナ内プロセス	どの実行環境が外部へ接続しているか

TUNを有効にし、まず通常の通信を確認する

初めて設定する場合は、GitやDockerの個別設定へ進む前に、TUNが正常に起動するかを確認します。クライアントで有効な設定とプロキシグループを選び、モードが意図した値になっていることを確かめてください。ルールモードならrulesの上から順に条件が評価され、最後の一致ルールがなければ想定外の経路になる場合があります。

クライアントの画面にTUNまたはサービスのスイッチがある場合は、必要な権限を許可してから有効化します。Windowsでは管理者権限やクライアントのサービスが必要になることがあり、macOSではネットワーク拡張の承認を求められる場合があります。Linuxではネットワークインターフェースやルートを設定する権限が必要です。組織管理端末では、管理者の許可なくセキュリティ制御を無効にしないでください。

mihomoの設定を直接管理する構成では、TUNの代表的な項目を次のように設定できます。これは既存の設定に統合するための例で、完全な設定ファイルではありません。既存のtun項目を置き換える場合は、同じキーを重複して記述しないでください。

tun:
  enable: true
  stack: mixed
  auto-route: true
  strict-route: true
  dns-hijack:
    - any:53

auto-routeは対応環境で経路を設定し、strict-routeはTUNの経路制御を厳格に扱うための項目です。stackの選択肢や挙動はコアとOSによって異なります。まずクライアントの推奨値を使い、起動ログにインターフェース作成やルート設定のエラーがないか確認しましょう。dns-hijackはDNS通信をmihomo側で処理するための設定であり、任意のHTTPS通信やブラウザー独自のDoHをポート53の問い合わせに変換するものではありません。

TUNを有効にした後、クライアントのログで初期化エラーがないことを確認します。
ブラウザーなど通常のアプリで、接続先と適用されたルール、出力先を接続パネルから確認します。
直接接続にしたいサイトと、プロキシを使いたいサイトをそれぞれ試します。両方が意図した経路になるまでは、ルールを追加変更しません。
動作しない場合は一度TUNをオフにし、システムプロキシだけで同じ接続を試して、問題がTUNの起動・ルート側か、ノード・ルール側かを分けます。

Gitとnpmを設定し、接続結果を切り分ける

GitやnpmはTUNだけで通信できる場合がありますが、環境変数やツール固有のプロキシ設定が残っていると、意図しない経路になることがあります。まずクライアントに表示されているHTTPプロキシのアドレスとポートを確認してください。以下では127.0.0.1:7890を例にしています。この値は共通の既定値ではないため、実際にmihomoが待ち受けているポートへ置き換えます。

明示的な接続テストには、次のようにcurlへプロキシを指定できます。URLは実際にアクセス可能なテスト先へ置き換えてください。エラーが出たら、DNS、認証、TLS、プロキシへの接続のどの段階で止まったかを記録します。

curl -I --proxy http://127.0.0.1:7890 https://example.com/

Gitでは環境変数を使う方法とGit自身に設定する方法があります。まず一時的なテストとして、シェルで環境変数を指定してから読み取り専用の接続を試します。

# macOS / Linux
export http_proxy=http://127.0.0.1:7890
export https_proxy=http://127.0.0.1:7890
git ls-remote https://example.com/organization/project.git

# Windows PowerShell
$env:http_proxy = "http://127.0.0.1:7890"
$env:https_proxy = "http://127.0.0.1:7890"
git ls-remote https://example.com/organization/project.git

上記URLは形式を示す例です。実際のリポジトリに置き換えてください。環境変数はHTTPプロキシを指定していますが、HTTPS接続も通常はHTTPのCONNECT方式でトンネル化できます。SOCKSを使う場合はクライアントの対応と指定形式を確認してください。Gitの設定を永続化する場合は、git config --global http.proxyで設定できます。共有端末で作業した後は、不要になった設定をgit config --global --unset http.proxyで削除します。

npmでは、現在の設定を確認してから必要な場合だけプロキシを設定します。

npm config get proxy
npm config get https-proxy
npm view <実際のパッケージ名> version

設定する場合は、npm config set proxy http://127.0.0.1:7890とnpm config set https-proxy http://127.0.0.1:7890を使えます。作業後に設定が不要なら、npm config delete proxyとnpm config delete https-proxyで消去してください。プロキシ認証が必要な場合、ユーザー名やパスワードをコマンド履歴、ログ、公開リポジトリに残さないようにします。

症状	確認する項目	次の操作
ブラウザーは動くがGitだけ失敗	Gitのプロキシ設定、環境変数、認証方式	`git config --show-origin --get http.proxy`で設定元を確認
npmの取得だけ失敗	npm設定、レジストリURL、TLSエラー	`npm config get registry`とプロキシ設定を確認
プロキシ指定時だけ失敗	ポート、待ち受けアドレス、プロキシ方式	クライアントのポートとHTTP/SOCKSの種類を照合
TUNをオンにすると失敗	OSのルート、DNS、localhostへの経路	明示的プロキシを一時解除してTUN単独で比較

Dockerではデーモンとコンテナを分けて確認する

Dockerの通信は、すべてホスト上のシェルと同じ環境変数を使うわけではありません。イメージの取得やビルド中の通信はDockerデーモンまたはビルド環境が担当し、コンテナで実行するアプリの通信はコンテナ内のプロセスが担当します。ホストでGitが成功しても、Dockerのpullやビルドが成功するとは限らないため、どの段階で失敗するかを分けて記録してください。

Dockerデーモンがホストのプロキシを使う必要がある場合は、Docker Desktopの設定またはLinux上のデーモン設定を確認します。Linuxではsystemdのサービス環境やDockerの設定方式が構成により異なります。変更後は設定を再読み込みし、デーモンを再起動しなければ反映されない場合があります。サービス管理方法を確認せず、設定ファイルを一律に作成しないでください。

ビルド時に外部からパッケージを取得する場合は、ビルド環境へ必要なプロキシ情報を渡す方法を確認します。コンテナ実行時にだけ必要な通信は、実行時の環境変数またはアプリ設定が対象です。Docker Desktopではホストのlocalhostとコンテナ内のlocalhostは同じ意味ではありません。コンテナ内で127.0.0.1:7890を指定すると、そのコンテナ自身を指し、ホスト上のmihomoには届かないことがあります。

# コンテナ内で環境変数を確認する例
docker run --rm alpine sh -c 'env | grep -i proxy'

# Dockerの基本情報を確認
docker info

環境変数にプロキシ認証情報を含めると、コンテナの設定や診断出力に残る可能性があります。実運用では組織の秘密情報管理方法に従い、不要な値をイメージへ書き込まないでください。Dockerのブリッジ通信をTUNで扱う方法はOS、Dockerのネットワーク方式、クライアントのルート設定で異なります。コンテナ通信が取り込まれていない場合、ホストのTUNスイッチだけで解決すると決めつけず、Dockerのネットワークとmihomoの接続ログを照合します。

OS別の確認とルールの調整

Windowsでは、TUN有効時に仮想アダプターとルートが作成されているか、クライアントのログと「ネットワーク接続」画面で確認します。複数のVPNや仮想ネットワークソフトが同時に動いていると、既定経路やDNSの選択が競合することがあります。PowerShellのGet-NetRouteやGet-DnsClientServerAddressで状態を記録し、設定変更後の差分を確認してください。

macOSでは、クライアントがTUN用のネットワーク拡張を開始できているか、OSの承認状態とクライアントログを確認します。システムプロキシがオンのままTUNも有効にすると、明示プロキシを使うアプリでは二重経路になることがあります。原因を調べる間は片方ずつ試し、ターミナルを再起動して環境変数が意図せず引き継がれていないかも確認します。

Linuxでは、仮想インターフェース、ルーティングテーブル、DNSサービスの状態を確認します。環境に応じてip route、ip addr、resolvectl statusを使えます。ディストリビューションによってはNetworkManagerやsystemd-resolvedが設定を管理するため、手動編集とサービス管理を混在させないでください。コンテナ環境や仮想マシン内では、ホストの権限やネットワーク名前空間が追加の制約になります。

ルールは通常、ドメインやIPなどの条件を基に通信を振り分けます。プロセス名によるルールはOSやコアの対応条件があるため、Gitやnpmという名前だけで全環境に適用できるとは限りません。開発ツールの通信先を調整するときは、まず接続パネルで実際のドメインと適用ルールを調べ、既存ルールの前後関係を確認します。たとえば特定ドメインだけ直接接続するなら、サンプルのドメインを実際の対象に置き換え、より広いルールより前に配置します。

rules:
  - DOMAIN-SUFFIX,example.com,DIRECT
  # 既存のルールをここに残す
  - MATCH,プロキシグループ名

上のexample.comは説明用の予約ドメインです。実際に使用するドメインへ置き換えてください。また、末尾のプロキシグループ名は設定内に存在する名前と一致させる必要があります。サブスクリプションが生成した設定を直接編集すると、更新で変更が失われることがあります。クライアントがローカルオーバーライドやマージに対応している場合は、その機能を使い、変更後に設定の構文検証と接続ログの両方を確認しましょう。

同じリポジトリやパッケージを使い、TUNオフ、TUNオンの順で結果を記録します。
接続パネルで対象ドメイン、ルール、選択された出力先を確認します。
必要ならGitまたはnpmの明示プロキシを一時設定し、TUN単独の結果と比較します。
設定を変えるたびに同じテストを再実行し、成功した条件を記録してから恒久設定にします。

よくある質問

ブラウザーは使えるのにGitだけ接続できないのはなぜですか？

Gitがシステムプロキシを参照していない、古いプロキシ設定や環境変数が残っている、認証方式が異なるなどの可能性があります。git config --show-origin --get http.proxyで設定元を調べ、次にTUN単独と明示プロキシ指定を別々に試します。

TUNを有効にすれば、Gitやnpmにプロキシを設定する必要はありませんか？

OSのルートを通ってmihomoへ到達し、ルールも正しく設定されていれば、アプリ側のプロキシ設定なしで通信できる場合があります。ただし、環境変数やツール固有設定が残っている場合や、通信がTUNの対象外になる構成では別途調整が必要です。実際の接続ログで確認してください。

Dockerコンテナからホストのlocalhostプロキシを使えますか？

コンテナ内の127.0.0.1は通常そのコンテナ自身を指すため、ホスト上のmihomoにそのまま接続できるとは限りません。Docker Desktopのホスト接続方法、Dockerネットワーク、クライアントの待ち受けアドレスを確認し、信頼できる範囲だけにプロキシを公開してください。

TUN有効化後にネットワークへ接続できなくなった場合は？

まずTUNをオフにして接続が戻るか確認します。戻る場合は、クライアントログ、仮想アダプター、ルート、DNS、ほかのVPNとの競合を順に調べてください。原因がわかる前にファイアウォールやOSの保護機能を無効にせず、必要なら変更前の設定へ戻します。