Clashのrule-providers自作とGitHub運用・YAML実践ガイド

rule-providersを使う理由と運用前の設計

Clashのルールが少ないうちは、rules: の下へすべての判定行を直接書いても問題ありません。しかし、広告除去、社内ドメイン、開発サービス、動画配信、地域別の接続先などを追加していくと、1つの設定ファイルが長くなり、変更範囲と原因の追跡が難しくなります。さらに購読プロファイルを定期更新している場合、手作業で追記したルールが上書きされることもあります。

rule-providers は、ルール集合を外部のYAML、テキスト、または配信可能なURLへ分離するための仕組みです。メイン設定には「どのプロバイダーを読み込むか」と「そのプロバイダーをどのポリシーへ送るか」だけを残し、実際のドメイン一覧は別ファイルで管理できます。これにより、購読設定を更新しても自分で管理するルールの責任範囲を分けやすくなります。

ただし、外部ファイルに分ければ自動的に安全になるわけではありません。取得先が停止したり、誤った内容へ差し替えられたりすれば、Clashはその内容をルールとして利用します。特に公開URLをそのまま採用する場合は、提供者、更新履歴、ライセンス、想定するドメイン範囲を確認してください。自分で管理できる小さなリポジトリを用意し、変更をPull Requestで確認する運用のほうが、巨大なリストを無条件で取り込むより原因を説明しやすくなります。

GitHubでYAMLを管理する基本構成

GitHubで管理する場合、まず専用リポジトリ、または既存リポジトリ内の専用ディレクトリを用意します。Clashが直接取得するファイルと、説明や検証用スクリプトを同じ場所へ置くと、更新の意図が分かりやすくなります。たとえば次のような構成です。

clash-rules/
├── README.md
├── providers/
│   ├── ai-services.yaml
│   ├── my-direct.yaml
│   └── ad-block.yaml
└── scripts/
    └── validate-rules.py

公開リポジトリでは、READMEに各ファイルの目的、更新頻度、対象ドメイン、推奨ポリシー、変更方法を記載します。ルールの行を追加しただけでも、なぜ必要なのかをコミットメッセージに残してください。「サービスの認証エンドポイントを追加」「誤判定されたCDNを除外」のように理由が読めれば、数か月後の自分や共同管理者が安全に判断できます。

URLは、可能であればGitHubの通常のHTMLページではなく、RawファイルのURLを使用します。ブランチの先端を参照するURLは更新が簡単な反面、意図しない変更も即座に反映されます。安定性を優先する環境では、タグやコミットハッシュに固定したURLを使い、変更時に手動で参照先を更新する方法もあります。常に最新版を自動取得したい個人環境と、変更審査を重視するチーム環境では、適切な運用が異なります。

YAMLの各フィールドと最小構成

Mihomo系のrule-providerでは、一般的に type、behavior、url、path、interval、必要に応じて proxy や format を指定します。type: http はURLから取得する外部プロバイダー、type: file はローカルファイルを利用する構成です。GitHubで公開したYAMLを定期取得するなら、通常はHTTP形式を使います。

behavior はルールの内容をClashがどの種類として解釈するかを示します。ドメイン名を列挙するなら domain、IP CIDRを扱うなら ipcidr、古い形式や混在したルールを利用するなら classical を選びます。ここを実際のファイル内容と合わせないと、取得そのものは成功してもルールが期待どおり評価されません。

rule-providers:
  AI_SERVICES:
    type: http
    behavior: domain
    url: https://raw.githubusercontent.com/example/clash-rules/main/providers/ai-services.yaml
    path: ./providers/ai-services.yaml
    interval: 86400

rules:
  - RULE-SET,AI_SERVICES,AI_PROXY
  - MATCH,DIRECT

url は取得元、path はローカルへ保存する場所、interval は更新間隔を秒数で指定します。24時間ごとなら 86400 です。更新間隔を短くしすぎると、GitHubやネットワークへ不要な負荷をかけるだけでなく、変更直後の不安定な内容を頻繁に取り込む可能性があります。個人用のルールであれば、まず1日または数時間単位から始め、実際の更新頻度に合わせて調整してください。

プロバイダーのYAML側は、利用する形式に応じて payload のようなルール配列を持たせます。行頭のインデント、タブ混入、全角カンマ、ポリシー名の誤記は頻出するため、GitHubへPushする前に構文チェックを行います。Clashのバージョンやクライアントによって対応フィールドが異なることもあるため、使っているコアのドキュメントと実際のログを基準にしてください。

RULE-SETの優先順位と更新タイミング

providerを定義しただけでは通信に適用されません。rules: の中で RULE-SET,プロバイダー名,ポリシー名 を呼び出す必要があります。Clashは基本的に上から順番にルールを評価し、最初に一致した行で処理を決定します。そのため、特定サービス用のRULE-SETを広い GEOSITE、GEOIP、または最後の MATCH より前に置かなければなりません。

rules:
  - RULE-SET,MY_DIRECT,DIRECT
  - RULE-SET,AI_SERVICES,AI_PROXY
  - GEOSITE,cn,DIRECT
  - GEOIP,CN,DIRECT
  - MATCH,PROXY

たとえば AI_SERVICES を GEOSITE,cn,DIRECT より下へ置くと、対象ドメインが別の広いルールで先に一致することがあります。また、広告ブロック用のproviderを上位へ置きすぎると、ログイン、決済、アップデート用のホストまで遮断する場合があります。優先順位は「広いルールを先、細かい例外を後」にするのではなく、通常は「明確な例外、用途別の集合、地域や分類の広い集合、最後のMATCH」という順番で考えると整理しやすくなります。

更新タイミングにも注意が必要です。Clashを起動した直後にproviderを読み込み、intervalを過ぎたら再取得する実装が一般的ですが、クライアントの再起動、プロファイル切り替え、手動更新によって挙動が変わることがあります。GitHub側で修正したのにすぐ反映されない場合は、ブラウザのキャッシュではなく、Clashが保存しているローカルprovider、更新時刻、HTTPレスポンス、現在選択中のプロファイルを確認してください。

ルールが効かないときのログ確認と安全な改善

ルールが効かないとき、いきなりproviderを作り直すのは効率的ではありません。まずClashのConnections、Logs、または接続一覧を開き、問題の通信を再現します。確認する項目は、接続先のホスト名、ポート、使用されたルール、選択された策略グループ、接続結果です。表示名はクライアントによって異なりますが、どのルールに一致して、どの出口へ送られたかを確認できれば、調査の方向を決められます。

最初に疑うべきは、ホスト名の想定違いです。ブラウザのアドレスバーに見えるドメインと、実際のAPI、認証、画像、CDNの接続先は一致しないことがあります。example.comを登録したのに、実際には api.example.net が使われているなら、providerのルールは正しくても一致しません。ログに現れた完全修飾ドメインを記録し、必要に応じて DOMAIN と DOMAIN-SUFFIX の使い分けを検討します。

次に、providerの取得状態を確認します。404ならURLやブランチ名、403なら公開設定やアクセス制限、YAML parse errorならインデントやキー名、空のルールなら生成処理やRaw URLの内容を疑います。ファイルをGitHub上で修正した直後は、Clash側が古い保存ファイルを使っていることもあるため、手動更新後にローカルの更新時刻と件数を確認します。取得に失敗した状態で古いキャッシュを使い続けるクライアントもあるため、「取得失敗＝ルールが空になった」と決めつけず、実際の表示を確認してください。

改善するときは、一度に複数の変更を入れないことが重要です。まず一つのドメインをproviderへ追加し、GitHubで差分を確認してから更新します。次にClashでproviderを手動更新し、ログ上のRULE-SET名と策略を確認し、最後に実通信を試します。これを小さな単位で繰り返せば、問題がURL、YAML、優先順位、ポリシーグループ、ノード品質のどこにあるかを切り分けやすくなります。

直接YAMLへ長いルールを埋め込む方法は、短期的には分かりやすくても、購読更新や複数端末への展開で差分管理が難しくなります。GUIだけで編集する方法も手軽ですが、変更履歴、レビュー、ロールバックの面では弱く、設定項目が増えるほど再現性を失いがちです。GitHub上の小さなrule-providerを使い、Clash V.COREなら用途別のYAML、更新間隔、ルール評価、接続ログを一つの流れで確認できます。複雑な外部管理ツールよりも変更点を追いやすく、他のClashクライアントで設定を読み替える際にも扱いやすいため、まずは安全なテスト用providerを作ってからダウンロードして実運用へ進めるのがおすすめです。