Clash YAML設定ガイド

設定の構造とYAML構文

Clashの設定ファイルは、コアがリクエストを待ち受け、ドメインを名前解決し、接続先を選ぶ方法を定めるものです。クライアント画面の設定をすべて保存するファイルではありません。ウィンドウ位置、メニューバーのアイコン、自動起動などは通常、GUIクライアント側に保存されます。設定を読む前に、実行中のコアの種類と、クライアントが実際に読み込んでいる設定を確認してください。ファイル名がconfig.yamlでも、現在有効な設定とは限りません。サブスクリプション設定、ローカル設定、実行時に生成されたファイルが同時に存在する場合があります。

マッピング・リスト・インデント

YAMLのマッピングはキーと値で構成され、リスト項目はハイフンで始まります。トップレベルのdnsはマッピング、proxies、proxy-groups、rulesは通常リストです。子項目は親項目より深くインデントします。タブは避け、半角スペース2つに統一するのがおすすめです。同じ階層の項目はインデントをそろえてください。エラーが特定の行を指していても、原因は直前の行にある場合があります。たとえば、引用符が閉じていない、リスト項目のハイフンが抜けているなどです。

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

dns:
  enable: true
  nameserver:
    - https://dns.alidns.com/dns-query

proxies: []

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

rules:
  - MATCH,出口の選択

これは直結先だけを含む構造例で、接続可能なリモートプロキシノードは含まれていません。YAMLの階層、プロキシグループの参照、ルールのフォールバックを確認するための例であり、サービス提供元のノード設定の代わりにはなりません。各章の例をそのまま連結して1つのファイルにしないでください。同じトップレベル項目は1か所にまとめます。特にdnsやrulesを重複して記述しても、コアが意図どおり自動マージするとは限りません。

文字列・真偽値・特殊文字

コロンと空白、シャープ記号、型の判定が曖昧になりやすい値は、引用符で囲むのがおすすめです。通常の文字列でも、シャープ記号以降がコメントと解釈され、パスワードや名前の一部が読み込まれないことがあります。真偽値はtrueまたはfalse、ポートは整数で記述します。ノード名、プロキシグループ名、ルールの接続先はいずれも文字列です。参照する際は表記を完全に一致させてください。日本語の名前も使えますが、前後の空白も文字列の一部として扱われる場合があります。

ダブルクォートを使う場合は、バックスラッシュによるエスケープに注意してください。エスケープが不要な文字列にはシングルクォートも使えます。エディターが引用符をスマートクォートに自動変換すると、ファイルを解析できても、意図しない文字列になることがあります。参照エラーを調べるときは、画面上の似た名前ではなく元のテキストを比較してください。ノードやプロキシグループに同じ名前を付けないでください。また、カスタムオブジェクトの名前にDIRECTやREJECTなどの組み込み接続先を使わないでください。

設定の取得元と検証方法

サブスクリプションURLから返される内容が、完全なYAMLとは限りません。エンコードされたノード一覧を返すURL、サーバー側での変換が必要なURL、リクエスト方法によって形式が変わるURLもあります。インポートに失敗したら、まずクライアントで設定の種類を確認し、次に解析ログを確認してください。ログイン画面、エラーページ、有効期限切れの案内をYAML拡張子で保存しても、有効な設定にはなりません。サブスクリプションURLにはアクセス認証情報が含まれる場合があるため、公開の掲示板やスクリーンショットに載せないでください。

mihomoのコマンドライン版を別途インストールしている場合は、ターミナルで次の構文チェックを実行できます。GUIクライアントに内蔵されたコアは、シェルの検索パスに含まれていないことがあります。コマンドが見つからなくても、設定ファイルが壊れているとは限りません。テストではクライアントに近いコアと同じリソースディレクトリを使ってください。外部ルールファイルを参照する設定では、該当ファイルも必要です。読み込みに成功しても、リモートノードへの接続やルールの振り分けが正しいとは限りません。

mihomo -t -f ./config.yaml

正常に接続できる元の設定を保存し、関連する項目をひとまとまりずつ変更して、期待する変化を記録しておきましょう。問題が起きたときに、構文エラー、クライアントのオーバーライド、ネットワークへの接続不可、ルールの誤照合を切り分けやすくなります。無関係な設定例を一度に大量に追加すると、原因同士が隠れ合い、比較できる基準がなくなって元に戻すのも難しくなります。

待ち受けポートとアクセス範囲

ポート項目は、ローカルアプリからコアへプロキシリクエストを渡す入口を指定します。リモートノードのポートや、コントロールAPIのポートとは別のものです。ブラウザーがローカルの混合ポートに接続すると、コアがルールに基づいてリモートノードまたは直結先を選びます。リモートノードのサーバーポートは、各ノードの設定に記述します。この2つを混同すると、システムプロキシをリモートサーバーに向けたり、リモートノードのアドレスを誤ってループバックアドレスに変更したりすることがあります。

HTTP・SOCKS・混合ポート

デスクトップで通常使う場合は、混合ポートを1つ設定すれば十分です。例では7890を使用していますが、すべてのクライアントがこの番号を使うわけではありません。画面表示、実行中の設定、システムプロキシの設定を一致させてください。独立した待ち受け口を複数使う場合は、同じアドレスでポートが競合しないよう、それぞれ異なる番号を指定します。不要な入口を無効にすると、すべてのポート項目を並べるより理解しやすく、アプリがどの入口を使っているかも確認しやすくなります。

mixed-port: 7890
allow-lan: false
bind-address: "127.0.0.1"
mode: rule

ループバックアドレスとLAN共有

127.0.0.1は、現在のデバイスを指すIPv4ループバックアドレスです。スマートフォンにこのアドレスを入力すると、スマートフォン自身に接続され、Macにはつながりません。MacのプロキシをLAN内のデバイスと共有するには、LAN接続を明示的に許可し、適切な待ち受けアドレスを設定したうえで、ほかのデバイスにMacの実際のLANアドレスを入力します。待ち受けを公開する際は、ファイアウォール、ネットワーク分離、アクセス認証も確認してください。スイッチを有効にするだけで、アクセス範囲への配慮を省くことはできません。

allow-lanはLANからのリクエストを許可するかどうかを制御し、bind-addressは待ち受けアドレスを制限します。実際にアクセスできるかどうかは、これらの項目の組み合わせ、コアの動作、システムファイアウォールによって異なります。デスクトップで自分だけが使う場合は、ループバック接続を維持するのがおすすめです。共有する場合は信頼できるネットワークに限定し、ルーターでローカルプロキシのポートをインターネットに公開しないでください。同じネットワークに接続していても、公衆Wi-Fi上のほかのデバイスが信頼できるとは限りません。

macOSのシステムプロキシ設定

macOSのWebプロキシとセキュアWebプロキシには、通常、ローカルのHTTP接続先を指定します。セキュアWebプロキシという名称でも、ローカルの接続口でTLSを別途有効にする必要があるわけではありません。HTTPSサイトへの接続には、通常HTTP CONNECTでトンネルを確立します。クライアントが混合ポートを使う場合、Webプロキシ、セキュアWebプロキシ、SOCKSプロキシに同じループバックアドレスとポートを指定できます。ポートを個別に使う場合は、それぞれ対応する番号を指定してください。例の数値をそのまま使えるとは限りません。

次のコマンドで、Wi-Fiという名前のネットワークサービスの現在の設定を確認できます。デバイスによってサービス名が異なるため、まず一覧表示コマンドで確認してください。ネットワークサービスが複数ある場合は、実際に通信を担っているサービスを調べます。外付けネットワークアダプター、有線LAN、サービス名の変更などによって、確認対象と実際の接続先が異なることがあります。コマンドの出力に正しいアドレスが表示されても、クライアントが待ち受け中とは限りません。ローカルプロセスも確認してください。

networksetup -listallnetworkservices
networksetup -getwebproxy Wi-Fi
networksetup -getsecurewebproxy Wi-Fi
networksetup -getsocksfirewallproxy Wi-Fi
lsof -nP -iTCP:7890 -sTCP:LISTEN

ポートが使用中の場合は、まず待ち受けているプロセスを特定してください。よく分からないシステムプロセスをすぐに終了しないでください。プロキシクライアントを2つ同時に起動すると、ポートを取り合ったり、システムプロキシを交互に変更したりすることがあります。片方を終了したあとも、システム設定が残っていないか確認してください。ポートを変更した場合は、シェルの環境変数、エディターのプロキシ設定、アプリに手動入力した設定も更新します。ブラウザーが復旧しても、一部のアプリが古いアドレスへの接続を続けることがあります。

動作モードとトラフィックの入口

動作モードは、リクエストがコアに届いた後に接続先を選ぶ方法を決めます。システムプロキシとTUNは、リクエストをコアに届ける方法です。これは別々の問題です。ルールモードを有効にしても、すべてのアプリが自動的に対象になるわけではありません。TUNを有効にしても、すべての通信がリモートプロキシを通るとは限りません。接続の挙動を確認するときは、まずアプリがどの入口を使うかを特定し、次にコアの動作モードを確認してから、対象の接続がどのルールに一致したかを調べます。

ルール・グローバル・直結モード

mode: ruleはルールリストの順に接続先を選びます。mode: globalはグローバル設定で選んだ接続先を使い、mode: directは直結します。これらは接続品質のレベルでも、ネットワーク権限の段階でもありません。グローバルモードは、問題がルールに関係するかを短時間で比較するのに役立ちますが、あらゆる問題を解決する設定ではありません。選択中のリモートノードに接続できない場合、グローバルモードに切り替えても通常は改善しません。

mode: rule
log-level: info
ipv6: false

GUIクライアントでは、画面からモードを切り替えられるのが一般的です。ただし、画面上の操作がコントロールAPI経由で実行中のコアに反映されても、元のYAMLに書き戻されるとは限りません。設定を再読み込みしたときにモードが維持されるかは、クライアントの保存方法によって異なります。確認時は設定ファイルとリアルタイムの画面表示の両方を見てください。エディターのmodeの値だけで、現在の動作モードを判断することはできません。クライアントの実行ログ、接続画面、生成された設定のほうが直接的な確認手段です。

システムプロキシとターミナルの環境変数

システムプロキシの影響を受けるのは、システムのプロキシ設定に従うアプリが中心です。多くのコマンドラインツールは独自のプロキシ設定を持ち、macOSのネットワーク設定を標準では読み込みません。比較テストでは、現在のシェルに一時的な環境変数を設定できます。別のターミナルウィンドウで後から設定した変数が、自動的に引き継がれることはありません。変数名や大文字・小文字の扱いはツールによって異なります。問題が続く場合は、システムプロキシを何度も切り替えるのではなく、該当ツールのドキュメントを確認してください。

export http_proxy=http://127.0.0.1:7890
export https_proxy=http://127.0.0.1:7890
export all_proxy=socks5h://127.0.0.1:7890

curl -I https://example.com

unset http_proxy https_proxy all_proxy

ここでのsocks5hは、この書式に対応するツールが接続先のドメイン名をプロキシ側で処理することを示します。ローカルで名前解決してからIPアドレスを送る方式とは異なります。環境変数の影響を受けるのは、それを読み込むプログラムだけで、OS全体のネットワーク経路は変わりません。ツールによってはコマンドライン引数や設定ファイルが環境変数より優先されます。検証時は重複する設定をできるだけ減らし、どの設定が作用しているかを特定しやすくしてください。

TUN設定と権限の範囲

TUNは仮想ネットワークインターフェースを使って、より広い範囲のIP通信を受け取ります。通常、クライアントによる補助サービスのインストールや、必要な権限の許可が必要です。以下はmihomoでよく使われる項目の組み合わせであり、すべてのGUIクライアントが同じ方法で設定するとは限りません。TUNの項目をクライアント側で管理したり、インターフェースを自動選択したり、除外ルートを生成したりする場合があります。まずはクライアントが対応する設定画面を使ってください。詳しい有効化手順はTUNモードガイドをご覧ください。

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

auto-routeはコアに必要なルートの設定を試みさせ、auto-detect-interfaceは外向きのネットワークインターフェースを自動検出します。Wi-Fiの切り替え、ドッキングステーションの接続、別のVPNの起動によって、インターフェースやルートが変わることがあります。接続が切れたときは、すぐにノードが原因と決めつけず、インターフェースとルートの状態を確認してください。企業VPN、仮想マシン、ほかのネットワーク拡張機能も同時に経路を変更する場合があります。併用する際は、1つずつ有効にして挙動を確認してください。

DNSのリダイレクト設定にも適用範囲があります。上記の設定は一般的なDNSポートの通信を対象とし、すべてのアプリに組み込まれた暗号化DNSを自動的に取り込むものではありません。TUNを有効にした後、一部のドメインだけに問題が起きる場合は、DNSモード、アプリ独自の設定、ルートの除外項目をあわせて確認してください。クライアントを終了する前に、クライアント自身にTUNの制御を正常に解除させてください。プロセスを強制終了すると、一時的にネットワークが使えなくなることがあります。

トラブルの切り分けは、順序を決めて進めると効率的です。まず追加のVPNを無効にし、システムプロキシだけでテストします。入口が使えることを確認してからTUNを有効にし、最後にほかのネットワークツールを戻してください。毎回1つの条件だけを変更し、ブラウザー、ターミナル、対象アプリの違いを記録します。Windowsのアプリループバックは別のプラットフォーム機能であり、macOSのTUNと同じものではありません。詳しくはWindowsのアプリループバックについてをご覧ください。

DNSの項目と名前解決の経路

DNS設定では、3つの点を確認します。アプリの名前解決リクエストがコアに届くか、コアがどのリゾルバーを使うか、解決結果が後続の接続にどう使われるかです。パブリックDNSのアドレスを1つ書くだけで、すべてのアプリがそれを使うとは限りません。システムプロキシを使う場合、アプリが最初にシステムのリゾルバーを呼び出すことがあります。HTTP CONNECTやリモート名前解決を使うSOCKS接続では、ドメイン名がそのまま渡される場合があります。TUN、アプリ内蔵の暗号化DNS、ローカルキャッシュによっても、実際の経路は変わります。

基本のリゾルバーとブートストラップ名前解決

dns.enableはコアのDNSモジュールを有効にし、nameserverには通常使用する上流リゾルバーを指定します。暗号化DNSのアドレスにドメイン名を使う場合、そのドメインを先にIPアドレスへ解決する必要があります。default-nameserverはこの初期の名前解決に使え、明示的なIPアドレスを指定するのに適しています。すべてのリゾルバーを相互に依存するドメイン名にし、まだ使えないプロキシ経路を通じて初回接続させる構成は避けてください。

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

この例は項目間の関係を示すもので、特定のパブリックDNSがあらゆるネットワークに適しているわけではありません。上流リゾルバーを選ぶ際は、現在のネットワークから直接接続できるか、組織内ドメインに専用DNSが必要か、リモートノードのネットワークでどの名前解決が必要かを考慮します。proxy-server-nameserverはプロキシサーバーのドメイン名解決に使い、ノードの名前解決と通常のWebサイトの名前解決を分けることで、起動時の循環依存を避けやすくします。

fake-ipモードと実IPモード

fake-ipモードでは、処理対象となるドメイン名に合成アドレスを返します。コアは対応関係を使って元のドメイン名を特定し、接続とルール判定を行います。例に使われているネットワーク範囲はベンチマーク用であり、リモートプロキシサーバーのアドレスではありません。アプリにこの種のアドレスが見えても、必ずしも名前解決エラーではありません。ただし、合成アドレスを取得した後にリクエストがコアを経由せず送信されると、接続に失敗することがあります。名前解決の入口と通信の入口を一致させてください。

実際のIPアドレスを返すモードは従来型のDNSに近い挙動ですが、ドメイン名と接続の対応関係は、アプリのキャッシュ、共有IP、接続方法の影響を受ける場合があります。2つのモードに単純な優劣はありません。LAN内のデバイス検出、ゲーム、機器管理、アドレスを明示的に検証する一部のアプリでは、fake-ipの対象外にする必要があります。フィルターを追加する前に、問題がアドレスとの互換性に起因するのか、リモートノードや接続先サービスに到達できないことが原因なのかを確認してください。

ドメインごとにリゾルバーを選択

nameserver-policyでは、指定したドメインに使用するリゾルバーを選べます。たとえば、社内ドメインの名前解決を社内DNSに任せる場合に便利です。以下は例示用のドメイン名とプライベートIPアドレスを使った構造例です。実際に使うときは、組織から提供された値に置き換えてください。社内DNSへのアクセスに企業VPNが必要な場合は、そのアドレスへの問い合わせがルーティングされることも確認します。社内ドメインをパブリックDNSに任せても適切な応答が得られないことが多く、不要な問い合わせ情報が外部に漏れる可能性もあります。

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

この設定は既存のdnsマッピングに統合し、同じ名前のトップレベル項目として追加しないでください。ルールに基づいてDNSの接続先を選ぶ高度な設定を導入する前に、まず基本的な名前解決が機能する状態にします。DNSリクエストもルール判定の対象にするオプションがあります。ルール判定自体にDNSが必要な場合は、リゾルバーを増やし続けるのではなく、コアのドキュメントを参照して依存関係を解決してください。

DNSの確認手順

まず、クライアントのログに対象の問い合わせが記録されているか確認し、次に応答アドレスと最終的な接続先を確認します。通常のdigテストだけでは、アプリ内蔵の暗号化DNSの挙動は確認できません。ブラウザーでWebサイトを開けても、ターミナルが同じ経路で名前解決しているとは限りません。設定変更後も、ブラウザー、OS、コアがそれぞれキャッシュを保持している場合があります。古い接続を閉じて新しいリクエストを開始し、必要であればクライアントの手順に沿ってキャッシュを消去してください。

IPv6も項目ごとに分けて考えましょう。トップレベルの有効化設定、DNSがIPv6アドレスを返すかどうか、OSに利用可能なIPv6ルートがあるかどうかは、それぞれ別の条件です。どれか1つを無効にしても、あらゆるIPv6の問題を説明できるわけではありません。接続が遅い、最初のリクエストで待たされるといった場合は、名前解決にかかる時間、接続の確立時間、選択された接続先を比較し、通信速度が遅いときの段階的な確認方法に沿って原因を絞り込みます。すべての待ち時間をDNSの問題と決めつけないでください。

プロキシノードの項目とリモートプロバイダー

プロキシノードは、特定のリモート接続方法を定義します。主な項目はプロトコルの種類、サーバーアドレス、サーバー側のポート、認証情報です。プロキシグループはノードを選び、ルールはプロキシグループを選びます。それぞれの役割は異なります。ノードの設定はサービス提供元が示す項目を基準にし、名前からプロトコルを推測しないでください。名前にプロトコルらしい文字列が含まれていても、それはラベルにすぎません。コアが実際に使うプロトコルはtypeの値で決まります。

共通項目とプロトコル固有の項目

nameはプロキシグループから参照する名前、serverはサーバーのドメイン名またはIPアドレス、portはリモートサービスの待ち受けポートです。認証方式はプロトコルによって異なります。パスワードを使うもの、ユーザーIDを使うもの、TLSとトランスポートの設定をあわせて必要とするものがあります。項目名が似ていても、別のプロトコルの設定をそのまま流用できるとは限りません。以下のShadowsocks例は構造を示すものです。ドメイン名とパスワードは説明用の仮の値であり、そのままでは接続できません。

proxies:
  - name: "サンプル接続先"
    type: ss
    server: proxy.example.com
    port: 443
    cipher: aes-128-gcm
    password: "your-password"
    udp: true

暗号化方式、パスワード、サーバー側のポートは、サーバーの設定と一致させてください。一般的なWeb用ポートを指定しても、そのノードがHTTPSサービスになるわけではなく、通常のブラウザーから直接アクセスできるわけでもありません。udp: trueは該当する機能を設定で許可することを示します。実際に使えるかどうかは、プロトコルの実装、サーバーの対応、上流ネットワーク、アプリのリクエスト経路によって異なります。UDPが通らない場合は、この項目だけを何度も切り替えず、経路全体を確認してください。

TLS・サーバー名・トランスポートの設定

TLSを使うプロトコルでは、接続先アドレスと証明書の検証に使う名前が異なる場合があります。serverは接続先を指定し、一部のプロトコルではservernameなどの項目を使ってサーバー名を送信・検証します。具体的な項目はプロトコルの設定形式によって異なります。WebSocketのパス、リクエストヘッダー、gRPCのサービス名などもサーバー側と一致させてください。これらの設定が抜けていると、TCPポートに接続できても、その後のハンドシェイクに失敗することがあります。

証明書エラーが発生した場合は、まずシステム時刻、サーバー名、証明書チェーン、サーバー側の設定を確認してください。証明書検証の無効化はセキュリティ上の境界を変えるため、一般的な対処方法として使うべきではありません。用途を理解しないまま、フィンガープリント、転送の最適化、接続の再利用に関する項目を追加するのも避けてください。ほかのプロトコルで使える項目が、現在のプロトコルでも使えるとは限りません。解析で未知または無関係な項目が受け入れられても、期待どおりに作用しているとは限りません。

リモートノードの集合とヘルスチェック

proxy-providersを使うと、ノードの取得元をメイン設定から分離でき、ノード一覧を定期的に更新する場合に便利です。プロバイダーファイルはノードプロバイダー用の形式に準拠している必要があります。DNSやルールを含む完全なサブスクリプションを、同じ形式の入力として扱えるとは限りません。以下はリモート取得元の記述例です。URLは説明用のものです。実際の設定には信頼できる取得元を使い、アクセス認証情報は非公開情報として扱ってください。公開リポジトリに登録してはいけません。

proxy-providers:
  remote-pool:
    type: http
    url: "https://example.com/proxies.yaml"
    path: ./providers/remote-pool.yaml
    interval: 86400
    health-check:
      enable: true
      url: https://www.gstatic.com/generate_204
      interval: 600

intervalは更新間隔を指定します。ヘルスチェックの間隔はノードの利用可否を確認する周期を制御するもので、役割が異なります。パスはコアの作業ディレクトリを基準に解釈されます。GUIクライアントでは専用のデータディレクトリを使う場合があります。更新に失敗した場合は、リモートからの応答異常、形式の不一致、ローカルディレクトリへの書き込み不可を切り分けてください。キャッシュが引き続き使えるかどうかも、ログで確認します。バックアップなしにキャッシュを削除し、まだ使えるノード一覧まで消さないでください。

ノード名と参照の安定性

サブスクリプションの更新によってノード名が変わることがあります。手動で作ったプロキシグループが古い名前を1つずつ参照していると、更新後に参照先が見つからなくなる場合があります。大量のノード名を複製するより、プロバイダーのuseでノード一覧を取り込むほうが、通常はメンテナンスしやすくなります。ただし、フィルター式も新しい命名方法に合わせて調整が必要です。複数の取得元を統合するときは、名前の重複を避けてください。重複は表示上の問題にとどまらず、接続先の選択、ログの確認、オーバーライドの特定を難しくします。

ノード一覧が表示されていても、接続可能であることが確認済みとは限りません。名前解決、サーバーへの接続、プロトコルのハンドシェイク、接続先へのアクセスの順に確認してください。1つのノードだけ失敗する場合は、同じプロキシグループにある別のノードと比較します。すべてのノードが失敗する場合は、ローカルネットワーク、通信の入口、システム時刻、設定の取得元を確認してください。速度テストの結果も、すべてのWebサイト、プロトコル、時間帯での実際の性能を示すものではありません。

クライアントを選ぶ際は、まずmacOSダウンロードページにあるClash Plusを確認し、必要な機能に応じてClash Verge RevやFlClashと比較してください。画面が似ていても、対応するコアの項目が同じとは限りません。GUIクライアントとコアの役割分担については、Clashのオープンソースエコシステムとmihomoの関係もご覧ください。そのうえで、どの層で設定を管理するか決めましょう。

プロキシグループの項目とヘルスチェック

プロキシグループはノードをまとめ、ルールから参照できる接続先の名前を付けます。ノードが頻繁に変わる場合、ルールから特定ノードではなくグループを参照すれば、ノードを入れ替えてもルール全体を書き直さずに済みます。グループから別のグループを参照し、手動選択と自動選択を組み合わせることもできます。ただし、参照関係を循環させないこと、グループ名を一意にすること、参照先のすべてが最終的な実行設定に存在することが必要です。元のサブスクリプションにあっても、オーバーライドで削除されたノードは参照できません。

手動選択グループと入れ子構造

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

  - name: "自動選択"
    type: url-test
    use:
      - remote-pool
    url: https://www.gstatic.com/generate_204
    interval: 300
    tolerance: 50

例のremote-poolは前の章で定義したプロバイダーを指します。proxiesには明示的なノード名やグループ名を指定し、useではプロバイダーのノード一覧を取り込みます。selectの場合、実際の接続先はユーザーが現在選択している項目によって決まります。リスト中のノードに問題が起きても自動で切り替わるわけではありません。自動選択の機能を持つ子グループを選んでいる場合は例外です。リストの順番から現在の選択状態を判断することもできません。

地域、用途、選択方法を分けるには、グループを複数階層にする方法が便利です。ただし階層が増えすぎると、設定が読みづらくなります。接続画面にルールの接続先が表示された後も、グループの現在の選択をたどって最終ノードを確認してください。問題の切り分けでは、既知のノードを直接参照するシンプルな選択グループを作り、まずノード自体が使えるか検証します。その後、自動選択や複雑な入れ子構造を戻すと、グループの選択ロジックとリモート接続の問題を分けて確認できます。

自動選択・フォールバック・負荷分散

url-testの結果は、指定したテストURLへの接続状況を示すもので、ダウンロード速度やすべての接続先を総合した評価ではありません。toleranceは小さな差による頻繁な切り替えを抑える項目で、単位はミリ秒です。一定の遅延を保証する値ではありません。候補ノードの品質が近い場合は、測定値の最小値を追い続けるより、ある程度の差を許容したほうが接続先を安定させやすくなります。

fallbackは候補の順番で優先順位を決めます。先にあるノードが利用可能ならそれを使い、テスト値が常に最小のノードを選ぶわけではありません。load-balanceは設定した分散方式に従って接続を処理します。1つの接続を複数の回線に分割し、帯域を合算する機能ではありません。ログイン状態、地域判定、セッションの一貫性が重要なアプリでは、複数の接続先を使う影響を考慮してください。名前に「負荷分散」とあるだけで、有効にするのは避けましょう。

テストURL・間隔・遅延チェック

テストURLには、安定していて応答が軽く、確認したい接続性を代表できるものを選びます。あるノードがテストサイトに接続できなくても実際の接続先には到達できる場合、自動選択ではテスト条件に合わないノードと判定されることがあります。逆にテストに成功しても、すべてのサービスが使えるとは限りません。テストURLのこうした限界を理解し、インターネット全体の状態を示すものとして扱わないでください。誤判定が疑われる場合は、実際の接続先へのリクエストとログを比較します。

intervalを短くするとテスト頻度が上がり、リクエスト数やデバイスの負荷も増えますが、ノードの帯域が直接向上するわけではありません。プロバイダーのヘルスチェックとプロキシグループのテストを併用すると、同じノードを重複してテストする場合があります。遅延チェックを必要になるまで行わないグループもあり、使われていない間は確認頻度が下がります。そのため、グループに切り替えた直後は状態が更新されるまで待つことがあります。すべての間隔を一律に極端に短くするのではなく、使い方に合わせて設定してください。

フィルター式と選択状態

filterや除外式でプロバイダーのノードを絞り込む場合は、まず名前に想定した文字列が含まれていることを確認します。正規表現の括弧、縦線、特殊文字にはそれぞれ意味があります。普通の説明文をそのまま確実なフィルター条件として使うことはできません。サブスクリプション更新後に名前が変わると、グループが空になる場合があります。フィルターを変更したら、グループ名が残っているかだけでなく、展開後の候補一覧も確認してください。候補が空になっている場合、自動選択の異常を疑う手がかりになります。

クライアントや設定で選択状態の保存が有効な場合、設定の再読み込み後に前回の手動選択が復元されることがあります。名前が変わると、選択状態を復元できない場合もあります。YAMLのリスト順をテストする際は、現在実際に選択されている項目を確認してください。先頭の項目が常に有効とは限りません。自動選択の3つの方式の詳しい違いと用途は、url-test・fallback・load-balanceの比較をご覧ください。必要に応じて既存のグループを調整します。

ルール構文と照合順序

ルールリストは順番に処理される判定リストです。コアは上から順に確認し、最初に一致したルールの接続先を使います。そのため、同じルールでも順番を変えると結果が変わることがあります。明確な例外を先に記述し、対象範囲の広いルールを後に置き、最後にフォールバックを追加してください。MATCHをリストの先頭に置いて、その後のドメインルールも有効になると考えてはいけません。制限のないリクエストは、フォールバックですでに処理されています。

ドメイン・サフィックス・キーワードのルール

rules:
  - DOMAIN,api.example.com,DIRECT
  - DOMAIN-SUFFIX,example.org,出口の選択
  - DOMAIN-KEYWORD,example,出口の選択
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - IP-CIDR6,fc00::/7,DIRECT,no-resolve
  - MATCH,出口の選択

DOMAINは完全一致するドメインを対象とし、特定ホストの例外設定に適しています。DOMAIN-SUFFIXはドメイン自身とそのサブドメインを対象にします。DOMAIN-KEYWORDは文字列を含むかどうかで判定するため、範囲が広く、無関係なサービスにも一致しやすくなります。ここで扱うのは完全なURLではないため、ルールにhttps://、パス、クエリパラメーターを含めないでください。特定のホストを判定する場合は、範囲が明確なルールを優先します。

各ルールの最後に指定する接続先は、実在するノード、プロキシグループ、または組み込みの接続先である必要があります。全角の読点は半角カンマの代わりにはなりません。名前に余分な空白があると、参照先との照合も難しくなります。接続先が見つからない場合は、ルールだけでなく、先行するノードのマージやプロキシグループのオーバーライドで名前が変わっていないかも確認してください。頻繁に更新されるノード一覧では、個別のノードよりも名前が安定したプロキシグループを参照するほうが管理しやすくなります。

IPルールと名前解決への影響

IP-CIDRとIP-CIDR6は、IPアドレスの範囲に基づいて判定します。リクエストにドメイン名しか含まれない場合、IPルールの判定前に名前解決が必要になることがあります。no-resolveを追加すると、そのルールの照合のためにコアが名前解決を開始するのを防げます。ただし、すべてのIPリクエストを無視する設定ではありません。接続先のIPアドレスがすでに分かっている場合は、そのアドレスで照合されることがあります。このオプションが制御するのは名前解決であり、直結かプロキシ経由かではありません。

プライベートIPアドレスの範囲を使うルールは、LAN内へのアクセスを保護するのに便利です。ただし実際のネットワークには、ほかのアドレス範囲や特殊なルートが含まれることがあります。ある検索結果から接続先が広いグローバルIP範囲の一部だと分かっても、その範囲全体を直結にしないでください。大規模サービスではIPアドレスを共有している場合があり、名前解決の結果もネットワークによって変わります。ドメインで明確に指定できる場合は、特定時点のIPアドレスに依存するより安定します。IPで振り分ける必要がある場合は、対象範囲と更新元を理解しておきましょう。

リモートルールセットの宣言方法

rule-providers:
  local-services:
    type: file
    behavior: domain
    format: yaml
    path: ./rules/local-services.yaml

rules:
  - RULE-SET,local-services,DIRECT
  - MATCH,出口の選択

対応するルールファイルは、以下の形式で記述します。ここでのbehavior: domainは、ファイルの内容がドメイン照合用であることを示し、ルールを1件ずつ記述した完全な形式ではありません。プロバイダーのclassicalを使う場合は、内容の形式と利用できるルールタイプが異なります。ルールプロバイダーの宣言、ファイル形式、実際の内容を一致させてください。拡張子が同じでも内部の構造が同じとは限りません。ダウンロード失敗時に返されたWebページをルールセットとして読み込むこともできません。

payload:
  - "+.example.org"
  - "router.example.com"

ルールセットには照合条件だけが保存され、実際の接続先はメイン設定にあるRULE-SETルールで決まります。ルールセットの読み込みに成功しても、その中のすべてのドメインが期待した接続先を使うとは限りません。先にあるルールが一致している場合があるためです。更新後は接続画面で、実際に適用されたルールの種類と接続先を確認してください。特定のドメインの問題を解決するために、リモートルール全体を最上部へ移動し、優先すべきLANや業務用の例外ルールまで変えてしまわないよう注意してください。

接続の再利用と検証方法

ルールを変更しても、通常は新しく確立する接続から反映されます。既存の長時間接続、ブラウザーの接続プール、アプリのセッションは、変更前の経路を使い続けることがあります。検証時は対象の接続を閉じ、接続先を明確にしたリクエストを送信して、適用されたルール、プロキシグループ、最終ノードを確認してください。1つのWebページでも複数のドメインにアクセスすることがあります。メインのページ、画像、ログイン、APIリクエストが同じ経路を使うとは限りません。ページが開くかどうかだけでは、各リクエストのルールが正しいか判断できません。

すべての通信入口でドメイン情報が必ず見えるとは限りません。アプリがIPアドレスに直接接続する場合、独自の名前解決を使う場合、以前の接続を再利用する場合は、ルールが利用できる情報が異なることがあります。適用可能な状況ではスニッフィング機能でドメインを補完できますが、完全なURLを識別する機能ではなく、すべての暗号化接続から情報を取得できるわけでもありません。接続記録に実際に表示されているメタデータをもとに調べてください。コアがブラウザーのアドレスバーにあるすべての情報を取得できると想定しないでください。

設定のオーバーライド・マージ・検証手順

オーバーライドを使うと、サブスクリプションを更新しながら、ローカルのポート、DNS、ルール、プロキシグループの選択などを維持できます。重要なのは、YAMLをもう1つ追加することではなく、複数の設定をクライアントがどのように統合し、最終設定を生成するかです。元のサブスクリプション、ローカルのオーバーライド、クライアントの設定、実行時のAPI変更は、それぞれ異なる階層にある場合があります。最終的にどの設定が適用されるかは、すべてのクライアントで共通ではありません。使用中のクライアントのマージ仕様と、実際に生成された設定を確認してください。

スカラー・マッピング・リストの違い

スカラー項目は、通常、新しい値が前の値を上書きします。たとえば、混合ポートが別の番号に変わります。マッピングは階層的にマージされる場合も、全体が置き換わる場合もあります。リストは置換、先頭への追加、末尾への追加、専用スクリプトによる処理など、クライアントによって異なります。あるクライアントでのマージ方法を、別のクライアントにそのまま当てはめないでください。特にルールリストは、置き換えると元のルールが消え、末尾に追加するとMATCHより後ろになり、実際には照合されないことがあります。

サブスクリプションとローカル設定を分ける

ノードの認証情報やリモートノード一覧は、信頼できるサブスクリプションに合わせて更新するのが適しています。待ち受けポート、LAN接続の許可、ローカルDNSの例外は、デバイス側に保存するのがおすすめです。一時的にダウンロードしたキャッシュファイルを直接編集しても、次回の更新で変更が失われる場合があります。ネットワークインターフェース名、絶対パス、ローカルの待ち受けアドレスをすべてのデバイスに同期するのも避けてください。OSやクライアントによって、データディレクトリ、権限、対応項目は異なります。

# ローカル項目の例。マージ方法はクライアントの仕様を確認
mixed-port: 7890
allow-lan: false
log-level: info

profile:
  store-selected: true

この例は維持したいローカル項目を示すもので、ルールのマージ方法を定義するものではありません。profile.store-selectedはプロキシグループの選択状態を保存する項目で、クライアントがサブスクリプションファイルを保存する設定とは異なります。クライアント側に同じ項目がある場合は、画面の設定値とオーバーライドのどちらが優先されるか確認してください。同じ項目を複数の場所で管理すると、エディターの値と画面表示が食い違い、後から問題を調べにくくなります。

最終設定の確認と最小限の変更

変更を始める前に、現在正常に動作している設定をエクスポートまたはバックアップし、使用中のクライアント、コアの種類、重要な設定を記録してください。変更後は最終的な実行設定を開き、対象の項目が含まれているか、別の設定レイヤーに上書きされていないか、参照先のグループ名が残っているか確認します。元のサブスクリプションが変わらず、実行設定だけが変わるのは、設定の生成処理として正常な場合があります。元のファイルを変更できても実行設定が変わらない場合は、別のファイルを編集したか、設定の再生成が行われていない可能性があります。

検証は4段階に分けて進められます。まずYAMLの構文とコアの読み込みを確認し、次にローカルポートで待ち受けていることを確認します。その後、接続先を明確にしたプロキシリクエストをテストし、最後に適用ルールと接続先を確認します。各段階で得られる証拠は異なります。構文が正しくてもノードに接続できるとは限りません。ノードに接続できてもシステムプロキシが設定済みとは限りません。ブラウザーが使えてもターミナルがプロキシ経由とは限りません。段階ごとに確認すれば、誤った設定箇所で試行を続けずに済みます。

mihomo -t -f ./config.yaml
lsof -nP -iTCP:7890 -sTCP:LISTEN
curl --proxy http://127.0.0.1:7890 -I https://example.com

コマンドラインでのテストは、クライアントの実際の動作環境と比較してください。単独で起動したコアでは、作業ディレクトリ、ルールキャッシュ、権限が異なる場合があります。単独のテストに成功しただけで、クライアントが生成した設定の問題を除外することはできません。設定の再読み込み後は、解析エラー、参照先の不足、待ち受けの失敗をログで確認し、最初に出た明確なエラーから対処します。後から大量に記録される接続エラーは、最初の読み込みエラーが原因のことがあります。1件ずつ独立したネットワーク障害として扱わないでください。

ロールバック・共有・よくある質問

変更によって接続できなくなった場合は、まず正常に動作していた設定に戻し、追加したオーバーライドを無効にしてから、変更点を1つずつ再適用します。元のサブスクリプションは残し、一時的なテストファイルで唯一のコピーを上書きしないでください。複数デバイスで同期するときは、共通して使える設定だけを共有し、ローカルパス、ネットワークインターフェース、デバイス固有のルールは各デバイスに残します。サブスクリプションURLやノードのパスワードは、アクセスを制限できる場所に保存してください。詳しくは複数デバイス間でClashの設定を同期する方法をご覧ください。

設定を管理する際は、各項目の取得元を明確にし、ルールの順序を説明できる状態に保ち、変更前にいつでも戻せる基準を用意することが大切です。問題が起きたら、まず原因の範囲を絞り、その後で必要な設定を追加してください。クライアントの再インストールや比較にはダウンロードページを、インポート、モード選択、接続確認を順に進めるにはクイックスタートガイドをご利用ください。このガイドを、すべての項目を一度に有効にするためのチェックリストとして使う必要はありません。