Clash設定ファイルリファレンス
このページでは、設定項目の確認や参照関係のチェック、コアが実際に読み込む設定の確認方法を解説します。初回インストールやサブスクリプションの読み込みは、まずクイックスタートガイドをご覧ください。接続を確認した後、このガイドに戻って設定を変更しましょう。以下はmihomoを前提とし、外部サービスを使う例には実行条件を記載しています。
YAMLの構造と設定の読み込み元
トップレベル項目、マップ、リスト
コアが読み込むのは、マップをルートとするYAMLドキュメントです。ポートやモードはトップレベルのキー、DNSはマップとして記述し、リゾルバーのアドレスはそのマップ内のリストに記述します。ノード、プロキシグループ、ルールにも、それぞれ専用のトップレベルキーがあります。項目の記述場所を判断するには、まず親項目を確認し、その親がキーと値の組を受け取るのか、リストを受け取るのかを見ます。ほかの設定と見た目の位置をそろえてインデントしても、自動的に正しいモジュールに入るわけではありません。
同じ階層の項目はインデントをそろえ、各階層は半角スペース2つにするのがおすすめです。リスト項目はハイフンで始め、ハイフンの後に半角スペースを入れます。リスト内の各ノードは1件のレコードです。ノード名、種類、アドレスは同じレコードに記述し、別々のリスト項目に分けてはいけません。一方、ルールは通常、1行につき1つの文字列です。カンマはルール文字列内の項目を区切るもので、複数のYAMLリスト項目に分割するためのものではありません。
ポート番号は数値で、フラグは true または false で記述し、すべてを一律に引用符で囲む必要はありません。名前や長い値には引用符を使えます。値にコメントやキーと値の区切りとして解釈される可能性のある文字が含まれる場合は、特に引用符を付けてください。たとえば、名前の途中に空白があり、その後に引用符なしのシャープ記号が続くと、シャープ記号以降がコメントとして扱われ、グループからその名前を参照できなくなることがあります。空のリスト [] と空のマップ {} も異なる値です。
最小構成と名前による参照
以下の最小構成では、ローカルの混合プロキシポートだけを開き、ここに届いた通信はすべて内蔵のDIRECT出力に送ります。サブスクリプションや追加リソースは不要で、まずローカルのプロキシ経由で、もともとアクセス可能なサイトに接続できるかを確認するのに適しています。この設定は暗号化プロキシではなく、コアに接続されていないアプリの通信も変更しません。すでに別のクライアントが同じポートを使用している場合は、空いているポートを選び、テストする側も同じ値に変更してください。
mixed-port: 7890
allow-lan: false
mode: rule
log-level: info
rules:
- MATCH,DIRECT
この構成を基にポリシーを追加したら、データの参照関係を次の順にたどれます。ルールがプロキシグループを参照し、グループがノード、別のグループ、または内蔵出力を参照します。ノードには実際の接続方式が記述されています。ルールから内蔵出力を直接指定することもできます。参照はリスト内の位置ではなく名前で行われます。ノード名を変更したら、すべてのグループを確認してください。グループ名を変更した場合は、ルールと、そのグループを参照するほかのグループも確認します。名前に空白が1つ増えただけでも、別のオブジェクトとして扱われます。
サブスクリプション、設定ファイル、プロキシプロバイダーの内容は、必ずしも相互に置き換えられるものではありません。クライアントのサブスクリプション読み込み機能は、完全な設定を取得して処理する場合もあれば、独自のルールで最終設定を生成する場合もあります。プロキシプロバイダーが読み込むのは、グループが選択に使うノードの集合です。ノード一覧だけでは、トップレベルのリスナーやルールを含む設定にはなりません。内容をコピーする前に、ルートキーを確認してください。ルートキーが payload の場合は、どの種類のリソースに属するかも確認し、メイン設定としてそのまま起動しないでください。
元の設定と実際に適用される設定を区別する
GUIクライアントを使う場合は、少なくともサブスクリプションの原文、ローカルの上書き設定、コアに渡される最終設定を区別してください。画面上のスイッチは最終ファイルの生成に関わる場合もあれば、ランタイムAPIを通じてコアの状態を変更する場合もあります。サブスクリプションを更新すると手動編集した内容が消える場合は、キャッシュファイルを何度も編集するのではなく、クライアントが対応する上書き設定にカスタム項目を移してください。設定場所はクライアントごとに確認しましょう。クライアント選びが初めてなら、ダウンロードページのおすすめとして紹介しているClash Plusから確認できます。
コメントで変更の目的を説明することはできますが、コメントで参照の不整合を解消することはできません。同じマップ内に同名キーを重複して記述しないでください。パーサーによってはエラーになり、別のパーサーではどちらか一方の値だけが残ることがあります。ルールを2か所に書いても追加にはなりません。1つのリストにまとめ、適用したい順に並べてください。保存後は、実際の構造を確認し、クライアントで正しい設定が選択されているかもチェックしましょう。
エディターの色だけで設定の妥当性を判断するのは危険です。シンタックスハイライトでインデントや引用符の問題の一部は見つけられますが、グループ名が定義されているかや、使用中のコアがその項目に対応しているかまでは分かりません。読み込みエラーが出たら、エラー箇所から上にたどって最も近い親キーを探し、リストの階層と項目の型を確認します。構文が通った後で、参照関係をチェックしてください。表記とポリシーを同時に変更して、どの修正で解決したか分からなくなるのを防げます。
基本ポート、リスナーの範囲、動作モード
入口を選び、実際の待ち受け状態を確認する
ポート項目は、コアがローカルでリクエストを受け付ける入口を指定します。リモートノードのサーバーポートではありません。混合ポートはHTTPプロキシとSOCKSの両方のリクエストを受け付けるため、2種類のアプリで同じアドレスを使う場合に便利です。アプリごとに別の入口が必要なら、HTTPポートとSOCKSポートを個別に設定できます。複数のリスナーにはそれぞれ異なるポートを割り当ててください。3つの項目すべてに同じ数値を設定してはいけません。
| 項目 | 対象 | 確認ポイント |
|---|---|---|
mixed-port | HTTP・SOCKS共用のプロキシ入口 | アプリ側では、用途に合ったプロキシプロトコルを選択してください。 |
port | HTTPプロキシの入口 | HTTPSサイトをプロキシする場合も、ローカルの入口をHTTPSプロキシとして設定するわけではありません。 |
socks-port | SOCKSプロキシの入口 | アプリが渡しているのが対象のドメイン名か、すでに解決済みのアドレスか確認してください。 |
allow-lan | LANからローカルのプロキシ入口への接続を許可するか | ローカルでのみ使用する場合は false にします。 |
bind-address | LAN接続を許可する場合のバインドアドレス | 共有する場合はインターフェースのアドレスを明示し、アクセス範囲も確認してください。 |
external-controller | コアのコントロールインターフェース | プロキシポートではありません。プロキシの入口と一緒に外部へ公開しないでください。 |
以下の例では、2種類の入口に別々のポートを割り当てています。クライアントがこれらの項目を管理している場合は、画面から値を設定するか、上書き後の最終ファイルを確認してください。設定ファイルにポート番号が記載されていても、プロセスが実際にバインドできているとは限りません。以前のインスタンスが動作中、別のツールがアドレスを使用中、OSがプロセスの待ち受けを制限しているなどの理由で、ポートを使えないことがあります。ポートが競合した場合は、まず使用中のプロセスを特定し、以前のインスタンスを終了するかポートを変更してください。
port: 7890
socks-port: 7891
allow-lan: false
mode: rule
log-level: info
rules:
- MATCH,DIRECT
ローカルのアプリでは通常、ループバックアドレス 127.0.0.1 と、そのプロトコルに対応するポートを設定します。検証時はまず待ち受けログを確認し、プロキシを手動設定できるアプリからリクエストを送信してください。そのアプリでは成功するのに、ほかのアプリに接続記録がない場合は、システムプロキシを参照しているか、アプリ独自のプロキシ設定がないかを確認します。プロキシのアイコンが点灯しているだけで、すべてのアプリが同じ入口を使っていると判断しないでください。
クライアントのシステムプロキシスイッチは通常、OSのプロキシ設定を書き換えるもので、実際に使うかどうかはアプリによります。TUNはネットワークインターフェースとルーティングの層で対象の通信を取り込み、通常はOSの許可も必要です。どちらも通信をコアに取り込む方法であり、その後どの出力を選ぶかとは別の問題です。mode を変更するだけではシステムプロキシは有効にならず、TUNのインターフェース設定の代わりにもなりません。問題を切り分ける際は、まず接続方法を1つに固定してください。
ルール、グローバル、DIRECTを区別する
rule モードはルールの順に出力先を選ぶため、通信を明確に振り分けたい設定に適しています。global モードではグローバル選択を使い、ルールリストを順に照合しません。使用前に、クライアントで現在どの出力先が選択されているか確認してください。特定のリモートノードを通ると思い込まないようにしましょう。direct モードでは、コアに入った通信をDIRECTで送ります。ローカルの待ち受けが停止するわけでも、OSのプロキシ設定が元に戻るわけでもありません。
同じサイトへの接続結果がルールモードとグローバルモードで異なる場合は、まず両方の接続ログで実際の出力先を確認します。グローバルモードで成功しても、そのとき選択されていた経路が使えたことしか分かりません。ルール設定全体に問題があるとは限りません。ルールがDIRECTに一致していた、参照先グループで別のメンバーが選ばれていた、あるいは2回の接続で異なる名前解決が行われた可能性もあります。DIRECTモードでテストする場合は、現在のネットワークからそのサイトに直接アクセスできるかも確認してください。
ログレベルは通常 info にしておくのがおすすめです。問題の調査中は一時的に debug に上げ、1度再現させたら元に戻してください。ログに記録される接続先や設定名から利用環境が分かることがあるため、共有時は問題に関係する記録だけを抜き出します。「リクエストが入口に届いた」「ルールで出力先が選ばれた」「リモート側で接続が完了した」の3段階を区別してください。最初の段階だけを確認して、問題の原因を接続先サイトに決めつけないようにしましょう。
ローカルとLANの境界を明確にする
ほかのデバイスから接続する必要がある場合に限り、LANアクセスの有効化を検討してください。接続する側では、コアを実行しているホストのLANアドレスを指定します。接続するデバイス自身のループバックアドレスではありません。公開前に、対象インターフェースとファイアウォールの範囲を確認し、テスト後は使わない機能を無効にしてください。コントロールインターフェースは別に判断が必要です。プロキシ経由でネットワークにアクセスできても、呼び出し側にコアを制御する必要があるとは限りません。ローカル接続の調査のために、プロキシポートとコントロールポートの両方を全インターフェース待ち受けにしないでください。
ポートを変更したら、システムプロキシ、ブラウザー独自の設定、ターミナルの環境変数に古い値が残っていないかも確認してください。再起動前は使えたのに、再起動後に使えない場合は、再起動前後の実際の待ち受けアドレスと設定名を記録し、同じインスタンスが起動しているか確認します。OSの設定場所やプラットフォームごとの許可については、まずクイックスタートをご覧ください。その後、このページでコアの設定項目を確認できます。
DNS項目とfake-ipの動作
クエリがコアの名前解決を通っているか確認する
設定でDNSを有効にすると、コアのDNSモジュールが有効になります。このスイッチだけでOS上のすべてのDNSクエリがコアに取り込まれるわけではありません。ブラウザーが独自の暗号化DNSを使用している場合や、アプリが解決済みアドレスをプロキシに渡す場合もあります。システムプロキシとTUNでは通信の取り込み方が異なり、DNSリクエストを受け取れるかどうかも設定によります。調査を始める前に、どのアプリがクエリを発行し、実際にどのリゾルバーへ届いているか確認してください。
DNS設定の nameserver は、一般的なドメインを解決するリゾルバーのリストです。nameserver-policy を使うと、指定したドメインに使用するリゾルバーを選べます。default-nameserver は、起動時にDNSサーバーのホスト名を解決するなどのブートストラップに使うもので、すべてのリクエストで順番に試す予備リストではありません。ホスト名を含む暗号化DNSのアドレスを使う場合は、ブートストラップ用のリゾルバーが現在のネットワークから到達可能であることを確認してください。設定を読み込めても、初回の名前解決がタイムアウトすることがあります。
proxy-server-nameserver は、プロキシノードのサーバー名を解決するための項目です。「ノードに接続する前に、ノードのアドレスをどう取得するか」を解決するもので、一般的なWebサイトの名前解決とは異なります。ノードがドメイン名で、その解決に必要な上流サーバーにノード経由でしかアクセスできない場合、依存関係が循環します。その場合はまず、接続開始前に利用できる名前解決経路をノードのアドレス用に用意し、その後で一般サイトのクエリをどの経路に流すか決めてください。
アドレスマッピング、フィルター、ローカルクエリの例
fake-ip モードでは、受信したドメイン名のクエリに対してコアが仮想アドレスを割り当て、ドメイン名とアドレスの対応を保存できます。そのアドレスへの接続が同じコアに戻れば、ドメイン名を復元してドメインルールで判定できる場合があります。この仮想アドレスは、接続先サーバーが公開している実アドレスではなく、現在のコアに保存された対応情報なしには使えません。クエリはコアを通ったのに、接続がシステムルートに直接渡されると、アプリが到達不能な仮想アドレスへ接続しようとすることがあります。
mixed-port: 7890
allow-lan: false
mode: rule
dns:
enable: true
listen: 127.0.0.1:1053
enhanced-mode: fake-ip
fake-ip-range: 198.18.0.1/16
fake-ip-filter:
- 'localhost'
- '+.lan'
nameserver:
- system
rules:
- MATCH,DIRECT
この例では、ループバックアドレスで専用のDNSポートを開き、通常のクエリをシステムリゾルバーに渡します。テストクエリを手動でそのポートへ送るためのもので、OSのDNS設定は変更しません。使用時は、システムリゾルバーがクエリを同じリスナーへ再転送しないことを確認してください。別のツールが同じポートを使っている場合は、空いているポートに変更します。仮想アドレスの範囲が、ローカルの既存ルートや別のプロキシインスタンスの仮想ネットワークと競合していないかも確認してください。
例の既定のフィルター動作では、fake-ip-filter に列挙した名前は仮想アドレスの割り当て対象から除外されます。ローカルドメインをリストに追加することで解決できるのは、「実際の名前解決結果が必要」という問題であり、そのドメインのレコードが自動的に用意されるわけではありません。内部ドメインを組織のリゾルバーで解決する必要がある場合は、システムの名前解決で応答を得られるか、またはそのドメイン用に到達可能なリゾルバーを別途設定し、ルーティングでそのDNSサービスにアクセスできるか確認してください。
もう一つの拡張モードである redir-host は、通常、アプリに実アドレスを返します。ドメインルールが引き続き適用されるかは、ドメイン情報がプロキシリクエストに含まれるか、コアが実際の接続経路からその情報を取得できるかによります。モードを切り替えれば、ドメインの照合に関する問題がすべて解決するわけではありません。同じ宛先についてDNSの応答と接続ログの両方を確認してください。前者だけが変わっても、後者で意図したルールが適用されたとは限りません。
名前解決の失敗、キャッシュ、接続後の失敗を区別する
サーバーとポートを指定できるクエリツールがインストールされている場合は、次の2つのクエリを実行できます。1つ目は例のリスナーを明示して使い、2つ目はツール既定のシステム名前解決経路を使います。2つのアドレスが一致するかではなく、応答ステータスとアドレスの種類を記録してください。仮想アドレスモードでは、結果が異なるのは想定どおりの場合があります。リスナーにリクエストが届かない場合は、まず使用中のアドレスとポートを調べ、上流リゾルバーを変更するのはその後にしてください。
dig @127.0.0.1 -p 1053 example.com A
dig example.com A
応答があるのに接続できない場合は、接続がマッピングを保存したのと同じインスタンスに届いているか確認し、ドメインルール、プロキシグループ、出力ログを調べてください。設定を切り替えた後も、ブラウザーやOSにアドレスがキャッシュされていたり、既存の接続が再利用されたりすることがあります。新しい接続で再テストし、必要ならテストしたアプリに関係する状態だけをクリアしてください。DNS、通信の取り込み、ノードの切り替えを同時に変更せず、一度に変更する要素は1つにします。
デュアルスタック環境では、IPv4とIPv6を分けて確認してください。DNSの ipv6 オプションが制御するのは、コアDNSでのIPv6クエリの動作です。OSのIPv6スタックを無効にする設定ではなく、IPv6の接続経路の確認に代わるものでもありません。診断時はクエリの種類と実際の宛先アドレスを記録します。一方のアドレスファミリーで接続できても、もう一方で同じポリシーや経路が使われているとは限りません。
プロキシノードの項目とプロバイダー
プロトコルに沿って出力レコードを作成する
proxies はノードレコードのリストです。一般的なレコードには名前、プロトコルの種類、サーバー、ポートが含まれ、プロトコル固有の項目は実際のサービスに合わせて設定します。名前は参照と表示に使い、アドレスとポートは接続先を決めます。アドレスにはホスト名またはアドレス自体を指定してください。スキームやパスを含むサブスクリプションURLを入力する場所ではありません。サブスクリプションURLは設定を取得・生成するためのもので、ノードのアドレスは出力接続を確立するためのものです。読み込みの流れでの役割が異なります。
以下は、既存のローカルSOCKSサービスに接続するノードの例です。別のSOCKSサービスがローカルの 1080 で独立して待ち受け、クライアントからアクセスできることが前提です。この例を使うために、そのサービスを変更する必要はありません。コアの受け入れ側のポートは 7890 です。ノードのサーバーポートを同じコアの混合ポートに変更しないでください。出力が入力に折り返され、二重処理や接続失敗が発生することがあります。
mixed-port: 7890
allow-lan: false
mode: rule
proxies:
- name: Local-SOCKS
type: socks5
server: 127.0.0.1
port: 1080
udp: false
rules:
- DOMAIN-SUFFIX,example.com,Local-SOCKS
- MATCH,DIRECT
この例では、例示したドメインに一致する接続だけをノード経由にし、それ以外はDIRECTのままにします。利用できるSOCKSサービスがない場合は、まず最小構成で入口を検証してください。ノードの例で接続に失敗しても、YAMLの読み込み失敗とは限りません。クライアントの一覧にノードが表示されるのは、レコードが読み込まれたことを示すだけです。動作を検証するには、アドレスへの到達、プロトコルのハンドシェイク、出力経由での接続先からの応答をそれぞれ確認します。どの段階で失敗しても、画面上では単にタイムアウトと表示されることがあります。
プロトコルを切り替えるときは、type だけ変更して古い項目をすべて使い回さないでください。たとえばShadowsocksでは、パスワードと暗号化方式をサーバー側に合わせる必要があります。TLSを使うほかのプロトコルでは、サービス名、証明書検証、トランスポート方式などが必要な場合もあります。設定の構造が似ていても、ハンドシェイクが互換とは限りません。証明書エラーが出たら、まずサービス名、システム時刻、サーバー証明書を確認してください。検証を無効にすることを一般的な解決策にしないでください。
udp は、一部のノードでUDP転送を有効にするかどうかを指定します。UDP非対応のサービスに、その機能を自動で追加するものではありません。ノード経由でWebページを表示できても、確認できたのはそのときのWeb接続だけで、音声通話などのUDPアプリも動作するとは限りません。トラブル時は、受け入れ側が該当する通信を扱えるか、ポリシーで互換性のある出力が選ばれているか、サーバーが実際に転送できるかを確認してください。ページが開くかどうかだけでプロトコル層の確認を代用しないでください。
プロキシプロバイダーのパスと読み込み順
個別に管理しているノード群がある場合は、proxy-providers を使えます。メイン設定でリソースの場所を宣言し、プロキシグループから use でプロバイダー名を参照します。以下はローカルファイルを使う例です。コアの作業ディレクトリに、記載したファイルをあらかじめ作成してください。前述の独立したSOCKSサービスを引き続き使う例なので、実際に接続する前にサービスが起動していることを確認します。ファイルが見つからない場合は、相対パスまたは起動時の作業ディレクトリを修正してください。
mixed-port: 7890
allow-lan: false
mode: rule
proxy-providers:
local-source:
type: file
path: ./local-proxies.yaml
proxy-groups:
- name: PROXY
type: select
proxies:
- DIRECT
use:
- local-source
rules:
- DOMAIN-SUFFIX,example.com,PROXY
- MATCH,DIRECT
proxies:
- name: Local-SOCKS
type: socks5
server: 127.0.0.1
port: 1080
udp: false
プロキシグループを開き、プロバイダーのメンバーが表示されたことを確認してから、手動で選択してください。接続記録にグループ名が表示されているだけでは不十分です。グループの現在の選択先がDIRECTのままなら、ノードを検証できていません。HTTPプロバイダーに変更する場合は、取得した内容がコアで認識できるノードリソースであり、ログインページや別の完全な設定ファイルではないことを確認します。プロバイダーの作業パスと更新間隔は個別に管理し、複数のリソースで同じキャッシュファイルを共有しないようにしてください。
リソースを更新するときは、「ダウンロード成功」「解析成功」「メンバーが利用可能」を分けて記録してください。更新によってメンバーが削除されたり、同じ名前のレコードが新しいサーバー情報で置き換わったりすることがあります。手動で選択したメンバーが更新後に見つからない場合は、まずプロバイダーの新しいメンバー一覧を確認し、次にグループの現在の選択先を確認します。古いスクリーンショットだけと比較しないでください。設定の一部を共有する際は、サブスクリプションURL、認証情報、内部ホスト名を削除し、構造が分かる項目だけを残します。
プロキシグループの種類、メンバー、ヘルスチェック
プロキシグループで出力先を選ぶ
proxy-groups は出力先を選ぶポリシーを定義するもので、新しいプロキシプロトコルを定義するものではありません。グループ名はルールから参照する宛先になり、メンバーにはノード、内蔵出力、別のグループ、プロバイダーのノードを指定できます。グループを使えば、メンバーの交換や調整をしても、そのグループを参照するルールを変更せずに済みます。まずグループの役割を明確にしてから、メンバーの取得元を決めてください。用途が異なるグループに、1文字だけ違う名前を付けて増やすのは避けましょう。
| 種類 | 選択方法 | 確認ポイント |
|---|---|---|
select | ユーザーがメンバーを選択 | クライアントが前回の手動選択を復元していないか確認してください。 |
url-test | 接続テストの結果でメンバーを選択 | テスト先、間隔、切り替え許容値が選択結果に影響します。 |
fallback | リストの優先順に利用可能なメンバーを選択 | 主系・待機系の順序はメンバーリストで決まります。遅延の短い順ではありません。 |
load-balance | 設定したポリシーに基づいて接続を割り当てる | 接続ごとに異なる出力先になることがあります。出口を固定する必要があるか確認してください。 |
固定メンバーは proxies に記述します。ここに書くのは定義済みの名前であり、ノードレコード全体をグループ内に再度埋め込むわけではありません。プロバイダーは use に記述し、リソースのURLではなくプロバイダー名を指定します。ノード名を use に書いたり、プロバイダー名を proxies に書いたりするのは参照階層の誤りです。設定を移行するときは、まず短い固定メンバーのグループで参照を検証し、その後プロバイダーのメンバーを追加してください。
次の例では、前章の Local-SOCKS ノードを再利用します。元ファイルのルールリストをここに示すルールに置き換え、グループ定義をトップレベルに追加してください。手動で比較できるよう、DIRECTも選択肢として残しています。最後のルールをフォールバックにすることで、指定したドメインだけが手動グループに入ります。テスト時は2つのメンバーをそれぞれ選んで新しい接続を行い、ログの最終メンバーが選択に応じて変わるか確認してください。
proxy-groups:
- name: PROXY
type: select
proxies:
- Local-SOCKS
- DIRECT
rules:
- DOMAIN-SUFFIX,example.com,PROXY
- MATCH,DIRECT
グループのネストは、たとえば自動選択グループと固定ノードを1つの手動選択グループにまとめる場合に便利です。参照の向きを追跡できる構造にしてください。グループAがグループBを参照し、グループBがAを参照する構造や、自分自身の参照は避けます。循環参照が起きたら、「外側のグループから内側のグループへ」という関係を図にし、ルールの参照先からノードまたは内蔵出力までたどります。同じグループに再び行き当たったら、構造を見直してください。
接続テストの結果だけでは実際の用途を検証できない
前述の手動選択グループを主系・待機系グループに変更する場合は、以下のグループ定義を使えます。ルールから参照するグループ名はそのままです。interval の単位は秒です。例では接続テスト項目の記述方法を示すため、公開されているドキュメント用ドメインを使っています。実際には、利用が許可され、応答が安定しているテスト先を選び、候補の各出力から正常にアクセスできることを確認してください。測定するのは指定先へのリクエスト結果であり、インターネット全体の利用可否ではありません。
proxy-groups:
- name: PROXY
type: fallback
proxies:
- Local-SOCKS
- DIRECT
url: https://example.com/
interval: 300
ここでは動作を比較するため、DIRECTをフォールバックにしています。特定の業務で出口を固定する必要がある場合は、このグループにDIRECTを自動フォールバックとして含めないでください。候補がすべて利用できない場合の扱いは、業務要件に従います。利用可能な結果を増やすためだけに、役割の異なる出口を1つのグループに混在させるのも避けてください。グループが使えるかどうかは、接続可能なメンバーがあるかだけでなく、そのメンバーが目的のアクセス条件を満たすかにも左右されます。
url-test グループに切り替え許容値を設定すると、テスト時間のわずかな変動による頻繁な切り替えを抑えられます。テスト間隔を短くしすぎると、追加リクエストが増え、一時的な揺らぎを安定した差として判断しやすくなります。テストであるメンバーが遅かった場合は、まずその傾向が継続するかを見てから、実際の接続先でも問題を再現できるか確認してください。テストは成功するのにアプリが失敗する場合、間隔を短くするのではなく、ドメイン、プロトコル、実際に選ばれた出力先を比較します。
プロバイダー側で独自のヘルスチェックを管理することもできます。調査では、「リソースに含まれるメンバー」「各メンバーのテスト状態」「グループで現在選択されているメンバー」を分けて確認してください。ポリシーの変更は通常、新しい接続に適用されます。アプリが既存のセッションを維持していると、すぐには変化が見えないことがあります。クライアントが選択内容を記憶する設定なら、設定を再読み込みしても以前のメンバーが選ばれる場合があります。必要に応じてセッションを再確立し、その接続のログで確認してください。
ルールの構文、マッチ順、ルールセット
最初に一致するルールから確認する
ルールモードでは、コアはリスト順にルールを調べ、最初に一致した結果を使います。一般的な構文は「種類、条件、対象」で、一部の種類には追加オプションを指定できます。MATCH は条件を必要とせず、対象だけを指定します。広い範囲のルールを先に置くと、その後にある具体的なルールが適用されないことがあります。例外は汎用ルールより前に置き、リスト末尾のフォールバックが意図どおりであることを確認してください。
以下の例はリモートノードに依存せず、DIRECTとREJECTでいくつかの条件を見分けます。完全一致する名前はDIRECTにし、同じサフィックス範囲のほかの名前はREJECTにします。ループバックアドレス宛ての接続はアドレスルールに一致すればDIRECTになり、それ以外のリクエストはフォールバックに進みます。この例が変更するのは、そのコアに入ったリクエストだけです。OSのルーティングから直接送られる通信は、設定にREJECTルールを書いても遮断されません。
mode: rule
rules:
- DOMAIN,example.com,DIRECT
- DOMAIN-SUFFIX,example.com,REJECT
- IP-CIDR,127.0.0.0/8,DIRECT,no-resolve
- MATCH,DIRECT
DOMAIN は完全なドメイン名を照合します。DOMAIN-SUFFIX はそのドメインとサブドメインに使うもので、任意の文字列の末尾を照合するものではありません。1つのホスト名だけに適用したい場合は、サフィックスルールに広げないでください。同じ登録ドメイン配下の別サービスまで変わる可能性があります。DOMAIN-KEYWORD はキーワードで照合するため、対象範囲が広くなります。そのキーワードを含む別の名前も先に確認してから使ってください。
IP-CIDR はIPv4アドレス範囲に使い、IPv6には IP-CIDR6 を使います。宛先アドレスが必要なルールで、接続にドメイン名しかない場合は、コアが先にアドレスを解決することがあります。no-resolve はそのルールのためだけに追加の名前解決を行わないようにする設定で、リクエストがすでに持つ宛先アドレスを消すものではありません。グローバルなDNSを無効にする指示として使わないでください。名前解決の結果によってルールを適用する場合は、まずそのルールで解決が許可されているかを確認し、次に解決結果が指定したネットワーク範囲内かを確認します。
GEOIP と GEOSITE は、それぞれコアが読み込める地理的なIPアドレスデータとドメイン分類データに依存します。これらが表すのはデータ内の分類であり、接続位置や所属をリアルタイムで測定するものではありません。異なるデータファイルを使う環境では、ルールの記述が同じでも一致結果が異なることがあります。この違いを調べる際は、データの取得元とクライアントで有効な設定を記録してください。1つのサイトの挙動から分類データ全体を推測しないようにしましょう。
ルール条件と適用する処理を分ける
複数のマッチ条件を個別に管理したい場合は、rule-providers を使えます。メインファイルでは RULE-SET でルールセットと適用する処理を指定し、リソース側では条件だけを定義します。以下のローカル例ではドメインのリストを使い、指定したドメインとそのサブドメインをDIRECTにします。設定を読み込む前にファイルを作成してください。相対パスは、エディターを開いたディレクトリではなくコアの作業ディレクトリを基準に確認します。
mode: rule
rule-providers:
reference-domains:
type: file
behavior: domain
format: yaml
path: ./reference-domains.yaml
rules:
- RULE-SET,reference-domains,DIRECT
- MATCH,REJECT
payload:
- '+.example.com'
この例の最後のルールは、リストにない宛先をREJECTします。許可範囲を意図的にテストする設定に限って使い、日常用のルールとそのまま置き換えないでください。behavior: domain はドメイン形式の条件を受け取ります。ipcidr はアドレス範囲、classical はルールの種類とパラメーターで構成された条件に使います。DOMAIN-SUFFIX,example.com,DIRECT の行全体をドメインリストに書いたり、メイン設定側で処理を一括指定する条件に出力先名を記述したりしないでください。
接続ログで一致条件を確認する
宛先がフォールバックに進んだ場合は、まずクライアントの記録で宛先がドメイン名か数値アドレスか確認してください。アプリが独自に名前解決し、アドレスだけを渡していると、ドメイン条件に使える情報がないことがあります。これは単にルール順を変えても解決しません。次に、より前に広範囲のルールがないか確認し、最後にルールセットファイルが実際に読み込まれているか確認します。接続ログに意図したルールが記録されているなら、条件の調整はやめて、グループのメンバーと出力先を確認してください。
Webページでは、メイン文書、静的ファイル、別サービスへ同時に接続することがあり、接続ごとに個別のルールが適用されます。メイン文書が開いても、そのページのすべてのリソースが同じ出力先を使うとは限りません。リソースが1つ失敗しても、登録ドメイン全体のルール変更が必要とは限りません。まず失敗した接続を1つ選び、宛先、一致ルール、最終メンバーを記録してから例外を追加するか判断します。項目を用語から探す場合は、用語解説のルール分岐の分類を参照してください。
上書き、マージ、更新後の差分
まず、どの機能がマージするか確認する
上書きとは、クライアントが最終設定を生成する処理です。同名キーが2つあるだけでコアが自動的に行う一般的な処理ではありません。クライアントによって、マップ、リスト、空の値のマージ方法が異なるほか、画面上の上書き機能とスクリプト処理機能を個別に備えている場合もあります。変更前に、どの機能を使うか、それが1つの設定だけに適用されるのかすべての設定に適用されるのかを確認してください。ほかのツール向けの上書き専用キーを、コアの項目としてメインYAMLに移さないでください。
変更内容は、スカラー、マップ、順序に依存するリストに分けて考えるのがおすすめです。ポートやモードは通常、単一の値を置き換えます。DNSはマップなので、ブロック全体を上書きすると既存のリゾルバーやフィルターが失われることがあります。ルールは順序付きリストであり、末尾への追加、先頭への追加、全置換では結果が異なります。クライアントが「マップを深くマージ」すると説明していても、リストが追加されるとは限りません。確認すべきなのは、上書きファイルの行数ではなく実際の出力です。
| データ型 | 変更例 | 確認する結果 |
|---|---|---|
| スカラー | mixed-port を別の空きポートに変更 | 最終設定、実際の待ち受け、アプリの接続先が一致している。 |
| マップ | dns.enhanced-mode を変更 | 必要なリゾルバーとポリシーマップが残っている。 |
| 順序付きリスト | rules に例外を追加 | 例外が、適用範囲を包含する既存ルールより前にある。 |
| オブジェクトのリスト | proxy-groups にグループを追加 | 既存グループが残り、名前が重複せず、メンバー参照もすべて有効である。 |
以下では、変更前と変更後のファイル全体を示します。混合ポートを変更し、例のドメインがフォールバックより前にREJECTに一致するようにします。ここに示すのは手動でマージした結果であり、特定のクライアントのパッチ構文には依存しません。クライアントで同じ設定を生成できる場合でも、出力のルールが1つだけで、例外が先頭にあり、既存のモードと待ち受け範囲が変わっていないことを確認してください。
mixed-port: 7890
allow-lan: false
mode: rule
rules:
- MATCH,DIRECT
mixed-port: 7892
allow-lan: false
mode: rule
rules:
- DOMAIN-SUFFIX,example.com,REJECT
- MATCH,DIRECT
クライアントが新しいルールを既存リストの末尾にしか追加できない場合、前の例のルールは MATCH の後ろに入り、適用されません。先頭への追加に対応した機能を使うか、ルールリスト全体を整理して置き換えてください。全置換を選ぶ場合は、保守も必要です。サブスクリプションに追加された重要なルールが、カスタムリストに自動で反映されることはありません。更新後は、設定を起動できるか確認するだけでなく、上流のルールと改めて比較してください。
名前の変更、空の値、YAMLマージキー
プロキシグループを追加する前に、名前が重複しないことを確認してください。上書き機能が名前でオブジェクトをマージする場合、同名グループが既存グループを置き換えることがあります。単純に追加するだけなら、読み込めない重複グループができる可能性があります。ノード、グループ、プロバイダーを削除する前に、それらを参照している箇所をすべて検索してください。ルールの対象が既存のグループ名でも、同じ名前のグループを残して有効なメンバーを設定すれば、すべてのルールを変更する必要はありません。グループ自体を削除する場合は、参照先を移行してください。
値が空の項目も区別が必要です。キーの後を空欄にすると、通常は null として解析され、「元の値を維持する」という意味にはなりません。空のリストも自動的に「変更しない」ことを意味しません。上書き機能によって、値のクリア、置き換え、無効な入力のいずれとして扱うかが異なり、対応していなければ拒否される場合もあります。サブスクリプション内の項目を維持するなら、通常は上書きファイルからその項目を省略し、最終ファイルを確認してください。マージ時の意図が未確認のまま、空の値で表現しないでください。
YAMLのアンカーとエイリアスは、1つのYAMLドキュメントの解析範囲内でのみ使えます。独立した上書きファイルから、サブスクリプション原文内のアンカーを共有することはできません。一部のパーサーが対応する << マージキーは、主にマップをマージするためのもので、ルールリストを連結する機能ではありません。クライアントが読み込んで再出力する過程で、この記述が展開または変更される場合もあります。複数の環境で管理する場合は、まずシンプルな構造を保ち、最終的にエクスポートされた通常のYAMLを確認対象にしてください。
サブスクリプション更新を設定の再生成として扱う
サブスクリプションを更新する前に、最後に正常動作した最終設定とローカルの上書き設定を別々に保存してください。更新後は、トップレベルのポートとDNSマップ、ノード・グループ・ルールの参照関係の順に比較し、最後に同じ宛先で再テストします。更新で問題が起きた場合は、まず上書きを一時的に無効にして元の設定で検証し、その後ローカル変更を1つずつ有効にしてください。これにより、元データの変化、クライアントのマージ処理、実行時の選択変更を切り分けられます。
別のクライアントへ移行する場合も、意味を確認できるコアの項目だけを移してください。同じmihomoコアを使っていても、クライアント間で上書きの適用順や設定ディレクトリ、プロバイダーのパスまで同じとは限りません。古い設定をmihomoに移行する場合は、mihomoコアとオリジナルClashの項目の違いを参照し、移行先クライアントが実際に使うコアと設定の読み込み元を確認してください。
設定の検証、接続テスト、よくある問題
まずファイルを検証してから実行時の確認へ進む
調査を始める前に、既知の正常な設定を保存し、テストするファイルには別の名前を付けてください。GUIクライアントでは、現在選択されている設定と、上書き後に起動に使われる設定を確認します。コアを単独で使う場合は、設定ファイルのパスと作業ディレクトリを明示してください。同じシステムに複数の方法でインストールしている場合は、ターミナルから実行するバイナリと、GUIが実際に使うコアが同じかも確認します。異なるものを使っていれば、一方のテストに通り、もう一方が読み込みに失敗しても矛盾ではありません。
以下のコマンドは、ターミナルで mihomo を実行できる環境向けです。例では、カレントディレクトリに config.yaml があるものとします。作業ディレクトリから、設定が依存するデータやローカルリソースを読み込める必要があります。テストに通っても、今回の設定チェックが完了したことを示すだけです。すべての待ち受けポートがバインドできること、すべてのリゾルバーに到達できること、ノードとのプロトコルハンドシェイクが成功することまでは確認できません。
mihomo -t -d . -f ./config.yaml
エラーが出たら、段階ごとに範囲を絞ってください。構文エラーでは、エラー行と直前の項目にコロンの付け忘れ、インデントの崩れ、閉じていない引用符がないか確認します。参照エラーでは、グループ、ノード、プロバイダーの名前を確認します。リソースエラーでは、作業ディレクトリ、パス、ファイルの形式を確認してください。ファイル名、ルール、サブスクリプションURLを同時に変更しないでください。修正するたびに同じ検査を実行し、エラーの段階が先に進んだことを確認してから次の箇所を調べます。
入口、ルール判定、出口の順に再テストする
起動後、まずローカルの待ち受けを確認し、指定したプロキシ入口から簡単なリクエストを送信します。以下では、混合ポートが 127.0.0.1:7890 で待ち受け、現在のポリシーで接続先へのアクセスが許可されているものとします。前述のポート上書き例を使っている場合は、コマンドのポートも合わせて変更してください。REJECTルールをテストしているなら、拒否されるのは想定どおりです。リクエストに失敗しただけで入口が動作していないと判断しないでください。
curl --noproxy "" --proxy http://127.0.0.1:7890 \
--max-time 15 --head https://example.com/
上記の行継続記号は、一般的なUnix系のコマンドライン環境で使うものです。この形式に対応していないターミナルでは、コマンドを1行にまとめ、実際に使っているcurlを実行してください。--noproxy "" は今回のコマンドのプロキシ除外リストを空にし、入口の動作確認をしやすくします。接続先サーバーから応答があっても、すべてのアプリがシステムプロキシを参照するとは限りません。このテストで確認できるのは明示的に指定した経路だけで、画面上のアイコン表示には依存しません。
新しい接続記録がない場合は、プロキシプロトコル、アドレス、ポートが正しいか、アプリがプロキシを迂回していないか確認します。接続記録はあるのにルールが違う場合は、そのときのモード、アプリからコアに渡された宛先の形式、ルールの順序を確認してください。ルール判定と出力先の選択が正しい場合は、出力側のハンドシェイク、ノード名の解決、接続先サービスの応答を確認します。毎回、宛先、モード、一致したルール、最終メンバーを記録してください。「接続できない」とだけ記録するより、トラブルの調査に役立ちます。
すべてのノードがタイムアウトする場合と、1つだけタイムアウトする場合は分けて考えてください。すべて失敗する場合は、共通のサブスクリプション、入口、名前解決、ローカルネットワークを確認します。1つだけ異常なら、入口と宛先を固定したまま別のメンバーと比較できます。確認が終わるまでは、複数の設定を同時に何度も切り替えないでください。症状に応じて調査を続ける場合は、ノードがタイムアウトするときの調査手順をご覧ください。OSの接続設定をやり直す場合は、クイックスタートガイドに戻ってください。
よくある設定の問題
読み込みに成功したのに、クライアントが古いポートを使い続けるのはなぜですか?
まず、画面に表示されている新しいポートが最終設定に反映されているか確認し、再読み込みと実際のバインドが完了しているか調べてください。コアが新しいポートで待ち受けているのに、アプリが古いポートへリクエストを送る場合は、システムプロキシ、アプリ独自のプロキシ設定、ターミナルの環境変数を更新します。古いポートから応答がある場合は、別のインスタンスが動作していないか確認してください。以前のインスタンスのログを今回のテスト結果と取り違えないようにしましょう。
ルールは正しいグループに一致しているのに、結果が想定と異なるのはなぜですか?
グループ名が示すのは入口となるポリシーだけです。手動選択グループでは以前の選択が復元され、主系・待機系グループでは待機側が選ばれ、自動選択グループではテスト結果の変化に応じて別のメンバーに切り替わる場合があります。まず、その接続が最終的にどのメンバーを使ったか確認し、グループ内のメンバーが用途に合っているかを調べてください。選択を変更したら、新しい接続で再テストします。既存の接続を使い続けるアプリでは、すぐに変化が現れないことがあります。
YAMLを戻しても、システムのネットワーク設定が元に戻らないのはなぜですか?
システムプロキシ、仮想インターフェース、ルート、OSのDNS設定は、それぞれ対応するシステム機能またはクライアントが管理しています。設定ファイルを上書きしただけでは解除されません。クライアントの画面で、最初に有効にした接続機能を必要に応じてオフにし、システムにどの設定が残っているかを確認してから、新しいリクエストで検証してください。以前の設定に戻す前後で同じ問題が再現する場合は、システム側の状態とコアの設定の問題を切り分けてください。