Clash 設定完全ガイド

1. YAML概要：ファイル構造から有効な設定まで

Clashの設定はノードアドレスの一覧ではなく、相互参照するオブジェクトの集合です。共通フィールドが入口と動作モードを定義し、DNSフィールドがコアのドメイン解決方法を決め、プロキシノードが利用可能な出口を定義し、プロキシグループが出口を整理し、ルールが接続を指定した対象へ振り分けます。見慣れない設定を読むときは、まずトップレベルのキーを確認し、次に名前の参照関係を追ってください。数百行のルールから読み始めると、接続経路を実際に決める入口設定や最終ポリシーを見落としやすくなります。

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

YAMLではインデントで階層を表します。コロンの後にスペースを1つ置くとキーと値を区切り、ハイフンで始まる行は通常リスト要素を表します。インデントは2スペースに統一し、タブを混在させないでください。同じ階層は必ず揃えます。トップレベルの dns と rules は同じ階層にあり、enable は DNS の下に置きます。中国語の名前も使用できますが、名前内のスペース、句読点、大文字小文字は参照対象に含まれるため、別の箇所で勝手に変更してはいけません。

ポートには整数を使い、スイッチには引用符なしの true または false を使います。ドメインパターン、パスワード、コロンやシャープ記号を含む文字列は、マッピングやコメントなど別の型として解釈されないよう引用符で囲むのがおすすめです。シャープ記号は文字列の外側ではコメントを示します。トップレベルキーの重複も避けてください。パーサーによってはエラーになり、別のパーサーでは片方だけが残るため、ルールリストを2つ書いて追加する方法には頼れません。

# 直接接続を確認する完全なサンプル設定。リモートプロキシノードは含まない
mixed-port: 7890
allow-lan: false
mode: rule
log-level: info

dns:
  enable: false

proxies: []
proxy-groups: []

rules:
  - MATCH,DIRECT

この設定は、該当フィールドに対応するコアの基本起動テストに使えます。ポートが空いていればローカルの混合プロキシ入口を作成しますが、すべての一致した接続は直接接続されます。アプリケーション側でもこの入口を明示的に使う必要があります。リモート出口は提供せず、コアのDNSも有効にしていません。独立したテストファイルとして保存し、使用中のサブスクリプションを直接上書きしないでください。元のノードとルールが削除されます。

まず入力ファイルがどの層に属するかを確認する

サブスクリプションURLは内容を取得するためのアドレスであり、返される内容が必ず完全なYAMLとは限りません。完全な設定を返す場合もあれば、ノード一覧だけ、エンコードされたテキスト、単一ノードの共有リンクだけを返す場合もあります。完全な設定は設定インポート入口に入れ、ノード集合はクライアントで変換するか、proxy-providers から参照する必要があります。入口を間違えると、URLからダウンロードできても、フィールド不足、解析失敗、ルール対象不在などが起こります。

設定ファイルはクライアントによって二次加工されることもあります。サブスクリプション原文にはサービス提供元の内容が保存され、ローカル設定にはポートや接続方式などの環境設定が保存され、オーバーライドファイルは一部フィールドの追加や置換に使われます。最終生成ファイルがコアに渡されます。ある層を編集したら、クライアントの実行設定プレビューまたはエクスポート機能で、変更が最終ファイルに反映されているか確認してください。画面にある数値が表示されていても、サブスクリプション内の同名フィールドが最終的な優先権を持つとは限りません。

構文だけでなく参照関係を確認する

ルール内のポリシー名は、ノード、プロキシグループ、または組み込みターゲットに対応していなければなりません。プロキシグループ内のノード名も存在する必要があります。名前が正しくても、グループ同士が循環参照を作ってはいけません。ノード、プロキシグループ、ルールの順に読むのがおすすめです。まず出口の一覧を把握し、次に選択方法を確認し、最後にどの接続がそこへ送られるかを見ます。ルールプロバイダーやプロキシプロバイダーがある場合は、トップレベルの宣言だけで読み込み成功と判断せず、パス、形式、読み込み結果も確認してください。

変更を始める前に、現在のクライアント名、コアの種類、設定の取得元を記録し、復元可能なバックアップを1つエクスポートしてください。動作している設定を優先して残し、一度に1つのテーマだけ変更して差分を検証します。クライアントがまだない場合は、クライアント配布ページでまず Clash Plus を検討し、プラットフォームと必要な機能に応じて他の入口と比較してください。インポート形式の詳しい違いはサブスクリプションリンクとYAMLインポートの説明を参照してください。

2. 共通フィールド：ポート、モード、アクセス範囲

共通フィールドは、ローカルプログラムがどのようにプロキシへ接続するか、またコアが接続を受け取った後にどの処理モードを使うかを決めます。特に混同しやすいのが、ローカル待受ポートとリモートノードのポートです。前者は端末上のコアが提供し、後者はサーバー接続のパラメーターです。ノード側のサーバーポートをシステムプロキシ設定に入力しても、自動的に接続されるわけではありません。通常、システムプロキシにはローカルの待受アドレスと対応するHTTPプロキシポートを指定し、ノードのポートはノード定義内に残します。

待受入口を選び、実際の使用状況を確認する

一般的なデスクトップ向けの検証設定では、まず混合ポートを1つ使うと問題を切り分けやすくなります。アプリケーションが独立した入口を必要とする場合だけ、HTTPまたはSOCKSポートを設定してください。異なる待受フィールドで同じポートを重複使用したり、GUIクライアントが動作中に同じポートで別のコアを起動したりしないでください。待受に失敗したら、まずポートの使用者を特定します。ポートを適当に変更してシステムプロキシの更新を忘れると、エラーが起動段階から接続段階へ移るだけです。

# 共通フィールドの断片。待受ポートは説明用
mixed-port: 7890
allow-lan: false
bind-address: "127.0.0.1"
mode: rule
log-level: info
ipv6: false

ここでは待受をローカル用途に限定しています。bind-address が各入口に与える具体的な影響は、コアとクライアントの生成結果を合わせて確認する必要があり、ファイルだけで外部アクセスの可否を判断できません。アプリケーションはリモートノードではなく 127.0.0.1:7890 に接続してください。デスクトップのプロキシ設定、ブラウザー独自のプロキシ設定、ターミナルの環境変数はそれぞれ独立している場合があります。そのため、同じ端末でもプログラムごとに異なる経路を使うことがあります。

モード選択とトラフィックの取り込みは別のもの

rule は、コアに入った接続に対してルールの順序に従いターゲットを選択します。global はそれらの接続をグローバルポリシーで処理し、direct は直接接続します。グローバルモードはOS全体のトラフィックを取り込む機能ではなく、すべてのプログラムがプロキシを経由する保証はありません。逆に、TUNを有効にしてもすべてのリクエストがリモートノードを通るわけではありません。トラフィックがコアに入った後も、ルールによって直接接続、拒否、プロキシ接続が決まります。

システムプロキシは、主にシステムプロキシ設定に従うアプリケーションへ影響します。TUNは仮想ネットワークインターフェースと対応するルーティングでトラフィックを取り込み、管理者権限、サービスコンポーネント、モバイルプラットフォームのVPN許可が必要になる場合があります。1つのWebページを確認するために、システムプロキシ、TUN、DNS、モードを同時に変更しないでください。まず単一のアプリケーションが明示したローカルポート経由でアクセスできることを確認し、必要に応じて取り込み範囲を広げます。詳しいインストールと権限設定はモードとトラフィック取り込みのガイドを参照してください。

LAN公開、ログ、IPv6

他の信頼できる端末がローカルプロキシを使う必要がある場合だけ、LANアクセスの有効化を検討してください。その際は待受ネットワークアダプター、ファイアウォールの受信規則、プロキシ認証も確認し、ルーターから入口がインターネットへ転送されないようにします。プロキシ入口とコントロールインターフェースは別のサービスです。後者にはポリシー切り替え、接続情報の読み取り、設定変更の権限がある場合があります。リモート管理が不要なら、コントロールインターフェースはローカルだけで利用できる状態にし、接続問題の解決を理由に管理権限を広げないでください。

log-level: info は日常的な確認に適しています。トラブルシューティング時に一時的に詳細度を上げると、より多くのエラー情報を確認できますが、ログにはドメイン、ノードアドレス、接続メタデータが含まれる場合があります。共有前に必ずマスキングしてください。調査が終わったらログレベルを戻し、大量の記録が継続的に書き込まれないようにします。ログをディスクへ保存するか、どのくらい保持するか、どこに保存するかはクライアント側の管理にも左右されます。

トップレベルの ipv6 とDNS領域にある同名フィールドは、作用する層が異なります。OS自体がIPv6を使い続ける場合もあります。サンプルで無効にしているのはテスト経路を簡単にするためであり、一般的なネットワーク最適化の提案ではありません。デュアルスタック通信が必要なら、名前解決結果、ルーティング、取り込み範囲、ノードから対象へ到達できるかを同時に確認してください。スイッチを1つ変更しただけでは、プロキシを迂回する接続がないとは証明できません。共通フィールドを変更したら、最終的な待受状態と実際のリクエスト経路で検証します。

3. DNS処理：解決入口、上流、Fake-IP

DNS設定で最初に確認すべきなのは、誰がクエリを開始し、誰が受け取り、どの経路で上流へ到達するかです。コアのDNSサービスを有効にしても、OSやすべてのアプリケーションが自動的にそれを使うわけではありません。ブラウザー内蔵の暗号化DNS、アプリ独自のリゾルバー、別のVPNが独立した経路を作ることもあります。調査では、アプリケーション、OSのリゾルバー、コアのDNS、上流サーバーの順序を図にし、リクエストが本当に目的の入口へ入っていることを確認してから、返されたアドレスの正しさを検討してください。

基本フィールドと名前解決の依存関係

# DNSの断片。OSのDNS設定を自動的に書き換えるものではない
dns:
  enable: true
  listen: "127.0.0.1:1053"
  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
  fake-ip-filter:
    - "*.lan"
    - "*.local"

listen はコアDNSの待受アドレスを宣言します。サンプルではローカルの非標準ポートを使っており、明示的なクエリテストには適していますが、多くのOSのネットワーク設定にはそのようなポートを直接指定できません。通常のアプリケーションに使わせるには、クライアントが提供するDNS取り込み、転送、TUNによるハイジャック機能なども必要です。標準ポートで待ち受けていないアドレスをOSのDNSに設定するだけでは不十分です。サンプルの上流は置き換え可能な例であり、到達性は現在のネットワークに依存します。

nameserver は通常の名前解決に使う上流を設定し、default-nameserver は上流DNSのアドレス自体がドメイン名である場合の解決に使われます。暗号化DNSサーバーをドメイン名で指定する場合、コアは暗号化接続を確立する前に、そのドメインに対応するIPを知る必要があります。この初期解決を、まだ確立していない同じ経路だけに完全に依存すると、依存ループになる可能性があります。上流を変更する前に、現在のネットワークから実際に到達できるか確認してください。

Fake-IPはドメインとの対応関係を保存する

Fake-IPモードでは、ドメインに仮想アドレスを返し、コアがそのアドレスとドメインの対応関係を保持します。その後、アプリケーションが仮想アドレスへ接続すると、コアは対応関係からドメイン情報を復元して後続処理を行います。仮想アドレスは対象サイトの実サーバーアドレスではないため、OSの検索結果でそれを見ても、直ちにDNS汚染と判断してはいけません。接続できるかどうかは、該当接続が同じコアに取り込まれているか、対応関係が有効なままかどうかにも左右されます。

従来の実アドレスを返す方式は、実IPを要求するプログラムとの互換性を保ちやすい一方、接続段階でドメイン情報を保持または復元する別の仕組みが必要になる場合があります。モードは、アプリケーションの互換性と取り込み方式を基準に選び、特定のモードが必ず高速だとは考えないでください。強化モードへ切り替えた後も、OSやアプリケーションが古い結果をキャッシュしていることがあります。関連キャッシュを消去し、接続を作り直してから比較してください。

fake-ip-filter は、仮想アドレスを返すのに適さないドメインを除外するために使います。一般的な出発点はLANサービスや実アドレスを必要とするアプリケーションです。サンプルはリスト構造を示すだけで、すべての内部ネットワーク名を網羅するものではありません。特に .local のサービスはマルチキャストDNSに依存する場合があり、除外項目を追加するだけではすべての検出問題を解決できません。仮想アドレスから除外しても、直接接続になるとは限りません。名前解決方式と接続ポリシーを分けて確認してください。

ドメイン別の上流選択とDNSリークの確認

# 既存の dns マッピングにマージする。2つ目のトップレベル dns キーを追加しない
# 内部ネットワーク用DNSアドレスは説明用の値。実際に到達できるアドレスへ置き換える
nameserver-policy:
  "+.corp.example":
    - 192.168.1.1

このポリシーは、特定のドメインを特定のリゾルバーへ渡せることを示すもので、内部名を持つネットワークに適しています。内部リゾルバーがそのドメインを知っており、現在の端末のネットワークから到達できなければなりません。外部ネットワークへ移動すると、以前使えた内部アドレスが存在しなくなる場合があり、タイムアウトをそのままリモートプロキシノードの問題と判断できません。ポリシーキーのマッチ構文はルールリストの構文とも異なるため、DOMAIN-SUFFIX ルールをそのままここへ置かないでください。

該当フィールドに対応する mihomo では、proxy-server-nameserver をプロキシノードのサーバードメイン解決に使えます。respect-rules を有効にするとDNS上流への接続がルーティングルールに従うため、ノード解決とプロキシ接続の依存関係に注意が必要です。fallback も、単に最初のサーバーがタイムアウトしたときの順番待機とは限らず、フィルター条件と組み合わせて結果を選ぶ場合があります。実装を確認できるまでは、名前解決経路を少なくしてください。

検証では、通常のドメイン、内部ドメイン、プロキシが必要なドメインを分けてテストし、名前解決結果と後続接続で一致したルールを記録します。LANアプリケーションだけが異常なら、まず除外範囲を狭めます。すべてのリクエストが名前解決で待機するなら、上流への到達性と依存ループを確認してください。仮想アドレスの検索と接続についてはFake-IPマッピングと除外項目の説明も参照してください。

4. プロキシノード：プロトコルフィールドと接続条件

proxies は静的なノード一覧であり、各ノードがリモートサービスへの接続方式を表します。ノードはプロキシグループではなく、どのサイトが使用するかも決めません。ルールから直接参照されるか、プロキシグループで選択されて初めて、対応する接続に参加します。ノード定義を調査するときは、サービスアドレス、認証情報、転送方式、TLSパラメーターを分けて確認してください。クライアントに名前が表示されるだけで、プロトコルパラメーターの接続検証が済んだとは限りません。

共通フィールドとプロトコル固有フィールド

# ノード説明用の断片。サンプルのドメインとパスワードは実際の接続には使えない
proxies:
  - name: "説明用ノード"
    type: ss
    server: edge.example.com
    port: 8388
    cipher: aes-128-gcm
    password: "your-password"
    udp: true

name はローカル参照用の識別子で、安定して一意であることが望ましく、サーバードメインと同じである必要はありません。type はコアが使うプロトコルと、後続フィールドの解釈方法を決めます。server と port はサーバーが実際に待ち受けている場所と一致させる必要があり、WebページのアドレスやサブスクリプションAPIのパスから推測してはいけません。サンプルの予約ドメインと説明用パスワードは、正規に取得した実際のパラメーターへ置き換えてください。名前を変更してもサーバーへの接続性は改善しません。

プロトコル固有フィールドは一式で対応していなければなりません。Shadowsocksの暗号方式とパスワードはサーバー側と一致させます。他のプロトコルでは、UUID、認証トークン、追加のハンドシェイクパラメーター、異なるトランスポート設定が必要になる場合があります。あるノードの type だけを別プロトコルへ変更し、残りのフィールドを使い回してはいけません。クライアントが共有リンクを認識できても、対応するインポート処理を持つことを示すだけです。生成されたフィールドが現在のコアでサポートされているか、最後に確認してください。

TLS名とトランスポートパラメーターを混同しない

# 独立したプロキシリストの断片。前述のトップレベル proxies と重複して貼り付けない
proxies:
  - name: "TLS説明用ノード"
    type: trojan
    server: edge.example.com
    port: 443
    password: "your-password"
    sni: edge.example.com
    skip-cert-verify: false
    udp: true

TLSを使うプロトコルでは、接続アドレスと証明書検証名が関係する場合がありますが、常に同じとは限りません。SNIはTLSハンドシェイクでサービス名を選択するためのもので、HTTP HostとWebSocketパスは別の層にあります。サービス提供元が異なる値を明示している場合は、そのパラメーターに従い、エラーを消すためにドメインを勝手に置き換えないでください。証明書エラーが出た場合は、システム時刻、サーバー証明書、中間装置も確認し、証明書検証を長期的に無効化しないでください。

udp: true はノードが対応するUDP機能の使用を許可するもので、UDP非対応のサーバーに機能を追加するものではありません。ゲーム、音声、その他のアプリケーションに異常がある場合は、アプリがプロキシに入っているか、プロトコルが対応しているか、サーバーが許可しているか、使用する入口がその通信を処理できるかを同時に確認します。Webテストは通常、一部の転送経路しか確認しないため、1回のWebアクセス成功だけでノードがすべてのアプリに適しているとは判断できません。

静的ノードとプロキシプロバイダーの使い分け

少数の固定ノードは proxies に直接書くと、読みやすく比較もしやすくなります。定期的に更新されるノード集合は proxy-providers で管理し、プロキシグループから use で参照できます。プロバイダーのダウンロード先が返す内容は、要求される形式に適合していなければなりません。通常、ノード集合と完全な設定は別の入力形式です。完全なサブスクリプションをノード集合専用の入口へ入れると、ネットワークのダウンロード障害ではなく、フィールド構造の不一致が起こる可能性があります。

プロバイダーには更新間隔、キャッシュパス、ヘルスチェックも関係します。リモート内容の更新に失敗しても、コアが既存キャッシュを使い続ける場合があるため、画面にノードが残っていても直前の更新が成功したとは限りません。リスト項目の数だけでなく、最後の読み込み結果とキャッシュ内容を確認してください。プロキシ経由でプロバイダーをダウンロードする必要があり、そのプロバイダーからプロキシを取得しなければならない場合、初回読み込みの依存問題が起こります。利用可能な導入経路を残しておく必要があります。

ノード名を変更したら、プロキシグループのメンバー、ルールからの直接参照、クライアントに保存された選択状態も確認してください。トラブルシューティングでは、まず信頼でき、パラメーターが揃ったノードを1つ残し、サービス状態と認証の有効性を確認してから集合を段階的に戻します。設定を共有するときは、サブスクリプションURLの認証情報、ノードのパスワード、個人を特定できる情報を削除してください。公開用サンプルは、スクリーンショットの一部を隠すだけでなく、説明用の値に置き換えます。

5. プロキシグループ：ノードを整理し、ルール入口を維持する

プロキシグループは、ルールとノードの間にある安定したインターフェースです。ルールは「出口選択」という名前のグループを参照し続け、グループ内のノードはサブスクリプションの更新やユーザーの選択に応じて変えられます。これにより、ルールが具体的なノード名に依存することを減らし、異なる用途で別々の出口を使えます。プロキシグループ自体がリモート接続を自動的に作るわけではありません。最終的には実際のノードまたは組み込みターゲットへ到達する必要があります。プロキシグループを読むときは、名前だけでなく、種類、メンバーの出所、最終的な到達先も確認してください。

手動選択グループと組み込みターゲット

# この断片は外部ノードに依存せず、グループとルールの参照を検証しやすい
proxy-groups:
  - name: "出口選択"
    type: select
    proxies:
      - DIRECT
      - REJECT

rules:
  - DOMAIN-SUFFIX,example.com,出口選択
  - MATCH,DIRECT

select グループでは、ユーザーがメンバーを手動で選択します。ここではリモートサービスに依存しない構造テストにするため、直接接続と拒否という2つの組み込みターゲットだけを入れています。拒否を選ぶと、そのグループに一致した接続はブロックされ、別のメンバーへ自動的に切り替わることはありません。実際に使う場合は、定義済みのノード名をリストへ追加できます。設定内のメンバー順とクライアントに保存された選択状態が、初回表示に同時に影響する場合があります。リロードのたびに必ず先頭が選ばれるとは考えないでください。

DIRECT は現在の端末から対象へ直接接続し、REJECT は一致した接続を拒否します。グループ名に組み込みターゲットの名前を再利用したり、名前とプロトコル種別を混同したりしないでください。ルールのターゲットに「自動選択」と書くなら、設定内に完全に同名のオブジェクトが必要です。1文字、スペース、句読点の違いだけでも参照が無効になることがあります。中国語の名前は読みやすい一方、更新経路が複雑になるほど安定した命名が重要です。

自動選択、フェイルオーバー、負荷分散

# 前提：proxies に「説明用ノード」が定義され、検証済みであること
proxy-groups:
  - name: "自動選択"
    type: url-test
    proxies:
      - "説明用ノード"
    url: "https://www.gstatic.com/generate_204"
    interval: 300
    tolerance: 50

  - name: "出口選択"
    type: select
    proxies:
      - "自動選択"
      - "説明用ノード"
      - DIRECT

url-test は指定したアドレスで到達性をテストし、結果に応じてメンバーを選択します。サンプルの間隔と許容差は説明用の値です。許容差は小さな差による頻繁な切り替えを抑えるためのもので、実際の業務遅延を保証するものではありません。テスト先にはノードの出口からアクセスするため、テスト失敗の原因がそのアドレスへの制限であり、ノード全体が利用不能とは限りません。メンバーが1つだけなら、自動選択にも比較対象となる別の出口はありません。

fallback はメンバー順に利用可能性を確認するフェイルオーバーに近く、主系・待機系に適しています。load-balance は接続の分散を目的とし、具体的な方式と設定項目は現在のコアのドキュメントで確認してください。負荷分散は通常、1つのダウンロード接続を複数ノードへ分割せず、帯域を単純に合算するものでもありません。ログインセッションや出口アドレスに敏感なアプリでは、出口の頻繁な変化が追加認証を招くことがあるため、安定性を優先してください。

ヘルスチェックが示せるのは、特定の時刻、対象、テスト方式における結果だけです。地域制限、UDP機能、認証更新、長時間接続の挙動をすべてカバーするものではありません。極端に短いテスト間隔で状態の即時性を追求しないでください。テストは端末とノードのリソースを消費し、ネットワークの揺らぎによる切り替えを増やす場合もあります。まず手動グループで安定した基準を作り、業務が正常であることを確認してから自動グループを導入し、実際の効果を比較するのがおすすめです。

プロバイダー参照、ネスト、選択状態の復元

ノードがプロキシプロバイダーから提供される場合、プロキシグループは通常 use でプロバイダー名を参照し、静的ノードは proxies で参照します。両者は参照対象が異なるため、ダウンロードURLをメンバー名の位置に入れてはいけません。ノードフィルターですべてのメンバーが除外され、空のグループになることもあります。更新後は、プロバイダーの読み込み成功、フィルター条件への一致、グループ内の実際のメンバーを同時に確認してください。サブスクリプション更新の表示だけでは不十分です。

プロキシグループは別のグループを参照できますが、依存関係には終点が必要です。たとえば手動グループが自動グループを参照し、自動グループがノードを参照する構成は明確です。2つのグループが相互参照すると循環が発生します。トラブルシューティングの経路を追いやすくするため、ネストの階層はできるだけ浅くしてください。画面で「出口選択」が自動グループを選んでいても、自動グループが最終的にどのノードを選んだかを確認しなければ、ログの実際の出口が利用者の想定と異なることがあります。

一部のクライアントやコアはプロキシ選択を保存し、設定更新後に以前のメンバーを復元しようとします。メンバー名が変更または削除された場合の復元動作は異なる場合があります。ルールやサブスクリプションを更新する前に重要なグループの選択を記録し、更新後に実際の到達先を確認してください。「ルールは正しく一致するのにアクセス結果が違う」場合は、まずグループが直接接続または無効なノードを選んでいないか確認し、その後にDNSやルーティングを調べます。ルールとプロキシグループの連携手順は接続確認の手順も参照してください。

6. ルール構文：マッチ条件、順序、最終ターゲット

rules は通常、上から下の順に一致判定し、マッチした接続を指定ターゲットへ渡します。順序はロジックの一部です。正確な例外は広いルールより前に置き、最後のフォールバックは末尾に置きます。ルールリストを自由に並べ替えられる分類表として扱わないでください。早い位置に広範なルールを置くと、後ろの詳細なルールが実行される機会を失います。変更前に、どの接続の扱いを変えたいのか、元々どの位置で一致していたのかを明確にしてください。

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

# 部分的なルール断片。組み込みターゲットでマッチ順を示す
rules:
  - DOMAIN,blocked.example.com,REJECT
  - DOMAIN-SUFFIX,example.com,DIRECT
  - 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,DIRECT

DOMAIN は完全一致のドメイン、DOMAIN-SUFFIX はドメインのサフィックスとサブドメイン、DOMAIN-KEYWORD はドメイン内のキーワードに使います。キーワードの範囲は想定より広く、同じ文字列を含む別ドメインにも誤って一致する場合があります。明確なサフィックスが分かっているなら、サフィックスルールを優先してください。ドメインルールは完全なWeb URLのパス、クエリパラメーター、ページ内容を認識しないため、URLのディレクトリ単位で直接振り分けることはできません。

IP-CIDR はIPv4アドレス範囲に使い、IPv6アドレス範囲には対応するIPv6ルール種別を使います。サンプルのプライベートアドレス範囲だけで、すべてのローカル通信をカバーできるわけではありません。実際のネットワークに応じて、他の特殊範囲やルーティングも考慮してください。MATCH はマッチ値を持たず、最終ターゲットを直接指定するため、末尾に置きます。先頭に置くと、後続の通常ルールが機能しなくなります。

ドメイン情報と no-resolve の境界

ドメインルールが一致する前提は、ルール判定時にコアが対応するドメイン情報を持っていることです。アプリケーションが先に独自解決し、対象IPだけを送信すると、コアはドメインルールを直接使えない場合があります。Fake-IPマッピング、プロキシプロトコルが持つホスト名、適用可能なスニッフィング機能が手がかりを提供することはありますが、すべての接続で元のドメインを復元できるとは限りません。ドメインルールが機能しない場合は、まずログ上の対象がドメインかアドレスかを確認してください。

アドレスルールは、対象がどのアドレス範囲に属するかを判定するために名前解決を開始する場合があります。no-resolve を付けると、そのアドレスルールのために能動的な名前解決を行わなくなりますが、グローバルDNSを無効にするわけではなく、後続の接続に必要な解決まで妨げるわけでもありません。接続に対象IPがすでにある場合、ルールはそのIPを使って一致判定できます。ドメインルールを先に置き、必要なアドレスルールを後に置くと、不要な名前解決依存を減らせますが、最終的には用途に合う順序にしてください。

ルールプロバイダーとローカルルールの管理

# 前提：対応する場所にルールファイルを作成済み
rule-providers:
  local-policy:
    type: file
    behavior: classical
    path: ./rules/local-policy.yaml

rules:
  - RULE-SET,local-policy,DIRECT
  - MATCH,DIRECT

# rules/local-policy.yaml の内容。メイン設定ではない
payload:
  - DOMAIN-SUFFIX,example.com
  - IP-CIDR,192.168.0.0/16,no-resolve

ルールプロバイダーはマッチ対象の集合を独立ファイルへ分け、メイン設定でその集合にポリシーを割り当てます。上例では classical 動作を使い、集合内のルールには最終ターゲットを記述しません。ドメイン集合とアドレス集合には、それぞれ対応する動作と内容形式が必要です。リモートルールでは、ダウンロード形式、キャッシュパス、更新結果も確認します。拡張子が同じでも内容構造が同じとは限りません。通常のテキストリストを payload を含むYAMLとして扱うと、読み込みエラーになります。

地理データ、プロセス名、プロセスパスのルールは、追加条件に依存します。地理分類はデータベースのカバー範囲と更新時期に左右され、プロセスルールはOSの権限、プラットフォーム、取り込み方式に制限されます。あるプラットフォームの書き方を汎用的な方法と考えないでください。ルールを管理するときは追加理由を記録し、マッチ範囲を最小限にします。新しいルールを検証するときは新規接続を作ってください。既存の長時間接続は、ルールをリロードしただけでは出口を再選択しないことが多いためです。

7. オーバーライドとマージ：サブスクリプション更新とローカル変更を両立する

サブスクリプションのダウンロードファイルを直接編集すると、次回更新時に変更が失われやすくなります。オーバーライドの目的は、サブスクリプションが管理するノードと基本ルールを、端末固有のポート、DNS、ルール設定から分離することです。すべてのクライアントに共通するマージアルゴリズムはありません。フィールド置換を提供するもの、ルールの前置・後置に対応するもの、完全なオブジェクトをスクリプトで処理できるものがあります。使用前に、その入口がYAML断片、完全な設定、実行可能スクリプトのどれを処理するか確認してください。

スカラー、マッピング、リストを分けて理解する

# 元の設定にある関連フィールド
mixed-port: 7890
mode: global
allow-lan: true

# この種のフィールド置換に対応するクライアントのオーバーライド入口専用
mode: rule
allow-lan: false

# ルールを仮定：同名スカラーはローカルオーバーライドで置換される
mixed-port: 7890
mode: rule
allow-lan: false

この例が示すのはスカラー置換だけです。元の設定のポートは残り、モードとLANアクセスはローカル値に置き換えられます。ネストしたDNSフィールドも項目ごとにマージされることや、ルールリストが自動的に追加されることを示すものではありません。クライアントのGUI設定がオーバーライド後に再び書き込まれる場合、最終結果が変わることもあります。実際には、オーバーライド入口の名前から処理順を推測せず、クライアントが生成した最終設定を確認してください。

マッピングのマージには、浅い置換と再帰的マージの違いがあります。たとえば元のDNSマッピングに上流、フィルターリスト、待受アドレスがあり、ローカル側に enable: true だけを書くとします。マッピング全体が置換される場合、他の内容が消える可能性があります。再帰的マージなら、指定していないキーが残る場合があります。フィールドの削除も、null と書けば必ず有効になるわけではありません。空値を保持する仕組み、入力を拒否する仕組み、専用の削除操作を提供する仕組みがあります。

リストを追加する方向がロジックを決める

ルール、ノード、プロキシグループはいずれもリストですが、区別なしの同じ追加ロジックを共有できるわけではありません。ルールには順序の意味があるため、ローカルの例外を既存の MATCH の後ろに置いても通常は機能しません。ノードリストでは名前の重複に注意し、プロキシグループのリストではグループ名だけでなく、内部メンバーへの参照も確認します。「マージに対応している」ことを、同名ノード、循環参照、ルールの優先順位まで自動処理できる意味に解釈しないでください。

# これは最終設定における順序の例であり、汎用的なオーバーライド命令ではない
rules:
  - DOMAIN,printer.lan,DIRECT
  - DOMAIN-SUFFIX,example.com,DIRECT
  - MATCH,出口選択

上例では、元の設定に「出口選択」グループが定義され、プリンターのドメイン名を直接接続する必要があると仮定しています。このルールを前に置くと、ルール層での出口選択だけを処理します。プリンターのドメイン解決に失敗したり、マルチキャスト検出やLANルーティングに問題があったりする場合は、別途対処が必要です。より具体的な拒否ルールがある設定では、前置したルールが本来ブロックしたい対象を誤って許可しないかも確認してください。

再現可能で取り消せる処理手順を作る

サブスクリプション原文、ローカルオーバーライド、最終実行設定を分けて保存することをおすすめします。原文はサービス提供元による構造変更の確認に使い、オーバーライドはローカルの意図を追跡し、最終ファイルはコアのテストに使います。一度に追加する処理は1つにし、それが依存するグループ名やフィールドを記録してください。原文のグループ名がサービス提供元によって変更されると、ローカルルールが構文的に正しくても対象を失うことがあります。サブスクリプション更新後に参照関係を再確認してください。

スクリプトによるオーバーライドには冪等性が必要です。同じ入力を1回処理しても繰り返し処理しても、結果が同じでなければなりません。よくあるミスは、実行するたびに同じルールをリストへ挿入して重複させること、または共有オブジェクトを直接変更して後続処理に予期しない状態を渡すことです。フィールドの欠落や型の変化にも対応し、すべてのサブスクリプションにDNSマッピングや同名のプロキシグループがあると仮定しないでください。スクリプトの動作を説明できない場合は、より単純なフィールド操作を優先します。

クライアントのアップグレード、コアの切り替え、サブスクリプション更新によって、マージ経路が変わることがあります。本番適用前にコピーで結果を生成し、ポート、モード、DNS、グループ名、末尾のルールを比較してください。既存のプロバイダーパスやセキュリティ設定が消えていないことも確認します。異常が出たら、最近追加したオーバーライドを無効にし、元の設定と既知の動作する選択状態を復元してから、処理を1つずつ再起動します。設定全体を何度もコピーするより、差分を最小限に保つ方が問題を特定しやすくなります。

8. 検証とトラブルシューティング：構文チェックから実接続まで

検証は段階的に行います。ファイルを解析できるか、参照を読み込めるか、待受を起動できるか、アプリケーションが入口へ入れるか、ルールが一致するか、出口が対象へ到達できるかを順番に確認します。前の段階を通過しても、後の段階が成功したとは限りません。設定テストコマンドは主に形式と読み込み可能性を確認するもので、すべてのノードのオンライン認証や業務テストを代行するものではありません。まず障害がどの層で起きたかを記録し、最短の検証経路を選ぶことで、無関係なパラメーター変更や再インストールを減らせます。

同じコアで最終設定を確認する

# macOS / Linux：カレントディレクトリに実行可能な mihomo がある
# check.yaml はエクスポートした最終設定のコピー
./mihomo -t -f ./check.yaml

# Windows PowerShell：カレントディレクトリに mihomo.exe がある
.\mihomo.exe -t -f .\check.yaml

実行前に、コマンドがクライアントの実行環境と一致するコアを指していることを確認し、その実行ファイルのヘルプで引数を確認してください。GUIクライアントの名前と実行ファイル名は同じとは限らず、システム上の別の同名プログラムが異なるフィールドに対応している場合もあります。テストは管理されたディレクトリで実行し、プロバイダー、ルールファイル、データベースなどの依存ファイルにもアクセスできるようにします。相対パスは通常、コアの作業ディレクトリや設定処理方法に依存するため、メインファイルだけを移動して同じテスト環境になるとは考えないでください。

解析エラーの行番号が表示された場合は、エラー行とその数行前を同時に確認します。閉じていない引用符、誤ったインデント、リスト階層のずれは、次のフィールドで初めて検出されることがあります。参照エラーなら名前を上流へ追跡し、グループ名、ノード名、プロバイダー名を確認します。リソース不足ならパス、権限、内容形式を調べてください。すべてのエラーをYAMLのインデントだけに帰結させたり、理解していないセキュリティ・ルーティングフィールドを削除してテストを通したりしないでください。

入口、ルール、出口を順に検証する

# 前提：mixed-port は 7890、コアは正常に起動済み
curl --proxy http://127.0.0.1:7890 --head https://example.com/

# Windows では curl.exe を使い、コマンドエイリアスの違いを避ける
curl.exe --proxy http://127.0.0.1:7890 --head https://example.com/

プロキシ入口を明示すると、システムプロキシ設定が有効かどうかという変数を一時的に切り離せます。HTTPレスポンスを取得できれば、そのリクエストで必要な経路が完了したことを示しますが、レスポンスステータスが必ず成功になるとは限らず、すべてのアプリケーションが取り込まれている証明にもなりません。テストドメインは通常の到達性確認にすぎません。特定の業務を検証する場合は、その業務で許可された実際のアドレスを使い、クライアントの接続記録で一致したルールと最終ポリシーを確認してください。

明示的なプロキシでは成功するのにブラウザーが失敗する場合は、ブラウザー独自のプロキシ、暗号化DNS、拡張機能、システム設定を重点的に確認します。両方とも失敗するなら、まずコアが待ち受けているか、ポートが一致しているかを確認し、次にDNSとリモート接続のエラーを調べます。直接接続は正常でプロキシノードだけタイムアウトする場合は、ルール体系全体をすぐに変更せず、サブスクリプションの有効性、ノードアドレス、認証パラメーター、上流ネットワークを確認してください。段階的な順序はプロキシノードのタイムアウトに関するトラブルシューティングを参照してください。

キャッシュ、ログ、安全なロールバック

DNS、Fake-IPモード、ルールを変更した後は、接続を新たに開始してください。ブラウザーの接続プール、アプリケーションの長時間接続、OSのDNSキャッシュ、コアのキャッシュにより、古い状態がしばらく残ることがあります。まず対象アプリケーションの関連接続を閉じ、OSまたはクライアントが提供する適切なキャッシュ削除方法を使います。1回のキャッシュ問題を解決するためにユーザーディレクトリ全体を削除しないでください。テスト前後のリクエスト時刻を記録すると、ログ上のイベントと正確に対応付けられます。

ログにはエラー種別、発生時刻、マッチしたルール、必要な接続段階を残し、サブスクリプションの認証情報、認証データ、公開不要なドメインを削除してください。GUIのクラッシュとコアの失敗は別の問題です。前者では実行環境とGUIコンポーネントを確認し、後者では設定、権限、待受エラーを重点的に調べます。クライアントを開けない場合は、まず起動失敗と設定復元の手順に従って状態を保存し、すぐにデータを消去しないでください。

ロールバックでは、まず最近有効にした取り込み方式を停止し、既知の正常な設定とプロキシ選択を復元してから、システムプロキシとDNSに手動設定が残っていないか確認します。クライアントを終了しても、ユーザー自身が書き込んだネットワークパラメーターまで取り消されるとは限りません。変更前の記録を残してください。最終確認では、通常のアクセス、対象業務へのアクセス、LANアクセスをそれぞれ1回以上行います。ログと経路が想定どおりであることを確認してから、通常のログレベルへ戻し、この設定をバックアップしてください。

初回接続を完了したいだけならクイックスタートの手順へ戻ってください。GUIクライアントを選び直す場合は、選定ガイドで設定管理方式を比較し、その後配布ページから対応プラットフォームへ進みます。本マニュアルの目的は、すべてのオプションフィールドを同時に有効化することではなく、変更ごとに明確な前提、観測可能な結果、復元方法を用意することです。