Clash設定項目リファレンス
YAMLと実行時設定

1. YAMLの構造と設定の範囲

mihomoが読み込むのは構造化された設定であり、上から順に実行するコマンドではありません。通常、ファイルのルートはマッピングで、その下に共通項目、DNS設定、プロキシのリスト、プロキシグループのリスト、ルールのリストを記述します。項目の記述順は通常、優先順位に影響しませんが、リストの順序は動作を直接左右することがあります。特にルールリストは上から順に照合されるため、自由に並べ替えられる説明一覧のように扱うことはできません。

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

マッピングではコロンで項目と値を区切り、リストではハイフンで複数の要素を記述します。インデントにはスペースを使い、階層ごとに半角スペース2つで統一するのがおすすめです。タブは混在させないでください。同じ階層の項目は位置をそろえ、子項目は親項目より深くインデントします。コロンの後には区切りのスペースが必要です。半角の句読点を全角のコロンや読点に置き換えないでください。エディターに表示された行が必ずしも原因とは限らず、前の行で引用符が閉じていないために、次の行でエラーになる場合もあります。

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

dns:
  enable: true
  listen: 127.0.0.1:1053
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  nameserver:
    - https://dns.alidns.com/dns-query

proxies: []

proxy-groups:
  - name: デフォルト出口
    type: select
    proxies:
      - DIRECT

rules:
  - MATCH,デフォルト出口

この例は設定の構造を理解するためのもので、すべての通信は最終的に直結となり、プロキシ接続を提供するものではありません。proxies: []は空のリストを表し、項目を空の値にするのとは異なります。ルート直下のdnsはマッピングで、nameserverはその中のリストです。プロキシグループのリストでは各要素がマッピングとなるため、同じファイル内でこれらの構造が使われます。例をコピーする際は、関連して見える1行だけではなく、階層全体を保ってください。

文字列の型と参照関係

パスワード、名前、パス、特殊文字を含む値には、引用符を付けることをおすすめします。特に数字に見えるパスワード、シャープ記号、コロン、バックスラッシュには注意してください。通常のスカラー値ではシャープ記号がコメントの開始と解釈される場合があります。また、Windowsのパスを二重引用符で囲むとエスケープ処理が発生することがあります。スラッシュ区切りのパスや、適切な単一引用符の使用が確認しやすい方法です。真偽値はtrueまたはfalseと記述します。見た目をそろえるためにすべての値を引用符で囲むと、真偽値が文字列として扱われることがあります。

ノード名、プロキシグループ名、ルールの出力先は、相互に参照し合います。ルールからグループを参照する場合、グループのnameと大文字・小文字や空白も含めて完全に一致させる必要があります。従来形式のルールではカンマが引数の区切りになるため、名前にカンマを含めるのは避けましょう。ノードの削除やグループ名の変更前に、他のグループやルールから参照されていないか検索してください。設定の解析に成功しても、すべての参照が解決できるとは限りません。参照の問題は設定の検証時や読み込み時に明らかになることがあります。

元ファイルと実行時の設定

サブスクリプションの元データ、クライアントのローカル設定、コアが実際に読み込むファイルは、それぞれ別のものです。クライアントは起動時にポート、DNS、TUNの項目を書き換えたり、サブスクリプションにルールを追加したりする場合があります。一時的な実行ファイルを直接編集しても、次回の更新や再起動で上書きされる可能性があります。まずクライアントの設定管理、上書き、マージの機能を確認し、変更がどの階層に保存されるかを把握してから、最終的に生成された設定を確認してください。画面から実行時設定を書き出せない場合は、ログやアクセス制限されたコントロールインターフェースで重要な項目を確認します。

部分的な設定例は、該当する項目の説明に限って使用してください。この章の構造例を除き、以降の断片をそのまま完全な設定として起動しないでください。参照先のノード、プロキシグループ、プロバイダーが、最終的な設定内に定義されていることを確認します。

YAMLアンカーは記述の重複を減らせますが、マージキーで結合できるのは主にマッピングです。2つのルールリストが自動で連結されることは期待できません。設定の管理に慣れていない場合は、複雑な再利用より明示的に記述したほうが、問題を切り分けやすくなります。追加を意図して同じ階層にdnsやrulesを重複定義するのも避けてください。重複キーの扱いはパーサーによって異なるため、項目を1つにまとめ、明確なマージ手順で処理する方法が確実です。

2. ポート、モード、ネットワークの制御

共通項目では、コアが接続を受け付ける方法、出力先の選び方、LANからのアクセス可否を設定します。変更前に、3つの経路を区別してください。アプリがプロキシの待ち受けポートに直接接続する方法、システムプロキシによってシステム設定に従うアプリをそのポートへ誘導する方法、仮想ネットワークインターフェースを使うTUNで対象範囲の通信を引き受ける方法です。これらは併用できますが、問題が起きたときは経路ごとに確認してください。複数の制御方式を同時に有効にすると、原因のある階層を特定しにくくなります。

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

互換性の要件がなければ、mixed-portだけを設定できます。複数のリスナーを使う場合は異なるポートを指定してください。portとmixed-portで同じアドレスとポートを同時に使用することはできません。ポートを変更しても、プロキシを手動設定したブラウザー、ターミナル、その他のデバイスには自動反映されません。ログにアドレスが使用中と表示された場合は、ポートを次々に変更してプロセスの競合を隠すのではなく、別のClashクライアント、古いコアのプロセス、ローカルサービスが待ち受け先を使用していないか確認してください。

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

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

上の例ではTUNを明示的に無効にし、まずアプリからプロキシへ直接接続する経路を確認します。有効にする場合はtun.enableをtrueに変更し、クライアントに仮想ネットワークインターフェースの作成とルート変更の権限があることを確認してください。stackの有効な値は、プラットフォームやコアの機能によって異なります。値の名前だけから互換性を判断することはできません。クライアントがこれらの項目を自動管理する場合もあるため、手動で設定した後は実行時の設定も確認してください。

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

mode: ruleではルールリストに基づいて通信を振り分けます。グローバルモードではグローバル用のプロキシグループに通信を渡し、直結モードは主にプロキシ経路の問題を切り分ける際に使います。グローバルモードにしても、すべての通信が必ずリモートノードを経由するとは限りません。グローバル用のグループでDIRECTが選択される場合もあります。モード変更後は、グループ内で実際に選択されているメンバーも確認してください。既存の長時間接続は変更前の出力先を維持することがあります。検証には新しいリクエストを使い、必要に応じて該当する接続を閉じてから再試行します。

LAN内で共有するには、待ち受け設定、ホストのファイアウォール、ネットワーク構成のすべてが接続を許可している必要があります。allow-lanを変更するだけで他のデバイスから接続できるとは限りません。接続元では自分自身のループバックアドレスではなく、ホストのLANアドレスを指定します。待ち受けを公開する前に、接続中のネットワークが信頼できるか評価し、必要に応じてプロキシ認証を設定してください。プロキシ認証はプロキシの接続口を保護するもので、コントロールインターフェースのアクセス認証とは別です。互いに代用できず、コントロールインターフェースをインターネットに直接公開してはいけません。

TUNとIPv6の注意点

auto-routeは関連するルートを自動設定し、auto-detect-interfaceは出力インターフェースの判定を補助します。ただし、複数のネットワークインターフェース、仮想マシン、他のVPNとの競合をすべて解消できるわけではありません。接続ループが発生した場合は、プロキシサーバー自身の通信が再びTUNに取り込まれていないか、他のソフトウェアがデフォルトルートを書き換え続けていないかを確認してください。デスクトップOSのサービス権限とモバイルOSのVPN許可は別の仕組みです。一方のプラットフォームでの手順を、もう一方にそのまま適用することはできません。

トップレベルのipv6とdns.ipv6は異なる階層の設定です。前者はコアでIPv6を使うかどうかに、後者はDNSでAAAAレコードを解決するかどうかに影響します。問題を切り分けるときは、システムに利用可能なIPv6ルートがあるか、ノードが該当する通信経路に対応しているか、DNSがIPv6アドレスを返しているかを併せて記録してください。片方のスイッチを無効にしただけで、接続経路全体がIPv4に切り替わったとは判断できません。接続ログと実際の名前解決結果に基づいて項目を調整してください。

3. DNSとFake-IPの設定

DNS設定は接続先ドメインの名前解決だけでなく、プロキシサーバーのアドレス解決にも影響する場合があります。まず、システムがどこに問い合わせるか、コアがどの上流DNSを使うか、その上流のドメイン名を最初にどう解決するか、問い合わせがどの経路から送られるかを区別してください。ページが開けることだけでは、想定どおりのDNS経路である証明にはなりません。アプリがキャッシュを使っていたり、独自の暗号化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:
    - 223.5.5.5
  nameserver:
    - https://dns.alidns.com/dns-query
  proxy-server-nameserver:
    - https://dns.alidns.com/dns-query
  nameserver-policy:
    "+.example.com":
      - https://dns.alidns.com/dns-query

enableでコアのDNSモジュールを有効にし、listenでサービスの待ち受け先を設定します。例にあるループバックアドレスと標準とは異なるポートは、同じデバイス内からの利用を想定しています。この項目を設定しても、システムのすべてのDNS問い合わせが自動的にここへ送られるわけではありません。実際の転送はクライアント、システムのDNS設定、TUNのDNSハイジャックなどによって行われます。TUNのany:53を設定しても、アプリが任意の暗号化DNSサービスへ直接送信する問い合わせまで制御できるとは限りません。通常、それらは一般的な暗号化通信として扱われます。

nameserverには通常の問い合わせに使う上流DNSを指定します。default-nameserverは、暗号化DNSサービスのドメインを最初に解決する場合など、初期名前解決に使用します。proxy-server-nameserverはプロキシサーバーのドメイン名解決に使い、ノードの名前解決がプロキシ接続に依存し、その接続がさらにノードの名前解決に依存するループを減らせます。例ではパブリックDNSを使っていますが、実際の選択はネットワークの到達性とプライバシー要件に基づいてください。上流を変更したら、まず現在のネットワークから接続できるか確認します。

Fake-IPと実アドレスによる名前解決

Fake-IPモードでは、アプリにアドレスプール内の合成アドレスを返し、コアがそのアドレスとドメインの対応を保持します。後続の接続がコアに取り込まれた際にドメインを復元し、ルールを適用します。これにより、ドメインに基づく振り分けに必要な情報を保持できます。ただし、アプリが受け取った合成アドレスと接続の両方が、同じコアの処理を通ることが前提です。コアを経由せず合成アドレスへ直接接続した場合や、コアの再起動後もアプリが古いキャッシュを使い続けた場合は、ノード自体が使えないのではなく接続に失敗することがあります。

fake-ip-filterを使うと、特定のドメインに合成アドレスを使わないよう設定できます。例にはLANでよく使われる名前のサフィックスを挙げていますが、フィルターに追加しても、パブリックDNSがLAN内のレコードを認識するわけではありません。必要に応じて、名前解決ポリシーでLAN内のDNSを指定します。LANデバイスの問題を直すためにすべてのドメインをフィルターへ追加すると、従来のドメイン復元経路が変わってしまいます。まず失敗するドメインを特定し、必要最小限の範囲で追加してから、アプリとシステムのキャッシュを消して再テストしてください。

redir-hostでは、アプリに実際の名前解決アドレスを返し、接続時に取得済みの情報を使って振り分けを行います。Fake-IPとの主な違いは、返すアドレスとドメインを関連付ける方法です。単純に一方が速く、もう一方が安全というわけではありません。実アドレスの表示、特殊なLAN内デバイスの検出、アプリ内部でのアドレスチェックなどが必要な場合は、通信の取り込み方法も含めて実際に確認してください。仕組みの詳しい説明はFake-IPとredir-hostの違いをご覧ください。

名前解決と通信の振り分けを分けて確認

nameserver-policyはドメインに応じてDNSの上流を選択し、ルールリストは接続情報に基づいて出力先を選択します。あるドメインを特定のDNSサーバーで名前解決しても、そのドメインへの接続が同じプロキシポリシーを使うとは限りません。DNS上流への接続にもルールを適用する必要がある場合は、respect-rulesを検討できます。ただし、有効にする前にプロキシサーバーのドメイン名を解決する独立した経路が使えることを確認し、上流DNSのドメイン名が循環参照にならないか調べてください。複数の仕組みを一度に追加して、問い合わせ経路を推測するような進め方は避けましょう。

DNSの結果が変わっても、既存の接続、アプリのキャッシュ、システムキャッシュに古い情報が残ることがあります。テストには新しいリクエストを使い、問い合わせたドメイン、返されたアドレス、適用された名前解決ポリシー、最終的な出力先を記録してください。キャッシュの違いを、設定が反映されていないと誤認しないようにしましょう。

fallbackを設定する場合は、対応するフィルター条件も確認してください。リストの先頭から順に試すだけの予備DNSサーバー一覧ではありません。地域判定を使う場合は、地理データベースの利用可否も結果に影響します。設定に慣れていない方は、到達可能な通常の上流DNSと、ノード用の独立した名前解決経路を1つずつ用意し、動作を確認してから複雑なポリシーを追加してください。名前解決がタイムアウトする場合は、上流に接続できないのか、初期名前解決に失敗しているのか、通信がDNSへ転送されていないのかを切り分け、すべてのDNS項目を一度に変更しないでください。

4. プロキシとプロトコルの設定

proxiesは、プロキシノードを直接記述するリストです。各要素はプロキシグループから参照できる出力先を表します。ノードには少なくとも一意の名前、プロトコル種別、そのプロトコルが求めるサーバーと認証情報が必要です。プロトコル間で設定項目を自由に置き換えることはできません。パスワードを使う場合でも、Shadowsocksの暗号化方式、TrojanのTLS設定、他のプロトコルのユーザー識別情報は、それぞれ異なる構造です。似た行を別々の解説から寄せ集めるのではなく、サービス提供元が示す設定値を基準にしてください。

基本項目とプロトコルごとの設定

proxies:
  - name: サンプル-SS
    type: ss
    server: proxy.example.com
    port: 8388
    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

例にある予約済みドメインと説明用パスワードは、実際の接続には使えません。サービス提供元から提示された設定一式に置き換えてください。serverにはドメイン名またはアドレスを指定し、portにはリモートサービスの待ち受けポートを指定します。ローカルのmixed-portとは関係ありません。nameはローカルで参照するための名前で、リモートの認証には使われません。名前を変更するとグループ内で見やすくなりますが、その名前を使うプロキシグループも同時に変更してください。そうしないと、ノードが存在していても正しく選択できません。

Shadowsocksのcipherはサーバー側の設定と一致させてください。認証に失敗する場合、DNSを変更しても通常は解決しません。Trojanは一般にTLSを使用し、sniにはTLSハンドシェイクで使うサーバー名を指定します。接続がタイムアウトするからといって、任意のアクセス可能なWebサイトのドメイン名に変更しないでください。アドレスで接続し、証明書がドメイン名に対して発行されている場合は、実際のサービス設定に沿って名前を指定します。接続先アドレス、ポート、認証情報、TLS上の識別情報は別々の項目なので、それぞれ確認してください。

TLS、トランスポート、UDP

skip-cert-verify: falseは証明書の検証を有効にした状態です。証明書エラーが発生した場合は、システム時刻、証明書チェーン、名前の一致、接続先が想定したサーバーかどうかを確認してください。検証を無効にすればエラーが見えなくなる場合はありますが、接続先の身元が正しいことの証明にはなりません。プロトコルによってはtlsでTLSを有効にしますが、プロトコル自体にTLSの仕組みが含まれる場合もあります。すべての種類が同じ設定項目を受け付けるとは限りません。未知の項目や階層が違う項目は、明確なエラーを出さず無視されることもあります。

WebSocket、HTTP/2などのトランスポートを使う場合、設定をサーバー側の構成に合わせる必要があります。WebSocketのパスは通常ws-opts.pathに、追加のリクエストヘッダーは該当するheadersマッピングに指定します。接続先アドレス、TLSのサーバー名、HTTPのHostヘッダー、リクエストパスが異なることはありますが、その違いは実際のサーバー構成に基づく必要があります。適当に混在させないでください。ノードの種類を正しく指定するだけでは、トランスポートに必要な設定がそろうとは限りません。

udp: trueは、ノードで該当するUDP通信を扱えるようにする設定です。もともとUDPに対応していないサーバーに、その機能を追加するものではありません。Webページは開けるのに音声通話、ゲーム、QUIC接続が失敗する場合は、アプリの通信が取り込まれているか、コアがプロトコルに対応しているか、リモートサービスやネットワーク機器に問題がないかを個別に確認してください。アプリのQUICを無効にする方法は切り分けには使えますが、UDPが復旧した証明にはなりません。テストではUDP転送とDNS問い合わせを区別してください。両者で異なる出力先を使う場合があります。

ノードのインポートと認証情報の取り扱い

サブスクリプション内のノードが必ずproxiesに直接記述されるとは限りません。プロキシプロバイダーを通じて動的に読み込む場合もあります。元の共有リンク、エンコードされたノード一覧、完全なClash設定は別の形式です。拡張子を変更しただけでYAMLとして使うことはできません。インポートに失敗したら、まず取得した本文がログインページ、エラーページ、非対応形式ではないか確認し、その後でプロトコル項目を調べてください。切り分けの手順はサブスクリプションの追加失敗・解析エラーの確認方法をご覧ください。

設定の一部を共有する前に、サーバーの識別情報、パスワード、ユーザーID、サブスクリプションURL、アクセス用の追加パラメーターを取り除いてください。ノード名に機密性がなくても、サブスクリプションURLでアカウントにアクセスできる場合があります。トラブル対処には、項目名、階層、プロトコル種別、エラーメッセージがあれば十分なことが多く、認証情報を公開する必要はありません。自動更新されるサブスクリプションのノードをインラインで複製し、長期間管理するのは避けましょう。サブスクリプションを元データとして維持し、クライアントが対応する上書きレイヤーでローカルルールやグループ選択を設定してください。

ノード名が重複すると、特に複数のサブスクリプションをマージした場合に参照先が曖昧になります。2つ目のソースを追加する前に、同じ名前のノードやプロキシグループ、同じプロバイダーパスがないか確認してください。クライアントに名前のプレフィックスやフィルター機能があれば、個別に手作業で名前を変更するのではなく、ソースごとにまとめて処理します。設定を管理しやすくするには、ソース、認証情報、プロキシの参照を分けておきましょう。いずれかを変更しても、他のすべてを編集し直す必要がありません。

5. プロキシグループとプロバイダー

プロキシグループはノードや他のプロキシグループをまとめ、ルールから参照できる出力先を作ります。グループの役割は出力先の選択であり、接続がどの用途に属するかを判定することではありません。よくある構成では、ルールが用途別グループを参照し、そのグループから手動選択用または自動選択用のグループを選び、自動選択用グループがプロバイダーからノードを取得します。この階層化により、ノードの変更がルールに与える影響を抑えられます。ただし、グループ間で循環参照があると、最終的な出力先を決定できません。

手動選択と自動テスト

proxy-providers:
  ローカルノード:
    type: file
    path: ./providers/local.yaml
    health-check:
      enable: true
      url: https://www.gstatic.com/generate_204
      interval: 600

proxy-groups:
  - name: 自動出口
    type: url-test
    use:
      - ローカルノード
    url: https://www.gstatic.com/generate_204
    interval: 600
    tolerance: 50

  - name: デフォルト出口
    type: select
    proxies:
      - 自動出口
      - DIRECT
    use:
      - ローカルノード

providers/local.yamlは実際に存在し、ルートにproxiesリストを含み、その中に実際のノードが記述されている必要があります。前章のサンプルノードは構造の確認にのみ使ってください。パスは通常、コアの作業ディレクトリを基準に解決されます。クライアントがファイルへのアクセス範囲をさらに制限する場合もあります。ファイルが見つからない場合は、現在編集中のファイルからの相対パスだと決めつけず、実際の作業ディレクトリを確認してください。ファイルプロバイダーは参照関係の説明に適しています。リモートサブスクリプションでは通常、HTTP形式と更新URLを使います。

selectではユーザーがメンバーを手動で選択します。url-testはテスト結果に基づいて利用可能な出力先を選びます。fallbackはメンバーの順序に沿って利用可能な出力先を探し、load-balanceは選択した方式に従って接続を振り分けます。自動テストで分かるのはテスト先への通信状態であり、すべてのWebサイト、ストリーミングサービス、業務サービスへの接続性ではありません。テスト先は安定してアクセスできるものを選び、特定のログイン状態が必要なページを稼働確認に使うのは避けてください。

テスト間隔、許容遅延、グループ内のメンバー

intervalの設定例では単位は秒です。toleranceは自動選択時に許容する遅延差を表し、例の値はミリ秒単位です。許容値を設けると、結果がわずかに変化しただけで頻繁に切り替わるのを防げますが、ノードの不安定さや不適切なテスト先を解決するものではありません。ヘルスチェックは実際のネットワークリクエストを発生させるため、大規模なサブスクリプションで短い間隔をむやみに設定しないでください。クライアントはバックグラウンド動作中やスリープ中にタスク実行を調整することがあり、画面の更新時刻だけでは各テストが予定どおり実行された証拠になりません。

proxiesでは明示的なメンバー名を列挙し、useではプロキシプロバイダー名を指定します。同じグループに両方を記述できますが、意味は異なります。前者は既知のノードやグループを参照し、後者はプロバイダー内のノード一覧を取り込みます。プロバイダーのヘルスチェックとプロキシグループのテストも別の階層です。同じテスト先を使う場合でも、結果や実行タイミングを同一視しないでください。グループが空の場合は、すべてのノードが使えないと判断する前に、プロバイダーの読み込み結果とフィルター条件を確認します。

ネストしたグループは、有向で循環のない参照関係にしてください。たとえば、用途別グループがデフォルト出口を参照し、デフォルト出口が自動選択用グループを参照する構成は可能ですが、自動選択用グループから用途別グループへ戻る参照は避けます。階層が深すぎると画面上の選択状態を把握しにくくなるため、ルールの出力先から最終ノードまでの参照経路を図にしておくと管理しやすくなります。ルールが正しく適用されているのに直結される場合は、最上位グループ名だけを見るのではなく、経路上の各グループでDIRECTが選択肢として許可され、選択されていないか確認してください。

リモートプロバイダーと更新後の設定保持

HTTP形式のプロバイダーでは通常、url、path、更新間隔を設定します。サブスクリプションURLはアクセス認証情報の一部です。公開リポジトリや公開ログに記載しないでください。キャッシュパスは一意にします。異なるソースで同じパスを使うと、互いに上書きされる可能性があります。自動更新に失敗した場合は、リモートへのリクエストが失敗したのか、ローカルキャッシュが引き続き使えるのかを切り分けてください。画面にノードが残っていても、最新のサブスクリプションを取得できたとは限らず、キャッシュ内のノードが現在も有効とは限りません。

名前でフィルターする場合は、正規表現のマッチ範囲、大文字・小文字、プロバイダー更新後の名前の変化を確認してください。フィルターに一致する項目が0件だと、自動選択用グループに候補がなくなります。テスト間隔を短くしても解決しません。まずフィルターを外してノードを読み込めることを確認し、その後、対象を段階的に絞り込んでください。グループ選択の保存には、profile.store-selectedなど、クライアントまたはコアの対応する永続化機能が必要です。保存されるのは選択状態であり、サブスクリプションの更新に代わるものでも、削除済みノードを再作成するものでもありません。

プロキシグループ名を安定させ、ノードのソースを更新可能にしておくほうが、サブスクリプション全体をコピーするより管理しやすくなります。ローカルルールの出力先を安定したグループ名に設定し、プロバイダー経由でノードを更新すれば、サブスクリプションの変更がルールに与える影響を抑えられます。

6. ルール構文と照合順序

ルールモードでは、rulesは上から順に照合されるルールリストです。通常、各ルールは種類、照合対象、出力先で構成され、一部の種類では追加パラメーターを指定できます。最初に一致したルールで出力先が決まり、それ以降のルールは評価されません。そのため、ルールの管理では数よりも順序の設計が重要です。ルールセットを大量に追加しても、振り分けの精度が自動的に上がるわけではありません。条件の重複や広範囲なルールの置き場所によって、細かいルールが意図せず適用されなくなることがあります。

ドメイン、アドレス、フォールバック

rules:
  - DOMAIN,printer.example.com,DIRECT
  - 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
  - IP-CIDR,172.16.0.0/12,DIRECT,no-resolve
  - MATCH,デフォルト出口

DOMAINは完全一致するドメインを照合し、DOMAIN-SUFFIXは指定したドメインとそのサブドメインを照合します。DOMAIN-KEYWORDはドメインに含まれるキーワードを照合します。キーワードの適用範囲は広く、無関係なドメインまで同じポリシーに含めてしまう可能性があります。対象を明確に分けたい場合は、完全一致またはサフィックスを優先してください。例では完全一致のドメインを前に置き、後続のキーワードルールが先に適用されないようにしています。ルールの出力先には、存在するノード、プロキシグループ、または組み込みの出力先を指定してください。

IP-CIDRは宛先のIPv4アドレス範囲を照合し、IPv6の範囲には対応するIP-CIDR6を使います。no-resolveは、この種類のルールを評価するためだけにドメイン名の名前解決を行わないようにする設定です。接続全体でDNSが不要になるという意味ではなく、宛先アドレスが既に分かっている場合に照合を防ぐものでもありません。プライベートネットワークを直結するルールも、接続時の情報に依存します。特にFake-IPモードでは、合成アドレスをアプリがアクセスする実サーバーのアドレスと混同しないでください。

ルールセットとルールの種類

rule-providers:
  ローカルドメイン:
    type: file
    behavior: domain
    format: yaml
    path: ./rules/local-domains.yaml

rules:
  - RULE-SET,ローカルドメイン,DIRECT
  - MATCH,デフォルト出口

この例を使うには、実際に存在するルールファイルが必要です。内容は次の例のようにできます。ドメイン形式のルールセットにはドメインだけを記述し、各項目にプロキシグループを追加しません。ルールの出力先は、メイン設定のRULE-SETルールで指定します。classical形式ではルール種別を含む項目を使い、ipcidr形式ではアドレス範囲を記述します。ルールセットの種類、ファイル形式、実際の内容を一致させてください。ダウンロードした別形式のセットを、ファイル名だけ変えて読み込ませることはできません。

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

RULE-SETのプロバイダー名は、rule-providersのキーと一致させる必要があります。ローカルパスやリモートURLではありません。複数のルールセットで条件が重なった場合も、優先順位はメインルールリスト内の位置で決まります。HTTP形式のルールプロバイダーではキャッシュと更新も関係するため、現在読み込まれているルールと更新時刻を併せて確認してください。リモート更新に成功したことは、対象のドメインがそのルールセットに含まれている証明にはなりません。

プロセスルールとプラットフォームの違い

プロセス名、プロセスのパス、アプリ識別子に基づくルールは、プラットフォームや権限、コアが接続元のプロセス情報を取得できるかどうかに依存します。デスクトップOSでプロセスルールが適用されたからといって、モバイルOSでも同じ情報が得られるとは限りません。ログに想定したプロセス情報が表示されない場合は、実行時の権限とクライアントの対応状況を確認してください。複数のプラットフォームで共用する設定では、ドメインとアドレスに基づくルールのほうが一貫して使いやすい傾向があります。プロセスルールは実機で確認した補助条件として使い、唯一の振り分け条件にはしないでください。

GEOIPや地理情報に基づくドメインセットは、データベースと読み込み方法に依存します。データベースがない、配布元が変わった、更新に失敗したなどの理由で、照合結果が変わることがあります。ルールが適用されない場合は、ルールの書き方を変える前に、対象の情報とデータの状態を確認してください。ドメインが一度解決されたときの単一アドレスを、対象サービスの固定アドレスとみなすのも避けましょう。CDN、地域別の名前解決、サービスの移行などでアドレスは変わります。特定のサービスを細かく制御する場合はドメインの範囲を管理し、接続ログで関連する他のドメインも確認してください。

MATCHはフォールバック用のルールで、通常は最後に置きます。前に置くと、後続のルールが照合されなくなります。カスタム例外は、その例外を覆うルールセットより前に配置しますが、機械的に必ず1行目にする必要はありません。変更後は新しい接続を作り、ルールの種類、照合内容、プロキシグループ、最終ノードを確認してください。正しいルールが適用されているのにアクセスできない場合は、ルールを重複して追加するのではなく、ノードやDNSを調べます。ルールによる振り分けと接続経路の利用可否は、別々に検証する必要があります。

7. サブスクリプションの上書きと設定マージ

サブスクリプションは通常、外部の提供元が管理します。一方、ローカルの要件には待ち受けポート、LAN設定、DNS、追加ルール、プロキシグループの選択などがあります。上書き機能を使うと、これらのローカル設定を別のレイヤーに保存し、サブスクリプション更新後に再適用できます。サブスクリプション提供元の内容を直接変更する機能ではなく、YAMLで統一された標準機能でもありません。マッピング、リスト、空の値の扱いはクライアントによって異なるため、まずマージ規則を確認し、上書きに完全なオブジェクトが必要か、変更箇所のみでよいかを判断してください。

まず各項目の管理元を確認する

ポートやTUNはクライアントの設定画面で管理されることが多く、ノードやプロバイダーは通常サブスクリプションから取得します。用途別のルールは、サブスクリプションとローカルの追加設定を組み合わせて生成される場合があります。同じ項目を複数のレイヤーで管理している場合、最終的な値は設定の生成順序で決まります。画面上のスイッチだけを見て元ファイルが変更されたと判断したり、元ファイルに値があるから実行時にも上書きされていないと考えたりしないでください。サブスクリプションの元データ、ローカルの上書き設定、最終的な実行ファイルを並べて比較し、重要な項目がどこから来たか記録してください。

マッピングのマージとリストの置き換え

以下はDNSとログを調整するための部分的な上書き例です。サブスクリプション内の他のDNS項目が保持されるかどうかは、クライアントが再帰的にマージするか、全体を置き換えるかによって異なります。全体置換の場合、nameserverを省略するとDNS設定が不完全になる可能性があります。適用前にマージ結果を出力または確認してください。保存できたことだけで正しく設定されたとは判断できません。クライアントによってはDNS専用の上書き設定があり、それを有効にすると、一般的な上書き設定にある同名項目が最終設定に反映されない場合もあります。

# 部分的な上書き例。マージ方法はクライアントによって異なります。
log-level: info
dns:
  enable: true
  ipv6: false
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  nameserver:
    - https://dns.alidns.com/dns-query

リストはマッピングよりも慎重に扱う必要があります。ルールが2つだけのrulesリストを共通の上書き設定に書くと、2つを追加するのではなく、サブスクリプションのルール全体を置き換えることがあります。プロキシグループのリストを記述した場合も、サブスクリプションにあるグループが削除され、多数のルール参照が無効になる可能性があります。クライアントが前置ルール、後置ルール、専用のマージ機能を明示的に提供している場合は、そちらを優先してください。全体置換しか使えない場合は、リスト全体を管理し、サブスクリプションの構造変更に合わせて更新する必要があります。

ルールを追加する場合は、挿入位置にも注意が必要です。元のサブスクリプションの末尾には通常MATCHがあるため、その後ろにドメインの例外を追加しても適用されません。例外を有効にするには、該当する広範囲のルールより前に挿入します。また、例外の出力先が新しいローカルグループの場合、そのグループとメンバーのソースが生成されることも確認してください。ルール、グループ、プロバイダーは一続きの参照関係です。一部だけ保存しても、実行可能なローカル設定にはなりません。

クライアントごとの違いと更新後の確認

Clash Plus、Clash Verge Rev、FlClashなどでは、サブスクリプション設定を管理する画面や手順が異なります。同じ設定断片を確認せずに別のクライアントで使い回さないでください。設定管理、上書き、ルール追加、実行時設定に関する機能を探し、説明を読んでから通信に影響しにくい項目でマージ方法を試します。たとえば、まずログレベルだけ変更して実行時に反映されるか確認し、次に挙動を確認しやすいドメインルールを1つ追加します。その後でDNSや通信の取り込み経路を変更すれば、どの階層で違いが生じたか分かりやすくなります。

サブスクリプションを更新する前に、ローカルの上書き設定と使用可能な設定のコピーを保存してください。ただし、認証情報を含むコピーを公開場所へアップロードしてはいけません。更新後は、安定して参照できるグループ名が残っているか、プロバイダー名が変わっていないか、ノードのフィルター結果が空になっていないか、ルールの出力先が有効かを重点的に確認してください。サブスクリプションの変更は、ノードの追加や削除だけでなく、グループの階層やルールリソースにも及ぶことがあります。更新後に動かなくなった場合は、何度もインポートし直すより前後の構造を比較するほうが効果的です。初回起動時の確認については初回インストールと初期設定のチェックリストをご覧ください。

クライアントが生成した一時的な実行ファイルを直接編集しないでください。継続して使う設定はクライアントが対応する上書きレイヤーに保存し、元に戻せるコピーを保管したうえで、サブスクリプションの更新後にも設定が残っているか確認します。

YAMLの&アンカー、エイリアス、マッピングのマージは、クライアントのファイル間マージ機能の代わりにはなりません。これらは現在のYAML文書内で構造を再利用するもので、外部のサブスクリプションをどう更新するかまでは判断できません。上書き目的でトップレベルのキーを重複させたり、空のオブジェクトで必ず既存設定が削除されると仮定したりするのも避けてください。管理しやすい上書き設定にするには、変更する項目を明確にしたうえで必要最小限にまとめ、変更ごとに結果を確認できる手順を設けます。

8. 設定の検証とトラブル対処

設定の問題は、ファイルの解析、参照の解決、待ち受けの開始、DNS、出力先への接続、ルール判定の順に分けて調べます。各段階で失敗の兆候は異なるため、すべてをサブスクリプションの問題とみなさないでください。読み込みに失敗した場合は構文と項目を確認します。読み込みに成功しても通信がない場合は、通信が取り込まれているかを調べます。通信があるのに名前解決できない場合はDNSを、名前解決できてもリモート接続に失敗する場合はノードを確認してください。接続できるのに意図しない出力先になる場合は、ルールとグループの選択を調べます。この順に確認すると、無関係な変更を減らせます。

静的チェックとコアによる検証

クライアントの外で設定ファイルを編集する場合は、まずエディターのYAMLチェック機能でインデント、引用符、重複キーを確認します。一般的なYAMLパーサーで読み込めても、プロトコル項目や参照先が有効とは限りません。実際に使うmihomoコアでも設定を検証し、可能な限りクライアントと同じバージョンを使用してください。別のコアで検証すると、項目の対応状況の違いによって誤った結果になることがあります。クライアントにコアのコマンド実行機能がない場合は、検証のためにプログラムファイルを安易に置き換えないでください。

# 独立したテスト用ディレクトリで確認します。パスは実際のファイルの場所に合わせてください。
mihomo -t -d ./mihomo-check -f ./config.yaml

# HTTPプロキシを明示して、待ち受けと基本的なリクエスト経路を確認します。
curl -I --proxy http://127.0.0.1:7890 https://example.com

# プロキシ側で接続先ドメインを名前解決し、SOCKSのリクエスト経路を確認します。
curl -I --proxy socks5h://127.0.0.1:7890 https://example.com

# このページの例にあるローカルDNSの待ち受けを確認します。
nslookup example.com 127.0.0.1

最後のDNSコマンドはシステムツールの標準DNSポートを使用し、前述の1053へ直接問い合わせるものではありません。ローカルの標準ポートでDNSサービスを動かしていない場合は、次の例のようにポートを指定できるツールを使ってください。この違いは重要です。誤ったポートへ問い合わせてタイムアウトしても、コアで設定した上流DNSに接続できないとは限りません。コマンドを使えるかどうかはOSとインストール済みのツールによって異なります。ターミナルでは実際のcurlプログラムが呼び出されていることも確認してください。

dig @127.0.0.1 -p 1053 example.com A

-tは設定のテスト、-dは作業ディレクトリの指定、-fは設定ファイルの指定に使います。設定が参照する相対パスのファイルは、該当する作業ディレクトリから参照できる必要があります。テスト時にプロバイダーファイルが見つからなくても、YAMLの構文エラーとは限りません。クライアントの通常起動時に作業ディレクトリが異ならないかも確認してください。テストのために2つ目のコアを起動して同じプロキシポートを使うと、新たなポート競合が発生し、元の問題が分かりにくくなるため避けてください。

新しい接続で通信の判定経路を確認

まずプロキシを明示したリクエストで待ち受けと基本的な通信先を確認し、次にシステムプロキシを有効にし、最後にTUNを検証します。これにより、アプリがシステムプロキシに従うかどうかと、コア自体が動作するかどうかを分けて確認できます。HTTPリクエストが成功しても、UDP、IPv6、すべてのアプリが正常とは限りません。実際の用途ごとにテストしてください。SOCKSでは、ドメインをローカルで解決するかプロキシ側で解決するかによって、診断結果の意味が変わります。例のsocks5hはプロキシ側で接続先ドメインを解決し、ローカルの名前解決経路と比較するために使います。

接続ログでは、接続先のドメインまたはアドレス、適用されたルール、最上位のプロキシグループ、ネストしたグループでの選択、最終ノードの順に確認してください。ルールやグループの選択を変更したら新しい接続を作り、既存の接続を再利用する可能性のあるページを更新するだけで済ませないでください。クライアントに接続を閉じる機能があれば、テスト用の接続に限って作り直します。作業中の通信を保存せずに、すべての接続をまとめて中断しないでください。DNSを変更した場合はキャッシュも考慮します。Fake-IPのアドレスが変わった後も、アプリが古いキャッシュを使うと新しい設定と一致しないことがあります。

ログレベルと最小限の切り戻し

通常は適切なログレベルに保ち、問題を調べるときだけ一時的に詳細度を上げてください。まず失敗を引き起こした最初のエラーを確認し、続いて発生した関連エラーも調べます。たとえば、リモートのドメイン名解決に失敗すると、その後の接続処理がすべてタイムアウトすることがあります。ポート競合は起動時に発生し、TLSの識別情報エラーはリモートとのハンドシェイク時に発生します。両者の対処方法は異なります。項目ごとの解説はmihomoのよくあるログエラーと確認手順をご覧ください。ログを共有する前に、認証情報とサブスクリプション情報を削除してください。

一度に変更する項目の種類を1つに絞り、変更前の値、変更理由、テスト結果を記録してください。問題が起きたら、クライアントの再インストール、サブスクリプションの変更、DNSの変更を同時に行うのではなく、直近の変更をまず元に戻します。直結の最小構成では動くのに完全な設定では動かない場合、プロバイダー、プロキシグループ、ルール、通信の取り込み機能を段階的に戻してください。最初に失敗したモジュールが、詳しく調べるべき箇所です。最小構成が動作しても、除外したリモートノードが正常とは限りません。

最終確認では、少なくとも設定の再読み込み、クライアントの再起動、サブスクリプションの更新を1回ずつ行い、設定を解析できること、永続設定が復元されること、更新で上書き設定が消えないことを確認します。LANの待ち受け範囲、コントロールインターフェースへのアクセス範囲、ログレベルも想定どおりか確認してください。操作手順を最初から確認する場合は入門ガイドへ、クライアントを変更する場合はインストーラーページで使用するOSを選んでください。動作確認済みの設定をローカルの基準として保存しておくと、今後の変更時に戻せる状態が明確になります。