ClashでGitHub・npmを安定接続する高度なルール設定とYAML管理

開発ツールを安定させる振り分けの考え方

GitHub の clone、npm install、Docker イメージの取得が途中で止まる場合、ノードの速度だけが原因とは限りません。GitHub はリポジトリ本体、API、Release、Git の SSH 接続で異なるホスト名を使います。npm もパッケージ情報を取得するレジストリ、認証、tarball の配布元が分かれることがあります。Docker ではレジストリ、認証サービス、イメージのレイヤー配信サーバーが別ドメインになるため、1つのサービス名だけをルールに追加しても通信全体をカバーできません。

Clash のルールは上から順番に評価され、最初に一致したルールで処理を終了します。そのため「GitHub はプロキシ」という大まかな設定を作るだけではなく、ローカルネットワークと開発ツールの例外を先に整理し、対象サービスを専用のプロキシグループへ送り、最後に一般通信のフォールバックを置く必要があります。特に TUN モードでは、ブラウザだけでなく Git、Node.js、Docker Desktop、IDE のバックグラウンド通信も Clash に取り込まれるため、ルールの不足が目立ちやすくなります。

GitHubは HTTPS の clone、SSH の 22 番ポート、API、Release のダウンロードを分けて確認する。
npmはレジストリ本体だけでなく、設定された registry と tarball の実配布先を確認する。
Dockerはレジストリ、認証エンドポイント、レイヤー配信先を個別に扱う。
ルールプロバイダーに変動するドメイン群をまとめ、メイン設定の rules を短く保つ。
DIRECT の例外をプロキシルールより上に置き、社内 Git やローカルレジストリを誤って外部ノードへ送らない。

最初に通信経路を確認する

設定を変更する前に、Clash の接続画面またはログで実際のホスト名を記録してください。git clone、npm install、docker pull は複数の接続を発生させるため、表示された1つのドメインだけを見て判断すると定義漏れが残ります。

GitHub・npm・Docker の対象を用途別に定義する

最初の段階では、サービスごとに専用のプロキシグループを用意します。グループ名は設定全体で一貫させ、例えば DEV-GITHUB、DEV-NPM、DEV-DOCKER とします。各グループには複数のノードを登録し、手動選択の select、遅延テストの url-test、障害時の切り替えを重視する場合は fallback を使い分けます。

GitHub の HTTPS 通信では、最低限 github.com と api.github.com を対象にします。Release や大容量ファイルの配布では別のホストへリダイレクトされることがあるため、実行ログに現れた配布ドメインも確認します。SSH で clone する場合はドメインだけでなく宛先ポートも重要です。SSH を HTTPS の 443 番ポートで提供する構成では、通常の DOMAIN-SUFFIX,github.com で捕捉できますが、22 番ポートを使う場合は DST-PORT,22 を開発用グループへ送る方法もあります。ただし、このポートルールはすべての SSH 接続に適用されるため、社内サーバーを除外するルールを先に置いてください。

npm は利用中のレジストリを先に確認します。端末で npm config get registry を実行し、通常のレジストリを使っているのか、社内の Verdaccio や Nexus を使っているのかを確認します。社内レジストリは DIRECT、外部レジストリは DEV-NPM に分けるのが安全です。パッケージの tarball が別ホストから配信される場合は、npm のログに出たホストを追加します。単に npmjs というキーワードで判定する DOMAIN-KEYWORD は、関係のないドメインまで巻き込む可能性があるため、明確なサフィックス指定を優先します。

Docker は docker.io とイメージ取得先を混同しないことが大切です。Docker Hub を利用する場合は、レジストリ本体、認証用ホスト、レイヤー配信用 CDN が別々に現れる場合があります。まず docker pull 実行時の Clash ログを保存し、接続先を確認してからルールに追加します。企業内レジストリやクラウド上のプライベートレジストリは、公開レジストリ用のルールに一括投入せず、ホスト名単位で専用の扱いにしてください。

用途	確認する情報	優先するルール	注意点
GitHub HTTPS	リポジトリ、API、Release のホスト	`DOMAIN-SUFFIX`	Release が別ホストへ転送される場合がある
GitHub SSH	接続ホストと 22 / 443 番ポート	`DOMAIN` または `DST-PORT`	社内 SSH サーバーを先に DIRECT にする
npm	`npm config get registry` の結果	`DOMAIN-SUFFIX`	tarball の配布先をログで追加する
Docker	レジストリ、認証、レイヤー配信先	専用 provider または個別定義	公開レジストリと社内レジストリを分離する

保守しやすい YAML の分割方法

ルールを1つの大きな YAML ファイルに書き続けると、サービス追加のたびに順序を壊しやすくなります。メイン設定にはプロキシグループ、rule-providers の参照、最終的な rules の順序だけを残し、対象ドメインの一覧は外部ファイルへ分離します。クライアントによって設定画面の名称は異なりますが、mihomo 系カーネルでは rule-providers と RULE-SET の組み合わせが基本です。

次の例では、開発ツールを1つのグループへまとめています。実際のノード名はサブスクリプションに含まれる名称へ置き換えてください。URL は例示用の値であり、利用するルール配布元の形式と信頼性を必ず確認します。

proxy-groups:
  - name: DEV-GITHUB
    type: select
    proxies:
      - PROXY
      - DIRECT

  - name: DEV-NPM
    type: url-test
    url: https://www.gstatic.com/generate_204
    interval: 300
    proxies:
      - PROXY-A
      - PROXY-B

  - name: DEV-DOCKER
    type: select
    proxies:
      - PROXY
      - DIRECT

rule-providers:
  dev-github:
    type: http
    behavior: classical
    format: yaml
    path: ./rules/dev-github.yaml
    url: https://rules.example.invalid/dev-github.yaml
    interval: 86400

  dev-npm:
    type: http
    behavior: classical
    format: yaml
    path: ./rules/dev-npm.yaml
    url: https://rules.example.invalid/dev-npm.yaml
    interval: 86400

  dev-docker:
    type: http
    behavior: classical
    format: yaml
    path: ./rules/dev-docker.yaml
    url: https://rules.example.invalid/dev-docker.yaml
    interval: 86400

rules:
  - RULE-SET,dev-github,DEV-GITHUB
  - RULE-SET,dev-npm,DEV-NPM
  - RULE-SET,dev-docker,DEV-DOCKER
  - GEOIP,PRIVATE,DIRECT,no-resolve
  - MATCH,PROXY

behavior: classical は各行にルールタイプ、対象、ポリシーを含める形式です。例えば dev-github.yaml は次のように作成できます。provider 内では出口を固定せず、メイン設定側の RULE-SET で出口を指定する構成もありますが、プロジェクト単位で出口を分けたい場合は下のように provider 内へポリシーを含める方法もあります。両方を混在させると意図が分かりにくくなるため、チーム内で方式を統一してください。

payload:
  - DOMAIN-SUFFIX,github.com,DEV-GITHUB
  - DOMAIN,api.github.com,DEV-GITHUB
  - DOMAIN-SUFFIX,githubusercontent.com,DEV-GITHUB
  - DST-PORT,22,DEV-GITHUB

ルールプロバイダーの形式には、一般的なルール行を持つ classical、ドメイン一覧を持つ domain、IP CIDR 一覧を持つ ipcidr があります。ドメインだけを管理する場合に domain を選ぶとファイルを短くできますが、GitHub の 22 番ポートや社内例外のような条件は表現できません。開発ツールの最初の構成では classical を使い、対象が安定してから種類を分割すると移行しやすくなります。

provider の更新失敗を見落とさない

rule-provider は設定ファイルの再読み込み時や指定した interval に従って更新されます。URL に接続できない、YAML のインデントが壊れている、behavior と実データの形式が一致しない、といった場合は古いキャッシュが使われることがあります。更新日時と Clash のログを確認し、空の provider を正常と判断しないでください。

ルール順序と DIRECT 例外を設計する

開発環境では、プロキシへ送る対象を先に書くだけでは不十分です。最初にローカルネットワークと社内リソースの例外を配置し、その後で GitHub、npm、Docker の provider を評価します。例えば社内 Git が git.corp.example、社内 npm が npm.corp.example なら、次のように明示的な DIRECT を先に置きます。

rules:
  - DOMAIN-SUFFIX,corp.example,DIRECT
  - IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
  - IP-CIDR,172.16.0.0/12,DIRECT,no-resolve
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - RULE-SET,dev-github,DEV-GITHUB
  - RULE-SET,dev-npm,DEV-NPM
  - RULE-SET,dev-docker,DEV-DOCKER
  - MATCH,PROXY

ただし DOMAIN-SUFFIX,corp.example,DIRECT は、その配下にあるすべてのサブドメインを直接接続にします。公開サービスと社内サービスが同じサフィックス配下にある場合は、より具体的なルールを上に追加してください。例えば公開対象をプロキシへ送る必要があるなら、個別の DOMAIN を社内一括ルールより前に置きます。

no-resolve は IP-CIDR ルールの判定時に DNS 解決を行わない指定です。LAN の予約アドレス帯のように、接続先 IP が最初から分かっているルールでは有効です。一方、ドメインを IP に変換しないと判断できないサービスに無差別で付けると、期待したルールへ一致しなくなることがあります。ドメインルール、IP ルール、プロセスルールを追加した後は、実際の接続ログで一致したルール名を確認してください。

社内ドメイン、localhost、LAN の CIDR を DIRECT の例外として先頭に置きます。
明確にブロックする不要な宛先がある場合は、開発ツールの provider より前に REJECT を置きます。
GitHub、npm、Docker の順に専用 provider を呼び出し、各サービスを専用グループへ送ります。
必要に応じて PROCESS-NAME を追加します。ただし同じプロセスが社内と外部の両方へ接続する場合は、プロセス単位のルールだけに依存しません。
最後の1行を MATCH,PROXY とし、未定義の外部通信を安全側へ送ります。

clone・npm install・docker pull の検証手順

設定を反映した後は、ブラウザでサイトを開くだけでなく、開発ツールごとの実処理を使って検証します。クライアントの「設定」または「Profiles」画面で YAML を再読み込みし、プロキシグループにノードが存在すること、rule-provider が更新済みであることを確認します。設定の読み込みに失敗している場合、古い構成が有効なままになるクライアントもあるため、画面に表示されたアクティブ設定名を必ず確認してください。

# GitHub HTTPS の接続先確認
git ls-remote https://github.com/example/example.git

# npm が参照するレジストリ確認
npm config get registry
npm view lodash version

# Docker レジストリへの取得確認
docker pull library/alpine:latest

Git の SSH 接続を使う場合は、HTTPS のテストとは分けて確認します。ssh -T の実行結果だけで認証成功を判断せず、Clash の接続ログにホスト名とポートが記録されているかを見ます。Docker Desktop は独自の仮想ネットワークやバックグラウンドサービスを使うため、ブラウザでの疎通が成功しても docker pull が失敗することがあります。TUN のオン・オフ、システムプロキシ、Docker Desktop 側のプロキシ設定が二重になっていないかも確認してください。

症状	確認する箇所	考えられる原因
git clone が認証前にタイムアウトする	GitHub のホストと 22 / 443 番ポート	SSH ポート未定義、または社内例外が先に一致している
npm install の metadata は取れるが tarball で止まる	npm の詳細ログと実配布ホスト	レジストリだけ定義し、tarball 配信先が漏れている
docker pull が認証エラーになる	認証エンドポイントとレジストリのルール	接続先ごとに異なる出口となり、認証セッションが不整合になっている
設定読み込み後も古い挙動が続く	Profiles の有効状態と provider の更新ログ	別の設定が有効、または provider のキャッシュが残っている
一部の開発ツールだけ DIRECT になる	ルールの上からの一致順序	GEOIP、DOMAIN-KEYWORD、広すぎる社内サフィックスが先に一致している

長期運用で壊れにくい YAML 管理

ルールの保守では、動いた設定をそのまま増築しないことが重要です。まず provider ごとに責任範囲を決め、GitHub 用ファイルに npm のホストを混ぜないようにします。追加したドメインにはコメントで「どのコマンドで確認したか」「どのサービスに必要か」を残すと、後から削除判断をしやすくなります。コメントを含められない形式へ変換する場合は、別の管理メモに根拠を保存してください。

名前を固定する。dev-github と DEV-GITHUB のように provider 名とグループ名を区別し、似た名前を乱立させない。
更新周期を短くしすぎない。頻繁な更新は安定性を高めるとは限らず、毎時更新より 86400 秒程度の定期更新から始める。
広いキーワードを避ける。DOMAIN-KEYWORD,git のような短い文字列は、無関係なホストをプロキシへ送る可能性が高い。
プロキシグループを分ける。GitHub と Docker で地域要件や速度が異なる場合、1つのグループにまとめず個別に選択できるようにする。
変更後に3つの実処理を再実行する。設定の構文確認だけでなく、clone、npm、pull の成功とログ上の一致ルールを記録する。

最終的に重要なのは、サービス名ではなく実際の接続先とルールの順序を管理することです。GitHub、npm、Docker を専用 provider に分け、社内リソースを先に DIRECT へ固定し、最後に MATCH のフォールバックを置けば、設定の意図を読みやすく保ちながら新しい配布ホストにも対応できます。mihomo のバージョンアップやクライアント変更を行ったときは、rule-provider の形式、TUN の取り込み状態、Docker Desktop の通信経路を再確認すると、突然の clone 停止やパッケージ取得失敗を早期に切り分けられます。