ClashのルールセットをGitHubで管理する方法|rule-providers実践設定
Clash のルールセットを GitHub で管理するメリット
Clash ルールセット GitHub 管理を検討しているなら、まず役割を分けて考えると設計しやすくなります。Clash の設定ファイルには、どの通信をどのポリシーへ振り分けるかを記述します。一方、対象ドメインや IP の一覧は別ファイルとして管理し、rule-providers から読み込めます。ルールが増えるたびに大きな YAML を直接編集する必要がなくなり、端末間で同じ一覧を共有したい場合にも便利です。
GitHub を使う利点は、単にファイルを公開できることだけではありません。変更履歴から「いつ、どの項目を追加したか」を追跡でき、誤った変更があれば過去の状態へ戻せます。Issue や Pull Request を使えば、ルールを追加する前に内容を確認する運用も可能です。仕事用、家庭用、テスト用など、複数の Clash プロファイルから同じルールセットを参照する構成にも向いています。
ただし、GitHub に置いたルールが自動的に安全で正確になるわけではありません。広すぎるドメイン指定や、意図しない DIRECT ルールは通信先を誤って振り分ける原因になります。また、公開リポジトリに購読 URL、認証トークン、個人情報を含む設定を置くのは避けてください。本稿では公開して問題のないルール一覧を対象に、GitHub での管理、Mihomo 系コアからの取得、更新、検証までを順に整理します。
rule-providers の対応項目や記述方法は、使用するコアとバージョンによって異なる場合があります。以下の例は Mihomo 系コアを想定しています。実際の利用前に、クライアントが使っているコアの種類とバージョンを確認してください。GitHub リポジトリとルールファイルを準備する
最初に GitHub で公開リポジトリを作成し、用途が分かる名前を付けます。たとえば自分で保守する一般的なドメインルールなら、リポジトリ名は clash-rules、ファイル名は custom.yaml のようにします。公開する理由がなければ private リポジトリを検討できますが、Mihomo から認証なしで取得するにはアクセス制御を別途考える必要があります。まずは公開して差し支えないデータだけを扱う構成が簡単です。
ルールセットの形式は、Clash のルール行をそのまま列挙する classical が理解しやすいでしょう。GitHub リポジトリ内のファイルには、ルール一覧を payload の下に記述します。ファイルを配置したら、ブラウザーで内容を開き、取得先の URL が HTML ページではなく生の YAML を返すことを確認してください。リポジトリの通常の閲覧ページ URL を url に指定すると、YAML として読み込めないことがあります。
payload:
- DOMAIN-SUFFIX,example.net
- DOMAIN,api.example.org
- DOMAIN-KEYWORD,docs
ここでは説明用のドメインを使用しています。実運用では、ログやサービスの公式情報など根拠を確認できるホストだけを登録してください。DOMAIN-KEYWORD は文字列の一部が一致した広い範囲に作用するため、思いがけないドメインまで対象に含める可能性があります。特定のホストなら DOMAIN、サブドメインを含めたいと確認できた場合は DOMAIN-SUFFIX を優先すると、意図を限定しやすくなります。
変更を加えるときは、GitHub の画面から直接編集する方法でも始められます。ローカルで Git を使う場合は、リポジトリを clone し、ファイルを編集して差分を確かめてから commit、push します。差分を見れば、想定外の削除や大量の行変更を配信前に発見しやすくなります。複数人で管理するなら、直接 main ブランチへ反映せず、変更案をレビューしてから取り込む流れが安全です。
Mihomo の rule-providers に GitHub の URL を設定する
ルールファイルを取得できる状態にしたら、Clash のメイン設定に rule-providers と rules を追加します。下記では GitHub の raw ファイル URL を参照し、定期的に取得し直す例を示します。URL の所有者名、リポジトリ名、ブランチ名、ファイルの場所は自分の構成に合わせて置き換えてください。
rule-providers:
custom-sites:
type: http
behavior: classical
format: yaml
url: "https://raw.githubusercontent.com/OWNER/clash-rules/main/custom.yaml"
path: ./ruleset/custom-sites.yaml
interval: 86400
rules:
- RULE-SET,custom-sites,手動選択
- GEOIP,CN,DIRECT
- MATCH,手動選択
type: http は HTTP 経由で取得する形式、behavior: classical は Clash のルール行を含む形式、format: yaml は YAML 形式であることを示します。path は取得したファイルのローカル保存先、interval は更新間隔を秒数で指定する項目です。例の 86400 は 24 時間です。保存先の扱いはクライアントやコアの起動環境に左右される場合があるため、設定ディレクトリの権限や永続化も確認してください。
RULE-SET 行は、プロバイダーのルールをどのポリシーへ送るかを定義します。ここで指定した 手動選択 は設定内に実在するポリシー名でなければなりません。またルールは上から評価されるため、プロバイダーの行を広い MATCH より後ろに置くと、先にすべての通信が一致してルールセットに到達しないことがあります。既存の例外ルールや地域別ルールとの順序を見直してから追加しましょう。
定期更新と Git の履歴を使った運用
interval はコアによるプロバイダー取得の周期を指定しますが、GitHub リポジトリの内容を編集したり、Git の変更を自動で commit したりする設定ではありません。ルールの追加や削除は、あくまで GitHub 側で管理します。取得頻度を短くしすぎると、不要な通信が増えるうえ、リポジトリ側で変更がない場合にも定期取得が繰り返されます。更新頻度は、ルールがどれくらい変わるか、障害時にどの程度早く反映したいかを基準に決めます。
日常運用では、変更理由を commit メッセージに残す習慣が役立ちます。「対象サービスのホストを追加」「誤判定したキーワードを削除」のように目的を書けば、数週間後に差分を読み直すときも意図を確認できます。変更前後の動作を比較したい場合は、一度に多くのルールを変えず、少数ずつ反映してください。問題が起きた際、変更履歴から最後の差分を特定して戻せるため、原因調査を短縮できます。
ブランチ名を URL に含めた raw URL は、ブランチの最新内容を取得します。手早く更新できる一方、main ブランチへ問題のある変更を push すると、次回の取得で利用中のすべての環境へ影響する可能性があります。再現性を重視する場合は、リリース済みファイルを使う、またはコミット ID に固定した URL を検討できます。その場合は新しいルールを公開するたびに参照先も更新する必要があるため、即時反映のしやすさと変更を固定する利点を比べて選んでください。
GitHub Actions などで定期的なチェックを組む場合も、外部のルール一覧をそのまま無条件に取り込むのではなく、差分確認や構文検証を挟むのが基本です。更新が失敗したときに空ファイルや不完全な内容を公開しないこと、変更内容をレビューできる状態にすることを優先してください。自動化を加える前に、手動で更新からロールバックまで一度実施しておくと、障害時にどの手順を戻せばよいか明確になります。
| 管理方法 | 利点 | 注意点 |
|---|---|---|
| ブランチの raw URL | 更新を push すれば同じ URL から新しい内容を取得できる | 誤った変更も次の取得で反映される可能性がある |
| コミット ID に固定 | 取得内容を固定し、同じ設定で動作を再現しやすい | 更新時に URL の変更が必要になる |
| リリース単位で管理 | 公開した版と変更履歴を区別しやすい | リリース作成と参照先更新の作業が増える |
設定とルールを検証し、取得エラーを切り分ける
設定を反映する前に、まず YAML のインデントとキーの位置を確認します。YAML は空白の階層が構造そのものです。タブとスペースを混在させたり、rule-providers の配下に置く項目をずらしたりすると、設定全体の読み込みに失敗することがあります。対応する Mihomo バイナリを利用できる環境では、設定ファイルのテスト機能を使って構文を検査します。
mihomo -t -f ./config.yaml
クライアントの画面からプロファイルを読み込む場合は、画面に表示されるエラーとコアのログも確認してください。コマンドで検証できても、GUI が別の設定ファイルや別バージョンのコアを使っていることがあります。実際に起動しているプロファイルとコアを確認し、検証したファイルと一致しているかを確かめることが重要です。
- 取得エラーやタイムアウト:raw URL をブラウザーで開き、URL のタイプミス、ブランチ名、ファイルの場所を確認します。端末から GitHub へ接続できるか、DNS やプロキシ経路に問題がないかも調べます。
- YAML の解析エラー:取得先が HTML のエラーページになっていないか、ファイルの先頭やインデントが正しいかを確認します。公開リポジトリの閲覧ページ URL と raw URL を取り違えていないかも見直してください。
- ルールが反映されない:設定の再読み込み後、プロバイダーが正常に読み込まれたかログを見ます。さらに
RULE-SETの位置、ポリシー名の一致、先行するルールへのマッチを確認します。 - 一部のサイトだけ誤って振り分けられる:接続ログで実際の接続先と最初に一致したルールを調べます。広すぎる
DOMAIN-KEYWORDが原因なら、より限定的なルールに置き換えるか、例外を上位に追加します。
ブラウザーで raw URL を開けることだけでは、Clash の取得成功を保証しません。クライアント側のネットワーク経路、証明書検証、起動時の取得状態が影響する場合があります。更新されないときは、プロバイダーの状態表示とログを先に確認し、ファイルの内容を変更したのに古い内容が残る場合は、取得間隔や手動更新の操作、ローカル保存先を一つずつ調べます。設定を何度も一括変更するより、エラーの発生箇所を一段ずつ確認するほうが安全です。
Clash rule-providers と GitHub のよくある質問
プライベートリポジトリのルールを直接取得できますか?
認証情報を渡さずにアクセスできないプライベートリポジトリは、通常の raw URL を指定するだけでは取得できません。認証トークンを設定ファイルへ直接書く方法は、漏えい時の影響が大きいため避けてください。利用するクライアントや配信方法で安全な認証手段が用意されているかを確認し、トークンの権限を必要最小限にする必要があります。公開しても問題のないルールだけを別の公開リポジトリへ分ける方法も検討できます。
GitHub 側のルールを追加したのに、通信先が変わりません。なぜですか?
プロバイダーが取得できているか、ルールセットの行が rules にあるか、参照名が一致しているかを順番に確認します。特に重要なのはルールの評価順です。対象通信が先行ルールに一致すると、後ろにある RULE-SET まで評価されません。接続ログで実際のホストと最初に一致したルールを調べ、必要なら専用ルールの位置を調整してください。
GitHub でファイルを変更したのに、すぐ反映されないのはなぜですか?
コアは指定した更新間隔に従って取得するため、push 直後に必ず切り替わるとは限りません。クライアントにプロバイダーの手動更新操作があれば実行し、ログで更新成功を確認します。URL がブランチの最新ファイルを指しているか、意図したリポジトリとブランチを更新したかも併せて確認してください。コミット ID に固定した URL を使っている場合は、参照先を更新しない限り内容は変わりません。
DOMAIN 形式や IP-CIDR の一覧も同じ設定で読み込めますか?
読み込める形式は behavior とファイル形式の組み合わせに依存します。本稿の例は、通常の Clash ルール行を payload に置く classical 形式です。ドメイン文字列だけのリストや CIDR 専用リストを扱う場合は、利用するコアがサポートする形式を確認して設定を合わせてください。異なる形式の行を一つのファイルへ混在させず、用途ごとにプロバイダーを分けると検証と保守が容易です。
一部の同種クライアントでは、ルールをメイン設定へ直接書く必要があったり、更新履歴を追いにくかったりして、複数端末で同じ一覧を保つ作業が煩雑になることがあります。Clash の Mihomo 系コアなら、rule-providers でルール一覧を設定本体から分離し、GitHub の履歴と組み合わせて変更の確認やロールバックを行えます。ルールの追加根拠を記録し、ログと構文チェックで反映を確かめれば、個人用から複数プロファイルの運用まで段階的に整えられます。これから Clash の利用環境を用意する場合は、ダウンロードページから対応クライアントを確認してください。