Clashのrule-providersをGitHubで運用する実践ガイド
Clashのルールを増やしていくと、設定ファイルの rules にすべてを書き込む方法では管理が難しくなります。広告ドメイン、社内サービス、特定の国や地域に属するサイト、直接接続したい開発サービスなどを一つのYAMLへ追加し続けると、設定全体が長くなり、サブスクリプション更新時に変更が失われることもあります。
rule-providers は、ルールを外部ファイルとして分離し、必要なときにClashまたはMihomoが取得して利用するための仕組みです。GitHubでルールファイルを管理すれば、変更履歴、レビュー、検証、定期公開をまとめて扱えます。さらにGitHub Actionsを使うと、誤ったYAML、空のファイル、重複したルール、意図しない形式変更を公開前に検出できます。
ただし、GitHubにファイルを置くだけで安全な運用になるわけではありません。Clash側のプロバイダー定義、ルールの参照順、キャッシュの保存先、公開URLの安定性、Actionsの失敗時に古いデータを残す設計まで考える必要があります。この記事では、Mihomo系コアで利用しやすい構成を中心に、個人運用で再利用しやすい設計と切り分け方法を整理します。
rule-providersの役割と基本構造
rules は通信をどのポリシーグループへ渡すかを決める参照側の設定であり、rule-providers はルール本体を提供するデータ源です。プロバイダーを定義しただけでは通信に適用されません。まず外部ファイルを取得する設定を作り、その後で RULE-SET またはコアが対応する参照形式を rules に記述する必要があります。
rule-providers:
private-sites:
type: http
behavior: domain
format: yaml
url: "https://example.invalid/rules/private-sites.yaml"
path: ./rules/private-sites.yaml
interval: 86400
rules:
- RULE-SET,private-sites,DIRECT
- MATCH,Proxy
private-sites はプロバイダー名です。半角英数字とハイフンを使った短い名前にすると、後から参照関係を確認しやすくなります。type: http はHTTP経由でファイルを取得する指定、behavior: domain はドメインルールとして扱う指定です。format: yaml は取得するファイル形式、path はローカルに保存するキャッシュファイルの場所、interval は更新間隔を秒単位で表します。
上の例では、取得したドメインリストを private-sites という名前で参照し、一致した通信を DIRECT へ渡しています。実際のポリシーグループ名は使用中の設定に合わせてください。プロバイダー名、ポリシーグループ名、ファイル内の形式が一つでも一致しないと、設定の読み込みエラーやルール未適用につながります。
| 項目 | 役割 | 確認する点 |
|---|---|---|
type |
取得方法 | 通常はHTTP。ローカルファイルを使う構成ではコアの対応仕様を確認する |
behavior |
ルールの種類 | domain、ipcidr、classicalを内容に合わせる |
format |
ファイル形式 | YAML、テキストなど、実ファイルと一致させる |
path |
キャッシュ保存先 | 書き込み可能な場所で、他のプロバイダーと重複させない |
interval |
自動更新間隔 | 公開頻度より短くしすぎず、取得先へ過剰なアクセスをしない |
ルールファイルの形式と分割方針
ルールファイルは、対象の性質ごとに分けると保守しやすくなります。たとえば、業務サービス、広告、開発ツール、地域別ドメインを一つの巨大なファイルにまとめるのではなく、用途ごとにプロバイダーを分けます。そうすると、業務サービスだけを直接接続し、広告リストだけを拒否し、開発サービスは別のプロキシグループへ送るといった運用が可能になります。
domain形式のファイル
behavior: domain のYAMLファイルでは、一般に payload 配下へドメインルールを記述します。ドメイン名だけを列挙する場合と、ドメインサフィックスや完全一致などの形式を利用する場合では、使用中のコアが期待する構文が異なることがあります。Mihomoの実装とクライアントのコアバージョンを基準に、実際に読み込める形式を確認してください。
payload:
- "+.internal.example"
- "service.example"
- "DOMAIN-SUFFIX,example.net"
同じファイルで複数の記法を混在させる場合は、対象の形式が本当に許可されているかを検証します。単純なドメインリストとして運用するなら、入力方法を一つに統一した方が事故は少なくなります。特に、先頭のドット、ワイルドカード、末尾の空白、URL全体を誤って追加する問題は頻繁に起こります。
classical形式のファイル
behavior: classical は、通常の rules に近いルール行を外部へ分けたいときに使います。ドメインだけでなく、キーワード、IP CIDR、ポートなど複数の条件を組み合わせたい場合に便利です。
payload:
- DOMAIN-SUFFIX,example.org
- DOMAIN-KEYWORD,development
- IP-CIDR,192.0.2.0/24,no-resolve
- PROCESS-NAME,example-app.exe
ただし、コアやバージョンによって対応するルール種類に差があります。特にプロセス名、脚本、ネットワークタイプ、拡張されたルール形式を含める場合は、Mihomoで動作することを確認してから公開してください。対応していないルールが一行混ざるだけで、プロバイダー全体を読み込めなくなる可能性があります。
分割しすぎない設計
プロバイダーを細かく分けすぎると、設定の参照関係と更新ログが複雑になります。目安としては、適用するポリシーが異なる単位、更新担当者が異なる単位、公開範囲が異なる単位で分けるとよいでしょう。単なる数個のドメインを別ファイルにするより、同じ目的のルールを一つのファイルへまとめた方が、取得回数とキャッシュファイルの数を減らせます。
GitHubリポジトリの構成と公開方法
GitHubでは、ルールの原本、生成済みファイル、検証用スクリプトを分けて保存すると管理しやすくなります。たとえば、入力データを sources、Clashが直接取得する公開ファイルを dist、検証プログラムを scripts に分けます。手書きのルールと自動生成されたルールを同じファイルへ直接編集すると、次回のActions実行で変更が消えるため注意してください。
rules-repository/
├── sources/
│ ├── private-domains.txt
│ └── blocked-domains.txt
├── dist/
│ ├── private-sites.yaml
│ └── blocked-sites.yaml
├── scripts/
│ └── build_rules.py
└── .github/
└── workflows/
└── validate-and-publish.yml
Clash側の url には、クライアントから安定して取得できる公開URLを指定します。GitHubの画面URLではなく、Raw形式のファイル配信URLや、リリース資産、静的ホスティングなど、実際にファイル本文だけを返すURLを使います。HTMLのエラーページ、ログイン画面、リダイレクト先の応答をルールファイルとして保存しないよう、公開後にHTTPステータスとContent-Typeを確認してください。
公開リポジトリであっても、サブスクリプションURL、ノード情報、APIキー、外部コントローラーの秘密鍵を置いてはいけません。ルールファイルに個人情報や社内限定のドメインが含まれる場合は、公開範囲を見直します。Gitの履歴には削除前の内容が残るため、誤って秘密情報をコミットした場合は、単に最新ファイルから削除するだけでは不十分です。該当する認証情報を失効させ、履歴の扱いも確認してください。
GitHub Actionsで検証と生成を自動化する
Actionsの役割は、変更を検出して検証し、問題がなければ公開用ファイルを生成することです。最初から複雑な自動デプロイを作る必要はありません。まず、プルリクエストと手動実行で構文検査を行い、次にメインブランチへの反映時だけ dist を更新する構成にすると、失敗箇所を把握しやすくなります。
name: validate-rules
on:
pull_request:
paths:
- "sources/**"
- "scripts/**"
- ".github/workflows/**"
push:
branches:
- main
workflow_dispatch:
jobs:
validate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Validate source files
run: |
test -s sources/private-domains.txt
test -s sources/blocked-domains.txt
python scripts/build_rules.py --check
- name: Build rule providers
run: |
python scripts/build_rules.py --output dist
- name: Check generated files
run: |
test -s dist/private-sites.yaml
test -s dist/blocked-sites.yaml
grep -q "^payload:" dist/private-sites.yaml
この例は構造を示すための簡略版です。実運用では、対象ファイルに許可されない空白、重複行、不正なドメイン、コメント以外のURL、プライベートアドレスの混入がないかを検査します。YAMLとして解析できることと、Clashのルールとして意味があることは別問題です。YAMLパーサーを通過しても、payload が存在しない、ルール種類が誤っている、空の文字列が含まれているといった状態は残ります。
生成スクリプトでは、入力を正規化してから出力します。具体的には、前後の空白を削除し、空行とコメントを除外し、大文字・小文字の扱いを決め、重複を除去します。ただし、ルールの順序に意味がある場合は単純な並べ替えをしないでください。classical形式では、より具体的なルールを先に置く必要がある場合があります。
Actionsの権限も最小限に設定します。単に公開ファイルを生成するだけなら、書き込み権限を持つトークンを必要としない構成にできます。リポジトリへ自動コミットする場合は、ワークフロー権限、同時実行、無限に自分自身を起動する条件を確認してください。外部からのプルリクエストで秘密情報を使うジョブを実行する設計は避けるべきです。
キャッシュ、更新間隔、ルール優先順位
rule-providers は取得したファイルを path に保存します。起動直後に毎回ネットワークから取得するのではなく、キャッシュを利用できるため、短時間の公開サーバー障害が直ちに全ルールの消失につながるとは限りません。ただし、キャッシュが存在しない初回起動、保存先への書き込み失敗、破損したキャッシュ、設定変更によるパス変更では挙動が変わります。
interval は小さくしすぎないでください。数分ごとに複数のプロバイダーを取得すると、公開元への負荷が増え、レート制限や一時的な取得失敗を招くことがあります。ルールを一日に数回更新する程度なら、数時間単位の間隔で十分なことが多いでしょう。緊急変更をすぐ反映したい場合は、GUIの更新操作やコアのAPIによる手動更新を使い、通常の自動更新間隔とは分けて考えます。
ルールの優先順位は、外部ファイルの中だけでなく、rules における RULE-SET の位置でも決まります。Clashのルールは通常、上から順に評価され、最初に一致したルールで処理が終了します。
rules:
- DOMAIN-SUFFIX,internal.example,DIRECT
- RULE-SET,blocked-sites,REJECT
- RULE-SET,private-sites,DIRECT
- GEOIP,PRIVATE,DIRECT,no-resolve
- MATCH,Proxy
たとえば internal.example を拒否リストにも含めている場合、最初の直接接続ルールが先に一致します。逆に、先に広い DOMAIN-SUFFIX,example をプロキシへ送るルールを置くと、後ろにある特定の直接接続ルールへ到達しません。ルールを追加した後は、想定したドメインだけでなく、サブドメイン、IP直打ち、同じアプリが使う別ドメインも確認してください。
実際にルールを追加して公開する手順
- 目的を決める。 直接接続、プロキシ、拒否のどれに送るルールなのかを先に決めます。目的が曖昧なままドメインを集めると、後でプロバイダーの分割をやり直すことになります。
- 原本へ追加する。
sources配下の入力ファイルへ一行ずつ追加します。URL全体ではなく、Clashが照合できるドメインまたはルール形式を記述します。コメントには登録理由と確認日を残すと、後から不要な項目を削除しやすくなります。 - ローカルで生成する。 生成スクリプトを実行し、空行、重複、不正な文字列が除去され、期待する
payloadが出力されることを確認します。 - Clash設定へプロバイダーを追加する。 プロバイダー名、URL、形式、キャッシュパスを設定し、
rulesにRULE-SETを追加します。既存の同名キャッシュを使わないよう、プロバイダーごとに固有のパスを指定します。 - Actionsを実行する。 プルリクエストで検証ジョブを通し、ログに警告や生成件数を出力します。生成件数が突然ゼロになった場合は、成功扱いにせず失敗させる方が安全です。
- 取得と適用を確認する。 ClashまたはMihomoのプロバイダー画面で最終更新時刻、ファイルサイズ、ルール件数を確認します。接続ログで対象ドメインに実際のルールが一致し、想定したポリシーへ渡っていることも確認してください。
テストでは、ルールの対象にしたドメインだけでなく、対象外のドメインも使います。対象外の通信まで同じプロバイダーへ一致している場合は、サフィックスやキーワードが広すぎる可能性があります。また、ブラウザーのDNSキャッシュ、既存のHTTP接続、アプリ内蔵DNSによって変更結果がすぐに見えないことがあります。更新後も古い判定が続くときは、プロバイダーを手動更新し、必要に応じて対象アプリの接続を再作成します。
更新失敗と未適用を切り分ける
プロバイダーが使えないときは、「取得できない」「取得したが解析できない」「解析できたがルールに一致しない」の三段階に分けて調べます。最初の段階ではURL、HTTPステータス、TLS証明書、DNS、Clashから公開先へ接続する経路を確認します。ブラウザーでURLを開けても、Clashの現在のプロキシ経路から取得できるとは限りません。
取得後に解析で失敗する場合は、ファイルの先頭と末尾、文字コード、YAMLのインデント、payload の有無、behavior と実際の内容の一致を確認します。公開URLがリダイレクトを返す、ファイルではなくエラーメッセージを返す、Actionsが途中まで生成した空ファイルを公開する、といった問題もあります。公開前にファイルサイズが一定以上あること、想定した先頭行を含むことを検査すると、単純な事故を防げます。
解析は成功しているのに通信へ適用されない場合は、まず rules のプロバイダー名を確認します。大文字・小文字、ハイフン、アンダースコアの違いでも別名として扱われます。次に、同じ通信へ先行ルールが一致していないか、動作モードが rule になっているか、現在有効な設定が編集したファイルと同じかを確認します。GUIクライアントではサブスクリプション設定とオーバーライド設定が分かれているため、編集したYAMLが実行中の設定へ反映されていないこともあります。
| 症状 | 主な確認箇所 | 対処 |
|---|---|---|
| 取得タイムアウト | URL、DNS、Clashからの経路、公開元の状態 | URLを確認し、手動更新と別経路の取得結果を比較する |
| 形式エラー | YAML構文、behavior、format、payload | 最小ファイルで検証し、問題の行を段階的に戻す |
| ルール件数がゼロ | 生成処理、入力パス、Actionsの成果物 | 空入力を失敗扱いにし、生成件数をログへ出力する |
| ルールが一致しない | RULE-SET名、ルール順、動作モード、DNS情報 | 接続ログとプロバイダー状態を同時に確認する |
よくある質問
GitHubの公開リポジトリは必須ですか?
必須ではありません。Clashから到達でき、安定してルールファイルを返すHTTP公開先であれば利用できます。ただし、GitHubは変更履歴、レビュー、Actionsによる検証をまとめやすい点が利点です。非公開リポジトリのファイルを、認証なしのClash設定から直接取得できるわけではないため、公開範囲と配信方法は分けて設計してください。
URLの内容を変更したのにClashへ反映されません
自動更新間隔、ローカルキャッシュ、CDNや配信側のキャッシュ、ブラウザーやアプリの既存接続が原因になります。まずプロバイダーの手動更新を実行し、最終更新時刻とファイルサイズを確認します。Actionsが成功していても、Clashがまだ更新時刻に達していなければ古いキャッシュを使い続けます。
domainとclassicalはどちらを選べばよいですか?
ドメインの集合だけを管理するなら domain が扱いやすく、通常のClashルールに近い複数条件を外部化するなら classical が適しています。対応形式はコアの種類とバージョンによって異なるため、最小のテストファイルを読み込ませてから本番のルールを移行してください。
ルールファイルに社内ドメインを含めても安全ですか?
公開URLから誰でも取得できる状態なら、安全とはいえません。社内ドメイン、利用者識別子、サブスクリプション情報を含める場合は、公開リポジトリや公開配信を避け、アクセス制御と認証方式を確認してください。ルールの利便性よりも、機密情報を誤って配信しないことを優先する必要があります。