仕組み解説 読了目安:12分

開発者向けClash設定術：Git・npm・AI開発環境を快適にする方法

クライアントのパネルで点滅する遅延数値を、多くの人が「この回線が使えるかどうか」の唯一の判断材料にしてしまいます。しかし80msと「快適に使える」との間には、テスト対象・パケットロス率・帯域幅の限界・回線混雑という4つの壁があります。本記事では遅延数値の測定方式を分解し、それが実際に何を反映していて何を見落としているかを説明した上で、実体感に近い自己診断方法をいくつか紹介します。

Clash開発者設定 ターミナルプロキシ TUNモード 読了時間目安:12分

開発者向けClash設定術:Git・npm・AI開発環境を快適にする方法

ブラウザは使えるのに、ターミナルのGitやnpm、Docker、AIコーディング支援だけが失敗する問題は珍しくありません。開発者の作業手順に合わせてClashのTUNモードを導入し、リポジトリ取得から依存関係の導入、IDEのログインまでを安定させる方法をまとめます。

ブラウザだけ使える理由:システムプロキシとアプリ別設定の違い

開発環境でよくある症状は、ブラウザでは対象サイトを開けるのに、ターミナルで git clone、npm install、docker pull を実行すると接続エラーになることです。これはClashのノードが必ずしも不安定だからではなく、アプリケーションごとにプロキシ設定の参照方法が異なるために起きます。

Clashの「システムプロキシ」を有効にすると、OSのHTTP/HTTPSプロキシ設定が書き換えられます。一般的なブラウザはこの設定を自動的に読み取るため、ブラウザの通信はClashへ送られます。一方、ターミナルのプログラムはOS設定を自動参照するとは限りません。Gitは独自の http.proxy 設定、npmは proxy と https-proxy、Dockerはデーモンまたはクライアント側の設定を使う場合があります。

さらに、アプリがHTTPSプロキシを理解していても、独自の名前解決処理、証明書検証、バックグラウンドサービス、子プロセスを使っていれば、ブラウザと同じ経路にはなりません。IDEの拡張機能やAIコーディング支援も、IDE本体とは別のランタイムやログインサービスを利用することがあります。そのため、まず「ブラウザが動く」ことと「すべての開発ツールが動く」ことを分けて考える必要があります。

注意:プロキシポートはクライアントによって異なります。HTTPポート、混合ポート、SOCKSポートを画面で確認してから設定してください。よくある 7890 や 7891 を推測して固定すると、ポート変更後にすべてのツールが失敗します。

TUNモードの役割:環境変数に依存せず通信を引き受ける

TUNモードは、Clashのコアが仮想ネットワークインターフェースを作成し、OSから出ていくIP通信を仮想インターフェースへ取り込む方式です。システムプロキシに対応していないCLI、独自のソケット処理を行うアプリ、プロキシ環境変数を子プロセスへ渡さないツールでも、IP通信としてClashに到達すればルールによる振り分け対象にできます。

これは「すべての通信を必ずプロキシにする」機能ではありません。Clashのルールが DIRECT を選べば直接接続になり、指定したプロキシグループを選べばそのノードへ送られます。開発用サービスだけをプロキシへ送り、社内Git、LAN上のレジストリ、ローカルホストは直接接続するという構成も可能です。

  1. Clash Verge Rev、Clash Nyanpasu、FlClashなど、mihomoコアとTUNに対応するクライアントを用意します。
  2. 設定画面でTUNを有効にし、Windowsでは管理者権限、macOSではネットワーク拡張機能の許可を完了します。
  3. DNS設定とルールモードを確認します。ドメインルールを正しく使うには、TUNだけでなくDNSの経路も確認する必要があります。
  4. まずブラウザと curl で動作を確認し、その後にGit、npm、Dockerの順で個別に試します。

TUNを有効にしても接続できない場合は、いきなり設定を増やさず、Clashのログで対象ドメイン、使用ルール、選択された策略グループを確認します。TUNの仮想インターフェースが起動していないのか、DNSが失敗しているのか、ルールが DIRECT を選んでいるのかを分けることが重要です。

Gitとnpmを安定させる:環境変数と専用設定の使い分け

開発マシンでは、TUNを有効にしたうえで、プロキシを明示的に指定する方法も役立ちます。明示設定は原因を追いやすく、TUNを一時的に無効にしても同じ経路を再現できます。ただし、TUNとアプリ別プロキシを無計画に重ねると、通信が二重にプロキシへ入り、接続ループやTLSエラーを起こす場合があります。

# macOS / Linux の例
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
export ALL_PROXY=socks5://127.0.0.1:7891
export NO_PROXY=localhost,127.0.0.1,::1,.local

# GitだけにHTTPプロキシを設定
git config --global http.proxy http://127.0.0.1:7890
git config --global https.proxy http://127.0.0.1:7890

# npmの設定
npm config set proxy http://127.0.0.1:7890
npm config set https-proxy http://127.0.0.1:7890

上の値は例です。Clashの実際のポートに合わせて置き換えてください。SOCKSポートを使う場合、アプリが socks5 と socks5h のどちらを理解するかも確認します。後者は名前解決をプロキシ側へ渡す意味を持つため、DNS経路を分離したい場面で有用ですが、すべてのツールが対応しているわけではありません。

Gitでは、リポジトリのURL形式も確認します。HTTPSのリポジトリはHTTPプロキシ設定の影響を受けますが、SSH形式の git@... は通常のHTTPプロキシ設定では動きません。SSHを使う場合は、TUNでTCP通信を引き受けるか、SSH自体のプロキシ設定を別途用意する必要があります。認証情報をURLへ直接書き込む方法は、シェル履歴や設定ファイルに残るため避けてください。

npmでは、レジストリの指定が意図したものかを確認します。社内レジストリやプライベートパッケージを利用している場合、すべてを外部プロキシへ送ると認証失敗や名前解決エラーになることがあります。Clashのルールで社内ドメインを DIRECT にし、外部レジストリだけをプロキシグループへ送る構成が扱いやすい方法です。

Dockerとコンテナの注意点:ホスト側とデーモン側を分けて考える

Dockerは、Gitやnpmよりも切り分けが難しい代表例です。ホスト上で実行する docker CLIと、イメージを取得するDockerデーモンは別プロセスであり、CLIのシェルに HTTP_PROXY を設定しただけでは、デーモンの通信に反映されないことがあります。特にDocker Desktopでは、仮想化された内部環境がイメージレジストリへアクセスします。

まずホストからレジストリの名前解決とHTTPS接続を確認し、次にDocker DesktopまたはDocker Engine側のプロキシ設定を確認します。設定変更後はデーモンの再起動が必要になる場合があります。TUNでホストの通信が取り込まれていても、仮想マシンや独立したネットワーク名前空間の通信が同じ経路になるとは限りません。

  • イメージ取得だけ失敗する: Dockerデーモンのプロキシ設定、レジストリの認証、企業ネットワークの証明書を確認します。
  • ビルド中の依存関係取得だけ失敗する: Dockerfile内のnpm、pip、aptなどがコンテナ内部で実行されるため、ホストの環境変数は自動では引き継がれません。
  • コンテナからホストサービスへ接続できない: localhost はコンテナ自身を指します。Clashのホストポートへ接続する場合は、Dockerのネットワーク構成とホスト名を確認します。
  • 社内レジストリだけ失敗する: プライベートCA、DNS、NO_PROXY、Clashのルールが一致しているかを確認します。

ビルド時にプロキシを渡す必要がある場合は、シークレットや認証情報をイメージレイヤーへ書き込まない設計にしてください。単純にプロキシURLをDockerfileへ固定すると、履歴や共有イメージから漏れる可能性があります。

IDEとAIコーディング支援の接続を確認する手順

IDEのログインやAIコーディング支援が失敗する場合、ブラウザログインが成功したことだけでは判断できません。IDE本体、拡張機能、認証用の外部ブラウザ、バックグラウンドの言語サーバーが別々の通信方式を使うことがあるためです。最初にIDEのネットワークログ、拡張機能の出力、OSのシステムプロキシ状態、Clashの接続ログを同じ時刻で照合します。

  1. Clashのログを開き、ログイン画面で使われる認証ドメインとAPIドメインが表示されるか確認します。
  2. 表示されたドメインが、意図したプロキシグループへ振り分けられているか確認します。CDN、認証、APIが別ドメインの場合もあります。
  3. ターミナルから curl -I などで対象のHTTPS応答を確認します。ブラウザだけでなく、同じOSユーザーのCLIから再現することが重要です。
  4. TUNを有効にした状態と、IDEへHTTPプロキシを明示した状態を一度に混ぜず、どちらの経路で成功するかを比較します。

証明書エラーが出る場合、ClashのHTTPS通信が常に復号されているとは限りません。多くの場合、クライアントはTLSをそのまま中継しますが、企業ネットワークの検査装置、カスタムCA、IDE独自の証明書ストアが影響することがあります。証明書検証を無効化して解決しようとするのは安全ではありません。まずシステム時刻、OSのCAストア、IDEの証明書設定、会社のネットワークポリシーを確認してください。

避ける設定:strict-ssl=false、証明書検証の無効化、認証トークンを含むプロキシURLの共有は、短期的に接続できても別のリスクを作ります。接続できない理由をログで特定し、必要なCAや正しいプロキシ経路を設定してください。

開発用ルールの組み立てと最終チェック

開発環境では、サービスごとにルールを分けるとトラブルの再現性が高まります。外部コードホスティング、パッケージレジストリ、コンテナレジストリ、AIサービスをまとめてプロキシへ送る方法もありますが、社内ドメインやローカル開発サービスまで巻き込まないようにします。ルールは上から評価されるため、例外を一般ルールより前に置くことが基本です。

rules:
  - DOMAIN-SUFFIX,corp.example,DIRECT
  - DOMAIN-SUFFIX,localhost,DIRECT
  - DOMAIN-SUFFIX,registry.example,Proxy
  - DOMAIN-SUFFIX,npmjs.org,Proxy
  - DOMAIN-SUFFIX,pypi.org,Proxy
  - DOMAIN-SUFFIX,github.com,Proxy
  - MATCH,DIRECT

実際の設定では利用しているドメインとプロキシグループ名に置き換えます。localhost は通常ドメインルールだけでなく、アプリケーション側の接続先設定や NO_PROXY も関係します。Fake-IPを使う場合、LAN内のホスト名、プリンター、NAS、社内DNSで解決するドメインは fake-ip-filter へ追加する必要がある場合があります。

  • Clashのログ:対象ドメイン、规则匹配、使用したグループ、接続失敗の理由を確認します。
  • OSのルート:TUNインターフェースが起動し、管理者権限やネットワーク拡張機能が許可されているか確認します。
  • DNS:ドメインが解決できるか、社内DNSと外部DNSのどちらを使うべきか確認します。
  • アプリ設定:Git、npm、Docker、IDEに古いプロキシや無効なポートが残っていないか確認します。
  • 例外経路:NO_PROXY、社内レジストリ、LANアドレス、ローカル開発ポートを確認します。

設定を変更した後は、クライアント、ターミナル、Dockerデーモン、IDEを必要に応じて再起動します。環境変数は既に起動しているプロセスへ自動反映されず、IDEの拡張機能も起動時に設定を読み込むことがあるためです。最終的には、リポジトリの取得、依存関係の導入、コンテナイメージの取得、IDEのログインという実際の作業順に確認するのが最も確実です。TUNを万能スイッチとして扱うのではなく、Clashのルール、DNS、アプリ固有のプロキシ設定を役割ごとに整理すれば、開発ツールだけが失敗する問題を段階的に切り分けられます。

Clashクライアントをダウンロード
クライアントをダウンロード