Clash YAML設定ファイルリファレンス

1. YAMLの構造と設定の読み込み経路

ソースファイルと実行ファイルを区別する

Clashの設定は、ノードだけを記録する一覧ではありません。通常、トップレベルには待ち受けポート、プロキシモード、DNS、ノード、プロキシグループ、ルールが含まれます。クライアントにサブスクリプションを読み込むと、リモートの内容を保存し、ローカル設定を重ねたうえで、コアに渡す実行ファイルを生成する場合があります。そのため、エディターで見ているサブスクリプションの内容と、コアが実際に読み込んでいる内容は異なることがあります。トラブルシューティングでは、現在選択中の設定名を記録し、クライアントに実行設定を確認する機能があれば利用してください。有効になっていないファイルを編集して何度も再起動する事態を避けられます。

元のサブスクリプションには、サービス側で管理されるノードやグループを残し、個人ルールはローカル拡張に保存するのがおすすめです。両者を分けておけば、更新時に互いの設定を上書きするリスクを抑えられます。クライアントで拡張設定の適用範囲が明確でない場合は、動作を確認しやすいルールを一つ使ってテストし、現在のサブスクリプションだけに適用されるか確認してください。設定ファイル名だけで読み込み状態を判断してはいけません。画面上の選択項目、ログの読み込み結果、実際のリクエストに記録されたルールが一致するか確認しましょう。

インデント、型、参照名

YAMLではインデントで階層を表します。半角スペース2つに統一し、タブは使わないでください。コロンの後のスペースでキーと値を区切り、ハイフンでリスト項目を表します。同じリスト内の各オブジェクトは、項目の位置を揃えます。ポートは通常、整数で記述し、真偽値には小文字の値を使います。真偽値を引用符で囲むと文字列になり、項目によっては型エラーになります。ノード名とプロキシグループ名は参照用の識別子です。大文字・小文字、空白、記号も照合対象となり、似た名前に自動修正されることはありません。

mixed-port: 7890
allow-lan: false
mode: rule
log-level: info

proxies: []

proxy-groups:
  - name: 出口選択
    type: select
    proxies:
      - DIRECT

rules:
  - MATCH,出口選択

上の例は、構文解析と参照関係を確認するための、DIRECTのみを使う基本設定です。プロキシの出口は含まれていません。ノードが空のリストでも有効で、プロキシグループは組み込みのDIRECTを参照しています。ノードを追加する場合は、まずproxiesに定義し、その名前をプロキシグループに追加します。ルールからプロキシグループを参照することで、リクエストからルール、ルールからグループ、グループから出口へとつながります。複雑な項目を一度に大量にコピーするより、この流れを理解することが大切です。

引用符と重複キー

パスワード、特殊記号を含む名前、別の型として解釈される可能性のある文字列には、引用符を使うのがおすすめです。文字列にコロンと空白、コメント記号、改行が含まれる場合は、解析結果に注意してください。単一引用符の中で単一引用符を使う場合は、2つ続けて記述します。二重引用符ではエスケープを使えますが、バックスラッシュもルールに従って扱う必要があります。ウェブページの表示による曲がった引用符は、YAMLの引用符として使わないでください。コメントは説明用で、項目の意味を変えたり、必須パラメーターの不足を補ったりするものではありません。

同じ階層でdns、rules、proxy-groupsを重複して定義しないでください。パーサーによっては重複キーを拒否し、別の処理では後の値が残ることもあり、結果を予測できません。dnsを含む設定例を2つつなげても、DNS設定がマージされるわけではありません。親キーは一つだけ残し、必要な子項目をその下にまとめてください。リストも同様です。ルールを追加する場合は、同名のトップレベルキーを新たに作らず、既存のrulesリストに追加します。

コアのコマンドラインを利用できる場合は、以下のテストコマンドを使えます。実行ファイル名と設定ファイルのパスは、実際の環境に合わせてください。GUIクライアントに設定チェック機能がある場合は、そちらを優先して使いましょう。構文チェックに通っても、ファイルが受け入れられることを示すだけで、リモートノードへの接続やポリシーの妥当性は保証されません。起動後も待ち受けポート、ルールのマッチ状況、出口の選択を確認してください。ログの詳しい読み方は実行ログで原因を特定する方法をご覧ください。

mihomo -t -f config.yaml

2. ポート、プロキシモード、共通項目

待ち受けポートはリクエストの受け口

portはHTTPプロキシの待ち受けポート、socks-portはSOCKSの待ち受けポート、mixed-portは同じポートでHTTPとSOCKSのリクエストを受け付けます。これらはアプリからローカルのコアに接続する入口を示すもので、リモートノードのポートではありません。アプリにローカルアドレスとmixed-portを設定すると、リクエストがコアに届きます。リモートノードへの接続方法は、ノードの項目で決まります。初期設定では通常、混合ポートを一つ使えば十分です。個別の入口が必要な場合に限り、ほかのポートを追加してください。

ポートの競合は、複数のクライアントを同時に起動している場合、古いコアのプロセスが終了していない場合、または別のプログラムが同じアドレスを待ち受けている場合に起こりがちです。アドレス使用中のエラーが出たら、まず重複するプロセスを終了し、その後でポートを変更するか判断してください。ポートを変更した場合は、ブラウザーの手動プロキシ、ターミナルの環境変数、LAN内のデバイス設定も更新します。クライアントの起動に成功しても、すべてのアプリが新しいポートを使っているとは限りません。クライアントのスイッチ表示だけでなく、アプリ側のプロキシ設定から接続先を確認してください。

mixed-port: 7890
allow-lan: false
bind-address: "127.0.0.1"
mode: rule
log-level: info
ipv6: false

ルール、グローバル、DIRECTモード

mode: ruleはrulesの順序に従って出口を決め、mode: globalはグローバルポリシーにトラフィックを渡し、mode: directはDIRECTで接続します。ここでいうグローバルモードは、すでにコアに入ったトラフィックだけが対象で、すべてのアプリを自動的に制御するわけではありません。システムプロキシに従わないアプリは、グローバルモードにしても直接接続することがあります。モードが機能しているか確認するには、まずリクエストが接続ログに記録されていることを確認し、次に該当する出口を調べます。モード切り替えの画面操作はプロキシモードの説明をご覧ください。

グローバルモードは、ルールによる振り分けが問題の原因かどうかを一時的に判断するのに便利です。あらゆるネットワーク障害を直すためのボタンとして使うものではありません。ルールモードでは失敗し、グローバルモードでは成功する場合は、マッチしたルールと選択中のプロキシグループを優先して確認してください。どちらのモードでも失敗する場合は、ノードのパラメーター、ネットワークへの到達性、名前解決の経路を確認しましょう。DIRECTモードにしても、OSのプロキシ設定が自動的に解除されるわけではありません。アプリからローカルの待ち受けポートに接続した後、コアが直接接続する場合もあります。コアを終了する前に、システムプロキシが正常に戻ることを確認してください。

待ち受け範囲と管理インターフェース

allow-lanとbind-addressは合わせて確認してください。前者はLANからの利用を許可するかどうか、後者は待ち受けアドレスを指定します。ローカルだけで使う場合は、ループバックアドレスに制限できます。共有が本当に必要な場合に限り、使用するネットワークインターフェース、ファイアウォール、認証の要件に応じて開放してください。待ち受けアドレスをすべてのインターフェースに設定しても、外部のデバイスから必ず接続できるわけではありません。ルーティングやOSのセキュリティ設定にも左右されます。スマートフォンから接続できないからといって、サービスをそのままインターネットに公開しないでください。

プロキシの入口とexternal-controller管理インターフェースは別のものです。管理インターフェースは設定、ポリシー、接続状態の制御に使います。ブラウザーのプロキシポートとして指定してはいけません。クライアントがインターフェースのアドレスやアクセス情報を自動生成することも多く、手動で変更すると画面から操作できなくなる場合があります。一般的なデスクトップ利用では、設定例に合わせるためだけに管理インターフェースを追加で公開する必要はありません。リモート管理が必要な場合は、プロキシの待ち受けポートと同じ信頼範囲を流用せず、アクセス制限を別に設計してください。

log-levelは通常、日常利用ならinfoで十分です。トラブルの原因を調べる場合は一時的にdebugへ変更し、再現を確認したら元に戻してください。ログにはアクセス先のドメイン、ノード名、ローカルパスなどが含まれる場合があります。共有する前に個人情報を削除してください。共通項目が起動のたびに元へ戻る場合は、クライアントの設定画面に同じ項目がないか確認しましょう。設定画面で管理されている場合は、そこで変更してください。自動生成されるファイルを編集し続ける必要はありません。ブラウザーとターミナルで動作が異なる場合は、システムプロキシの経路別トラブルシューティングもご覧ください。

3. プロキシノードの項目と外部ノードの管理

ノードオブジェクトの共通項目

proxiesはノードオブジェクトのリストです。各ノードには通常、name、type、server、portがあります。nameはプロキシグループからの参照名、typeはプロトコルとそのほかの項目の解釈方法、serverは接続先のアドレス、portはリモートサービスのポートを指定します。認証項目、暗号化方式、トランスポート設定はプロトコルごとに異なります。typeだけを別のプロトコルに変更し、ほかのパラメーターをそのまま残して互換性を期待してはいけません。クライアントでオブジェクトを解析できても、接続先が対応するサービスを提供しているとは限りません。

サブスクリプションに含まれるノードのパラメーターは、特にTLS、トランスポート層、プロトコル固有の項目を含め、全体をそのまま保つのが基本です。共有リンクをクライアントがノードオブジェクトに変換できる場合もありますが、変換後の設定もコアの対応範囲に左右されます。クライアント名が同じ、あるいは画面が似ているからといって、同じコアを内蔵しているとは限りません。クライアントを選ぶ際は、まずダウンロードセンターを確認し、Clash Plusを優先して検討してください。既存設定を移行する前に、クライアント比較で対応プラットフォームと設定の互換性を確認しましょう。

proxies:
  - name: サンプル出口
    type: ss
    server: proxy.example.com
    port: 8388
    cipher: aes-128-gcm
    password: "your-password"
    udp: true

proxy-groups:
  - name: 出口選択
    type: select
    proxies:
      - サンプル出口
      - DIRECT

上の例では、Shadowsocksノードとプロキシグループの参照関係を示しています。ドメインとパスワードは説明用なので、実際のサービスの値に置き換えてください。cipherはサーバー側と一致させる必要があり、複雑であればよいというものではありません。udpは、そのノードで該当するUDP通信を許可する設定ですが、UDP非対応のサービスを対応させるものではありません。ノード名を変更する場合は、そのノードを直接参照しているすべてのプロキシグループも同時に変更してください。変更しないと、参照チェックに失敗することがあります。

TLSとトランスポート層は、気軽に切り替える最適化項目ではない

TLSを使うプロトコルでは、server、servername、証明書の検証がそれぞれ異なる役割を持ちます。serverは接続先を指定し、servernameは通常、TLSハンドシェイク時のSNIや証明書名の判定に使われます。両者は同じ場合も異なる場合もあるため、サービス提供元の指定に従って入力してください。接続に失敗しても、まず証明書検証をスキップする設定にするのは避けましょう。デバイスの時刻、サーバー名、証明書の有効性、ネットワーク経路を確認し、設定ミスを長期間見えなくしてしまわないようにしてください。

WebSocketのパス、リクエストヘッダー、そのほかのトランスポート設定も、リモート側と一致させる必要があります。サーバーアドレスが正しくても、パスやヘッダーが抜けているとハンドシェイクに失敗することがあります。下位層から順に確認してください。ドメインを名前解決できるか、接続先ポートに到達できるか、TLSが成功するか、プロトコル認証を通過するか、最後にルールと対象サイトを確認します。ログに認証失敗と明記されているなら、DNSやプロキシグループの順序を何度も変更せず、ノードのパラメーターとアカウントの状態を確認しましょう。

proxy-providersで外部ノードを管理する

proxy-providersを使うと、ノードの一覧をメインファイルから分離できます。ノードを定期更新しながら、ルールやプロキシグループを安定させたい場合に便利です。プロバイダーの内容はコアが対応するノード一覧形式である必要があり、任意のウェブページや完全なクライアント用サブスクリプションと同じとは限りません。メイン設定のプロキシグループではuseを使ってプロバイダー名を参照します。プロバイダー名を通常のノードとしてproxiesに追加してはいけません。2種類のリストは参照方法が異なるため、混在させないでください。

proxy-providers:
  ローカルノード:
    type: file
    path: ./providers/local.yaml
    health-check:
      enable: false

proxy-groups:
  - name: 出口選択
    type: select
    use:
      - ローカルノード
    proxies:
      - DIRECT

ローカルファイルは次のような構造にできます。相対パスがどこを基準にするかは、実際の設定ディレクトリとクライアントの起動方法によって異なります。デスクトップのショートカットがあるフォルダーを基準にするとは限りません。まずファイルが実際に読み込まれていることを確認し、その後でノードが表示されるか調べてください。リモートプロバイダーでは、更新間隔、キャッシュ、リクエストの出口も関係します。更新に失敗した場合は、ダウンロードリクエストと古いキャッシュを個別に確認し、すぐに設定全体を削除しないでください。

proxies:
  - name: サンプル出口
    type: ss
    server: proxy.example.com
    port: 8388
    cipher: aes-128-gcm
    password: "your-password"

サブスクリプションURLにはアカウントの認証情報が含まれる場合があるため、認証情報として慎重に扱ってください。設定を共有するときは、パスワードだけでなく、外部プロバイダーのアドレスやリクエストヘッダーも確認します。サービス側の更新でノード名が変わると、手書きでノードを指定した設定が機能しなくなることがあります。プロバイダー経由のプロキシグループなら、ノード一覧の変更に追従しやすくなります。ノード選びではテスト結果だけでなく、用途、地域、通信ルールも考慮してください。詳しくはノードの選び方をご覧ください。

4. プロキシグループの種類と参照関係

プロキシグループは出口を決めるレイヤー

プロキシグループを使うと、ルールが参照する名前と実際のノードを分けられます。ルールでは変更の少ないグループ名を指定し、グループ内でノードや別のグループを選びます。こうすれば、通常はノードを入れ替えてもすべてのルールを書き直す必要がありません。グループ名とノード名は一意でわかりやすくし、同じ名前による混乱を避けましょう。設計時には、リクエストが一方向に流れる経路を考えます。ルールから用途別のグループ、選択用グループへ進み、最終的にノードかDIRECTへ到達する形です。経路は必ず終点を持たせ、グループ自身へ戻る循環参照を作らないでください。

selectは手動選択、url-testはテスト結果に基づく自動選択、fallbackは順番に利用可能な候補を探す方式、load-balanceは設定した方式で接続を振り分けます。それぞれ用途が異なり、性能の優劣を示す4段階ではありません。出口を固定したいログイン用途では、自動切り替えが頻繁に起きると再認証が必要になることがあります。一般的なブラウジングでは、自動選択によって手動管理の手間を減らせる場合があります。すべてのノードを同じ種類の自動グループに入れるのではなく、用途に合わせて種類を選んでください。

proxy-groups:
  - name: 出口選択
    type: select
    proxies:
      - 自動選択
      - DIRECT

  - name: 自動選択
    type: url-test
    use:
      - ローカルノード
    url: https://www.gstatic.com/generate_204
    interval: 300
    tolerance: 50

rules:
  - MATCH,出口選択

この設定例は、前章のローカルノードプロバイダーを使用します。urlは実際にテストする接続先、intervalはテスト間隔（秒）、toleranceは自動切り替えに使う遅延の許容範囲（ミリ秒）です。テスト先は用途を適切に反映し、継続的にアクセスできるものを選んでください。例に記載されたアドレスは外部ページのリソースではなく、このページを表示しているブラウザーが自動的に読み込むことはありません。テストリクエストが成功しても、そのテスト経路が使えることを示すだけです。すべてのサイト、動画サービス、UDPアプリの正常動作は保証しません。

自動選択と障害時の切り替え範囲

url-testは通常、テスト条件で良好な候補を優先し、fallbackは候補の順序と利用可能性を重視します。通常は固定した出口を使い、障害時に予備へ切り替えたい場合は、テスト時間の短さを追い続ける方式よりfallbackが適しています。テスト失敗の原因は、テスト先へのアクセス制限、一時的な名前解決の異常、ネットワークの揺らぎかもしれません。すぐにノード全体が使えなくなったと判断せず、実際の用途で確認してから、テスト先の変更や観察時間の延長を検討してください。

load-balanceを使っても、複数の回線を1本のダウンロード接続にまとめることはできず、すべての接続が同じグローバルIPを使う保証もありません。振り分け方式によって、対象や接続の扱いが異なります。使う前に、出口が変わっても問題ないか確認してください。アカウントの不正利用検知、決済、長時間のセッションが関わるアプリでは、固定した出口が適していることが多いでしょう。負荷分散を有効にしても、個々の接続速度は実際に経由するノード、接続先のサービス、ローカルネットワークに左右されます。グループ内のノード数をそのまま合計帯域として扱うことはできません。

名前、循環参照、選択状態の保持

プロキシグループから別のグループを参照できますが、循環参照は作れません。たとえば用途別グループが出口グループを参照し、出口グループが用途別グループを参照すると、実際の出口に到達できません。階層を増やす前に、その層に独立した役割があるか確認してください。入れ子が多すぎると、画面上は正常に見えても最終的にどのノードを使うのか把握しにくくなります。トラブルシューティングでは、現在選択されている項目を順番にたどり、実際のノード、DIRECT、REJECTのいずれかまで確認してから、接続ログと照合します。

クライアントによっては手動選択を記憶し、設定を再読み込みしても、以前に選んだグループ内の項目を復元します。そのため、YAMLの候補の並び順を変えても、現在の出口が変わらないことがあります。新しい設定が読み込まれたのに出口が変わらない場合は、ノードの順序をさらに入れ替えるのではなく、プロキシグループの現在の選択項目と選択状態の保持動作を確認してください。リセットが必要な場合は、まずクライアントの選択操作を使います。設定ディレクトリ全体を削除すると、サブスクリプションやローカルルールまで失うおそれがあります。

5. DNS設定とFake-IPの仕組み

まず、アプリがどこに名前解決を依頼しているか確認する

DNS設定はコアによるドメインの名前解決方法を決めますが、アプリが必ずコアのDNSを使うとは限りません。OSのリゾルバー、ブラウザーのセキュアDNS、アプリ内蔵の名前解決、TUNによるリダイレクトが同時に使われることもあります。ClashのDNS漏れが疑われる場合は、設定を変える前に、どの種類のリクエストが想定した入口を通っていないか確認してください。nameserverを暗号化されたアドレスに変えただけでは、デバイス上のすべての名前解決がプロキシ経由になったとは言えません。暗号化は通信内容の読み取りにくさを高めるもので、プロキシの出口やリクエストの取り込みとは別の問題です。

dns.enableはコアのDNS機能を有効にし、listenは待ち受けアドレス、nameserverは通常の上流DNSを指定します。default-nameserverは、上流DNSのアドレスに含まれるドメインを解決するために使われ、起動時の基本的な名前解決を助けます。proxy-server-nameserverでは、プロキシノードのサーバードメインに別の名前解決経路を指定できます。接続先サイトの名前解決とプロキシサーバーの名前解決は区別してください。後者に、まだ接続できないプロキシを必要とする設定にすると、起動時に循環してノードのドメインを解決できなくなることがあります。

dns:
  enable: true
  listen: "127.0.0.1:1053"
  ipv6: false
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  fake-ip-filter:
    - "*.lan"
    - "*.local"
  default-nameserver:
    - 223.5.5.5
  nameserver:
    - https://dns.alidns.com/dns-query
  proxy-server-nameserver:
    - 223.5.5.5

この設定例は項目の階層を示すもので、あらゆるネットワークに適した設定ではありません。上流DNSのアドレスに現在のネットワークから到達できるか確認し、ネットワークを変えた後は応答時間と結果を再テストしてください。ループバックアドレスで待ち受けるポートが、自動的にシステムDNSになるわけではありません。クライアント、TUN、OSの設定からクエリを送る必要があります。PCでシステムHTTPプロキシだけを有効にしている場合、SOCKSを使うアプリがローカルで名前解決すると、DNSの経路が異なることがあります。

Fake-IPと実際のアドレスの対応付け

Fake-IPはアプリに対応付け用の合成アドレスを返し、コアがそのアドレスと元のドメインの対応関係を記録します。その後の接続が再びコアに入ると、対応関係からドメインを復元してルールの判定に使えます。合成アドレスをインターネット上の宛先として直接扱うものではありません。Fake-IPはパブリックDNSが返す別の実アドレスではなく、ルーターからインターネットへそのまま転送するものでもありません。正しく設定するには、名前解決と接続の両方が、同じ対応関係を認識できる処理経路を通る必要があります。

LAN内の機器検出、デバイス管理、実アドレスが必要なプログラムは、合成アドレスに対応できない場合があります。その場合は実際の要件に応じてfake-ip-filterで対象を除外できます。除外すると通常の名前解決結果が返されますが、そのドメインにDIRECTルールが追加されるわけではありません。最終的な出口はrulesで決まります。一つのアプリの互換性問題を解決するためにすべてのドメインを除外すると、Fake-IPによるドメインの対応付けが失われます。まず対象のドメインサフィックスを絞り、古いキャッシュを削除してから、影響範囲を確認してください。

ドメインごとの上流DNSと名前解決経路

nameserver-policyを使うと、ドメインごとに上流DNSを指定できます。社内ドメイン、LAN内のサフィックス、パブリックドメインで異なるDNSを使いたい場合に適しています。以下では社内DNSの例示用アドレスを使っています。実際のネットワークでそのアドレスがDNSサーバーとして使える場合に限り、設定してください。ポリシーがマッチしても、上流DNSへの経路が到達可能でなければタイムアウトします。オフィスネットワーク内だけで使える上流DNSを、すべてのネットワーク環境にそのまま適用しないでください。

dns:
  nameserver-policy:
    "+.corp.example.com":
      - 192.168.1.1

respect-rulesなどの設定は、DNSの上流接続がルーティングルールに従うかどうかに影響します。有効にする前に関連する依存関係を理解し、ノードサーバーのドメインを個別に名前解決できるよう設定してください。すべてのDNSリクエストをまずプロキシに通し、プロキシサーバーのドメインも同じDNSに頼ると、初期化時に行き詰まることがあります。ドメインごとのDNS振り分けとプロキシのトラフィック振り分けは別々のルールです。指定したDNSが使われたからといって、その後の接続も同じ出口を通るとは限りません。

DNSを変更したら、古い接続を閉じてクライアントとOSのキャッシュを消去してください。必要に応じて、内部キャッシュを持つアプリも再起動してから、一連のリクエストをテストします。アプリの名前解決方法、返されたアドレスの種類、マッチした接続ルールを記録してください。IPv6も個別に確認が必要です。コア関連のIPv6設定を無効にしても、OSのほかの経路からIPv6リクエストが送られなくなるとは限りません。問題が続く場合はよくある質問のネットワークトラブルシューティングに沿って原因を絞り、一度に複数のセキュリティ設定や名前解決設定を無効にしないでください。

6. ルール構文、ルールセット、マッチ順序

ルールは上から順に評価され、マッチした時点で終了

rulesは順序に意味のあるリストで、精度に応じて自動で並べ替えられる集合ではありません。先にマッチしたルールが出口を決め、そのリクエストは後続のルールでは処理されません。そのため、具体的なドメインは範囲の広い地域ルールより上に置き、最後にMATCHでそれ以外を処理します。前のルールがすでにすべてのリクエストを対象にしている場合、その下に追加した例外は機能しません。サイトの出口が意図と異なる場合は、接続の詳細から実際にマッチした項目を確認し、その位置より前のルールを調べてください。期待するルールの行だけを検索しても原因は特定できません。

一般的なルールは、種類、マッチ条件、ポリシーの順で記述します。MATCHにはポリシーだけを指定します。ポリシーにはノード名、グループ名、組み込みアクションを指定できますが、存在していて利用可能でなければなりません。業務用ルールでは、頻繁に変わるノード名を直接指定せず、変更の少ないグループ名を参照するのがおすすめです。DOMAINは完全一致のドメイン、DOMAIN-SUFFIXはサフィックスとそのサブドメイン、DOMAIN-KEYWORDはキーワードでマッチします。キーワードは対象範囲が広いため、境界を明確にしたいサフィックス一致の代わりには使わないでください。

rules:
  - DOMAIN,login.example.com,出口選択
  - DOMAIN-SUFFIX,example.org,DIRECT
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - GEOIP,CN,DIRECT
  - MATCH,出口選択

上の例では、出口選択という名前のプロキシグループを使っています。1行目は指定したログイン用ドメイン、2行目は例として示したサフィックス、3行目は指定したネットワーク内の宛先アドレスへの接続を処理します。GEOIPはローカルの地理データを使って宛先アドレスの地域を判定するもので、アクセスした人の所在地を判定するわけではありません。最後の行で、それまでにマッチしなかったリクエストを処理します。実際の設定では、利用しているネットワークのほかのプライベートアドレス範囲も含めてください。例にある単一のネットワークだけで、すべてのLAN範囲を網羅できるわけではありません。

名前解決のタイミングとno-resolve

ドメインルールを使うには、コアがドメイン情報を取得できる必要があります。アプリからアドレスだけが渡され、対応するマッピングや別のドメイン識別手段がなければ、ドメインルールにマッチしないことがあります。ドメインを対象とするIPルールでは、処理時に名前解決が発生する場合があります。no-resolveは、そのルールのためだけにドメインを積極的に名前解決しないという意味です。リクエストでDNSクエリが一切発生しなくなるわけではありません。宛先アドレスがすでに得られていればアドレスで判定できます。利用可能なアドレスがなければ、後続のルールが引き続き評価されます。

ルールのREJECTは拒否アクション、DIRECTは直接接続のアクションで、どちらもノードの種類ではありません。正確なドメインに対するREJECTルールを一時的に設定すると、ルールが読み込まれているか確認できます。テスト後は想定する設定に戻してください。範囲の広いキーワード拒否を診断に使うと、ログイン、更新、リソース配信などに必要なドメインまで誤って拒否するおそれがあります。1つのウェブページから複数の接続が発生し、メインサイト、静的リソース、認証サービスで異なるポリシーが適用されることもあります。ページタイトルだけを見て、すべてのリクエストを判断してはいけません。

ルールセットで管理対象を分ける

rule-providersは外部ルールセットに使います。ノード集合を扱うproxy-providersとは別の機能です。ルールセットでは適切なbehaviorを選びます。主な種類はdomain、ipcidr、classicalです。ファイルの内容はbehaviorの種類と一致している必要があります。domainは主にドメインパターン、ipcidrは主にネットワーク範囲、classicalはルールの種類とマッチ条件を扱います。ルールセットを参照するときは、メイン設定でポリシーを指定します。同じルールセットを使いながら、設定ごとに異なる出口を適用できます。

rule-providers:
  業務用ドメイン:
    type: file
    behavior: classical
    format: yaml
    path: ./rules/business.yaml

rules:
  - RULE-SET,業務用ドメイン,出口選択
  - MATCH,DIRECT

対応するローカルルールセットは次のとおりです。payloadの各行に出口ポリシーを追加していないのは、メイン設定のRULE-SET参照時にポリシーを指定するためです。ファイルパス、文字コード、リストのインデント、behaviorのいずれかが合わないと、読み込みに失敗することがあります。リモートルールセットでは、ダウンロードの成否、キャッシュの更新、配信内容と宣言形式の一致も確認してください。URLの拡張子がYAMLでも、エラーページがルールセットになるわけではありません。

payload:
  - DOMAIN,login.example.com
  - DOMAIN-SUFFIX,example.org

ルールを管理するときは、まず実際に確認できる問題を解決し、それから対象範囲を広げてください。対象ドメイン、現在マッチしている項目、期待するポリシー、変更理由を記録すると、例外が積み重なって互いに上書きし合うのを防げます。地理データ、ルールセットのキャッシュ、メイン設定にはそれぞれ異なる更新周期があります。一つを変更しても、ほかが同時に更新されるわけではありません。ルールファイルが正しくても動作が変わらない場合は、実行設定に上書きがないか確認し、既存の接続が以前の出口を使い続けていないか調べてください。ルールを更新しても、既存の接続が自動的に移行するとは限りません。

7. TUN、システムプロキシ、DNSの取り込み範囲

振り分けを考える前に、入口を選ぶ

システムプロキシは、OSの設定に従うアプリにローカルのプロキシ入口へリクエストを送るよう指定します。TUNは仮想ネットワークインターフェースとルーティングを使い、より多くのネットワーク通信を処理します。どちらも入口側の機能で、ノードの認証パラメーターは変更せず、ルールの誤りを自動的に直すものでもありません。コマンドラインツール、ゲーム、独自のネットワークスタックを持つプログラムは、システムプロキシを参照しない場合があります。クライアントに接続記録がない場合は、リモートノードを何度も変えるのではなく、まず入口がそのアプリを対象にしているか確認し、必要に応じてTUNを検討してください。

TUNの実際の機能は、OS、権限、クライアントへの統合方法、コアの実装によって異なります。デスクトップクライアントではサービスコンポーネントを使って権限を取得し、モバイルでは通常、OSのVPN許可を使ってネットワーク入口を作ります。権限がない、仮想インターフェースの作成に失敗する、ルートを設定できないといった問題は、ノード接続より前に起こることがあります。Clash Plus、Clash Verge Rev、FlClashなどでは操作画面が異なります。あるクライアントのサービスインストール手順を、別のクライアントにそのまま当てはめないでください。

tun:
  enable: true
  stack: mixed
  auto-route: true
  auto-detect-interface: true
  dns-hijack:
    - any:53

この設定例は一般的な項目の関係を示すもので、すべてのプラットフォームで変更なしに動作することを保証するものではありません。enableは機能を有効にし、stackはプロトコルスタックの実装、auto-routeはルート設定、auto-detect-interfaceは出口のネットワークインターフェースの自動検出を試みます。複数のネットワークインターフェース、仮想ネットワーク、企業VPN、コンテナブリッジがある場合、自動検出が想定どおりにならないことがあります。プロトコルスタックを変更する前に、ログに明確なエラーがあるか確認してください。理由を確認せずにstackを切り替えることを、定番の最適化手順にしないでください。

DNSのリダイレクトは、すべての名前解決を取り込む設定ではない

dns-hijackは、条件に一致するDNSトラフィックをコアの名前解決処理に送ります。例は主に、従来型DNSの該当ポートを通る通信を対象にしています。アプリが暗号化プロトコルでDNSサービスに直接接続する場合、通信の形式が異なるため、この設定だけで通常のDNSクエリに切り替わるわけではありません。ブラウザーのセキュアDNS、アプリ独自の名前解決、システムの名前解決は個別に確認してください。アプリに共通の名前解決ポリシーを適用したい場合は、まずアプリ側の設定を調整し、リクエストが最終的にどの経路を通るか検証しましょう。

Fake-IPとTUNを組み合わせる場合、合成アドレスへの接続も同じコアに入るようにしてください。アプリが合成アドレスをキャッシュした後でTUNを無効にしたり、別の設定に切り替えたりすると、古いアドレスに対応するマッピングが失われ、一部のサイトに突然アクセスできなくなることがあります。その場合は、上流DNSをすぐに変更するのではなく、関連するキャッシュを消去して接続し直してください。クライアントの再起動、設定の復元、アプリの再起動も順序を記録しましょう。そうしないと、どの操作で復旧したのか判断しにくくなります。

ルートの競合とLANアクセス

企業VPN、ほかのプロキシクライアント、仮想マシンのネットワーク、セキュリティソフトは、ルートを変更する場合があります。複数のプログラムが同時にデフォルトルートを制御しようとすると、通信が行き来する、出口を誤る、ローカルサービスに接続できないといった問題が起こりえます。トラブルシューティングでは、一つのネットワーク制御方法だけを残して、ほかの制御入口を一時的に無効にしてから再現してください。ほかのツールを永久にアンインストールする必要はありません。単独で正常に動作することを確認した後、共存できるか調べ、直接接続が必要なネットワーク範囲を除外または振り分けます。

LANプリンター、ネットワークストレージ、開発用サービスに接続できない場合は、まず名前解決を確認し、次に宛先アドレスとルートを調べてください。ドメインにDIRECTルールを設定しても、OSのルーティング層が別のインターフェースに通信を送っている問題は解決しないことがあります。逆に、ルートが到達可能でもドメインを正しく解決できるとは限りません。名前と既知のアドレスの両方を使ってテストし、原因が名前解決か接続かを切り分けてから、最小限の範囲で調整します。LANサービス一つのために、すべての通信をネットワーク制御の対象外にしないでください。

サーバーをリモート管理する場合は、デスクトップ向けTUN設定をそのまま使ってすべてのルートを制御しないでください。まずコンソールなど復旧可能な接続手段を用意し、管理接続に影響しないことを確認してから、一項目ずつ有効にします。一般ユーザーはGUIクライアントのダウンロードページから、プラットフォームに合うものを選んでください。独立したコアは、サービス、権限、ネットワークルールを自分で管理できる環境に適しています。初回インストール時の権限に関する問題は、プラットフォーム別の初期設定も参考にしてください。

8. サブスクリプションの上書き、マージ、変更の検証

まず設定の各レイヤーを誰が管理しているか確認する

設定のソースは通常、リモートサブスクリプション、ローカル拡張、クライアント全体の設定、最終的な実行ファイルに分けられます。リモートサブスクリプションはサービス側で公開された内容、ローカル拡張は個人ルール、クライアント設定は待ち受け、権限、ネットワーク入口を管理し、実行ファイルはこれらを処理した結果です。クライアントによって処理順序や適用範囲は異なるため、特定の上書き構文をYAMLの標準と考えてはいけません。クライアントを移行する際は、拡張ファイルだけでなく、設定の意図と実際の項目を移してください。

サブスクリプションの元ファイルを直接編集すると、次回の更新で変更が置き換えられることがあります。実行ファイルを直接編集した場合も、再読み込みや設定の切り替えで再生成される可能性があります。長く使うカスタム設定は、クライアントが正式にサポートする拡張機能に保存し、別の場所にバックアップしておくのが安全です。クライアントがローカル設定ファイル全体しかサポートしない場合は、更新の手順を自分で管理する必要があります。一度変更が反映されたからといって、その場所に永続保存されるとは限りません。少なくとも一度、設定の再読み込みとサブスクリプションの更新を試してください。

オブジェクトのマージとリストのマージは別の処理

オブジェクトの項目はキーごとに再帰マージされる場合も、まとまりごと置き換えられる場合もあります。リストは先頭または末尾への追加、置き換え、専用の処理が行われることがあります。たとえばrulesの末尾に追加した例外がMATCHより後ろにあると、設定に記述されていてもマッチしません。リスト全体の置き換えでは、サブスクリプションの既存ルールが削除されることがあります。nameserverの場合、上流DNSの追加は古いサーバーの置き換えではなく、並行して問い合わせる範囲を広げることがあります。拡張機能を使う前に、オブジェクトとリストそれぞれの処理方法をクライアントの説明で確認してください。

# 目的は例外ルールを既存のルールより前に置くことです。
# この断片を、すべてのクライアントで使える上書き構文としてそのまま使わないでください。
rules:
  - DOMAIN,dev.example.com,DIRECT
  - DOMAIN-SUFFIX,example.org,出口選択
  - MATCH,出口選択

上の例は、最終的に期待するルールの順序を示しています。実際の設定では、使用中のクライアントが対応する前置ルール、拡張設定、スクリプト機能を使ってください。例をサブスクリプションの末尾にそのまま貼り付けてはいけません。最終確認では、実行ファイルにトップレベルのrulesキーが一つだけあり、例外がフォールバックより前にあり、参照先のプロキシグループが残っていることを確認します。また、拡張設定の適用対象を確認し、個人用の開発ルールがほかのサブスクリプションやデバイスに意図せず適用されないようにしてください。

サブスクリプションの更新と手動選択を個別に検証する

サブスクリプションの更新に成功しても、ある更新処理が完了したことを示すだけで、現在の実行設定が再生成されて有効になったとは限りません。クライアントによっては、ダウンロード、解析、保存、再読み込みが別々の処理です。どれか一つに失敗すると、古い内容が使われ続けることがあります。更新時刻に対応するログ、ノード一覧の変化、現在選択されている設定を確認し、その後でコアの再読み込み結果を調べてください。更新に失敗した場合は、サブスクリプションに関するよくある質問を参考に、ネットワーク障害、内容の形式エラー、認証の問題を切り分けます。

バックアップを復元するときは、クライアントが保存している選択状態にも注意してください。ファイルを元に戻しても、プロキシグループが以前の手動選択を引き継いだり、DNSキャッシュや既存の接続が残ったりすることがあります。再現テストではモード、プロキシグループの出口、リクエスト先、アプリの入口を固定します。必要なら古い接続を閉じてから新しいリクエストを送ってください。一度に変更する条件は一つだけにし、結果を記録しましょう。設定の復元で本当に解決したのか、たまたま接続先サービスが復旧したのかを判断できます。

4つのレイヤーで変更を検証する

第1レイヤーでは、インデント、引用符、真偽値、重複キーを確認し、構文と型を検証します。第2レイヤーでは参照関係を確認します。ルールが参照するグループ、グループ内のノード、プロバイダーがすべて存在し、循環参照がないことを確かめてください。第3レイヤーでは実行状態を確認します。コアが新しい設定を読み込み、ポートが正常に待ち受け、DNSとTUNの初期化エラーがないことを確認します。最後の第4レイヤーで、対象アプリから明確なアドレスにアクセスし、マッチしたルールと出口を検証します。前のレイヤーを通過する前に次へ進み、手当たり次第に設定を変更しないでください。

バックアップには、少なくともローカルルール、プロキシグループの構成、クライアント関連の拡張設定を含めてください。ノード一覧だけのエクスポートでは不十分です。機密性の高いノードパラメーターはアクセスを制限した場所に保管し、他人に共有するときは説明用の値に置き換えます。古いファイルを消す前に、どれがソースファイル、キャッシュ、クライアントの生成物か確認してください。キャッシュフォルダーを不用意に削除するとオフライン時に起動できなくなる場合があり、ソースファイルを削除すると未同期の個人設定を失うおそれがあります。

最後に、次の3点を説明できる状態にしてください。アプリのリクエストがどの入口から入り、どのルールが出口を決め、そのルールをどの設定レイヤーが管理しているかです。説明できない場合は、上書き設定をさらに積み重ねるより、最小限の基本設定に戻って機能を一つずつ追加するほうが原因を特定しやすくなります。接続をすぐに設定したい場合はクイックスタートをご覧ください。用語は用語集、具体的なエラーの分析は実行ログの解説をご確認ください。このリファレンスに載っている機能を、一度にすべて有効にする必要はありません。