CONFIG FILE REFERENCE

Clash設定項目

YAMLの依存関係に沿って、ポート、DNS、プロキシノード、プロキシグループ、ルール、オーバーライドを確認できます。例はそのまま検証しやすい構造ですが、実際のサーバーパラメータは利用中のサブスクリプションサービスが提供する設定を優先してください。

YAMLの読み込み順序 共通項目とDNS プロキシとプロキシグループ ルールとオーバーライド

SECTION SELECTOR

目次

CHAPTER 01 / INPUT

YAML構造の概要と読み込み関係

Clashの設定ファイルはYAMLドキュメントです。行ごとに実行されるスクリプトではなく、解析後にコアへ渡されるキーと値、リスト、オブジェクトの集合です。トップレベル項目は待ち受けポート、動作モード、DNSの挙動、コントロールインターフェースを決めます。プロキシノードは proxies に記述するか、proxy-providers から読み込みます。プロキシグループはノード名や他のプロキシグループ名を参照し、ルールリストがドメイン、IP、プロセス、ネットワーク種別を指定したプロキシグループへ振り分けます。設定を読むときは、まずオブジェクトが存在するか、次に参照名が完全に一致するか、最後にルールの順序を確認してください。1つのルールだけを見ると、参照先のプロキシグループ自体が読み込まれていないことを見落としやすくなります。

YAMLではインデントで階層を表します。半角スペース2つに統一し、タブは使用しないことを推奨します。リスト項目は先頭のハイフンで表し、ハイフンの後にはスペースを1つ入れます。コロンはキーと値の区切りに使い、通常はコロンの後にもスペースを入れます。コロン、シャープ記号、角括弧、特殊な真偽値表記を含む名前は、引用符で囲むと安全です。コメントは # から始まり、説明のみに使われ、コアには渡されません。インデントが正しくても項目の階層が間違っていると、パーサーが想定位置で読み取れない場合があります。そのため「ファイルを開ける」ことは「項目が有効になった」ことを意味しません。

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

dns:
  enable: true
  listen: 0.0.0.0:1053
  enhanced-mode: fake-ip
  nameserver:
    - https://1.1.1.1/dns-query

proxies:
  - name: "サンプルノード"
    type: ss
    server: 192.0.2.10
    port: 443
    cipher: aes-128-gcm
    password: "your-password"

proxy-groups:
  - name: "ノード選択"
    type: select
    proxies:
      - "サンプルノード"
      - DIRECT

rules:
  - DOMAIN-SUFFIX,example.org,ノード選択
  - MATCH,DIRECT

上の最小構成は、完全な参照関係を示しています。rules の「ノード選択」は proxy-groups の名前と完全に一致していなければならず、プロキシグループ内の「サンプルノード」も proxies のノード名と一致していなければなりません。名前では文字、スペース、全角・半角記号が区別されます。設定断片をコピーするとき、ルールだけをコピーしてプロキシグループを忘れたり、プロキシグループだけをコピーしてノードを忘れたりすると、いずれも未解決の参照になります。クライアントによってはインポート時に通知しますが、別のクライアントではコア起動時にのみエラーを記録します。そのためクライアントのログ確認が必要です。

トップレベル項目の推奨順序

YAML仕様ではトップレベルの順序は固定されていませんが、保守性を考えると「実行入口、DNS、ノードの供給元、ノード、プロキシグループ、ルールの供給元、ルール」の順に並べるとよいでしょう。この順序はデータの依存関係に近く、まずトラフィックをどのようにコアへ入れるかを決め、次にドメインをどう解決するかを決め、その後に利用可能な出口を用意し、最後にマッチングを実行できます。サブスクリプション生成ツールが異なる順序を採用していても、インデントと参照が正しければ通常は結果に影響しません。手動で管理する場合は順序を安定させることで、マージ時の誤削除を減らし、更新前後の差分も比較しやすくなります。

階層 主な項目 確認ポイント
実行入口 mixed-port、mode、allow-lan ポート競合、待ち受け範囲、モードが想定どおりか
名前解決層 dns、hosts 拡張モード、上流アドレス、除外ドメイン
出口層 proxies、proxy-providers ノード名、プロトコルパラメータ、供給元の更新
判断層 proxy-groups、rules 参照関係、マッチング順序、最終フォールバック

サブスクリプションから取り込んだ設定は、通常クライアントによってローカルコピーとして保存されます。コピーを直接編集するとテストは簡単ですが、次回のサブスクリプション更新でファイルが再生成される可能性があります。長期的に保持したいローカルルールは、キャッシュファイルの変更に頼らず、クライアントが対応するオーバーライド、マージ、スクリプトの入口に記述してください。目的が初回接続の完了だけなら、まずクイックスタート手順でサブスクリプションが利用できることを確認し、その後このページで構造を調整します。これにより「サブスクリプション自体が利用できない」問題と「カスタム項目の記述ミス」を切り分けられます。

CHAPTER 02 / RUNTIME

共通項目：ポート、モード、LAN、コントロールインターフェース

共通項目は、コアがアプリのトラフィックをどのように受け取り、管理機能をどのように公開するかを決めます。デスクトップクライアントでは通常GUIで管理しますが、最終的な基準は設定ファイルです。最も一般的な入口は mixed-port で、同じポートでHTTPとSOCKS5のプロキシリクエストを受け付けます。システムプロキシや、プロキシアドレスを手動設定するアプリに適しています。古い設定では port と socks-port を分けて使う場合もあります。複数の入口を定義する場合は、ポート番号が重複せず、他のプログラムにも使用されていないことを確認してください。

mixed-port: 7890
redir-port: 7892
tproxy-port: 7893

allow-lan: false
bind-address: "*"
mode: rule
log-level: info
ipv6: false
unified-delay: true
tcp-concurrent: true

redir-port と tproxy-port は主に透過プロキシで使用され、ルーティングルール、ゲートウェイスクリプト、特定のクライアントから自動的に接続されることが一般的です。通常のデスクトップ環境でシステムプロキシだけを使うなら、項目を揃えるためだけに無理に有効化する必要はありません。TUNモードにも固有のトラフィック入口とルーティング処理があり、待ち受けポートを1つ増やすだけでは完了しません。システムプロキシとTUNの適用範囲を比較するには、TUNモードとシステムプロキシの違いを読み、アプリがシステムプロキシを参照するかどうかに応じてルーティング方式を決めてください。

動作モードとルールの挙動

mode の代表的な値は rule、global、direct です。ルールモードは rules を上から順に照合する、日常利用の基本モードです。グローバルモードはトラフィックをグローバルなプロキシグループ選択へ渡し、ノードが一時的に利用できるかを確認するのに適しています。ダイレクトモードはプロキシ出口を迂回し、ローカルネットワークの問題を切り分けるのに役立ちます。モードを切り替えてもルール内容は書き換わらず、判断の入口だけが変わります。トラブルシューティングでは一時的にグローバルモードへ切り替えられます。グローバルモードでアクセスできてルールモードで失敗するなら、ルールのマッチングとプロキシグループを確認します。グローバルモードでも失敗するなら、まずノード、プロトコルパラメータ、システムのルーティング状態を確認してください。

allow-lan は、LAN上のデバイスが本機の待ち受けポートへアクセスできるかを制御します。true にした場合は、bind-address、OSのファイアウォール、LANアドレスも合わせて確認してください。待ち受けを公開すると、同じネットワーク上のデバイスからそのポートへリクエストを送信できる可能性があります。プロキシを共有する明確な必要がある場合だけ有効化し、コントロールインターフェースにもアクセス制限を設定してください。本機だけで使うなら false のままにする方が管理しやすくなります。クライアント画面に「LAN接続を許可する」スイッチがある場合は、複数のオーバーライド層で同じ項目を繰り返し設定しないようにし、画面表示と最終設定の不一致を避けてください。

コントロールインターフェースと設定の保存

external-controller: 127.0.0.1:9090
secret: "your-dashboard-password"
external-ui: dashboard
profile:
  store-selected: true
  store-fake-ip: true

external-controller はコントロールAPIを提供し、GUIクライアントやパネルからプロキシグループの読み取り、ノードの切り替え、設定の再読み込みを行えます。本機で管理するなら 127.0.0.1 にバインドすれば十分です。すべてのネットワークインターフェースにバインドする場合は、アクセス制御、ファイアウォール、実際の利用環境を必ず考慮してください。secret はコントロールインターフェースの認証に使うため、例の値はローカルで決めた内容に置き換えます。external-ui はパネルの静的ファイルディレクトリを指し、ノードの供給元でもプロキシルールを変更する項目でもありません。

profile.store-selected はプロキシグループの選択状態を保存し、コア再起動後に前回の選択を復元できるようにします。store-fake-ip はFake-IPのマッピングを保存し、再起動後のマッピング変更による影響を抑えます。これらの項目をクライアントが管理するかどうかは実装によって異なります。GUIクライアントでは、同じYAMLではなく独自データベースに状態を保存する場合もあります。「変更しても再起動すると戻る」場合は、項目がサブスクリプション、オーバーライド、クライアント設定のどこから来ているかを先に判断してください。同じキャッシュファイルを繰り返し編集するだけでは解決しません。

ポート使用状況の確認

コアの起動に失敗し、アドレスが使用中だと表示された場合は、まず重複起動しているクライアントを終了します。次に同じ設定内で複数の待ち受け項目に同じポートを指定していないか確認してください。ポートを変更した後は、システムプロキシやアプリ内の手動プロキシ設定も合わせて更新します。

log-level はログの詳細度を制御します。通常運用では info を使い、ルールのマッチング、DNSリクエスト、接続確立の過程を調べるときだけ一時的に詳細度を上げ、完了後に戻すとよいでしょう。大量のログで重要なエラーが埋もれるのを防げます。ipv6 はコア関連機能でIPv6を処理するかどうかを決めますが、これだけでローカルネットワークに利用可能なIPv6ルートがあることは保証されません。有効化後に接続待ちが発生した場合は、ローカルネットワーク、DNSの応答、ルールの適用範囲を個別に確認し、すべてを1つのスイッチの問題と考えないでください。

CHAPTER 03 / RESOLUTION

DNS項目：上流名前解決、Fake-IP、フォールバックルール

ClashのDNSモジュールは、ドメインリクエストとルールマッチングの間に位置します。本機やTUNでルーティングされたDNSクエリを受け取り、設定に応じて上流サーバーを選択できます。DNS設定の目的はアドレスをただ増やすことではなく、3つの点を明確にすることです。クエリがどこから入るのか、どの上流を使うのか、解決結果をルールとどう連携させるのかです。システムプロキシでは、一部のアプリが引き続きシステムDNSを直接使う場合があります。TUNモードでDNSハイジャックを併用すると、通常はより広い範囲をカバーできます。ブラウザは使えるのに他のアプリで名前解決に失敗する場合は、そのアプリのDNSトラフィックがコアに入っているかを先に確認してください。

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

enable は内蔵DNSを有効にするかを制御し、listen は待ち受けアドレスを指定します。0.0.0.0 で待ち受ける場合はLANからのアクセス範囲に関係するため、実際のネットワーク環境と合わせて設定してください。本機だけで使うなら、ローカルループバックアドレスを使うか、クライアントの自動設定に任せる方法があります。default-nameserver には通常、DoH上流自身のドメインなど基礎的な名前解決に使える、直接到達可能なIPアドレスを指定します。すべてのクエリを処理する主要な出口ではありません。通常のドメインクエリは nameserver に渡し、プロキシサーバーのドメインは proxy-server-nameserver で分けて解決できます。これによりプロキシ接続前の循環依存を避けられます。

Fake-IPとRedir-Hostの処理の違い

enhanced-mode: fake-ip は、予約アドレス範囲からドメインに対応するマッピングアドレスを返します。アプリがそのアドレスへ接続すると、コアがマッピングから元のドメインを復元し、ドメインルールとプロキシ判断を実行します。ドメイン情報を維持しやすく、TUN環境で統一的に処理できる点が利点です。fake-ip-range には専用の予約ネットワークを使い、LANで実際に使用しているアドレス範囲へ変更しないでください。マッピングアドレスはリモートサーバーの実アドレスではないため、パケットキャプチャツールで予約アドレスが見えるのは正常です。

一部のLAN機器の検出、時刻同期、ゲーム、実アドレスの返却に依存するアプリはFake-IPに適さない場合があります。その場合は対象ドメインを fake-ip-filter に追加し、実際の名前解決結果を使わせます。除外項目はできるだけ具体的にし、まず異常を確認したドメインから始めてください。広すぎるトップレベルのパターンを直接追加すると、ドメインルールの可視性が低下します。マッピングの流れと除外が必要な場面については、Clash Fake-IPモードの仕組みも参照してください。

redir-host は従来型の名前解決に近く、コアが実IPを取得してから接続を処理します。実アドレスに依存するプログラムには分かりやすい一方、後続のIP接続段階でドメイン情報が失われ、ルールマッチングがDNSキャッシュやスニッフィングに依存しやすくなります。どちらのモードにも、すべてのネットワークに適した固定解はありません。通常のWebアクセス、TUNによる全体ルーティング、大量のドメインルールでは、まずFake-IPを試すとよいでしょう。LANサービス、特殊なゲーム、企業内ドメインがある場合は、DNS構成全体をすぐ変更せず、対象ごとに除外を追加してください。

フォールバック、ポリシー、振り分け名前解決

dns:
  enable: true
  enhanced-mode: fake-ip
  nameserver:
    - https://dns.alidns.com/dns-query
  fallback:
    - https://1.1.1.1/dns-query
  fallback-filter:
    geoip: true
    geoip-code: CN
    domain:
      - "+.example.net"
  nameserver-policy:
    "geosite:cn":
      - https://dns.alidns.com/dns-query
    "geosite:geolocation-!cn":
      - https://1.1.1.1/dns-query

fallback と fallback-filter は、条件に応じて予備の結果を選択します。設定時は、利用中のコアが並列クエリ、結果のフィルタリング、Geoデータをどのように処理するかを理解する必要があります。「予備アドレスを記入すれば、すべての失敗が固定順で自動再試行される」と考えてはいけません。nameserver-policy では、ドメインやルールセットごとに名前解決サーバーを指定できます。中国本土と日本国内、家庭内ドメインと業務ドメインなどで異なる名前解決経路が必要な場合に適しています。ポリシーキーで geosite を参照する場合は、ローカルのGeoデータを読み取れる必要があります。

DNSトラブルシューティングの順序

まず内蔵DNSが待ち受けていることを確認し、次にクエリが実際にそのポートへ入っているかを確認します。その後、上流サーバーのドメインを基礎DNSで解決できるかを調べ、最後にFake-IPの除外とルールマッチングを確認します。上流アドレスを交換するだけでは、待ち受け、ハイジャック、ルーティング層の問題は直せません。

よくある障害は症状ごとに分岐して対応できます。すべてのドメインに失敗するがIPへの直接アクセスは正常なら、待ち受けと上流を確認します。プロキシノードのドメインだけが失敗するなら、proxy-server-nameserver と基礎名前解決を確認します。LAN名が失敗するなら、検索ドメイン、hosts、Fake-IP除外を確認します。ルールのマッチングが想定と異なるなら、ドメイン情報が保持されているか、Geoデータが読み込まれているかを確認します。変更後は設定を再読み込みしてログを確認し、拡張モード、上流アドレス、TUNハイジャックを同時に変更しないでください。どれが有効になったのか判断できなくなります。

CHAPTER 04 / ENDPOINTS

プロキシノード項目：名前、プロトコルパラメータ、トランスポート層

proxies はプロキシノードオブジェクトのリストです。各オブジェクトには最低限、名前、プロトコル種別、サーバーアドレス、ポート、プロトコルに対応する認証パラメータが必要です。ノード名は表示用だけでなく、プロキシグループからも参照されるため、一意に保つ必要があります。サーバーにはドメインまたはIPを指定できます。ドメインを使う場合は、接続前にDNS名前解決が必要です。ポートはサーバーが実際に待ち受けるポートであり、本機のプロキシ入口ポートと混同しないでください。サブスクリプションで生成されたノードパラメータは通常ひとまとまりで提供されるため、項目を1つだけ手動変更するとサーバーとクライアントのネゴシエーションが壊れる可能性があります。

proxies:
  - name: "SSサンプル"
    type: ss
    server: 192.0.2.10
    port: 443
    cipher: aes-128-gcm
    password: "your-password"
    udp: true

  - name: "Trojanサンプル"
    type: trojan
    server: proxy.example.com
    port: 443
    password: "your-password"
    sni: proxy.example.com
    skip-cert-verify: false
    udp: true

Shadowsocksノードでは cipher と password を使用します。暗号方式はサーバーと一致させ、項目名の綴りと大文字・小文字もコアの対応範囲に合わせてください。Trojanノードは通常TLSで接続し、sni はハンドシェイクで指定するサーバー名です。skip-cert-verify を false にすると証明書検証を行います。一般公開の正規証明書を使う場合は検証を有効にしてください。証明書名と接続先ドメインが一致しない場合は、検証を無効にすることを長期的な対策にせず、サーバー設定とサブスクリプション内容を確認してください。

VMess、WebSocket、TLS

proxies:
  - name: "VMess WSサンプル"
    type: vmess
    server: proxy.example.com
    port: 443
    uuid: 00000000-0000-4000-8000-000000000000
    alterId: 0
    cipher: auto
    tls: true
    servername: proxy.example.com
    network: ws
    ws-opts:
      path: /service
      headers:
        Host: proxy.example.com

VMessの uuid、alterId、トランスポートネットワーク、TLSパラメータはサーバーと一致させる必要があります。WebSocket設定は ws-opts の下に記述し、パスとHostヘッダーはトランスポート層のネゴシエーションに関わります。項目をノードオブジェクトの外側へ誤ってインデントしても、YAML自体は解析される場合がありますが、コアはそのノードのWebSocketパラメータとして扱いません。gRPC、HTTP、その他のトランスポートを使う場合は対応するオプションへ変更し、無関係な ws-opts を残して自動変換を期待しないでください。

TLS関連項目では、プロトコルオブジェクトによって sni または servername を使う場合があります。断片をコピーする前に、現在のコアが対応する項目を確認し、名前が似ているからという理由だけで置き換えないでください。サーバーアドレス、TLSサーバー名、HTTP Hostは同じ場合もあれば、異なる役割を持つ場合もあります。サーバーアドレスは接続先を決め、SNIはTLSハンドシェイクに使われ、Hostヘッダーはアプリケーション層のトランスポートで使われます。ハンドシェイクに失敗したら、ドメインが解決できるかだけでなく、この3つの層を個別に確認してください。

UDP、インターフェース、チェーン接続

udp: true はノードがUDPを処理できることを示しますが、実際に利用できるかどうかはプロトコル、サーバー、ローカルのルーティング方式にも左右されます。アプリがUDPリクエストを送信しても、システムプロキシが自動的に処理するとは限りません。多くのシステムプロキシ設定は主にTCPを対象とします。TUNや透過プロキシではUDPを統一的に処理しやすくなりますが、正しいルーティングとDNS設定が必要です。ゲーム、音声、QUIC接続に異常がある場合は、まずトラフィックがコアに入っているかを確認し、その後ノードの対応状況を判断してください。ノードオブジェクトの真偽値だけで結論を出してはいけません。

interface-name、routing-mark などの項目は、出口インターフェースを制限したり、システムルーティングと連携したりするために使います。主に複数NICのある環境、サーバー、ルーターで使用されます。設定を誤ると、プロキシ接続が再びプロキシ入口へ入り、ループが発生する可能性があります。チェーンプロキシでは dialer-proxy などで発信元の出口を指定できますが、参照先のノードやプロキシグループが先に存在し、相互参照になっていないことが必要です。通常のクライアント設定で明確なチェーン要件がない場合は、これらの項目を追加しないことを推奨します。

項目グループ 決まる内容 よくあるミス
基本接続 server、port、type アドレスを解決できない、ポートがサーバーと一致しない
認証パラメータ password、uuid、cipher コピー漏れ、異なるプロトコル項目の混用
TLS層 sni、servername、証明書検証 名前の不一致、設定ミスを検証無効化で隠す
トランスポート層 network、ws-opts など パスの誤り、オプションを誤った階層にインデント

サブスクリプションを取り込んだ後、推測でプロトコルパラメータを変更しないでください。まずクライアントが提供する設定更新を実行し、次にノード名がプロキシグループへ入っているか確認します。ノード一覧が空の場合、問題は通常、サブスクリプションの取得、形式変換、プロバイダーの読み込み段階にあります。ノードは存在するのに接続できない場合は、プロトコルパラメータ、DNS、システム時刻を確認してください。クライアントのダウンロードとプラットフォームごとの差異はクライアントダウンロードで確認でき、更新停止したクライアントからの移行は設定移行手順を参照してください。

CHAPTER 05 / POLICY

プロキシグループ項目：手動選択、自動テスト、フェイルオーバー

proxy-groups はノード、内蔵出口、他のプロキシグループを、ルールから参照できる判断オブジェクトとしてまとめます。ルールには通常、個別ノード名ではなくプロキシグループ名を記述するため、サブスクリプション更新やノード変更のたびにすべてのルールを書き換える必要がありません。代表的な内蔵出口には DIRECT と REJECT があります。前者は宛先へ直接接続し、後者はマッチしたトラフィックを終了させます。プロキシグループ名も一意にする必要があります。ノード名と重複すると読み取りや保守が難しくなるため、「ノード選択」「自動選択」「フェイルオーバー」など用途が分かる名前を推奨します。

proxy-groups:
  - name: "ノード選択"
    type: select
    proxies:
      - "自動選択"
      - "フェイルオーバー"
      - "SSサンプル"
      - DIRECT

  - name: "自動選択"
    type: url-test
    proxies:
      - "SSサンプル"
      - "Trojanサンプル"
    url: https://www.gstatic.com/generate_204
    interval: 300
    tolerance: 50

  - name: "フェイルオーバー"
    type: fallback
    proxies:
      - "SSサンプル"
      - "Trojanサンプル"
    url: https://www.gstatic.com/generate_204
    interval: 300

Select、URL-Test、Fallback

select は手動選択に使います。最上位の入口として、ユーザーが自動グループ、フェイルオーバーグループ、個別ノード、直接接続を明確に切り替えるのに適しています。url-test はテストURLで候補を確認し、結果に基づいて選択します。テスト結果は指定URLへの接続状況を示すだけで、すべてのWebサイト、プロトコル、時間帯での体感を意味しません。tolerance は結果が近い候補間で頻繁に切り替わるのを抑えるために使います。数値の単位と具体的な処理はコアの実装によって決まります。

fallback はリスト順に利用可能な候補を選び、現在の候補が使えない場合に次へ切り替えます。出口の優先順位が明確な場面に適しています。load-balance は複数の候補へ接続を分配しますが、セッションの一貫性を考慮する必要があります。ログイン、決済、固定出口に依存するサービスでは、接続ごとに出口が変わる構成が適さない場合があります。自動テストも負荷分散も「ノードが多いほどよい」わけではありません。候補が多すぎると検査リクエストと保守コストが増えます。まず地域、用途、プロトコルで絞り、規模を管理しやすいプロキシグループを作ってください。

プロキシプロバイダーでプロキシグループを構成する

proxy-providers:
  airport:
    type: http
    url: "https://example.com/api/v1/client/subscribe?token=xxxx"
    path: ./providers/airport.yaml
    interval: 21600
    health-check:
      enable: true
      url: https://www.gstatic.com/generate_204
      interval: 600

proxy-groups:
  - name: "プロバイダーノード"
    type: select
    use:
      - airport

proxy-providers はリモートのノード集合をローカルのプロバイダーファイルとして保存します。type: http はアドレス経由で更新することを示し、path はローカルキャッシュの場所、interval は定期更新の間隔を指定します。例のサブスクリプションアドレスには明らかなテスト値を使っています。実際のアドレスはサブスクリプションサービスからコピーし、公開ドキュメントやスクリーンショットで公開しないでください。health-check はプロバイダーレベルの可用性チェックに使います。プロキシグループ独自のテスト機能と併用できますが、間隔が短すぎると重複検査が発生します。

プロキシグループは use でプロバイダーを参照し、proxies で静的ノードや他のグループを参照します。2つの供給元は、コアが対応する方式で組み合わせられますが、保守時にはノードの出所を明確にしてください。サブスクリプション更新でノード名が変わると、proxies に直接記述した古い名前は無効になる可能性があります。動的な集合にはプロバイダー参照が適しています。さらに絞り込む場合は、対応するコアで filter や除外式を使い、ノード名から地域グループを作成できます。式はまず少数の名前でテストし、命名規則の変更によって空のグループにならないようにしてください。

プロキシグループの依存方向

プロキシグループは他のプロキシグループを参照できますが、依存関係は一方向に保つ必要があります。たとえば「ノード選択」が「自動選択」を参照する構造は合理的です。しかし「自動選択」が再び「ノード選択」を参照すると循環が発生します。プロキシ層は下から上へ設計するとよいでしょう。下層は静的ノードとプロバイダー、中層は地域フィルタリングと自動テスト、最上層はルールから参照する用途別グループです。メディア、仕事、ダウンロードなどの用途別グループは最上層の出口を参照し、下層の速度テストグループから用途別グループを参照しないようにします。

プロキシグループが空の場合

まず use に指定したプロバイダー名を確認し、次にプロバイダーファイルが正常に更新されたかを確認します。名前によるフィルタリングを使っている場合は、一時的にフィルタ式を外して元のノードが存在するか確認してください。空のグループは通常ルールの問題ではありません。ルールは定義済みのプロキシグループへリクエストを送るだけです。

interval を秒単位で設定する場合は、実際の必要性に応じて決め、高頻度を追求する必要はありません。ノードサブスクリプションの更新、ヘルスチェック、プロキシグループのテストは別々の操作です。サブスクリプション更新は候補集合を変え、ヘルスチェックはノードに接続できるかを判定し、プロキシグループのテストは候補から選択します。トラブルシューティングではそれぞれを手動で実行し、どの段階で失敗するかを確認してください。クライアント画面に自動更新間隔がある場合は、全体の設定を更新するのか、プロバイダーだけを更新するのかを確認し、複数のタイマーによる重複リクエストを避けます。

CHAPTER 06 / MATCHING

ルール構文、マッチング順序、ルールセット

rules は順序付きリストです。接続は先頭から下へ確認され、マッチするとその項目で指定されたプロキシグループを直ちに使い、後続のルールは同じ接続に対して処理されません。そのためルールで重要なのは内容だけでなく位置です。具体的なドメイン、プロセス、ネットワークは前方に置き、範囲の広いGeoルールは後方に置き、最後に MATCH でフォールバックします。広すぎるルールを早い位置に置くと、下にある精密なルールは永遠にマッチしません。

rules:
  - DOMAIN,api.example.com,ノード選択
  - DOMAIN-SUFFIX,example.org,ノード選択
  - DOMAIN-KEYWORD,example,ノード選択
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
  - GEOIP,CN,DIRECT
  - MATCH,ノード選択

DOMAIN は完全なドメイン名に対して完全一致します。DOMAIN-SUFFIX は指定ドメインとそのサブドメインに一致します。DOMAIN-KEYWORD はキーワードで一致するため範囲が広く、同じ文字列を含む別ドメインに誤適用されやすくなります。完全なドメインやサフィックスを使える場合は、キーワードを優先しないでください。ドメインルールは接続中に取得できるドメイン情報に依存します。アプリがIPへ直接接続する場合や、DNS処理でドメイン情報が保持されない場合は、IP系ルールに移る可能性があります。

IP、ポート、プロセス、ネットワーク種別

IP-CIDR はIPv4ネットワークに使い、IPv6には対応するIPv6ルール種別を使います。LANの予約アドレスは通常、GeoIPより前に直接接続へ振り分けます。no-resolve は、そのIPルールを照合する際にIPを取得するためのドメイン解決を自動的に開始しないことを示します。追加クエリやルール処理中の循環を避けるのに使えますが、適否はルール種別と実際のトラフィックによって決まります。CIDRを使う場合はプレフィックス長を確認し、広すぎるネットワークが意図しないアドレスまで対象にしないようにしてください。

rules:
  - PROCESS-NAME,example-app.exe,DIRECT
  - DST-PORT,22,ノード選択
  - NETWORK,udp,自動選択
  - IP-CIDR,172.16.0.0/12,DIRECT,no-resolve
  - MATCH,ノード選択

プロセスルールはOSの権限とクライアントコアの機能に依存し、プラットフォームによってプロセス名の取得方法も完全には同じではありません。Windowsでは実行ファイル名が一般的です。macOSとLinuxではプロセス名やパスで提供される場合があり、モバイル環境ではデスクトップのようにすべてのアプリを識別できないことが多くあります。ポートルールは宛先ポートを示すだけで、トラフィックの用途を証明するものではありません。多くのサービスが共有ポートを使うため、ポートだけの振り分けは範囲が広くなりがちです。NETWORK はTCPとUDPを区別できますが、特定の要件を補う目的に適しており、ドメインやIPルールの代わりにはなりません。

Rule Providerと動作種別

rule-providers:
  direct-domains:
    type: http
    behavior: domain
    format: yaml
    path: ./ruleset/direct-domains.yaml
    url: https://example.com/rules/direct-domains.yaml
    interval: 86400

  private-networks:
    type: http
    behavior: ipcidr
    format: yaml
    path: ./ruleset/private-networks.yaml
    url: https://example.com/rules/private-networks.yaml
    interval: 86400

rules:
  - RULE-SET,direct-domains,DIRECT
  - RULE-SET,private-networks,DIRECT,no-resolve
  - GEOIP,CN,DIRECT
  - MATCH,ノード選択

rule-providers は大規模なルールを独立ファイルへ分割します。behavior: domain は内容をドメイン系のデータとして解釈し、ipcidr はネットワークに使います。一部のコアでは、より汎用的なルールセットの動作にも対応しています。動作種別はリモートファイルの内容と一致させる必要があります。ドメインリストをIPネットワーク用として扱ったり、従来型のルールテキストを純粋なドメインデータとして直接扱ったりすることはできません。format はファイル形式を示します。更新に失敗した場合は、ネットワークアクセス、ファイル形式、保存先、解析ログを同時に確認してください。

ルールセットの更新間隔とサブスクリプション更新は独立しています。ノードサブスクリプションを更新しても外部ルールセットが自動的に更新されるとは限らず、ルールセットを更新してもノードは変わりません。GeoIP、GeoSite、外部ルールセットは別々のデータソースです。地域ルールが古い場合は、クライアントが使うデータファイルの場所と更新機能を確認し、サブスクリプションだけを更新しないようにしてください。Geoデータの読み込み問題については、ヘルプセンターで症状別に確認できます。

説明可能なルール順序を作る

「本機とLAN、手動の精密ルール、用途別ルールセット、地域ルール、最終フォールバック」の順に並べることを推奨します。各区分の前にコメントを書き、ルールの出所と用途を説明してもよいでしょう。手動ルールが少ない場合は、確認しやすいよう主設定へ直接記述します。数が多く、独立して更新する必要がある場合はルールプロバイダーを使います。複数のソースのルールを機械的に連結してそのまま使わず、重複、相反するプロキシグループ、広すぎるキーワードがないか確認してください。

ルールが有効にならない

まず接続ログで実際にマッチしたルールを確認し、上へたどって先にある広いルールが取り込んでいないか調べます。ログにIPしか表示されない場合は、DNSモード、スニッフィング、アプリの接続方式を確認します。プロキシグループ名が存在しない場合は、プロキシグループの参照関係に戻って対応してください。

ルールをテストするときは、一度に1つの区分だけを変更します。まず完全なドメインルールを1つ追加してリストの前方に置き、再読み込み後に対象ドメインへアクセスし、ログでマッチを確認します。構文とプロキシグループが有効だと確認してから、サフィックスやルールセットへ段階的に広げてください。グローバルモードへ切り替えるだけではノード経路を検証できても、ルールが正しいことは証明できません。テスト完了後はルールモードに戻し、最終的な MATCH の指向先が想定どおりか確認してください。

CHAPTER 07 / MAINTENANCE

オーバーライド、マージ、自動更新、設定トラブルシューティング

サブスクリプション設定はリモート内容に応じて更新されるため、ローカル変更は安定したカスタム層に置く必要があります。一般的なクライアントには、オーバーライド、マージ、拡張スクリプト、設定断片の機能がありますが、配列とオブジェクトの処理方法はクライアントによって異なります。オブジェクト項目は通常キー単位で上書きできます。たとえば mode を rule に変更したり、dns に子項目を追加したりできます。配列項目は全体置換、前後への追加、クライアント独自の構文による処理になる場合があります。rules、proxies、proxy-groups はすべて配列です。誤って全体を上書きすると、サブスクリプションにある元の内容が消えてしまいます。

設定を保守するときは、まず4つの出所を区別してください。リモートサブスクリプションの原文、クライアントが生成した実行設定、ローカルのオーバーライド断片、クライアント自身の設定です。画面に表示される最終状態は、これら4つをマージした結果である可能性があります。トラブルシューティングでは、ダウンロードしたサブスクリプションファイルだけを開くのではなく、クライアントが提供する「実行設定を表示」やログ出力を確認してください。サブスクリプション更新後にカスタムルールが消えるなら、変更がリモートコピーまたはキャッシュ層に入っていたことを示します。画面で変更してもYAMLが変わらないなら、その項目はクライアント設定に保存されている可能性があります。

オブジェクトの上書きと配列の追加

# 共通オーバーライドの例。実際の入口はクライアントの対応方式に従ってください
mode: rule
log-level: info

dns:
  enable: true
  enhanced-mode: fake-ip
  fake-ip-filter:
    - "*.lan"
    - "*.local"

上のオブジェクト構造は最終的な目的を表すのに適していますが、特定のクライアントが配列をどのようにマージするかまでは示せません。たとえば fake-ip-filter が置換方式なら、2項目を書き込むことでサブスクリプション側の元のリストが上書きされます。追加方式なら、元のリストを残したまま2項目が加わります。使用前にクライアントのドキュメントまたは実行設定で確認してください。ルール配列では特に挿入位置が重要です。優先してマッチさせたいローカルルールはリモートルールより前に入れる必要があります。MATCH の後ろに追加するだけでは、トラフィックがフォールバックルールで終了しているため有効になりません。

プロキシグループにも同じ問題があります。「ノード選択」にローカルグループを追加するために、リモートのプロキシグループリスト全体をコピーして長期的に管理するべきではありません。サブスクリプション更新で追加されたグループがコピーへ自動反映されないためです。より安全なのは、クライアントが提供するグループ単位のオーバーライド、スクリプト処理、プロバイダー参照を使い、最終設定では対象グループだけを変更する方法です。クライアントが細かいマージに対応していない場合は、カスタム範囲を減らすか、長期的なルールを独立したルールプロバイダーへ移してください。

自動更新の3つの層

自動更新には少なくとも、サブスクリプション全体、プロキシプロバイダー、ルールプロバイダーの3層があります。サブスクリプション全体の更新は通常クライアントがスケジュールし、更新後に完全な設定を再生成します。proxy-providers.interval はノード集合を更新し、rule-providers.interval はルール集合を更新します。これらを1つのスイッチとして扱ってはいけません。サブスクリプションアドレスが変わった場合、ルールプロバイダーだけを更新しても新しいノードは得られません。ルールセットが古い場合、ノードサブスクリプションだけを更新してもルールデータは変わりません。

周期を設定するときは、内容の変化頻度とクライアントの動作方式を考慮してください。デスクトップクライアントを長時間終了していると、タイマーはバックグラウンドで実行できません。再起動後に更新時刻を手動で確認してください。更新に成功しても実行設定が再読み込みされたとは限りません。自動適用するクライアントもあれば、手動の切り替えや再読み込みが必要なクライアントもあります。確実な手順は、更新を実行し、供給元の状態を確認し、最終設定を再読み込みし、プロキシグループの選択が保持されているか確認してから、アクセスをテストすることです。

保持しておきたい確認用ベースライン

正常に起動できる最小構成を1つ保存しておきます。機能ブロックは毎回1つだけ追加し、再読み込み後にログを確認してください。問題が起きたときは、DNS、TUN、プロキシグループ、ルールを同時に変更するより、直前の正常な状態へ戻す方が原因を特定しやすくなります。

名前解決エラーから接続エラーまでの切り分け

第1層はYAML解析です。よくある通知には、インデントエラー、コロン後のスペース不足、閉じていない引用符、リスト階層の誤り、重複キーがあります。処理時はエラー行の前後数行を確認してください。実際の構造エラーは、通知された行より前にある場合があります。特殊文字を含む値は、まず引用符で囲むと安全です。Webページからコピーした曲がった引用符や全角句読点は、通常のYAML文字へ変更してください。解析を通過したら、次に項目の型を確認します。たとえばポートは数字、真偽値は true または false でなければなりません。

第2層は参照の検証です。ルールの対象がプロキシグループまたは内蔵出口に存在するか、プロキシグループのメンバーがノード、プロバイダー、他のグループに存在するか、ルールプロバイダー名が RULE-SET の参照と一致するかを項目ごとに確認します。名前のスペースは特に見つけにくいため、一時的に名前をコピーして検索するとよいでしょう。第3層はリソースの読み込みです。サブスクリプション、プロキシプロバイダー、ルールプロバイダー、Geoデータが読み取れるか確認します。ネットワーク更新に失敗しても古いキャッシュが残っていればコアは起動できる場合があるため、更新時刻とログを同時に確認してください。

第4層は接続の確立です。ノードがタイムアウトする場合は、サーバーの名前解決、宛先ポート、ローカルネットワーク、プロトコルパラメータを確認します。TLSハンドシェイクに失敗する場合は、システム時刻、サーバー名、証明書を確認します。UDPだけに異常がある場合は、ルーティング方式とノードの機能を確認します。特定のドメインだけに異常がある場合は、DNSとルールのマッチングへ戻ります。第5層はシステムのトラフィック入口です。ブラウザ設定、システムプロキシ、TUNルーティング、アプリ独自のプロキシ設定が現在の構成と一致していなければなりません。設定ファイルが完全に正しくても、システムのトラフィックがコアに入っていなければアクセス結果は変わりません。

症状 優先して確認する項目 次の手順
設定を読み込めない インデント、引用符、項目の型、重複キー 最小構成まで縮小し、段階的に戻す
プロキシグループが空 ノードの供給元、use、フィルタ式 プロバイダーのログとキャッシュファイルを確認
ルールモードの挙動が異常 実際のマッチ項目、ルール順序、プロキシグループ名 完全なドメインルールで個別テスト
ドメインは失敗するがIPは利用できる DNSの待ち受け、上流名前解決、Fake-IP クエリがコアに入っているか確認
更新後にカスタム内容が消える 変更箇所、配列のマージ方式 クライアントのオーバーライドまたはルールプロバイダーへ移行

変更が完了したら、再現可能な検証手順を残してください。設定を再読み込みしてコアが起動することを確認し、プロバイダーを更新してノードとルールセットが読み取れることを確認します。次にプロキシグループの選択を確認し、直接接続すべきドメインとプロキシ経由にすべきドメインへ1つずつアクセスし、最後にログのマッチ結果を確認します。それでも問題を分類できない場合は、ヘルプセンターでインストール設定、使い方、トラブルシューティングの分類から確認してください。YAML全体の読み込み順序を改めて理解するには設定ファイルのYAML構造解析を参照し、基本的な取り込みをやり直す場合は入門ガイドへ戻ってください。サブスクリプションの利用可否を確認する前に、オーバーライドを重ねて追加しないでください。