開発者向けClash設定：TUNモードで端末開発環境を安定化

開発環境でTUNモードを使う理由

ブラウザだけを使う場合は、システムプロキシを有効にするだけで十分なことがあります。しかし、開発作業では通信経路がアプリごとに異なります。ターミナルのcurl、Git、npmやpnpm、Pythonのpip、Docker、VS Codeの拡張機能、AIコーディングツールなどは、OSのHTTPプロキシ設定を自動的に読み取らない場合があります。その結果、ブラウザではリポジトリやドキュメントを開けるのに、git cloneだけがタイムアウトする、パッケージの取得だけが失敗する、といった状態が起こります。

TUNモードは、アプリケーションが明示的なHTTPまたはSOCKSプロキシ設定を持っていなくても、仮想ネットワークインターフェースを通じて通信をClashまたはmihomoコアへ渡す方式です。アプリごとにプロキシ設定を追加する必要が減るため、開発端末全体の通信経路をそろえやすくなります。ただし、TUNは「すべての通信が必ず成功する機能」ではありません。DNS、ルーティング、権限、仮想インターフェース、ルール設定が正しく連携して初めて安定して動作します。

有効化前に確認する項目

使用中のGUIクライアントがClash Verge、Clash Verge Rev、Mihomo Party、Clash for Androidなどのどれであっても、まず実際に動作しているコアを確認してください。メニューの「設定」→「コア」「サービス」「カーネル情報」などで、mihomoのバージョンと実行状態を確認します。TUNのスイッチが表示されても、コアが起動していなければ通信は処理されません。

• 現在の設定ファイルが有効で、少なくとも1つのプロキシグループが存在している。
• プロキシグループ内に利用可能なノードがあり、テストURLへの接続がタイムアウトしていない。
• HTTPまたはmixed-portが、たとえば127.0.0.1:7890で待ち受けている。
• VPN、別のTUNアプリ、Dockerのネットワーク拡張、企業用セキュリティソフトが同じ経路を奪っていない。
• Windowsでは必要なドライバーや管理者権限、LinuxではTUNデバイスとルーティング権限が利用できる。

mihomoのTUN設定を安全に組み立てる

設定項目の名前や対応状況はコアの種類とバージョンによって異なります。以下はmihomo系の一般的な構成例です。設定ファイルへ追加する前に、クライアントが生成した現在の設定をバックアップし、YAMLのインデントを崩さないようにしてください。特にdns、tun、proxiesの階層を誤ると、設定全体を読み込めなくなります。

mixed-port: 7890
mode: rule
log-level: info

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

dns:
  enable: true
  enhanced-mode: fake-ip
  nameserver:
    - 223.5.5.5
    - 1.1.1.1

mixed-portはHTTPとSOCKS5の両方を受け付けるローカルポートです。TUNで処理される通信に必須とは限りませんが、curlやGitを手動で検証するときに便利です。auto-routeは端末のルートをTUNへ向け、auto-detect-interfaceは現在の物理ネットワークインターフェースを検出します。strict-routeはルート漏れを抑える方向に働きますが、社内ネットワークや仮想マシンとの通信まで遮断する場合があるため、問題が出たときはログとルーティングを確認します。

stack: mixedは環境によってTCPやUDPの処理互換性を確保しやすい設定です。パフォーマンスだけを理由に設定を変更せず、まずデフォルト値で開発ツールが動くか確認してください。TUNのスタック方式を変更した後は、TUNの再起動だけでなく、必要に応じてClashコアと対象アプリを再起動します。

DNSとルーティングを先に安定させる

開発ツールの失敗は、プロキシノードそのものではなくDNSで起きていることがあります。ドメイン名がローカルDNSで解決できない、国内向けDNSが海外サービスの名前を誤ったアドレスへ返す、あるいはFake-IPのアドレスをアプリが正しく扱えない、といった問題です。ログにno such host、DNS timeout、dial udpなどが出ている場合、ノードを切り替える前にDNS経路を確認します。

社内Git、ローカル開発サーバー、Dockerの名前解決は、外部サービスと同じ扱いにしない方が安全です。たとえばgit.internal.exampleやlocalhost、127.0.0.1、プライベートアドレス帯は、ルールとfake-ip-filterの設計を確認します。開発環境で使うドメインを無条件にプロキシへ送ると、社内ネットワークへ到達できなくなったり、認証情報が意図しない経路へ送られたりする可能性があります。

dns:
  enable: true
  enhanced-mode: fake-ip
  fake-ip-filter:
    - '*.lan'
    - '*.local'
    - 'localhost'
    - 'git.internal.example'

上のドメインは例です。実際の社内ドメインに置き換え、外部のDNSサービスへ問い合わせてもよいかを組織のポリシーで確認してください。ルールの末尾には通常、到達できなかった通信を処理するFINALまたはMATCH相当のルールがあります。意図せずすべてをDIRECTにする構成や、反対にすべてを同じプロキシグループへ送る構成は、開発用途では検証しにくいため避けましょう。

ターミナル、Git、パッケージマネージャーを検証する

TUNを有効にした後は、いきなり大きな依存関係をインストールせず、通信量の少ないコマンドから確認します。Clashのログ画面を開き、同じ時刻に接続画面で宛先、適用ルール、使用されたプロキシグループを確認してください。ログがまったく増えない場合は、TUNが無効、ルートが作成されていない、または対象アプリが別のネットワーク名前空間で動作している可能性があります。

curl -I https://registry.npmjs.org/
curl -I https://pypi.org/
git ls-remote https://github.com/example/example.git
npm config get proxy
npm config get https-proxy

最後の2つのnpm configは、npmに古いプロキシ設定が残っていないかを見るためのものです。TUNへ統一する場合、以前設定したhttp://127.0.0.1:7890や停止したポートを削除し、TUN経由と明示プロキシ経由が二重になるのを防ぎます。なお、実際のリポジトリURLは使用中のプロジェクトに置き換えてください。

環境変数を使う場合の最小構成

TUNを使えない環境や、一時的な比較テストでは、環境変数が役立ちます。HTTPプロキシとHTTPSプロキシの値にhttp://を指定するか、SOCKSをサポートするツールではsocks5://を指定します。多くのCLIツールは大文字と小文字の両方を参照しますが、シェルやツールによる差を減らすため、両方を設定する方法があります。

export http_proxy=http://127.0.0.1:7890
export https_proxy=http://127.0.0.1:7890
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
export no_proxy=localhost,127.0.0.1,::1,.local
export NO_PROXY=localhost,127.0.0.1,::1,.local

Windows PowerShellでは次のように設定できます。

$env:HTTP_PROXY="http://127.0.0.1:7890"
$env:HTTPS_PROXY="http://127.0.0.1:7890"
$env:NO_PROXY="localhost,127.0.0.1,::1,.local"

環境変数は現在のシェルや、そのシェルから起動したプロセスだけに影響します。VS Codeをデスクトップアイコンから起動した場合、ターミナルで設定した環境変数が拡張機能に引き継がれないことがあります。また、NO_PROXYへ広すぎるドメインを指定すると、外部サービスまで直接接続されます。社内ドメインやローカルアドレスだけを明示し、認証情報を含むプロキシURLをシェル履歴へ残さないよう注意してください。

Gitとパッケージ取得の実務的な確認

• Gitが失敗する場合は、git config --global --get http.proxyとgit config --global --get https.proxyで古い設定を確認します。
• npm、pnpm、Yarn、pipはそれぞれ独自の設定ファイルや環境変数を持つため、Clashのログとツール側の設定を分けて調べます。
• レジストリへ接続できても、ダウンロードURLが別ドメインの場合があります。最初のメタデータ取得だけで判断せず、実際のインストール完了まで確認します。
• GitのSSH接続は通常HTTPSプロキシと別経路です。git@形式の接続が失敗する場合は、SSHのProxyCommandやTUNのTCP処理を個別に確認します。
• 社内レジストリはDIRECT、外部レジストリはプロキシというように、ドメイン単位で目的を明確にします。

AIツール、VS Code、Dockerを安定させる

AIコーディングツールやエディター拡張機能は、ブラウザとは別のプロセスとして動作します。VS Code本体のプロキシ設定、拡張機能の設定、統合ターミナルの環境変数が一致しないこともあります。TUNを使う場合でも、拡張機能が独自のプロキシを固定していれば、TUNへ到達する前に接続が失敗します。設定を変更した後は、ウィンドウの再読み込みだけでなく、VS Codeを完全終了して起動し直してください。

AIサービスを利用するツールでは、APIのホスト、認証サービス、モデル一覧、ファイルアップロード先が別ドメインに分かれていることがあります。1つのURLへcurl -Iを実行できただけでは不十分です。Clashの接続画面で、ツールを起動してから発生した複数の接続を確認し、必要なドメインがすべて同じルール意図で処理されているか確認します。APIキーやアクセストークンをログ、画面共有、シェル履歴へ残さないことも重要です。

DockerはホストOSと異なるネットワーク名前空間を使います。ホストでTUNが正常でも、コンテナ内のnpm installやaptが同じ経路を使うとは限りません。コンテナへプロキシ環境変数を渡す場合は、ホストから到達可能なアドレスを指定します。コンテナ内の127.0.0.1は通常コンテナ自身を指し、ホストのClashを指さないため注意してください。

docker run --rm \
  -e HTTP_PROXY=http://host.docker.internal:7890 \
  -e HTTPS_PROXY=http://host.docker.internal:7890 \
  -e NO_PROXY=localhost,127.0.0.1 \
  node:22-alpine \
  npm view npm version

上のhost.docker.internalはDocker Desktopで利用される代表的なホスト名です。Linuxの環境やrootless構成では同じ名前が使えないことがあるため、Dockerのネットワーク方式に合わせてホストゲートウェイを確認してください。さらに、Clash側でallow-lan: trueを有効にする場合は、待受アドレスとファイアウォールを見直します。LAN公開は必要な場合だけ行い、認証なしのプロキシを公共ネットワークへ公開しないでください。

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

開発環境では、ノードを何度も切り替えるより、通信の層を固定して調べる方が早く解決できます。まずClashのコアが起動していること、次にTUNインターフェースが有効であること、最後にアプリの接続がログへ現れることを順番に確認します。ログに宛先が現れた後でタイムアウトするなら、ルール、DNS、ノード、TLSの問題を調べます。宛先が現れないなら、アプリの経路、権限、仮想ネットワークを調べます。

設定を戻すときの順序

1. 対象アプリと開発サーバーを停止し、古い接続が残らない状態にします。
2. ClashのTUNを無効にし、システムプロキシを一度オフにします。
3. 変更前に保存した設定へ戻し、コアを完全に再起動します。
4. システムプロキシだけでブラウザとcurlをテストします。
5. 次にTUNだけを有効にし、Git、パッケージマネージャー、Dockerを1つずつ確認します。
6. 問題が再現した時点のログ、対象ドメイン、ルール名、使用ノード、OSを記録します。

設定を戻しても通信が回復しない場合は、OSに残ったプロキシ設定、環境変数、Gitやnpmの永続設定、VPNのルートを確認します。Windowsでは管理者権限で追加された仮想アダプター、macOSでは他のVPNプロファイル、Linuxではip routeとNetworkManagerの設定が影響することがあります。開発環境の認証情報を削除する前に、どの設定を変更したかを記録しておくと復旧しやすくなります。

よくある質問