Clash YAML設定リファレンス

1. YAMLの構造と設定ファイルの編集場所

まず編集対象のファイルを確認する

エディターで保存できても、コアが新しい内容を使っているとは限りません。GUIクライアントでは通常、サブスクリプションから取得した元ファイル、ユーザーが設定する上書き内容、それらを統合してコアに渡す実行設定が分かれています。サブスクリプションを更新すると元ファイルが再生成されるため、そこへ直接ルールを書き込むと次回の更新で消えることがあります。実行設定を編集しても、クライアントの起動時に上書きされる場合があります。まず設定画面で現在有効な項目を確認し、設定プレビューや実行設定、設定のエクスポートから最終的な値を確かめましょう。

このページの設定例は用途ごとに分けています。各例をそのまま前後につなげて貼り付けないでください。YAMLドキュメントの最上位にはマッピングを置きます。dns、proxies、proxy-groups、rulesはそれぞれ別のキーです。同じ階層にdnsを2つ記述しても、自動で統合されるわけではありません。パーサーがエラーにするか、後の内容だけを残す場合があります。編集時は既存の項目を見つけ、そのセクション内を変更してください。以下の最小構成は、構文とローカルの待ち受けだけを確認するものです。通信はすべて直接接続となり、利用できるプロキシ回線は含まれていません。

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

proxies: []
proxy-groups: []

rules:
  - MATCH,DIRECT

インデント、リスト、文字列の基本

インデントで項目の所属が決まります。半角スペース2つに統一し、タブは使わないでください。コロンの後にスペースを置くとキーと値の区切りになり、ハイフンの後にスペースを置くとリスト項目になります。rulesの各ルールは文字列のリスト項目です。一方、proxiesの各ノードは通常、複数の項目を含むマッピングです。ノードのname、type、serverは同じインデント階層に置きます。portを1段深くすると、ポートが変わるのではなく、構文エラーになることがあります。

シャープ記号や、コロンの後にスペースが続く文字列などは、引用符で囲むのがおすすめです。パスワードや識別子は特に文字列として扱い、数字だけの値が数値と解釈されたり、先頭のゼロが消えたりしないようにしましょう。バックスラッシュを含む通常の文字列にはシングルクォートが適しています。ダブルクォートではエスケープシーケンスが解釈されるため、文字列内にダブルクォートを含める場合は正しくエスケープしてください。チャットアプリから全角コロン、曲がった引用符、見えないインデントを含む設定をコピーしないでください。見た目が似ていても、解析結果は同じとは限りません。

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

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

rules:
  - MATCH,手動選択

null、真偽値、項目間の参照

falseは真偽値ですが、"false"は文字列です。コアが型を自動修正することを前提にしないでください。[]は空のリスト、{}は空のマッピングです。キーの後に値を書かない場合は通常nullとなり、これら3つは自由に置き換えられません。ノード名、プロキシグループ名、ルールの接続先は相互に参照されます。名前は統一し、重複を避けましょう。ルールの引数はカンマで区切るため、名前にカンマを入れないでください。日本語の名前も使えますが、参照する箇所すべてで完全に一致させる必要があります。

設定の確認では2段階に分けて考えます。YAMLを解析できるのは、構文が成立していることを示すだけです。コアが読み込めて初めて、項目の型、プロトコルへの対応、名前の参照が基本的に正しいと判断できます。読み込みに成功しても、接続先やパスワード、ルールの意図まで正しいとは限りません。複雑なアンカー、マージキー、テンプレート構文を一度に導入すると、クライアントごとの差が問題になりやすくなります。まず通常のマッピングとリストで動作を確認し、重複の整理はその後に行いましょう。コアの種類が分からない場合は、画面の名前から対応状況を推測せず、クライアントの情報画面や起動ログを確認してください。

2. 共通項目：待ち受けポートとプロキシモード

ポートは通信を受け付けるためのもの。回線速度とは無関係

mixed-portは、同じ待ち受けポートでHTTPとSOCKSのプロキシリクエストを受け付けます。ブラウザーやコマンドラインツールの接続先を1つにまとめたい場合に便利です。portはHTTP専用、socks-portはSOCKS専用のポートで、すべて設定する必要はありません。一般的なデスクトップ環境では、まず混合ポートを使うと、複数の接続先による混乱を減らせます。ポート番号はローカルサービスのアドレスの一部にすぎません。番号を変更しても、リモートのプロキシ回線が速くなるわけではありません。

ポートを変更したら、設定を再読み込みし、新しい待ち受けが開始されたことを確認してください。その後、システムプロキシ、ブラウザーの手動プロキシ設定、ターミナルの環境変数にも新しい値を反映します。環境変数はYAMLを変更しても自動では更新されず、開いたままのターミナルでは古い設定が残ることがあります。デスクトップクライアントでは、画面上のポート設定がファイルの値を上書きする場合があります。実行設定と待ち受けログを基準に確認しましょう。ポートが使用中の場合は、まずプロセスを特定し、別のクライアントが起動していないか確認してください。用途の分からないシステムプロセスを、ポートを空けるためだけに終了しないでください。

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

ルール、グローバル、直接接続の違い

mode: ruleはルール一覧に基づいて接続先を決めるモードで、通常の振り分けに適しています。globalはコアに入った通信をグローバルポリシーで処理します。どの接続先が選ばれているかも確認してください。directは直接接続を選びます。ここで重要なのはコアに入った通信です。システムプロキシを設定していない、明示的なプロキシを使っていない、TUNにも取り込まれていないアプリは、グローバルモードに切り替えただけでは自動的にプロキシ経由になりません。モードと通信の取り込み方法は別の設定です。

モードの切り替えは比較テストには有効ですが、ルールの不具合を隠すために使うべきではありません。ルールモードでは失敗し、グローバルモードでは成功する場合は、グローバルのままにして終わらせず、ルールのマッチ、プロキシグループの選択、DNSを確認してください。どちらのモードでも失敗する場合は、ノード、認証、待ち受け、ネットワークへの到達性を優先して確認します。既存の長時間接続は切り替え前の出口を使い続けることがあるため、切り替え後は新しい接続で検証してください。詳しい違いはトラブル対処のプロキシモードの説明を参照してください。モードの切り替えを回線の最適化と混同しないようにしましょう。

LAN向け待ち受けとコントローラーは別々に管理

allow-lan: falseは、ローカルのアプリだけでプロキシを使う場合に適しています。他の端末にもプロキシを提供する場合は、LAN接続を許可するだけでなく、bind-address、ホスト側のファイアウォール、Wi-Fiの端末間通信制限、接続先のアドレスも確認してください。他の端末には、クライアントを実行しているPCのLAN内アドレスを入力します。その端末自身のループバックアドレスではありません。待ち受けを公開するとアクセス可能な範囲が広がります。公共のネットワークでポートをそのまま公開せず、信頼できるネットワークに限定し、認証やアクセス制御も設定してください。

external-controllerは管理用インターフェースであり、ブラウザーのプロキシ接続先ではありません。システムプロキシにコントローラーポートを設定しても、通常のプロキシ通信はできません。管理用インターフェースはまずループバックアドレスにバインドし、リモートから接続する必要がある場合に限って、認証とネットワーク境界を別途設計してください。log-level: debugは短時間のトラブル対処に役立ちますが、ログ量が増えます。ログを共有する前に、サブスクリプションのURLや認証情報を伏せてください。ipv6はアドレス処理に関する設定であり、ネットワーク自体のIPv6接続を可能にするものではありません。検証環境がない場合は、DNSを含む複数の設定を一度に変更しないでください。

プロセスの特定方法やポート変更の手順は、7890番ポートの使用状況を確認する方法を参照してください。重要なのは新しい番号を選ぶことではありません。待ち受けアドレス、接続プロトコル、アプリの設定を一致させること、そして新しいリクエストで変更が反映されたことを確認することです。

3. DNS：名前解決の経路とfake-ip

コアの名前解決とシステムの名前解決を区別する

DNS設定では、サーバーアドレスを入力するだけでは不十分です。ドメイン名を誰がコアに渡すのか、コアはどの上流DNSから実際のアドレスを取得するのか、取得した結果が後続の接続にどう使われるのかを確認しましょう。dns.enableは内蔵DNSサービスを有効にし、listenは待ち受け先を指定しますが、システムからのすべてのリクエストが自動的にここへ送られるわけではありません。システムDNS、ブラウザーのセキュアDNS、アプリ独自の名前解決、TUNによるDNSのリダイレクトが同時に動く場合があります。設定ファイルにDNSが書かれているだけでは、対象のリクエストが実際にそこを通ったとは判断できません。

以下は一般的なfake-ip設定の例です。ローカルの高い番号のポートで待ち受け、個別に動作を確認できます。完全な透過プロキシの設定ではなく、システムのリゾルバーを自動変更するものでもありません。default-nameserverは上流DNSサーバーのドメイン名を解決する項目です。直接到達できるIPアドレス形式のリゾルバーを指定してください。nameserverは通常のドメイン名を問い合わせる際に使います。例の上流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"
    - "localhost"
  default-nameserver:
    - 223.5.5.5
  nameserver:
    - https://dns.alidns.com/dns-query

fake-ipは名前解決の失敗でも、暗号化機能でもない

enhanced-mode: fake-ipは、問い合わせに対して合成アドレスを割り当て、ドメイン名との対応を保持します。これにより、後続の接続でもドメイン名を維持しやすくなります。198.18で始まる結果が返っても、必ずしも異常ではありません。重要なのは、合成アドレス宛ての接続も同じ仕組みでプロキシに取り込まれるかどうかです。DNSがfake-ipを返しても、その後の通信がコアを通らず直接送信されると、接続できない場合があります。つまり、DNSの経路と接続の経路を組み合わせる必要があります。システムにDNSサーバーだけを個別に指定すればよいわけではありません。

fake-ip-filterは、特定のドメインに合成アドレスを割り当てないための設定です。実際のアドレスが必要なLANサービスなどに使います。公共のドメインを大量にフィルターへ追加すると、ドメインとの対応を保つ利点が失われ、トラブル対処も複雑になります。redir-hostは実際の名前解決結果を返す別の方式ですが、必ず速く、安全というわけではありません。互換性の問題がある場合は、影響するドメイン、アプリ、接続経路を記録してから個別に比較し、例外設定が必要か判断してください。

nameserver、fallback、DNSの振り分け

fallbackは単純な第2候補のDNSサーバーではありません。設定すると、コアはfallback-filterなどの条件に基づいて、どちらの結果を使うか判断します。ドメイン、アドレス範囲、地理情報に関係する項目もあるため、具体的な動作は現在のコアのドキュメントで確認してください。条件を理解せずにfallbackの設定だけをコピーすると、問い合わせが増えたり、利用できる結果が置き換わったりすることがあります。まず到達可能な上流DNSを1つ設定して基本動作を確認し、その後、必要性を確認してから振り分けを追加しましょう。最初から複数のパブリックDNSを重ねて設定しないでください。

mihomoのnameserver-policyでは、ドメインごとに使用するDNSを指定できます。イントラネットのドメインをLAN内のDNSに問い合わせる場合などに便利です。プロキシサーバー自体のドメイン名解決には、proxy-server-nameserverが関係する場合もあります。プロキシ接続を確立する前に、そのプロキシ経由の名前解決を必要とする循環を避けるための設定です。暗号化DNSは対象のDNS通信を保護しますが、通常の通信まで自動的にプロキシ経由にするものではありません。ルーティングルールが適用されるか、上流への接続に何が使われるかは、現在のコアで使える項目を一つずつ確認してください。

dns:
  enable: true
  listen: "127.0.0.1:1053"
  enhanced-mode: fake-ip
  default-nameserver:
    - 223.5.5.5
  nameserver:
    - https://dns.alidns.com/dns-query
  nameserver-policy:
    "+.home.arpa":
      - 192.168.1.1
  proxy-server-nameserver:
    - 223.5.5.5

上の例は別のDNSセクションを示しています。192.168.1.1は実際のLAN内DNSサーバーに置き換えてください。前の例に追加して、トップレベルのDNSセクションを2つ作らないでください。TUNのdns-hijackはtun配下に設定するもので、dnsの一部ではありません。また、アプリが独自に送信するHTTPS DNSは通常取り込めません。トラブル対処では、コアの待ち受け、システムの名前解決、ブラウザーの動作を分けてテストしてください。キャッシュを消すか新しい接続を使い、古い結果が判断に影響しないようにしましょう。

4. プロキシノード：プロトコル項目とプロバイダー

共通項目が同じでも、プロトコルごとの設定は共通ではない

proxiesは、ローカルで定義するノードのリストです。主な共通項目はname、type、server、portです。名前はプロキシグループから参照され、タイプでプロトコルの解釈方法が決まり、サーバーとポートで接続先が決まります。serverには通常、ドメイン名またはIPアドレスだけを指定します。https://、パス、サブスクリプションのクエリパラメーターは付けないでください。ノードのポートはリモートサーバーのポートです。ローカルのmixed-portと同じである必要はなく、両者の値を流用しないでください。

プロトコル固有の項目は、サービス提供元が案内する値を使用してください。Shadowsocksでは暗号方式とパスワードを一致させる必要があります。Trojanでは通常、パスワードとTLS関連の設定が必要です。VMessやVLESSでは、それぞれのIDやトランスポート設定が関係します。typeだけを別のプロトコルに変更しても、元のノードが使えるようにはなりません。トランスポートの設定も一致させる必要があります。WebSocketのパス、リクエストヘッダー、gRPCのサービス名などは、サーバー側で該当するトランスポートを設定している場合にのみ有効です。項目を余分に追加しても互換性は高まりません。

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

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

TLS名やUDP対応は設定の切り替えだけでは補えない

sniはTLSハンドシェイクで使う名前です。接続先のアドレスと同じ場合もあれば、サービス提供元から別の名前が指定される場合もあります。証明書エラーが発生したら、まず端末の時刻、サーバー名、証明書の有効性、通信経路での差し替えを確認してください。skip-cert-verifyを有効にすることを、通常の解決策にしないでください。証明書の検証を有効にしておけば、名前の不一致などを明確に把握できます。最初のTCP接続が確立していない場合は、SNIや証明書の設定を変えても、アドレスに到達できない問題は通常解決しません。

udp: trueは、その機能を設定上許可するだけです。サーバー、プロトコル、回線、アプリの接続経路すべてがUDPに対応していることを意味しません。Webページは開けてもゲームや音声通話が失敗する場合は、実際に使われる通信方式と取り込み経路を確認してください。一方、速度テストがタイムアウトしても、すべての通信が失敗しているとは限りません。テスト対象、リクエスト方式、ノードのルーティングに違いがある場合があります。ハンドシェイク、認証、リモート接続の失敗を区別し、すべてをノードの障害として扱わないようにしましょう。

proxy-providersでノードの一覧を読み込む

proxy-providersはノードの一覧をコアに読み込ませる設定です。プロキシグループからuseで参照します。HTTPプロバイダーのurlはリソースのURL、pathはキャッシュの保存先、intervalは通常、秒単位の更新間隔です。プロバイダーのリソースと、クライアント用の完全なサブスクリプションは同じ形式ではありません。一般的なノードプロバイダーにはproxiesのリストが必要です。応答内容がログインページなど別形式の場合、拡張子を変えても有効なYAMLにはなりません。

proxy-providers:
  remote-nodes:
    type: http
    url: "https://example.com/proxies.yaml?token=xxxx"
    path: ./providers/remote-nodes.yaml
    interval: 3600
    health-check:
      enable: true
      url: https://www.gstatic.com/generate_204
      interval: 600

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

サンプルURLは構造を示すためのものなので、実際のプロバイダーのリソースに置き換えてください。クライアントの設定画面でサブスクリプションを管理している場合、通常は別の更新方法を手書きする必要はありません。提供元が案内しているのが完全な設定ファイル、ノード一覧、URIの一覧のどれなのかを確認してから、適切な方法で読み込みましょう。キャッシュの相対パスはコアの作業ディレクトリを基準に解釈され、エディターで開いたフォルダーが基準とは限りません。更新に失敗した場合は、YAMLを何度も移動するより、クライアントのデータフォルダーとアクセス権を確認してください。

認証情報は機密情報です。スクリーンショットや相談用のログには、ドメイン名、エラーの種類、必要な項目だけを残し、サブスクリプションのURL全体を公開しないでください。ノード名が更新されると、手作業で固定したプロキシグループの参照先が無効になることがあります。プロバイダーを参照すれば個別のメンテナンスを減らせますが、フィルター条件や利用可能なノードが空になる場合への対応は必要です。サブスクリプションをダウンロードできたことは、リソースの取得に成功したことを示すだけです。ノードへの接続確認の代わりにはならず、含まれるすべてのプロトコルが現在のコアで使えることも保証しません。

5. プロキシグループ：手動選択・速度テスト・フェイルオーバー

参照関係を明確にする

プロキシグループは、ルールと実際の接続先をつなぐ選択レイヤーです。ルールがグループを指定し、そのグループにノード、別のグループ、内蔵ターゲットを設定します。ノードを切り替えるたびに各ドメインのルールを書き換える必要はありません。基本となるselectは手動で選択する方式で、まず利用できる回線を確認するのに適しています。グループ内のproxiesにはノード名やグループ名を指定します。サーバーアドレスではありません。useにはプロバイダー名を指定します。参照する対象が異なるため、名前を1文字間違えただけでも設定の読み込みに失敗することがあります。

用途と選択方式を分けた名前にしましょう。たとえば「通常の接続先」は通信で使うグループ、「自動速度テスト」は選択方法を示します。通常のルールは前者を指定し、前者から速度テスト用グループ、予備グループ、個別ノードを選べるようにします。グループ自身をそのグループに含めたり、複数のグループが互いに参照してループしたりしないようにしてください。内蔵ターゲットと同じ名前やノード名と重なる名前も避けましょう。複雑な入れ子は読み込めても、メンテナンスしやすいとは限りません。階層が少ないほど、実際の接続先を確認しやすくなります。

proxies:
  - name: "回線 A"
    type: ss
    server: a.example.com
    port: 443
    cipher: aes-128-gcm
    password: "your-password"
  - name: "回線 B"
    type: ss
    server: b.example.com
    port: 443
    cipher: aes-128-gcm
    password: "your-password"

proxy-groups:
  - name: "通常の接続先"
    type: select
    proxies:
      - "自動速度テスト"
      - "予備回線への切り替え"
      - "回線 A"
      - "回線 B"
      - DIRECT

  - name: "自動速度テスト"
    type: url-test
    proxies:
      - "回線 A"
      - "回線 B"
    url: https://www.gstatic.com/generate_204
    interval: 300
    tolerance: 50

  - name: "予備回線への切り替え"
    type: fallback
    proxies:
      - "回線 A"
      - "回線 B"
    url: https://www.gstatic.com/generate_204
    interval: 300

rules:
  - MATCH,通常の接続先

自動速度テストで分かるのはテストリクエストの結果だけ

url-testはテスト結果に基づいて接続先を選びます。urlはテスト対象、intervalはテスト間隔、toleranceはわずかな差による頻繁な切り替えを抑える設定で、通常はミリ秒単位です。特にモバイル端末やノード数が多い環境では、テスト間隔を短くしすぎないでください。頻繁なリクエストは通信量やバッテリー消費を増やします。安定して応答が得られるテスト先を選び、ログインが必要なページ、複雑なリダイレクトが発生するページ、特定の回線からアクセスできないページは避けましょう。

ノードの遅延は、1回のテストリクエストで観測した結果です。動画の転送量、ダウンロード速度、すべてのWebサイトの応答時間を示すわけではありません。テスト先に接続できても、実際に使うサービスでは地域、アカウント、サービス側のポリシーが影響する場合があります。遅延の数値が小さいノードも、実際の用途で確認してから使ってください。すべてのルールを速度テストの結果だけで決めないようにしましょう。グループにDIRECTを含める場合は意図を確認してください。自動テストで直接接続とプロキシを競わせると、想定とは異なる接続先が選ばれることがあります。

fallbackと負荷分散の違い

fallbackは通常、リストの順序に沿って利用可能な項目を選びます。主な目的は遅延が最も小さい回線を毎回探すことではなく、障害時に別の接続先へ切り替えることです。先頭のノードが復旧した場合に、その後の新しい接続がどう選ばれるかは、コアの実装と現在の状態によって異なるため確認してください。切断されたTCPセッションを引き継ぐ機能ではないので、実行中のダウンロードは再接続が必要になる場合があります。「メイン回線と予備回線」と考えると分かりやすく、切り替え後に必ず通信が途切れないという意味ではありません。

load-balanceは複数の接続先に通信を振り分ける機能です。振り分け方は設定によって異なり、複数回線の帯域を合算して1つの接続を高速化するものではありません。接続元のアドレス変更に敏感なサービスでは、再認証やセッションエラーが発生する場合があります。そのような用途では、安定したプロキシグループに固定してください。設定を初めて作る場合は、まず手動選択で動作を確認してから自動化を追加しましょう。手動でノードを選んでも失敗するなら、速度テストの許容差ではなく、ノードや接続経路を確認してください。

クライアントがグループの前回の選択を保存していると、設定を再読み込みしてもリストの先頭が選ばれるとは限りません。profile.store-selectedなどの設定、GUIの選択状態を保存する仕組み、グループ名の変更が復元動作に影響する場合があります。トラブル対処ではYAMLの並びだけで判断せず、現在選択されている項目を確認してください。プロバイダーの更新でノードが変わる場合は、フィルター後に利用可能な項目が残っているかも確認しましょう。自動グループの項目が空、名前の参照先がない、すべてのテストに失敗する、という3つの問題は分けて対処する必要があります。

6. ルール設定：マッチ順とルールセット

ルールは上から順に評価され、最初に一致した項目が適用される

ルールモードでは、通常、ルールはリストの順番に評価され、最初に一致した接続先が使われます。問題になりやすいのは書式よりも配置です。広い範囲に一致するルールを先に置くと、後の細かい例外ルールが実行されません。MATCHは最終的なフォールバックとして通常のリストの末尾に置きます。Webサイトの例外を追加するときは、接続先のグループが存在し、正しく選択されていることも確認し、新しい接続でマッチ結果を調べてください。リストにドメインが書かれているだけでは、そのルールが実際に適用された証拠にはなりません。

DOMAINはドメイン名を完全一致で判定し、DOMAIN-SUFFIXはそのドメインとサブドメインに一致します。DOMAIN-KEYWORDはドメイン名に含まれる文字列で判定します。特定のサイトを直接接続にする場合は、短いキーワードだけで指定せず、完全一致かサフィックスを使うのがおすすめです。関係のないドメインまで影響することがあります。通常、ルールにはURLのプロトコル、パス、ページのパラメーターは書きません。同じWebサイトでも複数のリソース用ドメインを使う場合があり、トップページが直接接続になっても、画像、ログイン、APIが同じ接続先になるとは限りません。

rules:
  - DOMAIN,printer.home.arpa,DIRECT
  - DOMAIN-SUFFIX,home.arpa,DIRECT
  - DOMAIN-SUFFIX,example.org,通常の接続先
  - IP-CIDR,127.0.0.0/8,DIRECT,no-resolve
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
  - GEOIP,CN,DIRECT
  - MATCH,通常の接続先

IPルールとno-resolveの動作

IP-CIDRは宛先IPアドレスが属するネットワークを基準に判定します。イントラネットや明確なアドレス範囲に適しています。no-resolveは、このルールのためにドメイン名を積極的に解決しない指定です。通信全体でDNSを使わなくなるわけではありません。リクエストに宛先IPがすでにある場合は判定できます。ドメイン名しかなく、まだ解決されていない場合は、このルールを飛ばして次へ進むことがあります。すべてのIPルールにこの指定を付ける前に、問い合わせを減らしたいのか、名前解決の結果を使って接続先を判断したいのかを確認してください。

GEOIPは対応するIPアドレスデータベースに依存し、GEOSITEはドメイン分類データとコアの対応状況、関連リソースの設定に関係します。どちらもサーバーの物理的な場所をリアルタイムで判定する機能ではありません。データベースの更新状況や共有IPによって、判定がずれることがあります。特定の通信だけ誤って振り分けられる場合は、分類方法全体を大きく変えるより、個別のルールで上書きする方が安全です。企業ネットワークや複数のLANがある環境では、広範囲の例外でプライベートアドレスをすべて処理しないでください。

rule-providersの形式はbehaviorと一致させる

ルールプロバイダーを使うと、大量のルールを別のリソースに分け、メイン設定からRULE-SETで参照できます。behavior: domainはドメインのリスト、ipcidrはネットワーク範囲、classicalはルールタイプと引数を組み合わせた形式に適しています。リソースの内容もformatに合わせる必要があります。payloadを含むYAMLとして読み込む形式にプレーンテキストのリストを使ったり、バイナリリソースをテキストとして読み込んだりできません。ダウンロードに成功して解析で失敗する場合は、ネットワークの問題と決めつけず、形式と応答内容を先に確認してください。

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

rules:
  - RULE-SET,local-domains,DIRECT
  - MATCH,通常の接続先

対応するlocal-domains.yamlは、次のように記述できます。先にファイルを作成し、コアに読み取り権限があることを確認してください。相対パスの基準は引き続き実行ディレクトリです。メイン設定で指定する接続先「通常の接続先」は、プロキシグループに定義されている必要があります。ルールプロバイダーのファイルにはマッチ条件だけを保存し、各行に接続先のグループ名を繰り返し書かないでください。それぞれのファイルの役割を明確に分ける方が、すべてのファイルに接続先を混在させるより管理しやすくなります。

payload:
  - "+.home.arpa"
  - "printer.example.com"

mihomoのプロセス名によるルールなどは、OS、権限、通信の取り込み方法にも左右されます。あるプラットフォームでプロセスを識別できても、他のプラットフォームで同じように使えるとは限りません。アプリが先にドメイン名を解決し、その後IPアドレスで接続する場合は、ドメインを基準にしたルールに必要な情報が渡らないことがあります。トラブル対処では接続の詳細を確認し、ドメイン名、宛先IP、マッチしたルール、実際の通信経路を調べてください。入力情報が揃っているか判断してから、DNS、取り込み方法、ルールの順序のどれを調整するか決めましょう。

7. 上書きと統合：サブスクリプション更新を維持する

コアの設定とクライアント側の処理を区別する

上書きの方法は、すべてのクライアントで共通のYAML仕様ではありません。コアは最終的な設定を読み込みますが、GUIクライアントはその前に、共通設定、サブスクリプションごとの設定、設定の統合、スクリプトの実行などを行う場合があります。Clash Plus、Clash Verge Rev、FlClashなどでは、設定画面の場所や優先順位を単純に流用できません。まず使用中のクライアントの上書きに関する説明を確認し、すべてのサブスクリプションが対象なのか、個別の設定だけが対象なのかを確かめてください。生成後の設定が想定と異なる場合は、サブスクリプションの原文を繰り返し編集するのではなく、加工の手順を調べましょう。

よくある統合方法には、スカラー値の上書き、マッピングの再帰的なマージ、リストの置き換えがありますが、共通の決まりではありません。たとえば、上書き用の設定にdns.nameserverだけを書いた場合、元のDNSセクションにある他のキーが保持されるツールもあれば、セクション全体を置き換えるツールもあります。rulesやproxiesなどのリストは、特に注意が必要です。ルールが1件だけのリストを差分として渡すと、ルール全体が置き換わる場合があります。「統合」と書かれていても、必ず追加されるとは限りません。

# 通常のYAMLマージ用フラグメントに対応したクライアントでのみ使用してください。
# マッピングとリストの統合方法は、クライアント側で確認してください。
mixed-port: 7891
allow-lan: false
log-level: info

dns:
  enable: true
  ipv6: false

ルールの先頭追加、末尾追加、リスト置き換え

ローカルルールを追加する場合は、独自のフィールドを推測で使わず、クライアントが明示的に用意している「ルールを先頭に追加」「ルールを追加」などの機能を使いましょう。先頭への追加は、優先して適用したいドメイン例外に適しています。末尾に追加するときは、元のリストにMATCHが含まれていないか確認してください。その後に通常のルールを追加しても適用されません。ツールがリスト全体の置き換えしかできない場合は、既存ルールとフォールバックを残す必要があります。また、サブスクリプションのルール更新を自分で維持することになります。サブスクリプション側の設定をどこまで残したいかに応じて、方法を選んでください。

ノードとプロキシグループにも相互の依存関係があります。ノードを削除して参照元のグループを残すと、接続先が見つからなくなります。グループ名を変更してもルールを書き換えなければ、参照が壊れます。まず最終的な名前を決め、ノード、グループ、ルールの3つで参照関係をそろえてください。特定のWebサイトの接続先を固定したいだけなら、既存のグループを参照する完全一致のルールを1つ追加すれば十分なことが多く、ノード一覧全体を置き換える必要はありません。変更範囲を絞るほど、次回のサブスクリプション更新で競合しにくくなります。

YAMLのアンカーとマージキーは、パーサーが対応する範囲で設定の構造を再利用する機能です。ファイルをまたいで自動的に上書きしたり、リストへ追加したりする汎用構文ではありません。エディターのプレビューで正常に見えても、クライアントによって解析方法が異なる場合があります。スクリプトによる上書きは柔軟ですが、クライアント固有の関数の入口、実行順序、エラー処理にも対応する必要があります。このページでは、すべてのクライアントで使えると想定したスクリプト例は紹介しません。明確なインターフェースの説明がない場合は、出所の分からないスクリプトをコピーするより、通常の項目を上書きする方が検証しやすくなります。

元に戻せる設定の階層を作る

設定を3つの層に分けて管理する方法があります。サブスクリプション層にはノードとサービス提供元のルール、ローカル層にはポート、信頼できるLAN向けの例外、個人用のルールを置きます。一時的な層はトラブル対処だけに使います。一時的な変更で解決したら、適切な永続設定に整理し、重複したキーを削除してください。各上書き設定には用途を記載し、変更前の動作するバックアップを保管しましょう。GUI、共通の上書き、サブスクリプションごとの上書きで同じポートを設定すると、1か所を変えただけでは反映されない状況が起きることがあります。

上書き設定はファイルが保存されたかどうかだけでは検証できません。まず現在のサブスクリプションを再読み込みし、統合後の設定を開いて対象のキーを検索します。次にプロキシグループとルールの参照先が存在することを確認し、新しいリクエストでマッチ結果を調べてください。その後、サブスクリプションを手動で更新し、変更が維持されるか確認します。この手順で設定を置いた場所が適切か検証できます。更新後に変更が消える場合は、更新のたびに手作業で戻すのではなく、クライアントがサポートするローカル設定へ移してください。別のサブスクリプションに切り替えた場合の対象範囲も確認し、共通ルールが特定のサブスクリプションにしかないグループを参照していないか調べましょう。

複数人や複数端末で設定を管理する場合は、「項目、設定元、最終値、検証方法」を記録しておくと便利です。画面の操作手順だけを記録すると、クライアントの画面変更に対応できません。最終的な設定構造を記録しておけば、アップデート、移行、再インストールの後も復元しやすくなります。更新後に突然起動できなくなった場合は、まず最近追加した上書きと参照関係を確認してから、トラブル対処ページで問題を切り分けてください。

8. 検証とトラブル対処：読み込みから実際の通信まで

まず構文解析とコアのテストを行う

検証は、構文、コアによる読み込み、ポートの待ち受け、ノードへの接続、ルールのマッチ、最後に対象アプリの順で進めます。各段階の入力と結果が明確になります。起動に失敗したら、最近動作していた設定に戻し、問題のあるファイルに変更を重ねないでください。コマンドラインでテストする場合は、現在のクライアントで使われているコアを実行しているか確認します。システムに残っている古い実行ファイルは新しい項目に対応していない場合があり、そのテスト結果がクライアントの動作を表すとは限りません。

# 設定ファイルのあるディレクトリで実行します。コマンド名は、実際のインストール方法に合わせてください。
mihomo -t -d . -f ./config.yaml

-fは設定ファイル、-dは作業ディレクトリを指定します。プロバイダーのキャッシュや関連リソースを読み込むため、テスト時にも必要な場合があります。コマンドが成功すれば、その環境で設定の基本的な読み込みに成功したことを確認できます。リモートノードやすべてのルールリソースが正常だと証明するものではありません。クライアントに独立したコマンドラインの入口がない場合は、設定チェック画面とログ画面で同じ段階の検証を行えます。テストコマンドを実行するためだけに、コアのファイルを管理されていないフォルダーへコピーしたり、別の常駐プロセスを起動したりしないでください。

解析エラーには行番号が表示されても、原因が直前の行にある場合があります。文字列の引用符が閉じていない、リスト項目が欠けている、インデント階層が変わっているなどの可能性があります。エラー行付近のマッピング全体を確認し、必要なら最小構成に戻してから少しずつ追加してください。名前が見つからない場合は、エラー行を削除して済ませず、ノード、グループ、ルールの参照先を確認します。項目が未対応なら、コアの種類と項目を置く場所を調べてください。権限やリソースの読み込みエラーでは、YAMLのインデントではなく作業ディレクトリを確認します。

明示的なプロキシ接続でシステム側の取り込みを切り分ける

コアが正常に起動したら、まず明示的なプロキシを使って新しいリクエストを送り、システムプロキシとTUNの影響を一時的に切り離してください。以下のコマンドは、該当するオプションに対応したcurlで使えます。Windowsではコマンドのエイリアスによる違いを避けるため、curl.exeを明示できます。ポートは実際の待ち受け値に置き換え、テスト先も現在の環境から接続できると想定されるものを選んでください。1回のリクエストに失敗しただけで、すべてのプロキシ機能が動作しないとは判断できません。

curl --proxy http://127.0.0.1:7890 --connect-timeout 10 --max-time 20 https://example.com/
curl --proxy socks5h://127.0.0.1:7890 --connect-timeout 10 --max-time 20 https://example.com/

socks5hを使うと、ドメイン名の解決をプロキシ側に任せます。クライアント側で先に解決してから接続するテストとは経路が異なります。一方だけ成功する場合は、すぐにすべてのノードを変更せず、名前解決と接続方式の違いを調べてください。明示的なプロキシ接続は成功するのにブラウザーで失敗する場合は、システムプロキシ、ブラウザー拡張機能、独立したセキュアDNS、既存の接続を優先して確認します。TUNの場合は、システムルート、アクセス許可、他の通信制御ソフトも調べ、複数のツールが同じ接続経路を奪い合っていないか確認してください。

症状に合わせて必要最小限の情報を集める

相談する際は、OS、クライアント名、コアの種類、問題が起きた操作手順、関連するログのマスキング済み部分を記載してください。明示的なプロキシ接続が成功するか、ルールモードとグローバルモードで差があるか、特定の接続先だけで失敗するかも説明しましょう。「タイムアウト」と表示された画面の画像だけより、原因の特定に役立ちます。大量のdebugログだけを送らないでください。問題が起きる直前と直後の関連部分を抜き出して認証情報を隠し、各テストでどの設定を変更したか記載します。問題を安定して再現できれば、修正の効果も確認しやすくなります。

最後に回帰テストを行います。クライアントを再起動して待ち受けが復旧すること、サブスクリプションを更新してローカルの上書きが維持されることを確認してください。ネットワークを切り替えた後は対象の通信を再試行し、DNSキャッシュとプロキシグループの選択も調べます。トラブル対処が終わったら、ログレベルを通常に戻し、一時的に緩めた設定や重複ルールを削除しましょう。設定の目的は項目を増やすことではありません。各項目の用途を説明でき、変更の結果を検証できる状態にすることです。接続の流れを改めて確認する場合は使い方ガイドへ、クライアントを変更する場合はダウンロードセンターのOS・アーキテクチャ別の選択肢をご覧ください。