CONFIG.YAML / 設定項目ガイド
Clash設定ファイルの項目リファレンス
YAMLの読み込みからルール適用まで、項目の型や参照関係、適用範囲を解説します。
使い方ガイドでは初回の設定読み込みと接続確認を扱い、このページでは項目ごとの書き方とトラブル時の確認ポイントを解説します。使える設定がまだない場合は、まずガイドに沿って一通り設定してください。ポート、名前解決、ルーティングに問題があるときは、以下の目次から該当箇所を確認できます。mihomoを基準に説明しています。クライアント画面の項目や上書きの仕組みは、各製品の仕様をご確認ください。
01 YAML / STRUCTURE
YAMLの構造・項目の型・参照関係
トップレベルから通信経路まで確認する
Clashの設定ファイルはトップレベルのマッピングであり、ファイルの行順に実行されるコマンド列ではありません。まずトップレベルの項目を入口として捉えます。ポートと動作モードはリクエストがコアに入る経路を決め、DNSセクションは内蔵リゾルバーの応答方法、ノードセクションは接続先と接続方法、プロキシグループは選択可能な出口、ルールセクションは接続をどの出口に渡すかを定義します。ルールセクションをファイルの先頭に移しても、コアの初期化より先にルールが実行されるわけではありません。一方、同じリスト内でルールの順番を変えると、最終的な振り分けが変わることがあります。2つのファイルを比較するときは、トップレベル項目の位置とリスト内の順序を分けて考えてください。
mixed-port: 7890
allow-lan: false
mode: rule
log-level: info
proxies: []
proxy-groups:
- name: 手動出口
type: select
proxies:
- DIRECT
rules:
- DOMAIN-SUFFIX,example.org,手動出口
- MATCH,DIRECT
この完全な設定例にはリモートノードがなく、まずファイルの読み込みとローカル接続口を確認するのに適しています。ルールに対象ドメインが一致すると、「手動出口」というグループに接続を渡そうとします。グループにはDIRECTしかないため、その他のリクエストも末尾のルールで直接接続されます。この設定でウェブサイトを開けても、確認できるのはDIRECT経路が使えることだけで、プロキシサーバーへの接続を意味しません。特定のルールが実際に適用されたか確認するには、ページが表示されたかどうかから推測せず、クライアントの新しい接続記録も確認してください。ほかのプロキシソフトが例のポートを使用中なら、空いているポートに変更し、テストするアプリも同じポートに接続してください。
同名の項目は階層を分けて確認する
同じキーでも、階層によって意味が異なることがあります。トップレベルのproxiesはノードオブジェクトのリストですが、プロキシグループ内のproxiesはメンバー名のリストです。前者は各項目を複数の属性で記述し、後者は名前を1つずつ記述します。ノードオブジェクトを誤ってグループメンバーの下にインデントしても、YAMLとしては正しい場合がありますが、コアが想定と異なる型の値を受け取り、読み込みに失敗することがあります。グループ名を変更したら、その名前を参照する別のグループやルールも確認してください。定義だけを変えて参照を更新しないと、読み込めていた設定を適用できなくなる場合があります。
| 項目 | データ形式 | 編集時の確認ポイント |
|---|---|---|
mixed-port | 整数 | クライアントの実際の接続口と一致しているか |
dns | マッピング | 各キーが同じ親キーの下にインデントされているか |
proxy-groups | オブジェクトのリスト | 名前とすべてのメンバーを参照できるか |
rules | 文字列のリスト | リストの順序がマッチングの優先順位と合っているか |
構文・設定の検証・実行結果を分けて確認する
構文エラーはまずインデント、引用符、リストの記号を確認し、項目のエラーは型と参照先を確認します。インデントにはスペースを使い、タブは使わないでください。同じ親キーの下では同じ階層の項目をそろえ、リストのハイフンの後にはスペースを入れます。値にコメントとして解釈される可能性のあるシャープ記号や、コロンの後にスペースが続く箇所がある場合は、文字列を引用符で囲みます。ポートや真偽値は適切な型を保ち、文字列として扱う値だけ必要に応じて引用符を付けてください。書式付きの文章をコピーするときは、全角コロンや曲線型の引用符にも注意してください。見た目が似ていても、YAMLの記号としては使えません。
設定エラーに表示される行番号は、パーサーが問題を検出した位置であり、書き始めた行とは限りません。ある行でキーが不足していると表示されたら、ひとつ前の項目で引用符が閉じていない、または子項目のインデントが1段足りない可能性を確認してください。YAMLとして読み込めたら、重複するトップレベルキー、名前の重複、存在しない参照先がないか確認します。同じマッピングにルールキーが2つあっても、2つのリストが連結されるとは限りません。解析方法によっては読み込みが拒否されたり、片方が上書きされたりします。同じ階層のキーは1か所にまとめてください。
最後に、変更が実際に適用されているファイルに反映されたか、実行結果で確認します。クライアントにはダウンロード済みのサブスクリプションが表示されていても、別のローカル設定を読み込んでいることがあります。また、新しい設定の検証に失敗し、前の設定が使われ続けている場合もあります。現在の設定名、適用時刻、新しい接続のマッチ結果を記録し、想定と照らし合わせてください。既存の接続は開始時の出口を使い続けることがあるため、設定を切り替えた後はリクエストを新たに送信します。設定ファイルやサブスクリプションを初めて読み込む場合は、まず設定のインポート手順で現在有効な項目を確認してから、設定項目を調べてください。
02 INBOUND / MODE
共通設定:ポート・リスニング・動作モード
アプリが接続しているローカルの接続口を確認する
接続口のポートは、アプリからコアまでの接続を示すもので、プロキシサーバーのポートではありません。portはHTTPプロキシ、socks-portはSOCKSプロキシ、mixed-portは同じポートで両方のプロトコルを受け付けます。調査を始める段階では、接続口を1つに絞ると問題を切り分けやすくなります。ブラウザーやシステムプロキシでHTTPを使う場合は、アドレスとポートをHTTPまたは混合ポートに合わせてください。SOCKSに対応したアプリでは、対応するSOCKS設定を使います。アプリに自動設定アドレスと個別の手動プロキシが両方保存されている場合は、実際にどちらが使われているか確認してください。
mixed-port: 7890
allow-lan: false
mode: rule
log-level: info
この例では、混合ポートをローカルで使う設定にしています。クライアントのシステムプロキシ機能は、通常、システムの設定をコアのアドレスに向ける補助機能であり、すべてのアプリが自動的に従うわけではありません。独自のネットワーク設定を持つアプリもあれば、環境変数からプロキシアドレスを読み取るサービス、独自の接続方法を使うプログラムもあります。特定のアプリがプロキシを経由しているか確認するには、新しいリクエストを単独で送り、クライアントの接続画面に該当する接続先が表示されるか確認してください。接続記録がまったくない場合は、グループを何度も切り替えるのではなく、アプリのプロキシ設定、システムの例外設定、リスニングポートを優先して確認します。
同じリスニング先では、競合を解消してからアクセス範囲を調整する
同じアドレスの同じポートを、同種のリスナーが複数で共有することはできません。HTTP接続口と混合接続口に同じポートを設定したり、複数のクライアントが同じポートを同時に使用したりすると、バインドに失敗することがあります。起動ログにアドレスの使用中と表示されたら、混合ポート、コントローラー、内蔵DNSのどのリスナーで失敗したのか確認してください。ノードのポートを一律に変更するのは避けましょう。競合元を特定したら、不要なリスナーを停止するか、この設定に空きポートを割り当て、OSとアプリに保存されているプロキシアドレスも合わせて更新します。
ローカルでのみ使う場合は、allow-lan: falseのままで構いません。LAN内で共有する必要がある場合は、許可する範囲、リスニングアドレス、ファイアウォールのルールを別途確認し、信頼できるネットワークでアクセス元を検証してください。また、external-controllerとプロキシの接続口は区別が必要です。前者はパネルやプログラムからコアを管理するためのもので、後者がプロキシリクエストを受け付けます。画面からコントローラーに接続できても、プロキシ用ポートでリスニングできているとは限りません。公共のネットワークやアクセス範囲が不明な環境では、管理用とプロキシ用の接続口をローカル限定にすると、アクセス範囲を制御しやすくなります。
動作モードはルールを使うかどうかを決める。どのアプリがコアに接続するかは決めない
ルールモードでは、コアに入った接続をルールのリストに照らして出口に振り分けます。グローバルモードでは、通常のルールを個別に照合せず、グローバル設定で選択した出口を使います。DIRECTモードでは、コアに入った通常のプロキシ通信を直接接続します。3つのモードが変えるのはコア内部の処理経路であり、アプリのプロキシを自動的にオン・オフするものではありません。問題の切り分けには一時的にモードを切り替えて比較できます。同じリクエストがDIRECTでは成功し、指定した出口では失敗する場合は、まずその出口と名前解決に必要な経路を確認します。ルールモードだけで出口が誤る場合は、マッチしたルールとグループの選択を見直してください。テスト後は元のモードに戻し、ルールが有効だと誤解しないようにします。
ログレベルは、明確な調査目的に合わせて設定します。通常は起動失敗を特定できる程度にとどめ、接続を調べるときだけ一時的に詳細度を上げ、テスト範囲を絞ります。対象を一度に1つだけ開き、時刻を記録して、起動エラー、受信接続、名前解決、送信接続を区別してください。経路が正常でもページが遅い場合は、初回接続の確立と、確立済み接続での後続転送も分けて考えます。ログ1件だけを見てポートが原因だと判断しないでください。ログを共有する前に、サブスクリプションURL、LAN内のホスト名、アカウント関連の項目を削除します。エラーの種類と必要なポート情報を残せば十分です。
03 DNS / RESOLUTION
DNS設定:上流サーバー・名前解決の起点・Fake IP
どこからの問い合わせかを見極める
dns.enableが有効にするのはコアのDNSモジュールであり、システム全体のDNS設定を変更するものではありません。アプリはOSに問い合わせてからアドレスをプロキシ接続口に渡すこともあれば、対象ドメインをコアに直接渡すこともあります。独自の暗号化DNSを使い、システムの既定経路を通らないアプリもあります。調査では「どのコンポーネントが問い合わせたか」と「どのリゾルバーが応答したか」を分けて記録してください。一般的なウェブページが開けても、すべてのアプリが同じ上流サーバーを使っているとは限りません。また、名前解決でアドレスを取得できても、そのアドレスへの接続が成功するとは限りません。
dns:
enable: true
enhanced-mode: redir-host
default-nameserver:
- 1.1.1.1
nameserver:
- https://cloudflare-dns.com/dns-query
proxy-server-nameserver:
- 1.1.1.1
この例ではredir-hostで実際のアドレスを返し、通常の問い合わせには暗号化DNSを使い、ブートストラップ用の上流サーバーとノードの名前解決用上流サーバーを明示的に分けています。この設定を使うには、ローカル環境から例示したリゾルバーに接続できる必要があります。管理対象のネットワークでは、管理者が許可し、現在の接続経路から到達できる上流サーバーに置き換えてください。default-nameserverは主に、DNSサーバー自体がドメイン名で指定されている場合の初期解決に使います。暗号化DNSの接続先をドメイン名で指定し、その名前の解決にもまだ確立していない暗号化DNSを使うと、循環することがあります。ブートストラップには独立して到達できるIPアドレスを指定すると、この循環を通常の名前解決経路から切り離せます。
通常のドメインとノードのドメインで、名前解決の経路が異なる場合がある
nameserverは既定の上流リゾルバー、nameserver-policyは指定したドメインに別の上流リゾルバーを割り当て、proxy-server-nameserverはプロキシノードのサーバー名を解決します。ノードの接続先をIPアドレスではなくドメイン名で指定した場合、コアは接続を確立する前にそのアドレスを取得する必要があります。そのドメインの問い合わせを、まだ接続できていないノード経由にすると、初回接続が止まることがあります。こうした問題を調べるときは、まずノードのドメインを独立した名前解決経路で解決し、次に得られたアドレスへ接続できるか確認してください。通常の上流サーバーだけを何度も変更すると、ノードの名前解決という段階を見落としがちです。
内部サービスの名前解決では、対象ドメインを明確に指定し、社内ドメインを公共リゾルバーに渡して試すのは避けてください。内部と外部で異なる上流サーバーを使うと、同じ名前でも返される情報が異なることがあります。公共リゾルバーでレコードが見つからなくても、内部レコードが存在しないとは限りません。ドメイン別の設定を変更したら、内部ドメインと外部ドメインをそれぞれテストし、返されたアドレスが想定どおりか記録してください。ネットワークを切り替えると、以前使えていた内部DNSに到達できなくなることがあります。内外の名前がどちらも解決できない場合は、上流サーバーを一度にすべて置き換えるのではなく、まず最小構成で動作を復旧してから、ドメイン別の設定を順に追加してください。
Fake IPはマッピング用のアドレスであり、サービスの実アドレスではない
fake-ipモードは、問い合わせ元に合成アドレスを返します。コアがそのアドレス宛ての接続を受け取ると、マッピングを使って元のドメインを復元します。この仕組みを使うには、合成アドレスを取得したアプリからの接続が、マッピングを管理するコアに戻る必要があります。接続がこの経路の外に出たり、設定を切り替える前のアドレスがシステムにキャッシュされたりすると、アプリが通常の方法ではルーティングできないアドレスを受け取ることがあります。ローカル機器の検出や内部サービスに問題がある場合は、まず合成アドレスを使う構成が適切か確認してください。必要な名前に実際のレコードを返すにはfake-ip-filterを使い、すべてのドメインをまとめて例外にするのは避けましょう。
モードを切り替えたら、同じアプリで問い合わせと接続を新たに行い、キャッシュによる差の隠蔽を避けてください。次の3点を個別に確認できます。問い合わせに応答があったか、接続が対象ドメインに正しく関連付けられたか、ルールで想定どおりの出口が選ばれたか。1つ目で失敗する場合は上流サーバーへの到達性、2つ目ならアプリの名前解決元と接続の捕捉範囲、3つ目ならルールの順序を確認します。ログに名前解決のタイムアウトが先に記録されている場合、その後にウェブページで接続エラーが出ても下流側の症状にすぎません。ノードやシステムプロキシも疑わしい場合は、ノードのタイムアウトを段階的に切り分ける方法を参照してください。
04 PROXIES / OUTBOUND
プロキシノードの項目と接続の境界
ノードの表示名と接続パラメーターを分けて考える
ノードは、1つの送信接続に必要なパラメーターのまとまりです。nameは設定内で参照する名前、typeはプロトコル、serverとportは実際の接続先を示します。ノード名には見分けやすい文字列を使えますが、プロキシグループからの参照名と一致させ、ほかの出口名と重複しないようにしてください。ノードの表示名を変更してもリモートサーバーは変わらず、接続失敗も解決しません。反対に、接続先のパラメーターを変更しても名前を維持すれば、通常はプロキシグループから引き続き参照できます。設定を変更する前に、表示名と実際の接続条件のどちらを変更するのか明確にしてください。
proxies:
- name: 本機テスト出口
type: socks5
server: 127.0.0.1
port: 1081
udp: false
proxy-groups:
- name: ノード確認
type: select
proxies:
- 本機テスト出口
- DIRECT
rules:
- DOMAIN-SUFFIX,example.org,ノード確認
- MATCH,DIRECT
この例では、ローカルで動作している別のSOCKS5サービスがあり、例のポートで接続を受け付けている必要があります。内蔵ノードではなく、サービスを起動する設定でもありません。ローカルにサービスがない場合は、比較用にDIRECTを残すか、自分に利用が許可されたプロキシに置き換えてください。サーバー側のポートに、この設定自身の混合ポートを指定しないでください。送信接続が受信接続に戻り、独立したテスト経路になりません。設定を適用したら、グループでテスト用の出口を明示的に選び、例示したドメインにアクセスします。グループに保存されたDIRECTをノードが正常に動作している証拠と取り違えないようにしてください。
プロトコル・トランスポート・認証を個別に確認する
プロトコルごとの追加項目を、名前から推測して設定することはできません。ユーザー名とパスワードを使うもの、プロトコル固有の識別子が必要なもの、トランスポート層でTLSを有効にするもの、サーバーと一致するトランスポート設定も必要なものがあります。まずノードの提供元が示す項目一覧に従ってプロトコルを設定し、アドレス、認証方式、トランスポートのパラメーターを確認してください。サーバーまで接続できても、確認できるのはアドレスとポートへの到達性だけで、認証の成功を意味しません。ログにハンドシェイクや認証のエラーがある場合は、名前、時刻、サーバー証明書の設定を確認し、検証を無効にして問題を隠さないでください。
接続に使うアドレスと、証明書の照合に使うサーバー名が異なる場合があります。サーバーが特定の名前を要求する場合は、そのプロトコルでサポートされる項目に指定してください。ノードの表示名をハンドシェイク時の名前として使うことはできません。同様に、トランスポート設定のパスはサブスクリプションURLとは別物です。サブスクリプションURLは設定全体の取得に使い、パスはノードの接続パラメーターに含まれます。変更の対象が異なるため、混同しないでください。設定の提供元を確認するときは、通常の方法で読み込んだ後の設定を参照し、共有リンク内のエンコード済み文字列を、対応していない項目に直接貼り付けないようにします。複数の設定を比較する際は、同じプロトコルの同じ種類の項目を比べてください。
出口を1つに絞り、ネットワーク障害と選択ミスを切り分ける
UDPは個別に検証してください。UDPを有効にする項目が示すのはコアの送信動作であり、プロキシサーバー、下位のトランスポート、対象アプリが同じ通信に対応することまでは保証しません。ウェブサイトにTCPで接続できても、通話やリアルタイムアプリが正常に動くとは限りません。反対に、UDPのテスト失敗だけでノード全体が使えないと判断すると、正常なウェブ接続まで誤って排除することがあります。まず手動で1つのグループを選んで基本的な送信接続を確認し、次に実際にUDPを使うアプリで新しい接続記録を調べます。プロトコル、対象、マッチしたルール、選択された出口を個別に記録し、1回のウェブ速度テストで経路全体を判断しないでください。
ノードの読み込みに失敗した場合は、まず再現可能な最小構成を残します。グループが表示されているのに接続できない場合は、エラーが発生した段階に応じてパラメーターを確認してください。名前解決エラーはノードのドメインに関係する場合があり、接続拒否はポートやサービスの状態が原因のことが多く、ハンドシェイクのタイムアウトには経路やトランスポートの設定も関係します。症状だけで原因を1つに特定することはできません。ノードを削除する前に、名前が複数のプロキシグループやルールから参照されていないか検索してください。必要なコアがクライアントに含まれているか確認するにはダウンロードセンターをご覧ください。プラットフォームごとに「おすすめ」として紹介されているClash Plusを優先して確認し、各製品が実際に対応する項目も調べてください。
05 PROXY-GROUPS / SELECTION
プロキシグループの種類・メンバー・ヘルスチェック
プロキシグループは出口を管理し、ルールマッチングの代わりにはならない
ルールは接続を出口またはプロキシグループに渡し、グループはメンバーから実際の出口を選びます。ルールは正しくマッチしているのに接続経路が違う場合は、マッチしたグループ名と、グループ内で現在選ばれている出口の両方を確認してください。まず1段の手動グループで実際のノードを検証し、その後で自動グループを追加することをおすすめします。最初から複数の自動グループを入れ子にすると、ヘルス状態、テスト結果、ユーザーの選択が同時に影響するため、個々の接続がどのノードに向かったか説明しにくくなります。グループ名には「仕事用接続」や「予備出口」のように用途を表す名前を使い、更新で変わりやすいノード名は避けてください。
proxy-groups:
- name: 自動出口
type: url-test
proxies:
- 本機テスト出口
url: 'https://example.org/'
interval: 300
tolerance: 50
- name: 手動入口
type: select
proxies:
- 自動出口
- DIRECT
この内容はトップレベルのプロキシグループ一覧全体を置き換えるためのものであり、元のファイルに同名のトップレベルキーを追加するものではありません。ノードは前の章のものを使用します。前の章のルールも使う場合は、ルール内の「ノード確認」を「手動入口」に変更してください。ここでは構文を示すため、ノードを1つだけ設定しています。候補間の切り替えは発生しません。テストURLは例示用です。実際に使う際は、軽量で安定しており、想定される応答が明確で、どの候補からもアクセスできるアドレスを選んでください。自動グループが確認するのはそのアドレスへのリクエストであり、テスト用PCからノードサーバーまでの片道の遅延ではありません。他の業務サイトの応答を示すものでもありません。
切り替えたい目的に合わせてグループの種類を選ぶ
| 種類 | 選択基準 | 用途 |
|---|---|---|
select | ユーザーが選択 | 経路を手動で指定する、出口を固定して調査する |
url-test | テスト結果と許容差 | 候補ごとの応答を比較する |
fallback | メンバーの順序と可用性 | 優先出口を使い、失敗したら予備に切り替える |
load-balance | 負荷分散方式 | 利用可能な複数のメンバーに接続を振り分ける |
優先する出口を決めておきたい場合は、最速ノードの選択ではなく、優先順位をfallbackで指定してください。テスト結果を比較する場合、url-testの許容差を設定すると、小さな差による頻繁な出口の切り替わりを避けられます。toleranceはミリ秒単位、intervalは秒単位で設定します。テスト間隔が短すぎるとテスト通信が増え、長すぎると状況の変化を検出するまで時間がかかります。まず時間帯ごとの実際の変動を確認し、必要に応じて2つの項目を調整してください。1回のテスト結果だけでグループ全体を書き換える必要はありません。
load-balanceが振り分けるのは接続であり、1つのダウンロードを複数のノードに分割するものではありません。セッションの維持が必要な業務では出口の変更に影響を受けることがあるため、ほかの接続とローテーション方式を共有せず、固定グループに分けるのが適しています。方式を選ぶときは、優先順位、接続の固定、均等な振り分けのどれを重視するかを明確にしてから、自動プロキシグループの選び方と項目の比較をご覧ください。グループを切り替えた前後で同じ接続先に新しい接続を複数回行い、結果を確認します。確立済みの接続は切り替えの成否を判断する材料には適しません。
グループの参照は一方向にする
グループに別のグループを含めることはできますが、自分自身を直接または間接に参照することはできません。ルール向けの入口グループから下位の自動グループを参照し、その自動グループからノードを参照する構成は確認しやすくなります。プロキシプロバイダーからメンバーを取得する場合、グループ内のuseで参照するのはプロバイダー名であり、その中に含まれる個々のノード名ではありません。グループを起動しても選択可能なメンバーがない場合は、まずローカルの定義と参照先の存在を確認します。次にプロバイダーが読み込まれているか、フィルター条件ですべてのメンバーが除外されていないかを確認し、最後にテストの失敗を調べてください。定義があるのにメンバーがない状態と、メンバーはあるがすべて到達できない状態は別の問題です。
自動グループの異常を調べるときは、同じ候補と同じ接続先を手動グループで個別に試してください。手動接続も失敗する場合は、まずノードの経路を調べます。通常の通信はできるのにテストだけ失敗する場合は、テスト先でアクセスが制限されていないか、その出口から想定と異なる応答が返っていないか、テストが実行されているかを確認してください。クライアントによっては手動グループの前回の選択を保持します。YAMLを変更しても、画面の選択が自動的に先頭へ戻るとは限りません。候補の順序、実際に選択された項目、テスト時刻を記録すると、設定変更とクライアントに保持された実行状態を区別できます。
06 RULES / MATCH ORDER
ルール構文・マッチ順序・フォールバック
対象範囲の狭いルールから照合し、徐々に広げる
ルールモードでは、ルールリストを上から順に処理し、最初に一致したルールが出口を決めます。特定のドメインを指定するルールは、それを含むサフィックスルールより前に置いてください。範囲の狭いネットワークも、範囲の広いネットワークより先に指定します。ルールは多ければよいのではなく、適用範囲と優先順位を説明できることが重要です。ルールを追加する前に、同じ対象を含む広いルールが前にないか確認してください。すでにある場合は、新しい例外をそのルールより前に置きます。最後のフォールバックより後に例外を置いても、設定は読み込めることがありますが、期待どおりの振り分けにはなりません。
mode: rule
proxy-groups:
- name: ドキュメント用出口
type: select
proxies:
- DIRECT
rules:
- DOMAIN,upload.example.org,DIRECT
- DOMAIN-SUFFIX,example.org,ドキュメント用出口
- IP-CIDR,192.0.2.0/24,DIRECT,no-resolve
- MATCH,DIRECT
この例の1つ目のルールはアップロード用サブドメインだけに一致し、2つ目は例示したメインドメインとそのサブドメインを対象にします。3つ目はIPアドレス範囲の指定方法を示すもので、使用しているネットワーク範囲は文書用に予約されています。末尾のルールは、それ以前の条件に一致しなかった接続を受けます。例のグループにはDIRECTしかないため、最初の2つのルールの違いを確認するには、接続記録に表示されるルールまたはポリシーの経路を見てください。MATCHにはドメインやネットワーク範囲の引数がなく、出口だけを指定します。この書き方ではカンマを含むルール全体がYAMLリストの1項目になります。条件とポリシーを複数のハイフンに分けて別々の項目にしないでください。
対象ドメイン・接続先アドレス・データの取得元を分けて考える
ドメインルールを使うには、コアが対象ドメインを確認または復元できる必要があります。アプリからIPアドレスだけが渡され、利用可能なドメイン情報がない場合、ドメインルールはマッチしません。IP-CIDRはアドレス範囲で判定します。対象がドメイン名しかない場合、一部のIP系ルールは名前解決を行います。対応するルールタイプではno-resolveを付けると、そのマッチングのためだけに追加の問い合わせが発生するのを防げます。すでに対象アドレスが分かっている場合は、アドレスを使って判定できます。このオプションを追加した後は、ドメイン名とIPアドレスの両方でテストしてください。そうしないと、「名前解決なしでは判定できない」状態を、ネットワーク範囲の記述ミスと誤解しやすくなります。
GEOIPは地理情報データベースを参照し、ドメインのサフィックスから地域を推測するものではありません。RULE-SETはrule-providersで定義済みのルールセットを参照します。データベースが更新されると、同じIPアドレスでも分類が変わることがあります。ルールセットには独自の動作タイプとデータ形式もあります。ファイルをダウンロードできても、コアがその中のルールを正常に読み込めたとは限りません。この2種類の条件を実際のルールリストに加える前に、現在の設定でデータが読み込まれているか確認し、対象外と対象内の両方でテストしてください。更新の失敗、ノードの異常、振り分けの不一致などは、トラブル対処FAQでよくある事例を確認できます。
対象・反例・フォールバックで順序を検証する
検証では最低でも3種類の対象を用意してください。特定の例外に一致する対象、より広い条件に一致する同種の対象、前段のルールに一致せずフォールバックに進む対象です。まず各対象に適用される想定ルールと出口を記録し、新しい接続を作成します。特定の対象が広いルールに処理される場合は、上下の順序を確認してください。複数のドメインがフォールバックに進む場合は、対象値、ドメイン情報の可視性、現在のモードがルールモードかを確認します。ルールは正しいのに出口が異なる場合は、グループ内のメンバーを調べてください。ウェブサイトは複数のサブドメインや外部リソースに同時にアクセスすることがあります。アドレスバーのメインドメインだけをサイト全体の接続先とみなさず、接続を1つずつ確認してください。
フォールバックを変更する前に、分類されていない通信をどのように扱うか決めてください。フォールバックをDIRECTにすると既知のルールの影響を切り分けやすく、設定の検証にも適しています。実運用ではネットワークと業務要件に合わせて明示的な出口を選び、よく使うアプリでその経路を確認してください。変更を保存するときは、どのルールが変更によって先に処理されるようになったかも記録します。後で一時的な例外を削除するときに、どの経路を置き換えていたか記録から確認でき、記憶に頼らずに済みます。頻繁に更新される外部ルールセットでは、繰り返し検証できる対象を1〜2個残し、更新後も同じ順序で確認してください。
07 OVERRIDES / EFFECTIVE CONFIG
設定の上書き・マージ・ロールバック
元のサブスクリプション・ローカル変更・有効な設定を分けて保存する
変更が反映されないときは、エディターに表示されたサブスクリプションのコピーだけでなく、コアが実際に読み込んだ設定と照らし合わせてください。クライアントはまずベースとなるサブスクリプションを取得し、ローカルの上書きをマージした後、画面の設定に応じて実行用の項目を追加することがあります。上書きファイルに、すべてのクライアントで共通するコアの構文があるわけではありません。製品の機能が、設定全体の置き換え、キー単位のマージ、リストへの追加、スクリプト処理、または別の方式のどれに該当するか確認してください。製品が対応する機能を提供していない場合、YAMLに独自のマージ指示を追加しても、コアが自動的に実行することはありません。
変更していないサブスクリプションの元データを保管し、検証用のローカル設定を別に保存してください。接続口だけを変更する場合は、以下のYAMLを変更項目の一覧として使うか、マッピング形式の上書きに対応したクライアントで仕様に従って適用します。この断片だけを元の設定の代わりに使わないでください。元のノード、グループ、ルールは一緒に読み込まれません。まず2項目を適用し、実際のリスニング状態が想定と一致するか確認してから、DNSやルールを変更します。変更を複数回に分けて適用すれば、問題が発生したときに、どの変更で挙動が変わったか特定できます。
mixed-port: 7891
allow-lan: false
マージする前に値のデータ形式を確認する
ポートはスカラー値なので、変更後は通常、そのポートを使うアプリの設定を合わせるだけで済みます。DNSセクションは入れ子のマッピングです。ツールによって子キー単位でマージする場合もあれば、新しいセクションで古いセクション全体を置き換える場合もあります。そのため、強化モードだけを変更したつもりでも、既存の上流サーバーや内部ドメインのポリシーが失われることがあります。生成後の設定に古い項目が残っているか確認し、以前は名前解決できていた内部の対象で再テストしてください。削除の挙動を確認するために空の値を使わないでください。項目の欠落、空のリスト、YAMLの空値はそれぞれ異なる状態であり、クライアントとコアでの扱いも異なる場合があります。
リストは、置き換え・先頭への追加・末尾への追加のどれが行われるか、さらに確認が必要です。特にルールリストでは、マージ後に項目がすべて残っていても、順序が正しいとは限りません。以下は既存ルールを残す場合の最小例です。1行目が新しい例外、2行目とフォールバックはベース設定から引き継いでいます。ツールがリスト全体の置き換えにしか対応しない場合は、残したい既存項目も最終リストに含めてください。先頭への追加に対応するツールでは、新しい項目だけを指定し、既存ルールを重複して挿入しないようにします。例外が参照する出口も存在する必要があります。2つのYAMLがどちらも読み込めるからといって、マージ後も必ず適用できるとは限りません。
rules:
- DOMAIN,status.example.org,DIRECT
- DOMAIN-SUFFIX,example.org,ドキュメント用出口
- MATCH,DIRECT
読み込みテストで構造を確認し、ロールバックで操作手順を確認する
mihomoを単独で使っていて、ローカルに実行ファイルがある場合は、テストモードで読み込み予定の設定全体を検証できます。クライアント環境では、まずクライアントが提供する検証機能を使ってください。別途コマンドラインを使う場合は、作業ディレクトリと必要なルール用リソースを実際の環境に合わせます。外部リソースに関するエラーは、テスト環境の違いだけを示している場合があります。テストに通った後も、設定を再読み込みし、リスニング状態、ドメインの名前解決、新しい接続の出口を確認してください。静的テストでは、リモートノードやリゾルバーへの到達性を保証できず、OSのプロキシ接続確認の代わりにもなりません。
mihomo -t -f ./config.yaml
サブスクリプションの更新前後で、名前と順序の変化に注意してください。更新によってノードが削除されたり、ノード名が変わったり、プロキシグループのメンバーが別の候補に置き換わったりすることがあります。ローカルの上書きがノード名を使って参照していると、更新後に参照先が見つからなくなる場合があります。プロキシグループがプロバイダーから利用可能な候補を取得し、さらにフィルター条件を適用している場合は、フィルター結果を確認してください。複数の端末で設定を共有する場合は、ノード、グループ、ルールを共通部分とし、リスニングポートなどの環境設定は各端末のローカル層に分ける方法があります。詳しくは複数端末で設定を同期する方法の比較をご覧ください。
バックアップでは、更新前のベースファイル、ローカルの上書き、ロールバック用の有効な設定を区別できるようにしてください。変更ごとに、目的、影響範囲、検証結果を含む短いメモを残します。例:「リスニングポートを変更し、ブラウザーで新しいポートの接続を確認済み」。有効な設定にアカウント情報が含まれる場合はアクセスを制限し、公開の問い合わせに元ファイルをそのまま添付しないでください。サブスクリプションの更新とローカル変更が同じ日に重なっても、まず動作が確認できている経路に戻し、変更記録から差が生じた手順を特定できます。