Clash 設定リファレンス

YAML構造と設定の依存関係

トップレベルのマッピングで設定の範囲を把握する

Clashの設定は順番に実行するスクリプトではなく、稼働状態を記述するマッピングです。トップレベルのmixed-port、mode、log-levelはスカラー値、dnsは入れ子のマッピング、proxies、proxy-groups、rulesはリストです。インデントが親子関係を決めるため、項目の位置は値と同じくらい重要です。たとえばrulesをdnsの下にインデントしても、特別なDNSルールにはなりません。構造が変わり、エラーになったり無視されたりする可能性があります。

設定ファイル全体を読むときは、まず4つの依存関係を確認します。待受入口からコアへ接続が入り、ルールが接続の処理先を決め、プロキシグループが宛先名をノードまたは別のグループに対応付け、DNSがドメイン名の名前解決を担います。プロバイダーはノードやルールのデータを補いますが、それだけで通信の出口になるわけではありません。ノードプロバイダーがグループから参照されるか、ルールプロバイダーがルールから参照されて初めて、該当リソースが実際の処理に使われます。こうした関係を把握すれば、行ごとに推測しながら原因を探す必要がなくなります。

# 最小限の直接接続設定。ファイル構造と待受入口の確認に使用
mixed-port: 7890
allow-lan: false
mode: rule
log-level: info

proxies: []

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

rules:
  - MATCH,出口選択

この最小構成では組み込みの宛先DIRECTのみを使用し、リモートプロキシは提供しません。コアがファイルを読み込めること、ポートを起動できること、クライアントをルールモードに切り替えられることの確認に使えます。プロキシ出口が必要な場合は実際のノードを追加し、その名前をグループに登録してください。構造例と利用可能なサブスクリプションは別物です。構文チェックに通っても、構造や一部の参照が正しいことを示すだけで、リモートサーバーの稼働やアカウントのアクセス権までは確認できません。

インデント、引用符、リストでよくある注意点

インデントは常に半角スペース2つを使い、タブと混在させないでください。短いリストは[DIRECT, 出口選択]のように書けます。項目の多いオブジェクトリストは1項目ずつ改行すると階層を把握しやすくなります。コロンの後に空白が続く文字列、シャープ記号を含む文字列、真偽値に見える文字列は、型を明確にするため引用符で囲みます。パスワード、サブスクリプションURL、数字だけの名前も引用符で囲むと、パーサーによる別の型への解釈を防げます。コメントは文字列の外側でのみ有効です。アカウント情報をコメントに保存しないでください。

同じマッピング内でキーを重複して定義しないでください。たとえばファイルの先頭と末尾にdnsをそれぞれ書いても、信頼できる差分マージにはなりません。パーサーによっては重複キーを拒否し、別のパーサーでは一方だけを残すことがあります。DNS項目を追加する場合は、同じマッピング内を編集してください。リストの項目も名前で自動マージされません。同名のグループを2つ定義すると、候補ノードが結合されるのではなく競合するのが一般的です。設定が長くなるほど、定義箇所を一つに定め、ほかから参照するルールが重要になります。

元の設定、リソースファイル、実行時設定を区別する

クライアントは通常、サブスクリプションの原文、プロバイダーのキャッシュ、オーバーライドの断片、コアに渡す実行時設定をそれぞれ管理します。画面に表示されるファイルが最終設定とは限らず、キャッシュを編集しても次回の更新で上書きされることがあります。変更前に、選択中の設定名を記録し、個人情報を含まない構造のバックアップをエクスポートして、編集対象がサブスクリプションの原文か永続オーバーライドかを確認してください。クライアントをインストールする場合はClash Plusを選び、実際のプラットフォームで設定編集画面と実行ログの場所を確認できます。

ファイルの分割は保守性を高めるためのもので、YAMLに任意のファイルを読み込む機能が備わっているわけではありません。includeを独自に追加して、コアがディレクトリを読み込むと期待しないでください。ノードやルールの分割には、対応するプロバイダー機能を使います。共通設定の再利用には、クライアントが明示的に提供するマージ機能が必要です。相対パスは通常、作業ディレクトリを基準とし、編集中のファイルの場所を基準にするとは限りません。別の端末へ移行するときは、メイン設定に加え、リソースのパス、書き込み権限、クライアントが生成するディレクトリも確認してください。

待受ポート、モード、コントロールインターフェース

入口プロトコルと待受アドレス

portはHTTPプロキシの入口、socks-portはSOCKSの入口です。mixed-portは同じポートでHTTPとSOCKSのリクエストを受け付けます。通常は混合ポートを1つ選べばよく、入口ごとに待受を有効にする必要はありません。アプリがプロキシアドレスを明示的に使用して初めて、接続がこれらのポートに入ります。待受を開始しただけでは、システムの通信は自動的に取り込まれません。クライアントのシステムプロキシ設定はOSとの連携機能で、TUNは別の接続方式です。ポートの有無だけで判断しないでください。

allow-lan: falseは、この端末だけで使う場合に適しています。LANアクセスを有効にする場合は、bind-address、OSのファイアウォール、ネットワーク分離ポリシーがほかのデバイスからの接続を許可しているかも確認してください。ループバックアドレスで待ち受けるサービスには、別の端末から接続できません。すべてのアドレスで待ち受けても、ファイアウォールが通信を許可したことにはなりません。単一アプリの問題を調べるために、端末全体の公開範囲をすぐに広げないでください。まず端末内から入口に接続できることを確認し、必要に応じて段階的に開放します。

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

# 管理インターフェースはローカルのみで待受。認証情報はローカルで個別に設定
external-controller: "127.0.0.1:9090"

実行モードとログの詳細度

mode: ruleはルールリストに基づいて宛先を選び、globalは接続をグローバルポリシーに渡し、directは直接接続します。ルールファイルが正しくても、画面上でグローバルモードになっていれば、ルールは想定どおり選択に使われません。クライアントによってはAPI経由で前回のモードを復元するため、ディスク上の初期値と画面上の現在の状態が異なる場合があります。ルーティングがおかしい場合は、まず実行モードを確認し、次にルールの順序を見直してください。すべてのルールをすぐにプロキシへ変更するのは避けましょう。

log-levelはログの詳細度を指定します。通常はinfoのままにし、解析、接続、リソース読み込みを追跡する必要がある場合だけ一時的にdebugへ切り替えてください。詳細ログにはドメイン名、宛先アドレス、リクエストの情報が含まれることがあります。共有する前に、サブスクリプションURL、アカウント項目、その他の個人情報を削除してください。調査が終わったら元のレベルに戻し、不要なアクセス情報を長時間記録しないようにします。ログに接続記録があっても、通信が特定の処理段階に到達したことを示すだけで、リクエスト全体の成功を直接証明するものではありません。

管理APIと実行環境の制約

管理インターフェースはグループの切り替え、接続情報の取得、実行状態の変更ができ、通常のプロキシ入口とは権限が異なります。ローカルクライアントから呼び出せるよう、ループバックでの待受を推奨します。別の端末から管理する必要がある場合は、専用の認証情報を設定し、接続元アドレスを制限したうえで、信頼できるネットワーク内で使用してください。認証情報を公開リポジトリに保存したり、管理URL全体をスクリーンショットで公開したりしないでください。画面を開けない場合は、まずコントロールアドレスとクライアント側の設定が一致しているかを確認し、次にポート競合とコアの終了状態を調べます。

ポート番号自体に固定の特別な意味はなく、例の数値は変更できます。ただし、アプリ、システムプロキシ、クライアントの設定をすべて一致させる必要があります。複数のプロキシプログラムを同時に起動したときは、ポートの競合、システムプロキシ設定の上書き、仮想ルートの競合がよく起こります。調査中は通信を取り込む仕組みを1つだけ有効にし、接続経路を確認してからほかのツールを戻してください。Linuxのサービスでは実行ユーザー、作業ディレクトリ、ファイル権限も確認します。デスクトップクライアントで正常に動く設定でも、システムサービスから同じファイルを読み込んだときに同じリソースを参照できるとは限りません。

ipv6は単なるネットワーク高速化のスイッチではありません。有効にするかどうかは、ローカルネットワーク、ノードの出口、DNSの応答を踏まえて判断してください。コアのIPv6対応を無効にしても、OSのファイアウォール設定の代わりにはならず、IPv6で直接接続される問題をすべて解決できるわけでもありません。アプリがプロキシ入口を経由せずに接続している場合は、まず通信を取り込む範囲を見直してから、アドレスファミリーを検討します。システムプロキシの不具合、ポート競合、LAN接続の問題はFAQ・トラブル対処も確認してください。

プロキシノードの項目とプロトコルごとの違い

ノードオブジェクトの基本構成

proxiesの各オブジェクトは1つの出口を表します。すべてのノードに参照用のnameが必要で、プロトコルはtypeで決まります。serverとportにはサーバーの待受アドレスを指定します。認証方式、暗号化方式、トランスポート、TLSの設定はプロトコルによって異なるため、異なるプロトコル間で機械的にコピーできません。名前は接続パラメーターではありませんが、グループから参照する識別子です。ノード名を変更したら、手動管理のグループやルールの宛先など、直接参照している箇所もすべて更新してください。

以下ではShadowsocksを例に構造を示します。サーバーには予約済みのサンプルドメインを使用し、パスワードは説明用のダミー値です。接続するには、サービス提供元が指定した値に置き換えてください。ポート番号やプロトコル名だけから、パスワード、暗号化方式、トランスポートを推測しないでください。サブスクリプションにノードの設定がすべて含まれている場合は、上流の項目をそのまま維持するのが基本です。意味を確認してから必要な箇所だけ変更してください。トランスポート設定を誤って削除すると、構文上は正しくてもハンドシェイクに失敗する設定になりかねません。

proxies:
  - name: サンプル出口
    type: ss
    server: proxy.example.com
    port: 443
    cipher: chacha20-ietf-poly1305
    password: "your-password"
    udp: true

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

トランスポートとTLSの項目は使い回せる汎用部品ではない

TLSを使用するプロトコルでも、項目名が異なる場合があります。ノードによってはservernameでハンドシェイク名を指定し、別のプロトコルではsniを使用します。tlsの有効化が必要か、特定のトランスポート設定に対応しているかは、そのプロトコルのコアのドキュメントで確認してください。サーバーアドレスにはドメイン名とIPアドレスのどちらも指定できますが、証明書は通常ドメイン名に対応しています。ドメイン名をIPアドレスに置き換え、正しいハンドシェイク名を保持しないと、サーバーが停止しているのではなく証明書名の不一致が起きることがあります。

WebSocket、HTTP/2、gRPCなどのトランスポートでは、パス、Hostヘッダー、サービス名も関係します。これらはサーバー側の仕様の一部であり、自由に省略できる補足情報ではありません。トラブル時は、プロトコル、アドレス、ポート、認証、トランスポートの順に確認し、その後で証明書とネットワーク到達性を調べます。証明書検証を無効にするのは通常の解決策ではありません。サーバーの身元を確認する能力が低下するうえ、パスワードやパスの間違い、サーバー側で該当プロトコルが有効になっていない問題は解決できません。

UDP、名前解決、ノードの更新

udp: trueは、該当プロトコルが対応している場合にUDP転送を許可する設定です。UDPに対応していないサーバーに機能を追加するものではありません。アプリもUDP対応の入口からコアに接続し、出口の経路でも該当トラフィックが許可されている必要があります。Webサイトは見られるのにゲームや音声通話が使えない場合は、入口、グループで選択中のノード、リモート側の対応状況をそれぞれ確認してください。HTTPのテスト結果だけで判断しないでください。反対に、ノードのテストに成功しても特定サイトへ接続できない場合は、ノードではなくルールが誤った出口を選んでいる可能性があります。

serverにドメイン名を指定した場合、ノードへの接続前に名前解決が必要です。プロキシ経由でWebサイトにアクセスするときの宛先ドメインの名前解決とは別の段階です。ノード名を解決するDNSリクエストが、まだ確立していないプロキシに依存すると、起動時の依存関係が循環します。プロキシサーバーのドメイン専用に名前解決先を設定すると、初期接続経路を明確にできます。詳しくは後述のDNSの章をご覧ください。まずノードサーバーのアドレスを正しく解決できることを確認してから、接続先サイトの名前解決方針を調べます。

サブスクリプションの更新でノード名や数が変わることがあります。手動のグループにノードを1つずつ列挙していると、上流で削除や改名があった際に参照切れが起きます。動的なサブスクリプションでは、プロバイダーのノード集合をuseで取り込む方法が適しています。サブスクリプションの内容を確認するときは、個人情報を伏せた単一ノードの構造だけをエクスポートして比較し、サブスクリプションURL全体を公開しないでください。ノード一覧、完全なYAML、URIリンクはそれぞれ形式が異なります。形式の見分け方はサブスクリプション形式の違いと変換方法を参照し、エンコードされたテキストをそのままproxiesに貼り付けないようにしてください。

プロキシグループと出口の選択

固定のグループ名と変動するノード集合

プロキシグループを使うと、ルールと個別ノードを切り離せます。ルールは長期にわたって出口選択を参照し、ノードの変更はグループ内で行えるため、ルールを1つずつ直す必要がありません。グループ名、ノード名、組み込みの宛先はいずれも参照対象となるため、名前の重複を避け、DIRECTやREJECTと混同しやすい名前も使わないでください。リスト内のproxiesは明示的な宛先、useはノードプロバイダーへの参照です。意味が異なるため、プロバイダー名をノード名として指定することはできません。

selectはユーザーが出口を選択し、url-testはプローブ結果に基づいて候補を選びます。fallbackはリスト順に利用可能な出口を探し、load-balanceは指定した方式で接続を振り分けます。自動選択でも、すべての通信を比較して最適な経路を選ぶわけではありません。プローブURLが示すのは、ある時点で特定の宛先へ到達できるかどうかです。アクセス先、プロトコルの種類、サーバー側の制限が異なれば、実際の通信とプローブ結果が一致しないこともあります。

# 前の章の「サンプル出口」ノードと組み合わせて使用
proxy-groups:
  - name: 出口選択
    type: select
    proxies:
      - 自動選択
      - サンプル出口
      - DIRECT

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

rules:
  - MATCH,出口選択

プローブ間隔、許容差、フェイルオーバー

intervalは秒単位でプローブ間隔を指定します。toleranceは、対応する自動選択グループで切り替えの許容差をミリ秒単位で指定します。許容差を設定すると小さな変動による頻繁な切り替えを減らせますが、リモート側の混雑を解消するものではありません。間隔を短くするとリクエスト数が増え、端末のスリープ解除も増えるため、特にモバイル端末ではバッテリー消費やネットワーク切り替えを考慮してください。プローブ先には、ログインを必要とせず、安定して予測可能な応答を返すURLを指定します。プローブ先自体に到達できないと、候補全体が利用不可と誤判定される可能性があります。

フェイルオーバーグループでは、リストの順番が通信の動作に関わります。先頭の宛先が常に最速なのではなく、利用可能と判定された場合に優先されます。ロードバランシングも通常は接続単位の振り分けであり、1回のダウンロードを複数ノードに分割して帯域を合算するものではありません。ログイン状態や送信元アドレスの維持が必要なサービスでは、出口をまたぐ振り分けは慎重に行い、アドレスの変化が許容されるかを事前に確認してください。ルールの宛先を切り替えても、既存のTCP接続は通常新しい出口へ移行しません。検証時は新しい接続を確立してください。

グループの入れ子参照と選択状態

グループは別のグループを参照できますが、出口に到達する有向関係になっている必要があります。グループAがグループBを参照し、BがAを参照すると循環依存になります。画面で保存できても、実行時に設定が拒否されたり、有効な出口を選べなかったりする場合があります。保守時は最終ルールの宛先から下へ追跡し、具体的なノードまたは組み込みの宛先に到達して、各経路が確実に終端することを確認してください。グループの階層を深くしすぎると、画面の最初の選択だけでは実際の接続先を説明できなくなります。

クライアントは手動選択を保存し、再起動や更新後に復元する場合があるため、リストの先頭が現在の出口とは限りません。profile.store-selectedなどの永続化機能も復元動作に影響します。クライアントによっては独自の状態ファイルに選択内容を保存します。グループが機能しているか判断するときは、グループの現在の選択項目と、接続記録にある経路全体を併せて確認してください。YAMLの順番だけで判断しないでください。グループ名を変更した場合、以前の選択が対応しなくなることがあるため、改めて確認してください。

ノード集合が空の場合、自動選択グループが利用可能な出口を生成することはできません。フィルター式を使う場合は候補が残っているか確認してください。上流の命名規則が変わったときは特に注意が必要です。手動グループに直接接続を含めるべきかは用途次第です。プロキシ出口を固定する必要があるサービスでは、直接接続を確認なしの代替経路として扱わないでください。ルールのテスト、ポリシーの確認、サービスへの接続検証を分けて行えば、候補不足、プローブ失敗、選択状態の復元異常、リモートサービスのアクセス制限を切り分けられます。

ルール構文とマッチ順序

最初に一致したルールで処理先が決まる

rulesは順序のあるリストです。コアは上から順に確認し、一致した時点でそのルールの宛先を使用して処理を終えます。より具体的なドメインや例外ルールは広い条件より前に置き、MATCHは最後のフォールバックとして末尾に置いてください。ルールに「最長プレフィックス優先」や「ドメインルールがIPルールより常に優先」といった全体的な自動ソートはありません。実際の優先順位はファイル内の順番です。広範囲に一致するルールを前に置くと、後続のルールに到達できなくなることがあります。

多くのルールは「種類、マッチ対象、宛先」の形式です。DOMAINはドメイン名と完全一致し、DOMAIN-SUFFIXはドメイン自体とサブドメインに一致します。DOMAIN-KEYWORDはドメイン内のキーワードを確認します。IP-CIDRとIP-CIDR6は宛先アドレスの範囲に一致し、GEOIPとGEOSITEは対応する地理情報またはサイト情報のデータを使用します。PROCESS-NAMEはプロセス識別機能に依存するため、すべてのプラットフォームや入口で使えるとは限りません。

rules:
  - DOMAIN,login.example.com,出口選択
  - DOMAIN-SUFFIX,example.com,DIRECT
  - DOMAIN-KEYWORD,example,出口選択
  - IP-CIDR,127.0.0.0/8,DIRECT,no-resolve
  - IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
  - IP-CIDR,172.16.0.0/12,DIRECT,no-resolve
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - IP-CIDR6,::1/128,DIRECT,no-resolve
  - MATCH,出口選択

この例ではログイン用ドメインが先にプロキシへ一致し、そのほかのドメインサフィックスは直接接続になります。キーワードルールが判定するのは、先の2つに該当しなかった場合だけです。例のドメインはルール順を説明するためのもので、実際のサービスに対する経路設定を推奨するものではありません。ネットワーク範囲のルールにあるno-resolveは、そのIPルールのためにドメイン名を積極的に名前解決しない設定です。接続に宛先IPがすでにある場合は、そのIPを使って引き続き判定できます。すべてのDNSリクエストを禁止するスイッチではなく、後続の名前解決を必要とするルールを無効にするものでもありません。

ドメイン、アドレス、プロセス情報が常に揃うわけではない

入口によって取得できる情報は異なります。HTTPプロキシのリクエストでは通常、宛先のホスト名を取得できます。一方、名前解決後のIPアドレスしかプロキシに渡さないアプリでは、コアが元のドメイン名を把握できない場合があります。TUN、fake-ipのマッピング、スニッフィングで情報を補えることもありますが、それぞれ適用範囲に制約があります。ドメインルールが一致しない場合は、まず接続情報でコアが実際に何を取得しているかを確認し、その後で名前解決やスニッフィングの設定を検討してください。ドメイン情報がそもそも判定処理に入っていなければ、ドメインルールを増やしても解決しません。

データベースを使うルールと拒否先

地理情報を使うルールでは、実際に読み込まれているデータの形式とファイルパスを確認してください。GEOSITEの分類名はデータベースで定義されており、任意のラベルを指定できるわけではありません。GEOIPの判定もデータの更新状況やIPアドレスの帰属変更に左右されます。IPアドレスの所在地をサービス所有者の所在地と同一視したり、コンテンツが必ず特定地域から配信されると推測したりしないでください。データベースの読み込み失敗、分類の不存在、ルール順の誤りはそれぞれ別の問題です。調査方法はGeoIP・GeoSiteデータベースの更新方法をご覧ください。

REJECTは接続を拒否する宛先で、明確に遮断したい範囲に使用します。範囲の広すぎるキーワードルールを拒否先に向けると、ログイン、認証コード、静的リソースまで影響することがあります。テストではまず対象を絞り、ルールの一致記録を確認してください。ルールの宛先にはノードやグループも指定できますが、実在する必要があります。表記の違い、末尾の空白、グループ名の変更などで参照エラーが起こることがあります。マッチ条件だけでなく、宛先も確認してください。

変更を検証するときは対象を1つに絞り、モード、リクエストのドメイン、一致したルール、最終出口を記録したうえで、1箇所だけ変更して新しい接続を確立してください。ブラウザーの接続プール、HTTP/2の接続再利用、アプリの長時間接続では、古い接続が使われ続けることがあります。ページを再読み込みしてもルール判定が再実行されるとは限りません。必要に応じて対象の接続を閉じて再テストしますが、「すべての接続を閉じる」ことを日常的な操作にしないでください。ルールが処理できるのは、コアに入った通信だけです。接続一覧に対象のリクエストがまったくない場合は、入口と通信を取り込む範囲から確認してください。

DNS、fake-ip、TUNによる通信の取り込み

リゾルバーの役割と起動時の依存関係

dns.enableはコアのDNS機能を有効にし、listenは待受アドレスを指定します。nameserverは通常のリゾルバー一覧、default-nameserverはDNSサーバー自体のドメイン名を解決するための設定、proxy-server-nameserverはプロキシサーバーのドメイン名を解決するための設定です。3つは異なる段階を担うため、応答が速いという理由だけで一律に置き換えないでください。特に、暗号化DNSの接続先にドメイン名を指定する場合、起動時に依存関係が循環しないよう、先に動作する初期解決経路が必要です。

enhanced-mode: fake-ipはドメイン名に対応するマッピング用アドレスを割り当てます。後続の接続がコアに届いたときに、この情報を使って元のドメイン名を復元できます。これはリモートサーバーの実アドレスではなく、Webサイトがそのアドレス範囲でホストされていることを示すものでもありません。アプリがコアを経由せずにマッピング用アドレスへ接続すると、通常は通信できません。そのためDNSの応答と通信の取り込みを連動させる必要があります。LAN内のデバイス検出、特定の機器プロトコル、実アドレスを確認するアプリでは、必要に応じてfake-ip-filterを設定できます。ただし、すべてのドメインを除外したまま、同じマッピング効果を期待することはできません。

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"
    - "localhost"
  default-nameserver:
    - 1.1.1.1
  nameserver:
    - https://dns.cloudflare.com/dns-query
  proxy-server-nameserver:
    - https://dns.cloudflare.com/dns-query

名前解決の方針は出口ルールの代わりにならない

nameserver-policyはドメインごとに使用するリゾルバーを選択します。これは名前解決の結果をどこから取得するかを決めるもので、通信がどの出口を通るかを直接決める設定ではありません。fallbackとfallback-filterは予備の名前解決先と結果のフィルタリングに使われます。「最初のDNSが失敗した場合だけ、2番目へ順番に問い合わせる」と単純に解釈することもできません。実際の動作はフィルター条件によるため、設定前に期待する応答を明確にしてください。名前解決経路、DNS通信の出口、実際の通信先の出口は、関連はありますが別々の問題です。DNSの結果を1つ見るだけで判断しないでください。

暗号化DNSが保護するのはクライアントとリゾルバー間の通信です。HTTPSのURLを使っているだけでDNS漏えいがないとは判断できません。OS、ブラウザー、アプリがそれぞれ別のリゾルバーを使うことがあります。ブラウザー内蔵の暗号化DNSリクエストも、通常のHTTPS接続としてネットワークに送られ、コアの待受ポートを通らない場合があります。リクエストの発信元、コアに入っているか、最終的にどのポリシーを通るかを確認してください。項目ごとの役割はnameserver、fallback、fake-ipの解説もご覧ください。

TUNのルーティング、権限、通信を取り込む範囲

TUNは仮想ネットワークインターフェースで通信を受け取り、システムプロキシを参照しないアプリに適しています。通常は管理者権限またはOSの該当機能が必要で、ルーティング設定、デバイスインターフェース、コアのネットワークスタックの対応も求められます。有効にしても、あらゆるネットワーク通信が取り込まれるわけではありません。仮想マシン、コンテナ、別のVPN、特定のインターフェースにバインドされたアプリなどには独自の経路がある場合があります。複数の自動ルーティングツールを同時に起動して試すのではなく、まず1つの設定に絞り、インターフェースとルートが正常に作成されたか確認してください。

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

dns-hijackは、通信を取り込む範囲内の従来型DNSリクエストをコアのDNS機能に渡します。暗号化DNSの通信をすべて識別して解読する機能ではありません。上記の設定例は、有効にしたdnsと組み合わせる必要があります。実際の対応状況はプラットフォーム、ルーティング、ファイアウォールによって異なります。auto-detect-interfaceは出力インターフェースの自動選択を試みますが、複数のネットワークインターフェース、ネットワーク切り替え、別のトンネルがある場合は選択結果を確認してください。デフォルトの出口が誤っていると、ノードへの接続が仮想インターフェースに戻され、異常な経路になることがあります。

fake-ipモード、マッピング範囲、DNSの取り込み方法を変更すると、アプリやOSのキャッシュに古い結果が残ることがあります。テスト接続を新しく作成し、必要に応じて該当するキャッシュを消去して、コアのマッピングが再起動で失われていないか確認してください。一部のアプリだけ失敗する、LAN内のドメインに問題がある、スリープ復帰後に接続できない場合は、名前解決経路とルートの変化を個別に比較します。DNS機能を恒久的に無効にしないでください。DNS漏えいの確認と対処を参考に再テストし、変更前後の設定を保存して元に戻せるようにしてください。

ノードサブスクリプションとルールプロバイダー

リモートリソースの定義と実際の参照

proxy-providersを使うと、ノード集合をメイン設定から分離でき、上流で定期更新されるサブスクリプションに適しています。プロバイダーには、リソースの取得元がHTTPかローカルファイルか、保存先、更新間隔を指定します。プロキシグループからuseでその集合を取り込みます。プロバイダーを定義しただけでは、グループが参照しない限り、ルールでノードを自動選択することはできません。完全な設定のサブスクリプションと比べ、ノードプロバイダーはローカルのポリシーやルールを保持したまま、上流からノード情報だけを更新できます。更新の影響範囲を小さくできる点が利点です。

以下のURLには例示用ドメインを使用しています。実際に利用する場合は、ローカルで自分のリソースアドレスに置き換えてください。リモートのノードファイルは通常、トップレベルキーにproxiesを持つノードリストである必要があります。任意のWebページ、Base64テキスト、変換前のURI一覧をそのまま指定することはできません。クライアントによっては形式変換に対応していますが、これはクライアントの機能であり、すべてのコアが任意の形式を受け付けるわけではありません。返された内容の形式を確認してから、プロバイダーを使うか、完全な設定をインポートするかを決めてください。

proxy-providers:
  上流ノード:
    type: http
    url: "https://example.com/proxies.yaml"
    path: ./providers/upstream.yaml
    interval: 3600
    health-check:
      enable: true
      url: https://www.gstatic.com/generate_204
      interval: 300

proxy-groups:
  - name: 出口選択
    type: select
    use:
      - 上流ノード
    proxies:
      - DIRECT

ルールプロバイダーの動作と形式

rule-providersはルール集合を管理し、メインのルール一覧からRULE-SETで参照します。behaviorは集合の解釈方法を表します。domainはドメイン集合、ipcidrはIPアドレス範囲、classicalは複数種類の従来型ルール条件を扱います。formatはYAMLやテキストなど、リソースの形式を指定します。動作と形式は別の属性です。ファイル拡張子がYAMLだからといって、完全なクラシックルールが含まれているとは限りません。

rule-providers:
  ローカル直接接続ドメイン:
    type: file
    behavior: domain
    format: yaml
    path: ./rules/direct.yaml

rules:
  - RULE-SET,ローカル直接接続ドメイン,DIRECT
  - MATCH,出口選択

対応するrules/direct.yamlには、以下の構造を使用できます。ドメイン集合の+.example.comは、そのドメインとサブドメインをまとめて照合する表現です。メインのルール一覧に1つのルールとしてそのまま記述するものではありません。クラシックルール集合には通常、宛先を付けずにマッチ条件を記述し、参照元のRULE-SETで出口を決めます。2種類の構文を混在させると、読み込みに失敗したり、想定と実際の対象範囲が食い違ったりすることがあります。

# rules/direct.yaml
payload:
  - "+.example.com"
  - "localhost"

更新間隔、キャッシュ、アクセス経路

リソースの更新間隔と稼働状況の確認間隔は別々です。前者は新しいノードやルールをダウンロードし、後者は既存の候補が利用可能かを検査します。更新間隔を変更しても、すぐに更新が実行されるとは限りません。リソースの更新時刻、ログ、現在の集合を確認してください。ダウンロードリクエストには初期のネットワーク経路も必要です。リソース取得にプロキシが必要なのに、そのノードがまだダウンロードされていない同じリソースにしか存在しない場合、起動時に行き詰まります。再起動を繰り返すのではなく、利用可能なキャッシュを保持するか、初回の取得方法を明確にしてください。

pathには書き込み可能な作業ディレクトリを指定し、プロバイダーごとに異なるファイルを割り当ててください。複数のプロバイダーでキャッシュパスを共用すると内容が上書きされます。デスクトップ環境からサービス環境へ移行すると、作業ディレクトリの変更でファイルが見つからなくなることもあります。リソースの取得に失敗したときに古いキャッシュを使い続けるかどうかは、現在のクライアントとコアのログで確認してください。失敗時に常に安全に前の内容が保持されると決めつけないでください。重要なルールには復元用のコピーを用意し、リモートリソースの一時的な障害で全体の読み込みに影響しないようにします。

サブスクリプションURLにはアカウント識別情報が含まれることが多いため、完全なURLは個人用のアクセス認証情報として扱ってください。設定を共有するときは、URL、認証ヘッダー、ノードの認証項目をまとめて伏せます。パラメーター付きのURLを公開スクリーンショットや問い合わせに載せないでください。更新結果がHTMLページだった場合は、ログイン画面へのリダイレクト、URLの期限切れ、HTTPステータスをまず確認します。ページの内容をYAMLの誤りとして一字ずつ修正しないでください。上流の形式が正しいと確認した後で、ローカルのプロバイダー項目、参照名、キャッシュパスを調べると、誤った層を何度も編集せずに済みます。

オーバーライドのマージと実効設定の検証

最終ファイルを生成する仕組みを把握する

オーバーライドは、クライアントが元の設定と実行時設定の間で行う処理です。すべてのクライアントに共通するコアの構文ではありません。一般的な処理では、サブスクリプションを読み込み、共通設定を適用し、オーバーライドやスクリプトを実行した後、実行用ファイルを生成します。実際の順序は使用中のクライアントで確認してください。override.yamlをディレクトリに置いただけで自動的に有効になるわけではなく、クライアントによる明示的な読み込みが必要です。更新後に変更が消えた場合は、生成済みファイルを繰り返し編集するのではなく、編集画面と処理順を確認してください。

スカラー値の上書き、マッピングの再帰的マージ、リストの連結は、それぞれ異なる操作です。modeをグローバルからルールに変更するのは、通常スカラー値の置き換えです。dns.nameserverだけを変更した場合にほかのDNS項目が残るかどうかは、深い階層までマージするかによります。rulesの変更では、リスト全体が置き換わる場合もあれば、先頭や末尾に追加される場合もあります。クライアントが「マージ」と呼んでいても、3種類のデータに同じ処理が使われるとは限りません。小さな断片で結果を確認してから変更範囲を広げてください。

# クライアントのオーバーライド入力専用。マージ方法はクライアントで確認
mode: rule
log-level: info

dns:
  enable: true
  enhanced-mode: fake-ip

profile:
  store-selected: true

リスト操作ではルール全体の意味を保つ

ルールの先頭への追加と末尾への追加では結果が異なります。例外ルールをMATCHの後ろに追加しても一致しません。新しいフォールバックルールを先頭に置くと、既存のリストが後から判定されなくなります。グループも名前だけを見てマージできるとは限りません。同名のオブジェクトを追加すると競合する可能性があり、既存オブジェクトを置き換えるとプロバイダーへの参照が失われることがあります。オーバーライドを設計する前に、「末尾のフォールバックより前にLAN向けの例外を挿入する」など、期待する変更を明確にしてください。そのうえで、クライアントが該当操作に対応しているかを確認します。見た目が似たYAMLを先に作ってはいけません。

クライアントがスクリプトによるオーバーライドを提供している場合は、スクリプトと変更内容の説明をローカルに保管し、出所不明の処理をそのまま実行しないでください。スクリプトは設定全体を読み取ったり変更したりすることがあり、通常の項目上書きより影響範囲が広くなります。必要なキーだけを操作し、対象オブジェクトがない場合やリストが空の場合も処理できるようにして、変更後もほかの項目を保持するのが安全です。別のクライアントに移行するときは、期待する設定結果とデータファイルを優先して移してください。元のクライアントのスクリプトAPI、変数名、マージ順がそのまま使えるとは限りません。

静的チェックから実際の通信経路の検証まで

単体で動作するコアでは、設定テストコマンドを使って構造や参照を確認できます。以下のコマンドは現在のディレクトリを作業ディレクトリとし、config.yamlを読み込みます。実行ファイル名やディレクトリは、実際のインストール先に合わせてください。デスクトップクライアントには通常、設定チェックやログの画面があります。待受ポートを競合させる別のコアを起動する必要はありません。テストに成功しても、確認できるのはチェック段階だけです。アカウントの有効性、リモートサービスの状態、システムプロキシ、TUNの権限、各アプリの実際の通信経路までは検証できません。

mihomo -t -d . -f ./config.yaml

変更前に動作している設定を保存し、適用後は元の設定ファイルが保存されているかだけでなく、実行時ファイルの重要な項目も確認してください。その後、新しいテスト接続を作り、入口、モード、一致したルール、プロキシグループの経路、出口を順に確認します。DNS関連の変更では、名前解決の結果とキャッシュが使われているかも調べてください。確認項目を分けて記録すると、問題が読み込み段階、リソース段階、実際のアクセス段階のどこにあるかを特定できます。「インターネットに接続できない」という症状が同じでも、対処方法はまったく異なります。

設定を元に戻すときは、ファイルと実行時の状態の両方を確認してください。以前のファイルを復元した後も、現在のモード、手動グループの選択、DNSキャッシュ、TUNのルートに新しい状態が残っていないかを確認します。一度に変更する動作は1種類に絞り、短い変更履歴を残すと、ノード、DNS、ルールを同時に入れ替えるより原因を特定しやすくなります。初期設定に戻る場合はクイックスタートガイドに沿って基本の通信経路を確認できます。個別の問題はよくある質問をご覧ください。このリファレンスは項目同士の関係を説明するもので、あらゆるネットワークで使える固定の設定値を提供するものではありません。