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

1. YAMLの構造と設定の読み込み範囲

設定ファイルは、型と階層を持つデータであり、行ごとに実行されるコマンドの集まりではありません。トップレベルの mixed-port は待ち受けポート、dns はマッピング、proxies、proxy-groups、rules は通常リストです。カーネルはまずデータを解析し、待ち受けを開始してからプロキシとプロキシグループを解析し、最後に接続を受け付けます。そのため、設定項目の記述順と起動手順は一致しません。ただし、ルールリスト内の順序はマッチ結果に影響します。

インデント・型・名前の参照

インデントには半角スペース2つを使い、タブは使わないでください。同じ親要素の項目は位置をそろえます。リスト項目の先頭にあるハイフンは、新しい要素を示す記号です。enable を dns と同じ階層に書くと、項目の所属先が変わります。また、rules をプロキシグループの内側にインデントしても、期待するトップレベルのルールにはなりません。文字の見た目だけで判断するより、エディターのインデントガイドを使うほうが確実です。

真偽値は true または false、ポート番号や時間間隔は通常、整数で指定します。ノード名、パスワード、特殊文字を含む文字列には引用符を付けるのがおすすめです。特に、コロンの後に空白が続く場合、シャープ記号を含む場合、先頭にゼロがある場合は注意してください。引用符を付けても、インデントの誤りは直りません。また、リストがマッピングに変わるわけでもありません。エラーが出たら、まず構造を確認し、その後に値の型を確認します。

プロキシとプロキシグループは名前で相互参照します。名前に含まれる空白、大文字・小文字、日本語の句読点もそのまま識別に使われます。"手動選択" と "手動 選択" は別の名前です。ルールを追加する前に参照先の名前が存在することを確認し、ノードを削除する前に、どのプロキシグループから参照されているか検索してください。名前の重複も解消しておきましょう。画面上の表示と実際の解析結果を対応させにくくなることがあります。

起動できるローカル環境の基本設定

以下の設定ではローカルの混合プロキシポートだけを用意し、すべての通信を直接接続します。ファイルの読み込み先、ポートの待ち受け、ルールの解析が正常かを確認するための設定であり、リモートプロキシ機能はありません。テスト時はブラウザーにローカルの混合ポートを設定するか、一時的にクライアントのシステムプロキシを有効にしてください。「カーネルの起動に成功した」ことと「リモートノードに接続できた」ことは別です。

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

proxies: []

proxy-groups:
  - name: "手動選択"
    type: select
    proxies:
      - DIRECT

rules:
  - MATCH,手動選択

まず検証済みの基本設定を保存し、実際のノード、自動テスト用グループ、DNSを一つずつ追加してください。変更の種類ごとに再読み込みしてログを確認すれば、問題の範囲を直近の変更に絞れます。設定全体を一度に置き換えると、構文、ネットワーク、参照関係、クライアントによる上書きの問題が同時に発生し、原因の特定に時間がかかります。

YAMLのマッピングでは、同じキーを重複して定義しないでください。ファイルの前半と後半にそれぞれ dns があっても、2つの設定が自動で統合されるわけではありません。解析器によっては重複キーを拒否する場合も、後の値を採用する場合もあります。この動作に依存すると、クライアントごとに結果が異なる可能性があります。設定を統合する場合は、生成段階でトップレベルのキーを一つにまとめてください。

元ファイルと実行時ファイルを区別する

サブスクリプションから取得した原文、ユーザーが編集した設定、クライアントが生成した実行時設定は、別々のファイルである場合があります。クライアントは起動前にコントローラーを追加したり、ポートを書き換えたりすることがあります。そのため、実行用フォルダー内のファイルを手動で編集しても、次の更新で上書きされる可能性があります。クライアントが用意するローカル設定、拡張設定、上書き機能を優先し、その適用範囲も確認してください。

設定エラーの行番号が示すのは、カーネルが実際に読み込んだファイルです。サブスクリプションの原文とは限りません。参照先の欠落や項目の不一致が起きたら、クライアントで現在有効な設定名と実行時設定の内容を確認してください。トラブル対応用の情報を共有する前に、サブスクリプションURL、ノードのパスワード、コントローラーのシークレットを削除します。問題の再現に必要な構造だけを残し、実行時ファイル全体を公開しないでください。

2. 共通項目・待ち受けポート・動作モード

共通項目では、どこからカーネルに通信を取り込むか、またカーネルがどのように処理するかを指定します。リモートノードを作成する項目ではなく、すべてのアプリのネットワーク設定を自動で変更するものでもありません。トラブル時は「カーネルが待ち受けている」「システムプロキシが設定されている」「アプリがシステムプロキシを利用している」の3つを切り分けてください。入口の問題をノード障害と取り違えずに済みます。GUIクライアントのスイッチとYAMLの項目は関連する場合がありますが、同じ階層の設定ではありません。

ポートと待ち受け範囲の選び方

混合ポートは複数のアプリで一つの入口を共有する場合に便利です。独立したポートはHTTPとSOCKSの接続を分けて管理できます。必要がなければ、すべての入口を有効にする必要はありません。同じアドレス上で、複数の待ち受けプロセスが同じポートを使うことはできません。ポートの競合は、別のプロキシソフト、終了していない旧カーネルプロセス、バックグラウンドで動作中のクライアントが原因の場合もあります。現在の設定ミスとは限りません。

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

同じデバイス内で使う場合は、ループバックアドレスだけで待ち受ける設定を優先してください。スマートフォンや別のPCからこのデバイス経由で接続する必要がある場合に限り、LANからの接続を許可し、ネットワーク範囲に応じてファイアウォールとアクセス認証を設定します。allow-lan を true にするだけでは、ほかのデバイスから接続できるとは限りません。ファイアウォールを開放しただけでも、ループバックアドレスにバインドされたサービスは外部接続を受け付けません。

ルール・グローバル・ダイレクトモード

mode: rule は rules を上から順に照合するため、日常的な通信の振り分けに適しています。global はグローバル用のプロキシグループで接続先を選び、通常のルールリストでは接続先を決定しません。direct は直接接続するモードです。画面でモードを切り替えても、クライアントがコントローラー経由で実行状態を変更している場合、設定ファイルの mode は更新されないことがあります。現在の画面表示と接続ログを確認してください。

グローバルモードにしても、カーネルを経由していない通信は修正できません。あるアプリがシステムプロキシを使わず、ルールモードで接続ログにも表示されない場合、グローバルモードに切り替えてもログが表示されないことがほとんどです。まずアプリ独自のプロキシ設定を確認し、必要な場合にTUNを使ってください。一方、通信がすでにカーネルに届いていて、ダイレクトルールにマッチしている場合は、モードとルールの順序を調べます。

log-level はログの詳細度を変える項目で、通信の振り分けには影響しません。通常は info に設定し、原因を特定しにくい問題を再現するときだけ一時的に debug に切り替えてください。調査後は元に戻します。詳細ログにはドメイン、接続先、アクセス時刻が含まれる場合があります。保存や共有の範囲には注意してください。タイムアウトのログが一つあっても、すべての通信が失敗しているとは限りません。ノードとのハンドシェイク、DNS、ヘルスチェックのどれに関するログかを確認します。

コントローラーと状態の保存

external-controller はコントローラーの接続先であり、ブラウザーに設定するプロキシポートではありません。通常は接続情報の取得、プロキシグループの切り替え、実行時設定の更新などに使われます。アプリのプロキシ接続先にコントローラーのアドレスを設定すると、プロトコルが一致せず接続できません。カーネルを手動で実行する場合は必要に応じて有効にします。GUIクライアントは通常、関連する項目を自動生成して管理するため、上書きで同じアドレスを重複して指定しないでください。

コントローラーを有効にする場合は、ループバックアドレスにバインドし、専用のシークレットを設定してください。公共のネットワークに直接公開してはいけません。例にあるシークレットは構造を示すだけなので、実際に使う値は自分で生成してください。クライアントに認証情報を管理する機能がある場合は、その機能を使い、サンプル値を公開リポジトリに長期間保存しないでください。

external-controller: "127.0.0.1:9090"
secret: "replace-with-a-local-random-secret"

profile:
  store-selected: true
  store-fake-ip: true

store-selected はプロキシグループの選択状態を、store-fake-ip はfake-ipのアドレス対応状態を保持します。状態を保存しても、設定そのものの代わりにはなりません。プロキシグループ名を変更すると、旧名の選択状態を引き継げない場合があります。モード、ポート、保存設定を変更したら、入口、ルーティング、再起動後の動作をそれぞれ確認してください。画面上のスイッチの状態だけでは、すべての設定が適用されたとは判断できません。

3. プロキシノードの項目とノードプロバイダー

プロキシノードは具体的なリモート接続先を定義し、プロキシグループはその接続先から利用するものを選びます。ノード名は参照用のラベルにすぎません。接続できるかどうかを決めるのは、プロトコル、サーバー、ポート、認証情報です。名前を変えても接続先は変わらず、通信の遅延も短くなりません。異なるサービスから同じ名前のノードを追加する場合は、同じ設定に入れる前に名前を変更し、グループ内の参照先が曖昧にならないようにしてください。

プロトコルに合わせて必須項目を指定

proxies の各項目は一つのプロキシオブジェクトです。少なくとも、現在のプロトコルが認識できる種類と接続情報を指定する必要があります。別のプロトコルの項目をそのまま流用しないでください。Shadowsocksの暗号方式、Trojanのパスワード、ほかのプロトコルのユーザー識別情報は、それぞれ役割が異なります。設定の解析に成功しても、接続先サーバーがその情報を受け入れるとは限りません。

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

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

server は実際に接続するサーバーのアドレス、port はリモートサービスのポートです。ローカルの混合ポートを指定しないでください。サーバーにドメイン名を使う場合、ノードへの接続前に名前解決が必要です。そのためDNSの設定がすべてのプロキシに影響することがあります。サーバーをIPアドレスに変更しても、プロトコルでTLSが必要なら、サーバーが要求する正しいドメイン名の項目を維持してください。接続先アドレスと本人確認の設定は別です。

udp: true は、そのノード設定でUDP転送を利用できることを示します。通信経路全体があらゆるUDPアプリに対応するとは限りません。プロトコルの実装、サーバー側の設定、ネットワーク制限、アプリの接続方法も確認してください。ブラウザーでは問題なく閲覧できるのに音声通話が失敗する場合は、まず実際の通信方式を確認します。ウェブページの表示速度だけでUDPの可否を判断しないでください。

TLSの本人確認とトランスポート設定

TLS接続では、サーバーアドレスと sni の役割が異なる場合があります。前者は接続先を決め、後者はハンドシェイク時に接続先の名前を通知します。証明書の検証には、名前、有効期間、信頼チェーンが適切であることも必要です。証明書エラーが発生したら、まず端末の時刻、ノードのドメイン、サーバー証明書、ネットワーク上のリダイレクトを確認してください。検証を無効にすることを、通常の解決策にしないでください。

skip-cert-verify: false は通常の証明書検証を維持します。trueにすると接続の信頼境界が変わりますが、サーバーに到達できない、パスワードが違う、プロトコルが一致しないといった問題は解決しません。サービス側でWebSocketやgRPCなどのトランスポートを使う場合は、パス、ホスト名、サービス名もサーバーの設定に合わせる必要があります。サーバーアドレスとポートだけでは、これらの項目は特定できません。

ノードの項目は、使用中のカーネルが対応している機能の範囲に左右されます。オリジナルのClash、各種派生版、mihomoでは、プロトコルや拡張項目の対応状況が完全には一致しません。インポート時に未対応のプロキシタイプが表示されたら、インデントを何度も変更するのではなく、クライアントが実際に使っているカーネルを確認してください。カーネルとGUIの役割分担については、Clash・mihomo・クライアントの関係図をご覧ください。

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

ノードプロバイダーは、外部のノード一覧を独立したリソースとして読み込みます。継続的に更新されるノードをプロキシグループから参照する場合に便利です。あらゆるサブスクリプション形式を読み込める汎用インポーターではありません。リモートの内容はカーネルが対応するノードプロバイダー形式である必要があり、一般的には proxies: をルートに持つ構造です。クライアントから読み込めるサブスクリプション全体が、そのままプロバイダーのURLとして使えるとは限りません。

proxy-providers:
  remote-nodes:
    type: http
    url: "https://config.example.com/proxies.yaml"
    path: ./providers/remote-nodes.yaml
    interval: 3600
    health-check:
      enable: true
      url: "https://www.example.com/"
      interval: 600

proxy-groups:
  - name: "サブスクリプション選択"
    type: select
    use:
      - remote-nodes
    proxies:
      - DIRECT

ここでの interval はリソースの更新間隔を秒単位で指定します。ヘルスチェックにある同名の項目はチェック間隔を指定するため、用途は異なります。path はローカルキャッシュの保存先です。手動実行する場合は、作業ディレクトリと書き込み権限を確認してください。異なるプロバイダーには別々のキャッシュパスを設定します。リモート更新に失敗した場合は、初回読み込みでキャッシュがない状態なのか、既存のキャッシュを引き続き使える状態なのかを区別してください。

プロバイダーのURLにはアクセス用の認証情報が含まれることが多いため、スクリーンショットや公開リポジトリに載せないでください。調査時はドメイン名を残してパス内の機密情報を削除し、更新ログ、応答の形式、ノード数の変化を確認できます。ノードの更新後もプロキシグループに新しい名前が表示されない場合は、グループの use、フィルター条件、有効な設定を確認してください。更新ボタンを繰り返し押すだけでは解決しません。

4. プロキシグループの種類・テスト・選択状態

プロキシグループは、ルールとノードをつなぐ安定したインターフェースです。ルールは常に「業務用出口」を参照するようにし、グループ内のノードを必要に応じて入れ替えれば、各ルールにノード名を直接指定するより管理しやすくなります。プロキシグループ自体がリモートサービスを提供するわけではありません。最終的にはノード、別のグループ、組み込みの出力先のいずれかを選びます。グループ名は用途、ノード名は接続先を表すように分けると、接続ログが読みやすくなります。

手動選択と自動テスト

select は手動で接続先を選ぶグループです。用途、ネットワーク、地域に応じて選びたい場合に適しています。グループ内の並び順は一覧表示に影響しますが、選択状態の保存が有効だと、起動時に先頭の項目が選ばれるとは限りません。url-test は指定したテストURLへの接続結果をもとに候補を選ぶため、似たノードの間で接続先を自動調整する場合に適しています。結果はテスト対象に左右され、あらゆるサイトで同じ性能を示すものではありません。

proxy-groups:
  - name: "業務用出口"
    type: select
    proxies:
      - "自動選択"
      - "サンプル SS"
      - DIRECT

  - name: "自動選択"
    type: url-test
    proxies:
      - "サンプル SS"
      - "サンプル Trojan"
    url: "https://www.example.com/"
    interval: 300
    tolerance: 80
    lazy: true

この設定例は前章にある同名ノードを参照するため、単独でコピーすると参照先が不足します。interval はテスト間隔、tolerance は切り替えの許容幅です。単位は異なります。適切な許容幅を設定すると、結果が少し変動するたびに頻繁に切り替わるのを防げます。ただし、セッションの継続を保証するものではなく、故障したノードで通信を続けられるようにもなりません。ノード数、ネットワークの安定性、テストの負荷に応じて値を調整してください。

lazy: true を設定すると、実際に使用されるまでグループの不要なテストを抑えられます。そのため、起動直後にテスト結果が揃っていなくても、必ずしも異常ではありません。手動でテストしても失敗する場合は、テストURLに接続できること、証明書が正常であること、ノード経由でリクエストを完了できることを確認してください。テストの通信もノードを経由するため、間隔を短くしすぎると端末、ネットワーク、サーバーに負荷がかかります。

フェイルオーバーと負荷分散

fallback は優先順位に基づいて接続先を選びます。通常は候補を先頭から確認し、利用可能なものを選ぶため、メインの出口と予備の出口を用意する場合に適しています。テスト遅延の低さを重視する url-test とは目的が異なります。先頭のノードが常に利用可能なら、後ろのノードは業務通信にほとんど使われないことがあります。これは優先順位方式として正常な動作であり、グループへの追加に失敗したわけではありません。

load-balance は複数の候補に接続を振り分けるための機能です。複数ノードの帯域を合算して、一つのダウンロードに使う機能ではありません。振り分け方式によって、同じ接続先に対する出口の安定性も変わります。ログイン地域の固定やサーバー側セッションの維持が必要な場合は、出口が切り替わる影響を事前に検討してください。グループ内のノードが多いからといって、手動選択より負荷分散が適しているとは限りません。

既存の接続は通常、プロキシグループを切り替えても新しいノードへ自動で移りません。ブラウザーの長時間接続、ストリーミングセッション、バックグラウンド通信は古い出口を使い続けることがあり、変更が反映されるのは新しい接続からです。切り替えを検証する場合は、該当する接続を閉じるか、リクエストを再実行してください。転送中の処理が中断される場合があります。既存接続が変わらないことを、設定が読み込まれていないと誤解するのはよくあるトラブルシューティング上の落とし穴です。

プロバイダーの参照・フィルター・循環依存

グループ内の proxies は名前を指定してノードを参照し、use はノードプロバイダーを参照します。必要に応じて組み合わせれば、ダイレクト接続や固定ノードを残しながら、更新されるノード一覧を読み込めます。候補名は filter などの項目で絞り込めます。正規表現は引用符で囲み、フィルター後に想定した候補が一つ以上残ることを確認してください。

proxy-groups:
  - name: "リモート出口"
    type: select
    use:
      - remote-nodes
    filter: "(?i)office|backup"
    proxies:
      - DIRECT

プロバイダーのノード名が変わると、フィルター結果にも影響します。ノード数が急に減った場合は、ネットワークを調べる前に、更新後の名前と正規表現を確認してください。名前の問題を隠すためにすべてのノードにマッチする設定にすると、本来その用途に適さない出口までグループに入る可能性があります。複雑なフィルターを変更する前に、フィルターを外した小さな設定でプロバイダーが正常に読み込まれるか確認してください。

プロキシグループは別のグループを参照できますが、AがBを参照し、BがAを参照するような循環は作れません。階層構造には明確な終点が必要で、最終的に実際のノードか組み込みの出力先に到達しなければなりません。自動選択グループを何段も入れ子にすると、動作の把握が難しくなります。接続に失敗したら、最上位のグループ名だけでなく、各階層で現在選択されている項目を確認してください。テスト値と実際の使用感の違いについては、Clashの遅延テストの仕組みもご覧ください。

5. ルール構文・マッチ順序・ルールプロバイダー

ルールモードでは上から順に照合し、最初に一致したルールが接続先の出力先を決めます。同じ接続の出力先を決める際、後続のルールは通常使われません。そのため、ルールが存在するかどうかだけでなく、どこに配置されているかが重要です。対象を限定した例外を前に置き、範囲の広いルールを後ろに配置し、最後に MATCH で受け皿を指定すると、接続ログの判定経路を追いやすくなります。

ドメインルールとIPルール

DOMAIN は完全一致のドメインを、DOMAIN-SUFFIX は指定したドメインとそのサブドメインを照合します。DOMAIN-KEYWORD はキーワードで照合します。キーワードルールは対象範囲が広く、関係のないドメインまで同じポリシーに含めてしまうことがあります。用途別の通信振り分けには、明確なドメイン名やサフィックスを優先してください。ドメインルールが照合するのはホスト名であり、完全なURLではありません。プロトコル、パス、クエリパラメーターは指定できません。

rules:
  - DOMAIN,api.example.com,業務用出口
  - DOMAIN-SUFFIX,example.net,業務用出口
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
  - IP-CIDR,172.16.0.0/12,DIRECT,no-resolve
  - MATCH,業務用出口

IPルールは宛先アドレスの範囲を扱い、ドメインルールとは対象が異なります。no-resolve は、ドメイン名のリクエストを判定するために、そのIPルールが新たな名前解決を開始するのを防ぐ項目です。リクエストに宛先IPがすでにある場合は、引き続き照合できます。ルール自体を無視する設定でも、すべてのDNSリクエストを停止する設定でもありません。アプリからカーネルに渡されるのがドメイン名かIPアドレスかを踏まえて、マッチ結果を確認してください。

一つのサービスが、ログイン、API、静的ファイル、更新など複数のドメインを使う場合があります。トップページのドメインだけを振り分けると、ページは表示されてもログインに失敗することがあります。これはルールの対象範囲が不足している典型例です。すぐに広範なキーワードルールやグローバルモードへ変更するのではなく、接続ログで実際の依存先を確認し、必要なルールを追加してください。ドメインが分かっているのにIPアドレスしか表示されない場合は、アプリ自身が名前解決していないか、DNSがカーネルを経由しているかを確認します。

ルールの出力先とデータ依存関係

ルールの最後に指定する出力先には、既存のプロキシ、プロキシグループ、DIRECT や REJECT などの組み込み出力先を使えます。存在しないグループ名を指定すると、読み込みエラーが発生したり設定を利用できなくなったりします。多くの用途別ルールは、用途が変わらないプロキシグループを参照させると、ノード名を変更した際にルールを一つずつ修正せずに済みます。拒否ルールの対象はできるだけ限定してください。認証や証明書に関係する通信を誤って遮断すると、原因を特定しにくい連鎖的な障害につながります。

GEOIP などのルールは対応する地理データに依存し、ルールプロバイダーは外部リソースに依存します。設定ファイルの構文が正しくても、データファイルが存在しない、ダウンロードに失敗する、キャッシュ先に書き込めないといった理由で初期化できない場合があります。ログを調べるときは、「ルールの文字列が不正」なのか「ルールに必要なリソースを利用できない」のかを切り分けてください。修正方法は異なります。

プロセス名に基づくルールは、OS、アクセス権、通信の取り込み方に左右されます。デスクトップで使えるプロセスルールが、ルーター経由の転送通信でも元のアプリを識別できるとは限りません。特に、ほかのLAN内デバイスからの通信では、カーネルが受け取るのは転送された接続であり、リモート端末上のプロセス名を自動的に把握することはできません。このような環境では、ドメイン、宛先アドレス、識別可能な送信元条件に基づいてポリシーを構成してください。

大量のルールをrule-providersで管理する

ルールプロバイダーを使うと、長いルール一覧をメイン設定から分離でき、メイン設定には優先順位と出力先の指定を残せます。behavior はルールの意味を、format はファイル形式を示します。どちらもリモートの内容と一致させてください。以下の例ではYAML形式の classical コレクションを使います。コレクション内にはルール条件だけを記述し、各条件にプロキシグループを付けません。出力先はメイン設定の RULE-SET で指定します。

rule-providers:
  work-domains:
    type: http
    behavior: classical
    format: yaml
    url: "https://config.example.com/work-rules.yaml"
    path: ./rules/work-rules.yaml
    interval: 86400

rules:
  - RULE-SET,work-domains,業務用出口
  - MATCH,DIRECT

対応するリモートファイルは、次のような構造にできます。プロバイダーがドメインの一覧として宣言されている場合、従来形式のルール文字列全体を通常のドメイン名として記述することはできません。形式が混在すると、解析に失敗したり、期待どおりにマッチしなかったりします。更新間隔をむやみに長くするのではなく、まずファイルの内容と形式を確認してください。

payload:
  - DOMAIN,api.example.com
  - DOMAIN-SUFFIX,example.net

ルールセットには、信頼性とメンテナンス上の注意点もあります。更新によってマッチ範囲が広がったり狭まったりし、同じサービスの通信経路が変わることがあります。用途が明確で、内容を確認できるセットを選んでください。変更前にキャッシュと正常動作が確認できている設定を保存します。検証では、マッチするはずの対象とマッチしないはずの対象を一つずつ選び、実際のルールと最終的な出力先を確認してください。成功例を一つ試すだけで、すべての振り分けが正しいと判断しないでください。

6. DNS名前解決・fake-ip・起動時の名前解決経路

DNSは、接続先ドメインの名前解決、ノードサーバーの名前解決、一部のルール判定に関わります。ウェブサイトにアクセスできない場合、アプリが名前解決結果を取得できない、カーネルがノードのドメインを解決できない、名前解決経路と接続の出口が一致しないなど、さまざまな箇所が原因になり得ます。どのドメインを、どのコンポーネントが、どの経路で解決しているかを先に確認し、それに合わせて項目を変更してください。すべてのDNSサーバーを一度に変更すると、元の問題を再現しにくくなります。

名前解決の入口とアドレス拡張モード

dns.enable はカーネルのDNS機能を有効にし、listen はDNSリクエストを受け付けるアドレスを指定します。ただし、OSのDNS設定を自動で変更する項目ではありません。明示的なシステムプロキシ、アプリ内蔵の暗号化DNS、TUN経由では、DNSの処理方法が異なります。リクエストが実際にカーネルに届いて初めて、DNS関連のポリシーが適用される可能性があります。設定項目が存在するだけで、名前解決がカーネルに引き継がれているとは判断できません。

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

fake-ip は仮想アドレスを使って、ドメインと後続の接続を関連付けます。その後、カーネルがドメイン名とルールに応じてリクエストを処理します。このアドレスはウェブサイトの実際のサーバーアドレスではありません。テスト用のアドレス範囲が表示されても、DNSが改ざんされたとは限りません。LAN内の機器検索や特定の検証で実アドレスが必要なアプリは、フィルター対象に追加する必要がある場合があります。ただし、互換性の問題を避けるために、すべてのドメインをフィルター対象外にするのは適切ではありません。

redir-host は通常、実際に名前解決したアドレスを返します。fake-ipとはアドレスの関連付け方法が異なり、単純な「速い・遅い」の違いではありません。どちらを使うかは、通信の取り込み方、アプリの動作、ルールの要件に応じて決めます。切り替え後は、システムやアプリのDNSキャッシュ、既存の接続も考慮してください。設定を切り替えた直後の最初のリクエストだけで判断しないでください。

ブートストラップDNSとノードの名前解決

default-nameserver は、DNSサーバー自身のドメイン名を解決するなど、ブートストラップ時の名前解決に使います。すべての通信に使う、同じ優先度の通常のDNSサーバーを追加する項目ではありません。暗号化DNSの接続先をドメイン名で指定する場合、クライアントは最初にそのDNSサービスのアドレスを知る必要があります。ブートストラップの名前解決がまだ確立していないプロキシに依存し、そのプロキシも同じDNSサービスに依存すると、起動時に循環依存が発生することがあります。

proxy-server-nameserver は、ノードサーバーのドメイン名を解決する経路を個別に指定し、通常の名前解決と依存関係が混在するのを避けるために使えます。ここでは現在のネットワーク環境で実際に名前解決できるサービスを指定してください。別のネットワークで使えたアドレスが、現在のネットワークでも必ず使えるとは限りません。ファイアウォール、通信事業者のネットワーク、端末のDNSポリシーが結果に影響します。

respect-rules を有効にすると、DNS接続のルーティングに通信振り分けルールが適用されます。出口ポリシーを統一する必要がある場合に適していますが、ルールやノードの名前解決への依存も増えます。有効にする前に、ノードのドメインを個別に解決する方法を用意してください。DNSリクエストがプロキシを待ち、プロキシがDNSを待つ状態を避ける必要があります。初回のトラブルシューティングでは、まず単純な名前解決経路で基本接続を確認し、その後にポリシーによる振り分けを追加します。

ドメインごとのDNS指定とキャッシュの確認

nameserver-policy を使うと、特定のドメインにDNSサーバーを個別指定できます。たとえば、社内ドメインを社内ネットワークのDNSに問い合わせる設定が可能です。社内DNSのアドレスはネットワーク環境に依存するため、環境が変わったらドメインごとの設定も見直してください。社内の名前をパブリックDNSに送っても、通常は期待するアドレスが返りません。不要な社内ドメインの問い合わせを外部に送ることにもなります。

dns:
  enable: true
  enhanced-mode: fake-ip
  default-nameserver:
    - 1.1.1.1
  proxy-server-nameserver:
    - 1.1.1.1
  nameserver:
    - "https://cloudflare-dns.com/dns-query"
  nameserver-policy:
    "+.corp.example.com":
      - 192.168.1.53

この設定例は、実際に使っているDNS設定と統合してください。同じファイルに2つ目の dns を追加してはいけません。社内ネットワーク用のサンプルアドレスは、現在の環境で使えるDNSサーバーに置き換えてください。fallbackとフィルター条件を併用する場合は、通常の応答と予備の応答を選ぶ仕組みもそれぞれ確認します。予備のDNSサーバーを追加しても、ドメインごとの振り分けが自動で設定されるわけではなく、毎回同じサーバーが使われる保証もありません。

変更後は同じドメイン、同じアプリ、同じ接続方法で再テストしてください。ターミナルの名前解決ツールはOSのDNSを直接使う場合があり、ブラウザーの暗号化DNSとは経路が異なります。結果が違っても、必ずしもカーネルの異常とは限りません。名前解決の経路を確認したうえで、関連するキャッシュを消去し、接続を作り直してください。fake-ipのマッピングを使っている場合は、保存状態も確認し、古いアドレスと新しい設定の混在による断続的な失敗を防いでください。

7. TUNによる通信取り込み・システムルート・プラットフォーム別の違い

TUNはOSに仮想ネットワークインターフェースを作成し、明示的なプロキシを使わない通信の一部をカーネルに取り込みます。TUNが担当するのは通信の取り込みであり、プロキシグループ、ノード、ルールの代わりにはなりません。有効にした後も、各接続を直接接続、拒否、プロキシ経由のどれにするかはカーネルが判断します。ノードがもともと利用できない場合、TUNを使うと同じ障害に影響されるアプリが増えるだけで、リモート接続の問題は解決しません。

最小限の設定と必要な権限

デスクトップクライアントで仮想インターフェースやルートを作成するには、サービスのインストールや適切な権限が必要なことがあります。カーネルを手動で実行する場合は、OSの認可を自分で処理してください。設定に enable: true とあるのに、ログでインターフェースの作成に失敗している場合は、ルールをさらに変更するのではなく、権限、ドライバー、サービスの状態を先に確認します。GUIでスイッチがオンになっていても、実際のインターフェースとルートの確認は必要です。

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

auto-route は通信取り込みに必要なルートの設定をカーネルに要求し、auto-detect-interface は送信インターフェースの選択を補助します。有線、無線、仮想マシン、ほかのトンネルインターフェースが同時に存在する端末では、デフォルトルートの変化が自動選択に影響することがあります。ネットワークを切り替えた後だけ問題が起きる場合は、サブスクリプションを疑う前に、現在のデフォルトルートと実際の送信インターフェースを確認してください。

stack は、仮想インターフェースの通信をどのネットワークスタックで処理するかを指定します。利用できる選択肢と動作は、使用中のカーネルに従ってください。いわゆる万能の推奨設定をそのまま使わないでください。同じアプリでも、UDP、LANアクセス、大量データの転送で結果が異なる場合があります。ネットワークスタックを変更するときは、ほかの設定を変えずに同じ用途で再テストし、変更がこの項目によるものかを確認してください。

DNSのリダイレクトと通信取り込み範囲

dns-hijack は、条件に一致する通常のDNS通信をカーネルのDNSに渡します。アプリ独自のHTTPS DNSを自動的に復号する機能ではなく、TUNのルート範囲外にあるリクエストをすべて取り込めるわけでもありません。アプリが独自の名前解決経路を使い続ける場合、ルールから見える接続先情報が想定と異なることがあります。設定を変更する前に、アプリのDNS設定と実際の接続を確認してください。

ルーティングの取り込みでは、LAN内のプリンター、ネットワークストレージ、開発環境、仮想マシンのネットワークも考慮してください。ルールのDIRECTは、カーネルに取り込まれた通信の出力先を決めます。一方、システムルートからの除外は、その通信をカーネルに取り込むかどうかを決めます。役割は異なります。ローカルサービスに接続できない場合は、まずリクエストがカーネルに届いているかを確認し、その後に宛先アドレスのルールを調べてください。設定する階層を間違えたまま例外を追加し続けないようにしましょう。

strict-routeなどの設定は、想定外の経路を制限するのに役立つ場合がありますが、OSのコンポーネント、ほかのトンネル、LAN内通信に影響することもあります。プラットフォームごとの動作を理解したうえで有効にしてください。リモート管理中の端末やサーバーでは、ルート変更によって現在の管理接続が切断される可能性があります。別のアクセス方法や復旧手段を用意し、戻す方法がない状態でデスクトップ向けの設定を適用しないでください。

プラットフォーム別に適用状態を確認

Windowsでは、まず明示的なプロキシが正常に動くことを確認し、その後システムプロキシを無効にしてTUNを個別にテストすると、2つの通信経路を切り分けやすくなります。明示的なプロキシ利用時にUWPアプリで発生するループバック制限と、TUNによる通信取り込みは別の問題です。接続できない原因をすべてファイアウォールに帰さないでください。インストールとサービスのトラブルシューティングについては、Clash Verge RevのWindowsインストールとTUNのトラブル解決をご覧ください。

Linuxでは、転送設定、ファイアウォール、ポリシールーティングが別のサービスに管理されていないかも確認してください。ネットワークマネージャーの再読み込み後に、既存の設定が変わる場合があります。macOSやモバイルプラットフォームでは、現在のクライアントが用意する認可手順に従ってください。デスクトップ向けのファイルをそのまま上書きしないでください。Clash Plus、Clash Verge Rev、FlClashでは画面構成が異なるため、設定入口は各プラットフォームのクライアントで確認してください。

すべての通信が途絶えた場合は、まずTUNを無効にし、OS本来のネットワーク接続が復旧するか確認します。その後、カーネルの起動ログ、DNS、ノードを順に調べてください。TUNを無効にしても異常が続く場合は、残ったシステムプロキシやルートを確認し、ノードの切り替えを繰り返さないでください。テスト終了後は、必要な通信取り込み方式だけを有効にします。トラブルシューティング中に複数のプロキシやトンネルを同時に動かすと、通信経路が分かりにくくなります。

8. クライアントによる上書き・設定の統合・検証手順

最終的に適用される設定は、サブスクリプションの原文、ローカル拡張、クライアントの設定、実行時の状態によって決まることがあります。サブスクリプション更新は取得元の内容を更新し、上書きはローカルの差分を保持し、コントローラーは現在の選択状態を変更する場合があります。これらが併存すると、エディター内のファイルだけでは動作全体を説明できません。「どの設定をカーネルが実際に読み込み、通信がどの経路を通ったか」を調べることが、トラブルシューティングのゴールです。単に「項目を保存した」ことではありません。

統合ルールと保存先を把握する

マッピング、リスト、スカラーでは、設定を統合するときの処理が異なる場合があります。マッピングは再帰的に上書きされることも、リストは全体が置き換えられることも、クライアントによって末尾に追加されることもあります。こうした動作はクライアントの拡張機能で決まり、YAML共通の規格ではありません。特に rules は、項目がすべて残っていても追加位置が変わると優先順位が変わります。統合後の順序を必ず確認してください。

たとえば、サブスクリプション末尾にすでに MATCH があるのに、クライアントが独自のドメインルールをその後ろに追加すると、そのルールはマッチしません。クライアントが対応する先頭追加用のルール設定を使うか、生成時に独自ルールをフォールバックより前に挿入してください。画面に「追加しました」と表示されただけで検証を終えず、対象のリクエストを実際に送信して、どのルールにマッチしたかを確認します。

# 統合後に想定するルールの順序
rules:
  - DOMAIN,api.example.com,業務用出口
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - MATCH,業務用出口

ポート、コントローラー、TUNはクライアントが管理することが多く、同じ項目を上書きしても後から再度変更される場合があります。項目ごとにどの階層が管理するかを決め、変更元を一つにまとめてください。GUI設定とファイルの上書きが互いを変更し合う状態は避けます。Clash Plusはクライアント選びの出発点として使えます。別のクライアントでも、ローカル拡張の仕組みに合わせて変更を保存してください。特定のクライアント用スクリプトの構文を、カーネル共通の項目として扱わないでください。

サブスクリプション更新後に変更が消える場合は、編集場所が適切でないか、上書きが現在の設定に関連付けられていない可能性があります。まず更新前後の原文を比べ、次に拡張機能が有効か、適用範囲が正しいかを確認してください。特定の設定だけに作用する拡張と、すべての設定に作用する拡張があります。範囲を誤ると、テスト用の設定が普段使う環境にも影響します。長期間管理する場合は、ローカル差分の目的と削除条件を記録してください。

まず静的検証を行い、その後に実行時の動作を検証

mihomoを手動で実行する場合は、有効にするファイルを先に設定テストできます。以下のコマンドで確認できるのは、現在のカーネルが指定ファイルを受け付けるかどうかです。リモートノード、外部ルールリソース、すべての通信がエンドツーエンドで正常とは限りません。GUIクライアントは独自のカーネルと作業ディレクトリを使うことがあります。ターミナルの別のmihomoでテストが成功しても、クライアントが同じファイルを使っているとは限りません。

mihomo -t -f ./config.yaml

静的検証では、インデントや型の誤り、参照先の欠落、使用中のカーネルが対応していない項目、外部リソースの読み込み問題の順に確認します。エラーが出たら、実際の原因を示す最初のメッセージを記録してください。後続のエラーは連鎖的に発生している場合があります。一か所を修正したら、もう一度テストします。意味が分からないまま複数の項目を同時に削除すると、起動できても元のポリシーが失われる可能性があります。

実行時は、まず待ち受けが成功していることを確認し、次にテストリクエストがカーネルに届いているかを調べます。その後、モード、ルール、プロキシグループ、最終的なノードを確認します。出口のIPアドレスと実際のサービス利用結果を判断するのは最後です。直接接続するリクエストとプロキシ経由のリクエストを一つずつ選んで検証し、必要に応じて接続を作り直してください。初回接続の確認手順は、ノード選択・遅延測定・プロキシの動作確認をご覧ください。

症状に合わせて確認する階層を選ぶ

復旧手順も変更時と同じように明確にしておきましょう。まず正常動作が確認できている設定に戻し、最近追加した上書きやTUN設定を無効にして、システムプロキシとDNSの状態を確認します。一つの項目の問題を解決するためにクライアントのフォルダー全体を削除しないでください。ノードの選択状態、キャッシュ、ローカル拡張が保存されている場合があります。再インストールが必要な場合は、プラットフォーム別ダウンロードページから該当するインストーラーを選び、必要なローカル設定をバックアップしてください。