上級設定 読了目安 16分

開発者向けClash設定術｜TUNでGit・npm・AI開発を安定化

GitHubへのpushやclone、npm・pipの依存関係取得、Docker Hubのイメージpull、CursorやGitHub Copilotの接続で困る開発者向けに、ClashのTUNモードを活用した実用設定を解説します。ターミナルとIDEの通信をまとめて安定させる方法、分岐ルール、よくある失敗例まで紹…

開発通信をプロキシへ通す仕組みを整理する

ブラウザでWebサイトを開けるのに、ターミナルの git clone、npm install、Dockerイメージの取得、AIコーディングツールのログインだけが失敗することがあります。これはClashのノードが必ずしも停止しているという意味ではありません。ブラウザはOSのシステムプロキシを読み取りますが、コマンドラインツールやIDE、Docker Engineは、それぞれ独自のプロキシ設定、環境変数、仮想ネットワークを使う場合があるためです。

Clashの通信経路は、大きく「システムプロキシ」「アプリ内プロキシ」「環境変数」「TUNモード」に分けて考えると整理しやすくなります。システムプロキシはHTTPリクエストやHTTPSのCONNECTに対応するアプリへ有効ですが、すべてのTCP・UDPパケットを強制的にClashへ送るものではありません。一方、TUNモードは仮想ネットワークインターフェースを作り、OSのルーティングを利用して、プロキシ設定を読み取らないアプリの通信もClashのルール処理へ渡します。

方法 主な対象 設定例 注意点
システムプロキシ Chrome、Edge、一般的なデスクトップアプリ 127.0.0.1:7890 アプリがOS設定を読み取る必要がある
環境変数 curl、Git、npm、一部のCLI HTTP_PROXY、HTTPS_PROXY シェルや起動済みプロセスごとに反映範囲が異なる
アプリ内プロキシ IDE、Docker、パッケージマネージャー 各アプリの設定画面や設定ファイル Clashとは別に設定が保存される
TUNモード プロキシ非対応アプリ、UDP、開発用仮想ネットワーク Clashの設定から有効化 管理者権限、DNS、VPNとの競合を確認する

TUNモードを安全に有効化する

TUNモードを有効にすると、Clashは仮想インターフェースを通じて端末の通信を受け取ります。ブラウザのようにプロキシ設定へ対応しているアプリだけでなく、GitのSSH接続、Docker関連の通信、IDEが内部で起動するランタイム、一部のAI開発ツールなども対象にしやすくなります。ただし、TUNは「すべての通信を自動的に海外ノードへ送る機能」ではありません。ルールモードなら、ドメインやIPに一致した通信がプロキシ、直通、拒否のいずれかへ振り分けられます。

Clash Nyanpasu、Clash Verge Rev、Mihomo系クライアントでは、通常「設定」または「Profiles」付近にTUNのスイッチがあります。メニュー名はクライアントやバージョンによって異なりますが、次の順番で確認すると安全です。

  1. 現在使用しているプロファイルをバックアップし、変更前のノード選択とモードを記録します。
  2. ほかのVPN、プロキシ強制ソフト、企業用セキュリティエージェントを一時的に停止します。
  3. Clashの設定でTUNモードを有効にし、必要であれば管理者権限またはシステム拡張の許可を与えます。
  4. DNSの仮想化を使う場合は、まず既定値で動作を確認し、問題が出たときだけDNS設定を個別に調整します。
  5. 最初は「ルール」モードで、ブラウザ、ターミナル、Gitの順番に通信を確認します。

Mihomoの設定ファイルを直接編集する場合、基本的な形は次のようになります。フィールド名や利用できる値はコアのバージョンとクライアントの実装によって異なるため、既存プロファイルの構造を壊さず、バックアップを取ってから変更してください。

mixed-port: 7890
mode: rule
allow-lan: false

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

dns:
  enable: true
  enhanced-mode: fake-ip

auto-routeは端末のルートをTUNへ向けるための設定です。auto-detect-interfaceは利用中の物理インターフェースを検出し、ルーティングのループを避ける目的で使われます。stack: mixedは環境によってTCP・UDPの互換性を取りやすい選択肢ですが、すべての端末で同じ結果になるとは限りません。TUNを有効にした後に通信が完全に止まった場合は、まずTUNを無効にしてコアとシステムプロキシを個別にテストし、DNS、ルート、VPN競合の順に戻って確認します。

Gitとターミナルの接続を安定させる

GitはリモートURLの方式によって必要な設定が変わります。HTTPS形式のリポジトリは、GitのHTTPプロキシ設定または環境変数を利用できます。SSH形式のリポジトリは通常のHTTPプロキシ設定ではなく、SSHの接続経路を別に設定する必要があります。TUNモードを使わずにSSHを通したい場合は、ローカルのSOCKS5入口を ProxyCommand 経由で利用する方法があります。

HTTPS形式のGitを確認する

まずClashのHTTP入口へ明示的に接続できるか、curlで確認します。

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

応答が返ったら、Gitのグローバル設定にプロキシを登録します。リポジトリごとに経路を変えたい場合は、グローバル設定ではなく対象リポジトリのディレクトリで実行してください。

git config --global http.proxy http://127.0.0.1:7890
git config --global https.proxy http://127.0.0.1:7890

git config --global --get http.proxy
git config --global --get https.proxy

HTTPSプロキシの設定は、GitがHTTPSリモートへ接続するときに使用されます。社内GitサーバーやLAN内のリポジトリまで外部ノードへ送る必要がない場合は、除外設定を検討します。

git config --global http.https://git.example.local.proxy ""
git config --global https.https://git.example.local.proxy ""

作業終了後に設定を解除したい場合は、次のコマンドを使います。環境変数だけを削除しても、Gitのグローバル設定が残っていれば通信は引き続きプロキシ経由になります。

git config --global --unset http.proxy
git config --global --unset https.proxy

SSH形式のGitを確認する

git@host:owner/repository.git のようなSSHリモートは、GitのHTTPプロキシ設定の対象ではありません。TUNモードでTCP通信を取り込むか、SSHクライアントにプロキシ経路を指定します。Mihomoの混合ポートをSOCKS5として使える環境なら、OpenSSHの設定例は次のようになります。

Host git.example.com
  HostName git.example.com
  User git
  ProxyCommand connect -S 127.0.0.1:7890 %h %p

ここで使う connect コマンドはOSに標準搭載されているとは限りません。別のプロキシ補助ツールを導入していない場合は、TUNモードを有効にしてSSHをそのままテストするほうが簡単です。SSHの接続確認には次を使います。

ssh -T [email protected]
GIT_SSH_COMMAND="ssh -v" git ls-remote [email protected]:owner/repository.git

ログに秘密鍵の認証エラーが出るならプロキシではなく鍵の問題です。接続先へ到達できない、TCP接続がタイムアウトする、またはTUNを有効にしたときだけ経路が変わる場合は、Clashの接続ログで対象ドメインと選択されたプロキシグループを確認します。

npmとパッケージ取得の経路を分ける

npm install が失敗する場合、npm本体のレジストリ設定、プロキシ設定、Node.jsプロセスが継承する環境変数、証明書検証のいずれかを確認します。まず現在の設定を表示してください。

npm config get registry
npm config get proxy
npm config get https-proxy
npm config list

公式レジストリへHTTPSプロキシを使う例は次のとおりです。

npm config set registry https://registry.npmjs.org/
npm config set proxy http://127.0.0.1:7890
npm config set https-proxy http://127.0.0.1:7890

プロキシを環境変数で設定する方法もあります。現在のシェルと、そこから起動したnpmにだけ適用したい場合はこちらが便利です。Windows PowerShellとmacOS・Linuxでは書式が異なります。

# Windows PowerShell
$env:HTTP_PROXY="http://127.0.0.1:7890"
$env:HTTPS_PROXY="http://127.0.0.1:7890"
npm install

# macOS / Linux
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
npm install

npmのプロキシ設定と環境変数を同時に設定すると、どちらが採用されているのか分かりにくくなります。動作確認が終わったら、不要な片方を削除して経路を1つに統一してください。また、社内レジストリやローカルのパッケージミラーは NO_PROXY に登録すると、外部ノードを経由せずに済みます。

# Windows PowerShell
$env:NO_PROXY="localhost,127.0.0.1,.example.local"

# macOS / Linux
export NO_PROXY=localhost,127.0.0.1,.example.local

証明書エラーが出ても、最初からTLS検証を無効にしてはいけません。UNABLE_TO_VERIFY_LEAF_SIGNATURE や社内CAに関するエラーは、企業プロキシやNode.jsのCA設定が原因かもしれません。strict-ssl=false は通信の安全性を下げるため、恒久的な解決策として使用せず、必要なCA証明書を正しく登録する方法を優先してください。

Docker、IDE、AIツールを切り分ける

Dockerでは、ホスト上のDocker CLIと、バックグラウンドで動作するDocker daemonが別プロセスである点に注意が必要です。ターミナルに HTTP_PROXY を設定しても、Docker daemonがその値を継承するとは限りません。イメージのpull、ビルド中のパッケージ取得、コンテナ内の通信は、それぞれ異なる設定が必要になることがあります。

Docker Desktopを使用している場合は、Docker Desktopの設定画面にあるResourcesまたはProxies付近の項目を確認し、ClashのHTTPポートを指定します。Docker EngineをLinuxのsystemdサービスとして動かしている場合は、daemon用の環境変数を設定してから再起動します。

[Service]
Environment="HTTP_PROXY=http://127.0.0.1:7890"
Environment="HTTPS_PROXY=http://127.0.0.1:7890"
Environment="NO_PROXY=localhost,127.0.0.1,.local"

# 設定後
sudo systemctl daemon-reload
sudo systemctl restart docker
docker info

Linuxホストの 127.0.0.1 はホスト自身を指します。DockerコンテナやVMの内部から見た 127.0.0.1 はホストではありません。そのため、コンテナからホスト上のClashへ接続する場合は、Docker Desktopのホスト名機能、ブリッジネットワークのゲートウェイ、または安全に設定したLANアドレスを使う必要があります。allow-lan を有効にする場合は、LAN全体へ無制限に公開せず、ファイアウォールで接続元を制限してください。

VS Code、JetBrains系IDE、各種AIコーディングツールは、UI本体、拡張機能、内蔵ターミナル、外部ランタイムで通信経路が分かれることがあります。IDEの設定にプロキシ項目がある場合は、まず「システムプロキシを使用」またはClashのHTTPプロキシを明示します。内蔵ターミナルで env、Get-ChildItem Env: などを実行し、古いポート番号が残っていないかも確認してください。

ルール、DNS、ログで開発環境を仕上げる

開発用の通信では、すべてを同じプロキシグループへ送るより、外部レジストリ、Gitホスティング、AI API、社内ドメイン、ローカルネットワークを分けるほうが安定します。たとえば、社内Gitやプライベートレジストリを外部プロキシへ送ると、アクセス制御や証明書検証に失敗することがあります。一方、外部のパッケージレジストリやAI APIは、現在のネットワークから直接到達できない場合があります。

rules:
  - DOMAIN-SUFFIX,git.example.local,DIRECT
  - DOMAIN-SUFFIX,registry.example.local,DIRECT
  - DOMAIN-SUFFIX,npmjs.org,開発用プロキシ
  - DOMAIN-SUFFIX,github.com,開発用プロキシ
  - DOMAIN-SUFFIX,githubusercontent.com,開発用プロキシ
  - MATCH,DIRECT

この例のドメインとグループ名は環境に合わせて変更してください。GitHubのWebページだけでなく、リリースファイル、サブモジュール、依存パッケージの取得先など、実際の通信先は複数のドメインに分かれることがあります。AIツールもログイン、API、更新確認、モデル一覧の取得で別ドメインを使う場合があるため、推測で大量のルールを追加せず、接続ログから必要な宛先を確認するのが確実です。

DNS設定も開発通信の安定性に影響します。ドメイン解決がローカルDNSで行われ、取得したIPが現在のネットワークから到達できない場合、Clashのノード自体が正常でも接続は失敗します。逆に、社内ドメインを外部DNSへ送ると、名前解決できない、または誤ったアドレスが返ることがあります。TUNのDNS機能とOSのDNS、ブラウザのセキュアDNSが同時に有効になると、想定した経路と実際の経路がずれるため、テスト時はどのDNSが応答しているかを確認してください。

最後に行う確認手順

  1. Clashの画面でコアが実行中であり、現在のプロファイル、モード、ノード、混合ポートが正しいことを確認します。
  2. curl -I -x http://127.0.0.1:7890 https://対象ドメイン でHTTPプロキシ入口を直接テストします。
  3. TUNを無効にした状態で、環境変数またはアプリ内プロキシを1つだけ設定してGitとnpmを確認します。
  4. TUNを有効にし、明示的なアプリ内プロキシを一時的に外して、同じコマンドを再実行します。
  5. Clashの接続ログで、対象ドメイン、ルール、プロキシグループ、最終ノード、エラー内容を記録します。
  6. 動作した構成を残し、不要な環境変数、古いポート、重複するプロキシ設定を削除します。

開発環境では、設定を増やすほど安定するとは限りません。システムプロキシ、TUN、Git設定、npm設定、Docker設定を一度に変更すると、どの層が通信を処理しているのか分からなくなります。まずローカルポートを直接テストし、次に1つのツール、最後にTUNとルールを追加する順番を守ると、原因を再現しやすくなります。Windows、macOS、Linux、Docker Desktopでは権限と仮想ネットワークの挙動が異なるため、同じ設定ファイルをそのまま共有するのではなく、OSごとの入口と例外ルールを確認してください。

Clashクライアントをダウンロード OSに合ったインストーラーを選択