Mihomoのrule-providers設定ガイド:自作ルールをGitHub公開・CI検証
Mihomo の rule-providers でルールを外部管理する理由
Mihomo rule-providers は、通信先の判定に使うルールをメインの設定ファイルから分離し、HTTP 配信されるリストとして読み込む機能です。たとえば GitHub 上で自作のドメインルールを管理すれば、ルールを追加するたびに長いプロファイル全体を書き換える必要がなくなります。差分が小さくなり、変更のレビューや取り消しもしやすくなるため、個人の端末だけでなく複数のクライアントを運用する場合にも便利です。
一方で、rule-providers は「GitHub にファイルを置けば自動で安全に反映される」という仕組みではありません。公開 URL、ルール形式、Mihomo の読み込み設定、参照するポリシー名がそれぞれ正しく揃って初めて動きます。ファイルの YAML 構文が正しくても、ルールの意味や記述形式が対象の behavior と合わなければ期待どおりに分類されません。まずは小さなリストを作り、読み込みとマッチ結果を段階的に確かめるのが確実です。
この記事では、Mihomo の rule-providers 設定を GitHub で管理し、GitHub Actions で最低限の検証を行う流れを紹介します。サンプルはルール行をそのまま記述できる classical を使います。ルールの順序やポリシーへの割り当てを理解したい場合は、通常の分流ルールと同じく、プロバイダーを参照する RULE-SET がどこで評価されるかも意識してください。
GitHub リポジトリとルールファイルを用意する
最初に、用途が分かる名前でリポジトリを作り、ルールファイルを専用ディレクトリに置きます。次の例では ruleset/custom.yaml を管理対象にします。ファイルには payload 配下へルールを並べます。classical は通常のルール形式を扱えるため、ドメインだけでなく、必要に応じて IP 範囲なども同じプロバイダーにまとめられます。
payload:
- DOMAIN-SUFFIX,example.net
- DOMAIN,api.example.org
- DOMAIN-KEYWORD,dev-portal
ここに書くドメインは説明用の例です。実際には、ブラウザーやアプリの接続ログで観測したホスト名を根拠に登録してください。広いキーワードを安易に追加すると、意図しない別サービスまで同じポリシーへ流れることがあります。単一ホストに適用する DOMAIN、サブドメインも対象にする DOMAIN-SUFFIX、文字列を含むホストを対象にする DOMAIN-KEYWORD の違いを確認し、必要最小限の条件を選びます。
GitHub から Mihomo が取得する URL は、リポジトリの画面を開いたときの URL ではなく、ファイル本文を返す Raw URL です。公開リポジトリであれば、通常は https://raw.githubusercontent.com/<owner>/<repo>/<branch>/ruleset/custom.yaml の形になります。ブランチの既定名が main とは限らないため、リポジトリの実際のブランチ名とパスを確かめてください。
URL に main を指定すると、そのブランチの更新が次回取得時に反映されます。変更を即時反映したくない運用や、端末間で同じ内容を再現したい運用では、リリース用ブランチやコミットに紐づく URL を使う方法もあります。どの方式でも、ルールを更新した日時や変更理由をコミットメッセージに残すと、後から不具合の原因を追いやすくなります。
rule-providers と RULE-SET を設定する
次に、Mihomo のメイン設定へプロバイダー定義と参照ルールを追加します。以下は構成の要点を示す例です。すでに利用しているプロファイルがある場合は、既存の proxy-groups や rules を保ったまま、プロバイダー名と参照行を統合してください。
proxy-groups:
- name: PROXY
type: select
proxies:
- DIRECT
rule-providers:
custom-sites:
type: http
behavior: classical
format: yaml
url: https://raw.githubusercontent.com/OWNER/REPOSITORY/main/ruleset/custom.yaml
path: ./ruleset/custom.yaml
interval: 86400
rules:
- RULE-SET,custom-sites,PROXY
- MATCH,DIRECT
type: http は HTTP 経由で取得するプロバイダー、behavior: classical は通常形式のルールを扱う指定です。format: yaml は配信ファイルが YAML 形式であることを表します。path は取得したファイルを保存する場所で、実行環境によって相対パスの基準や書き込み可能な場所が異なります。GUI クライアントではプロファイル管理領域に保存される場合があるため、設定ファイルを置いた場所と同じだと決めつけず、クライアントのログと実際の構成を確認してください。
interval は更新確認の間隔を秒数で指定します。例では 86400 秒、つまり 24 時間ごとです。更新頻度を短くしすぎても、GitHub 側の変更が早くなるわけではなく、取得回数だけが増えることがあります。変更が少ない個人用リストなら、まずは一日程度の間隔から始め、反映速度の要件に合わせて調整します。
RULE-SET,custom-sites,PROXY はプロバイダー名 custom-sites に一致した通信を PROXY へ送ります。プロバイダーの定義だけではルールは適用されず、rules 内に参照行を置く必要があります。またルールは上から評価されるため、先に広い条件が一致すると、後ろに置いた RULE-SET まで到達しない場合があります。テスト対象の通信が既存ルールに先取りされていないかも併せて確認してください。
RULE-SET の参照名、YAML のインデントは完全に一致させてください。名前の大文字・小文字やハイフンの違いも、読み込みエラーの原因になります。GitHub Actions で YAML とルール内容を検証する
GitHub に変更を push する前に、CI で YAML の構文とファイルの基本構造を確認しておくと、単純なタイプミスを早い段階で発見できます。次のワークフローは、ルールファイルを変更したときに Python の YAML パーサーで読み込み、payload が配列になっていること、各ルール行が文字列であることを検査する簡易例です。リポジトリ直下に .github/workflows/validate-rules.yml として保存します。
name: Validate rules
on:
push:
paths:
- "ruleset/**"
- ".github/workflows/validate-rules.yml"
pull_request:
paths:
- "ruleset/**"
- ".github/workflows/validate-rules.yml"
jobs:
yaml-check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: "3.x"
- name: Install YAML parser
run: python -m pip install PyYAML
- name: Check rule file
run: |
python - <<'PY'
import yaml
from pathlib import Path
path = Path("ruleset/custom.yaml")
data = yaml.safe_load(path.read_text(encoding="utf-8"))
if not isinstance(data, dict) or not isinstance(data.get("payload"), list):
raise SystemExit("payload must be a YAML list")
if not data["payload"]:
raise SystemExit("payload must not be empty")
if not all(isinstance(rule, str) and rule.strip() for rule in data["payload"]):
raise SystemExit("every payload entry must be a non-empty string")
print(f"Validated {len(data['payload'])} rules")
PY
このチェックで分かるのは YAML の読み込みと、ファイルの最低限の形までです。ドメイン名が意図したサービスに属するか、Mihomo が個々のルールを有効な条件として解釈するか、参照先のポリシーが存在するかまでは保証しません。たとえば DOMAIN-SUFFIX の綴りを誤っても、上の簡易検証は文字列として受け入れます。そのため、CI の成功を「実機で必ず正しく分流できる」という意味に読み替えないことが大切です。
検証を強化するには、許可するルール種別を限定する追加チェックを設けたり、CI で使用する Mihomo のバージョンを固定して構成テストを実行したりします。コアのテストでは、CI 用の設定ファイルから同じプロバイダーをローカルパスで参照し、対象バージョンの Mihomo が設定を受け付けるかを確かめます。CI の依存ツールやコアを常に最新版へ追従させるより、利用中のクライアントに近いバージョンでテストし、更新時に意図的にバージョンを上げるほうが結果を比較しやすくなります。
運用では、プルリクエストごとに変更内容をレビューし、CI が通ったあとに既定ブランチへマージする流れが扱いやすいです。ルールをまとめて大量に追加するより、数件ずつ変更し、対象ホストと必要性を説明できる状態を保ちます。公開ルールを複数端末で共有する場合も、まずテスト用プロファイルで検証してから普段使いの設定へ反映してください。
更新確認と読み込みエラーの切り分け
設定を読み込ませたら、いきなり全通信の挙動で判断するのではなく、プロバイダーの取得、ファイルの解析、ルールのマッチ、ポリシーへの経路という順に確認します。Clash Verge、Clash Verge Rev などの画面では、コアのログやプロファイル状態を開き、起動時にプロバイダーの取得エラーが出ていないか見ます。表示名はクライアントの版によって異なるため、該当する項目が見つからないときはコアのログを優先してください。
- Raw URL を確認:ブラウザーで設定した URL を開き、GitHub の HTML 画面ではなく YAML の本文が表示されることを確かめます。404 なら owner、リポジトリ名、ブランチ、ファイルパスを順に見直します。
- YAML の構造を確認:タブ文字やインデントのずれ、コロンの不足、引用符の閉じ忘れを確認します。CI が成功していても、CI が別のファイルを検査していないか、対象パスを照合してください。
- 設定の対応関係を確認:
rule-providersのキーとRULE-SETの名前、behaviorとファイル形式、pathの保存先が一致しているか確認します。 - 更新条件を確認:プロファイルやコアを再起動した直後でも、キャッシュや更新間隔のために以前の内容が残ることがあります。クライアントの更新操作とログを使い、取得日時や応答結果を確認します。
- マッチ先を確かめる:対象アプリで接続を発生させ、接続ログに表示されるホスト名と命中ルール、選択されたポリシーを確認します。ログに現れた実際のホストが、リストの条件に合うか照合します。
エラーの見え方から原因を絞ることもできます。HTTP 404 や接続失敗なら URL、ネットワーク、公開範囲の問題を優先します。YAML の解析エラーならインデントやファイル形式を調べます。設定全体は読み込めるのにルールが一致しない場合は、ルールの順序、対象ドメイン、既存ルールによる先行マッチを確認します。読み込みが成功しているのに想定と違う出口へ進むなら、プロバイダーそのものではなく、RULE-SET の第三引数や参照先グループの選択状態が原因かもしれません。
更新を GitHub の既定ブランチへ反映したのに端末で変化がない場合は、まずブラウザーで Raw URL の内容が新しくなっているか確認します。そこが古ければコミット先やブランチ、パスが違う可能性があります。Raw URL は更新済みなのに端末が古い内容を使うなら、Mihomo の更新間隔、プロバイダーのキャッシュ、クライアントのプロファイル更新状態を切り分けます。変更を何度も連続して行うより、一度の更新で取得状況とログを記録し、原因の範囲を狭めるほうが安全です。
安全に保守するための運用方針
自作ルールは、動き始めてからの保守で品質が決まります。ホスト名を追加するときは、なぜ必要なのか、どのログや資料を根拠にしたのか、どのポリシーへ送るのかをコミットやレビューに記録します。使われなくなったルールは定期的に見直し、広すぎる条件や重複した条件を整理してください。複数のリストを組み合わせる場合は、目的別にプロバイダーを分けると、更新頻度や障害時の影響範囲を把握しやすくなります。
また、GitHub の公開リポジトリは誰でも内容を閲覧でき、Raw URL も公開されます。社内環境のホスト名、個人情報、アクセス制御に関わる情報を含めないこと、第三者のルールを再配布する場合は利用条件を確認することが必要です。コアやクライアントを更新した際には、既存のプロバイダー設定をそのまま使えるかテスト環境で確認します。設定項目の互換性やログの表示はバージョンによって変わることがあるため、長期間更新していない構成を本番へ一気に適用しないようにします。
一部の同種クライアントでは、ルール一覧の編集や更新状況が画面から把握しづらく、配布された一枚の設定ファイルを手作業で差し替える運用になりがちです。その方法では、誰が何を変えたか追いにくく、端末ごとの差分も増えます。Mihomo は rule-providers によってルールを分離し、GitHub の履歴と CI を組み合わせて変更確認や構文検査を行えます。Clash 系クライアントで同じプロファイルを使いながら、変更の根拠と適用結果をログで確認できる点が実務上の利点です。自分の環境に合わせた設定を始める場合は、ダウンロードページから利用するクライアントを確認できます。