Clash 設定ファイル完全ガイド

01 / DOCUMENT SHAPE

YAML構造の全体像：階層を確認してから項目を変更

トップレベルの各ブロックが連携する仕組み

実行可能なClash Meta設定は、互いに無関係な項目の集合ではなく、参照方向が明確な処理チェーンです。共通項目が待受ポート、動作モード、LANアクセスの範囲を決め、dnsが名前解決を担当し、proxiesとproxy-providersが利用可能なプロキシを提供します。proxy-groupsはプロキシや他のプロキシグループを、選択、速度テスト、フェイルオーバーの関係に整理します。rule-providersは外部ルール集合を提供し、最後にrulesが記述順に従って接続を各プロキシグループへ振り分けます。どこか一つでも名前が一致しなければ、後続の構造が構文的に正しくても、読み込み時または実行時に機能しないことがあります。

YAMLではインデントで親子関係を表し、通常は半角スペース2つを使います。タブ文字を混在させてはいけません。コロンの後にはスペースを置き、リスト項目はハイフンで始め、同じ階層の項目は同じインデントにそろえます。文字列を引用符で囲むかどうかは内容によって決まります。通常の英語名はそのまま書けますが、コロン、シャープ、波括弧を含む文字列や、真偽値として解釈されやすい内容は引用符で囲む方が安全です。プロキシグループ名に空白や日本語を含めることはできますが、すべての参照箇所で大文字・小文字、空白、記号まで完全に一致させてください。

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

dns:
  enable: true
  listen: 0.0.0.0:1053
  enhanced-mode: fake-ip
  nameserver:
    - https://1.1.1.1/dns-query

proxies:
  - name: "サンプルノード"
    type: socks5
    server: 127.0.0.1
    port: 1080

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

rules:
  - DOMAIN-SUFFIX,example.com,ノード選択
  - MATCH,DIRECT

マッピング、シーケンス、スカラーの違い

dns: の後に続くのはマッピング、つまりキーと値の項目です。nameserver: の後に続くのはシーケンスで、上流サーバーごとに1つのリスト項目を置きます。mode: rule のruleはスカラーです。よくある構造エラーは、リスト項目に属するはずの項目をトップレベルへ戻してしまうこと、または2番目のノードの項目を1番目のノードの内部にインデントしたままにすることです。複雑なノードは「ハイフン1つで完全なオブジェクト1つを開始する」形式で書き、各オブジェクト内の項目を縦にそろえると、階層のずれを見つけやすくなります。

YAMLのアンカーとエイリアスを使えば設定の一部を再利用できますが、サブスクリプション変換、クライアントの上書き、編集ソフトによって高度なYAML構文の扱いが完全に一致しないことがあります。長期運用する設定では、分かりやすい明示的な項目を優先してください。多数のノードが同じパラメータを共有し、読み込み経路がアンカーに対応していることを確認できた場合に限り、&nameと*nameを導入します。数行を重複して書く方が、隠れた継承関係よりトラブル対処しやすいことが多いです。

最小構成と完全構成

最小構成は待受ポート、1つのプロキシ、1つのプロキシグループ、末尾のルールだけでも作れます。しかし実運用では、DNS、サブスクリプションプロバイダー、ルール集合、TUN、永続化設定なども必要になることが多いです。まず最小構成を正常に読み込ませ、その後ブロックを1つずつ追加してください。複雑な設定を一度に追加してからトラブル対処を始めると、原因がDNS、ノードパラメータ、ルール参照のどれなのか判断しにくくなります。ブロックを追加するたびに「読み込み成功、接続成功、ルール一致」の3段階で確認し、すべての異常を設定ファイルの問題として扱わないようにしましょう。

設定ファイル内のコメントは#で始まり、項目の用途や変更理由を記録するのに適しています。ただし、コメントで説明している重要な名前を頻繁に変更しないでください。サブスクリプションの更新でノードやプロキシグループが再生成され、ローカルコメントも上書きされることがあります。長期的な説明は別ドキュメントに保存し、設定内には現場でのトラブル対処に役立つ短いコメントだけを残します。例えば、LAN機器向けの直通ルールや、プロキシ経由でしかアクセスできないDNS上流の説明などです。

02 / GENERAL

共通項目：ポート、モード、待受、実行状態

ポート項目の選び方

portはHTTPプロキシ用ポート、socks-portはSOCKS5用ポート、mixed-portは同じポートでHTTPとSOCKS5の両方を受け付けます。デスクトップクライアントで他のアプリに1つのプロキシアドレスだけを公開するなら、mixed-portが最も簡単です。特定のソフトが特定のプロトコルを要求する場合や、2種類の接続を分けて記録したい場合は、独立したポートに分けます。ポート番号は他のプロセスに使用されていなければよく、一般的な番号に固定する必要はありません。

redir-portとtproxy-portは透過プロキシの入口で、通常はLinuxのファイアウォールルールと組み合わせて使います。システムプロキシ用ポートとは別物です。この2項目を書くだけで通信を自動的に取り込めるわけではなく、ルーティングテーブル、ポリシールーティング、nftablesまたはiptablesのルールも連携させる必要があります。GUIクライアントのTUNモードは通常、クライアントが仮想NICとルートを作成します。ルーター用の透過プロキシルールを同時に流用すると、二重転送やループが発生する可能性があります。

modeはルールを処理するかどうかを決める

mode: ruleはrulesを上から順に照合する、日常的な振り分けの基本モードです。globalでは通信をすべてグローバルポリシーへ送るため、特定ノードの利用可否を一時的に確認するのに向いていますが、既存のルール処理は迂回します。directは宛先へ直接アクセスするため、障害の原因がプロキシ経路にあるかを判断するのに役立ちます。「ルールが一致しない」場合は、まず現在の動作モードがruleか確認してください。GUIクライアントのモード切り替えが、設定ファイルの初期値を上書きすることがあるためです。

log-levelはログの詳細度を制御します。通常運用ではinfo、ルールや接続の問題を調べるときだけ一時的にdebugへ上げ、確認後は戻してください。ログ量の増加を防げます。ログのルール一致、DNS問い合わせ、ダイヤル失敗、タイムアウトは分けて読み取る必要があります。特定のプロキシグループに振り分けられたことは、振り分け先が決まったことを示すだけで、グループ内の最終ノードへの接続成功を意味しません。

mixed-port: 7890
allow-lan: false
bind-address: "*"
mode: rule
log-level: info
ipv6: false
unified-delay: true
tcp-concurrent: true
find-process-mode: strict

LANアクセスと待受範囲

allow-lanは、他の端末がClashの待受ポートへ接続できるかを決めます。trueにした後は、OSのファイアウォールで対象ポートが許可されていることを確認し、プロキシサーバーにはClashを実行している端末のLANアドレスを指定します。bind-addressは待受アドレスを制限します。本機だけで使うならループバックの範囲を維持し、LANで共有するときだけ待受範囲を広げてください。共有プロキシをパブリックなインターフェースへ直接公開してはいけません。特にクラウドサーバーやグローバルアドレスを持つNICでは注意が必要です。

external-controllerは制御インターフェースを提供し、GUIクライアントやWebパネルが接続、ログ、プロキシ状態を読み取るために使います。制御インターフェースとプロキシポートは用途が異なり、ブラウザのプロキシアドレスとして使うものではありません。本機以外からのアクセスを許可する場合は、認証情報を設定し、ファイアウォールで接続元を制限してください。設定内の制御用認証情報はローカルの機密情報であり、公開リポジトリや公開質問欄に投稿しないでください。

ipv6は、コアがIPv6アドレスを処理・返却するかに影響しますが、単純な通信高速化スイッチではありません。上流ネットワーク、プロキシノード、宛先サイトのいずれかでIPv6経路が不完全だと、一部の接続だけ待機した後にフォールバックすることがあります。利用可能なIPv6ネットワークがない場合は無効にした方が動作をそろえやすくなります。完全なデュアルスタック環境がある場合に有効化し、DNSの応答と実際の接続経路をそれぞれ確認してください。

03 / DNS PIPELINE

DNS設定：名前解決経路、Fake-IP、振り分けの関係

DNSブロックは単なる名前解決だけを担うものではない

ClashのDNSモジュールは、ドメインをアドレスへ解決するだけでなく、ドメインルール、Fake-IPマッピング、ポリシーに応じた上流選択の基盤も担います。内蔵DNSを無効にすると、アプリは通常システムの解決結果を直接使い、コアには宛先IPしか見えなくなるため、ドメインに依存するルールが安定して一致しないことがあります。DNSを有効にする場合は、取り込むべき問い合わせが実際に待受アドレスへ届くようにしてください。設定にdns.enable: trueと書くだけで、システムが別のサーバーへ問い合わせ続けているなら、完全な名前解決経路にはなりません。

listenはDNSサービスの待受位置とポートを指定します。デスクトップGUIのTUN実装では、DNSハイジャックをクライアントが自動処理することが多いです。ルーターで直接実行する場合は、LANクライアントの問い合わせをこの待受ポートへ転送するか、ファイアウォールでリダイレクトする必要があります。すべてのインターフェースで待ち受ける場合は、制御されていないネットワークへ再帰DNSサービスを公開しないよう、ファイアウォールのアクセス範囲も確認してください。

dns:
  enable: true
  listen: 0.0.0.0:1053
  ipv6: false
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  use-hosts: true
  respect-rules: true
  default-nameserver:
    - 223.5.5.5
  nameserver:
    - https://1.1.1.1/dns-query
    - https://8.8.8.8/dns-query
  proxy-server-nameserver:
    - https://223.5.5.5/dns-query
  fake-ip-filter:
    - "*.lan"
    - "localhost.ptlogin2.qq.com"
    - "+.local"

default-nameserver、nameserverとプロキシノードのドメイン

nameserverは主要な名前解決の上流で、従来のUDPアドレスだけでなく暗号化DNSアドレスも指定できます。暗号化DNS自体がドメイン名の場合、コアはそのドメインに対応するアドレスを先に知る必要があるため、default-nameserverで導入時の名前解決を行います。導入用サーバーには通常、直接アクセスできるIPアドレスを指定し、「上流ドメインを解決しないと上流へ接続できないのに、その解決が同じ上流に依存する」という循環を避けます。

proxy-server-nameserverは、プロキシサーバー自体のドメインを解決するために使います。この経路では、現在のネットワークから直接アクセスでき、結果が安定した上流を優先してください。プロキシノードが確立する前に、ノードのドメインを解決する必要があるためです。ノードのドメイン解決を、そのノード経由でしかアクセスできないサーバーに強制すると、同じように起動依存の循環が起こります。ドメイン形式のノードだけがすべてタイムアウトし、IP形式のノードは正常な場合は、まずここを確認してください。

respect-rulesを有効にすると、DNS問い合わせもルールを参照して出口を選ぶようになります。DNS通信にも振り分けを適用したい設定に適していますが、導入時の解決、プロキシノードの解決、通常の解決が互いに待ち合わないことを確認してください。複雑な設定では、まずルール連動を無効にして基本的な名前解決を確認し、その後段階的に有効化する方が、DNS項目を一度にすべて追加するより安全です。

Fake-IPとRedir-Hostの違い

fake-ipモードでは、予約済みアドレスプールからマッピング用アドレスを返します。アプリがそのアドレスへ接続すると、コアがマッピング表から元のドメインを復元してルールを適用します。接続時にもドメイン情報を保持でき、アプリが実アドレスを先に取得して接続することによる振り分けのずれも抑えられます。アドレスプールは本機または管理下のネットワーク内だけでマッピングに使うもので、対象サイトの実アドレスではありません。予約済みネットワークの結果が表示されても、DNS障害とは限りません。

redir-hostは実際に解決したアドレスを返すため、実IPに依存するLANサービス、一部のゲーム、特殊なネットワーク検査との互換性があります。一方、ドメインと後続接続を関連付ける能力は比較的限定されます。プリンターの検出、LANホスト名、端末へのキャスト、特定アプリのログインに問題がある場合は、まず該当ドメインをfake-ip-filterへ追加してみてください。拡張モード全体を切り替える必要はありません。フィルターはできるだけ正確に指定します。範囲を広げすぎると多くのドメインがマッピングを迂回し、ドメインルールの一貫性が低下します。マッピングの仕組みと対象範囲については、Fake-IPモードの仕組みを詳しく解説も参照してください。

nameserver-policyによる振り分け解決

nameserver-policyを使うと、特定のドメインに指定したDNS上流を割り当てられます。例えば、内部ドメインをLANのDNSへ、特定の公開ドメイン群を別のリゾルバーへ渡せます。ポリシーキーにはドメインルール集合やドメインマッチ形式を使え、値には1つまたは複数の上流を指定できます。これは「どの種類のドメインをどこで解決するか」を決める機能であり、「最終的にどのプロキシを通るか」を決めるものではありません。接続先はrulesとプロキシグループが決めます。

dns:
  enable: true
  enhanced-mode: fake-ip
  nameserver:
    - https://1.1.1.1/dns-query
  nameserver-policy:
    "+.corp.example":
      - 192.168.1.1
    "rule-set:private-domain":
      - 192.168.1.1

04 / PROXY OBJECTS

プロキシノード項目：接続対象、プロトコルパラメータ、プロバイダー

ノードオブジェクトに共通する基本構造

proxiesはノードオブジェクトのリストです。各オブジェクトには少なくとも名前、タイプ、サーバーアドレス、ポートが必要で、認証、トランスポート、暗号化の項目はプロトコルによって決まります。nameは他のブロックからノードを参照する一意の識別子であり、重複させないでください。同名ノードがあると、画面表示とポリシー参照の判別が難しくなります。serverにはIPまたはドメインを指定できます。ドメインを指定する場合は、ノード接続前にDNSブロックが解決できることも確認してください。

プロトコル項目を別タイプのノードへそのまま流用してはいけません。あるプロトコルで有効な項目が、別のノードでも同じ効果を持つとは限らず、未知の項目は無視されることも、設定チェックを失敗させることもあります。サブスクリプションを整理するときは、プロトコルに必要なパラメータを残し、変換過程で残ったもののコアが認識しない装飾項目は削除してください。ノード接続に失敗したら、まずタイプ、サーバー、ポート、認証の4点を確認し、その後にTLS、トランスポート、サーバー名を調べます。最初からプロキシグループやルールを変更するのは避けてください。

proxies:
  - name: "オフィス SOCKS"
    type: socks5
    server: 192.168.1.10
    port: 1080
    username: "proxy-user"
    password: "your-password"
    udp: true

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

TLSとサーバー名

TLSを使用するプロトコルでは、通常tls、サーバー名、証明書検証が関係します。サーバー名はハンドシェイク時に証明書や仮想ホストを選択するために使われ、ノードの接続先と同じ場合も、サーバー側で個別に指定される場合もあります。接続先をIPで指定し、サーバー証明書がドメイン向けに発行されている場合は、正しいサーバー名の指定が特に重要です。証明書エラーを検証無効化で長期的に隠すのではなく、システム時刻、ノード情報、サーバー名、中間ネットワークを確認してください。プロキシ有効時にブラウザで証明書警告が出る場合は、HTTPS証明書エラーの項目別トラブル対処を参照してください。

WebSocketやgRPCなどのトランスポート層には、パス、Host、サービス名が含まれることもあります。これらはサーバー側のデプロイ設定で決まり、クライアントが推測して得られるものではありません。パスのスラッシュ、大文字・小文字、空白文字はハンドシェイクに影響することがあります。サブスクリプション変換時には、ネストされた項目を誤って展開しないよう注意してください。TCPでサーバーポートまで接続できるのにすぐ切断され、ログにハンドシェイク失敗が出る場合は、ネットワーク到達性よりTLSとトランスポート層のパラメータを重点的に確認します。

proxy-providersで動的なノード集合を管理

ノード数が多い場合や、定期的に取得元を更新する場合はproxy-providersを使えます。プロバイダーはファイルまたはリモートアドレスからノードを読み込み、ヘルスチェックも設定できます。プロキシグループはuseでプロバイダー全体を参照し、proxiesへ各ノード名を手作業で並べる必要はありません。この構成なら、サブスクリプション更新後に新しいノードがグループから漏れる問題を減らせ、取得元ごとに集合を分けることもできます。

proxy-providers:
  primary:
    type: http
    url: "https://example.com/subscription.yaml"
    path: ./providers/primary.yaml
    interval: 3600
    health-check:
      enable: true
      interval: 600
      url: https://www.gstatic.com/generate_204

proxy-groups:
  - name: "自動選択"
    type: url-test
    use:
      - primary
    url: https://www.gstatic.com/generate_204
    interval: 300

pathはプロバイダーの内容を保存するローカルキャッシュの場所です。実行ユーザーには親ディレクトリへの書き込み権限が必要です。コンテナやシステムサービスでは相対パスがプロセスの作業ディレクトリを基準にするため、設定ファイルのあるディレクトリとは限りません。プロバイダーのダウンロードは成功するのにキャッシュの書き込みに失敗する場合は、実際の作業ディレクトリとマウントパスを確認してください。リモートアドレスのアクセスパラメータは機密情報なので、ログや設定の断片を共有する前に削除します。

ヘルスチェックが確認するのは、テストアドレスへのリクエストをそのノード経由で完了できるかどうかだけです。すべての宛先へアクセスできることや、帯域幅を測定することを意味しません。テストアドレスのネットワーク、ノードからの経路、ローカルDNSが結果に影響します。テスト値が低いノードでも実際のダウンロードが遅い場合は、帯域幅、混雑、宛先サイトまでの経路、接続再利用の違いが原因かもしれず、プロキシグループの計算ミスとは限りません。チェック間隔が短すぎると接続を継続的に作成し、ノード数が多いほど余分なリソースを消費します。長すぎると障害状態の反映が遅れます。ノード数と切り替えの要件に応じてバランスを取ってください。

05 / POLICY LAYER

プロキシグループ項目：選択、速度テスト、フェイルオーバー、ネスト

プロキシグループはルールとノードの間をつなぐ振り分け層

ルールは通常、固定ノードではなくプロキシグループを指します。これによりノードが変わっても、グループのメンバーや現在の選択だけを調整すればよく、ルール全体を書き直す必要がありません。selectグループはユーザーが手動でメンバーを選び、url-testはテスト結果に基づいて自動選択し、fallbackはメンバー順に利用可能な項目を探し、load-balanceは複数の利用可能なメンバーへ接続を分配します。タイプごとに解決する問題が異なるため、画面に表示される遅延だけで適性を判断しないでください。

proxiesリストにはノードだけでなく、別のプロキシグループやDIRECT、REJECTなどの組み込みポリシーも指定できます。ネストを使えば「用途の分類」と「ノード選択」を分離できます。例えば、ストリーミングのルールを「メディアサービス」に送り、メディアサービスから「ノード選択」を参照します。ただし階層が深すぎると判断が難しくなり、循環参照につながることもあります。依存方向は一方向に下るよう設計し、どのグループも直接・間接を問わず自分自身を含まないようにしてください。

proxy-groups:
  - name: "ノード選択"
    type: select
    proxies:
      - "自動選択"
      - "フェイルオーバー"
      - "サンプルノード"
      - DIRECT

  - name: "自動選択"
    type: url-test
    proxies:
      - "サンプルノード"
      - "予備ノード"
    url: https://www.gstatic.com/generate_204
    interval: 300
    tolerance: 80

  - name: "フェイルオーバー"
    type: fallback
    proxies:
      - "サンプルノード"
      - "予備ノード"
    url: https://www.gstatic.com/generate_204
    interval: 300

  - name: "メディアサービス"
    type: select
    proxies:
      - "ノード選択"
      - DIRECT

速度テストの結果をどう読むか

url-testが測定するのは、クライアントからノード経由で指定したテストアドレスへアクセスを完了するまでの時間です。接続確立とリクエスト応答を含みますが、すべてのサイトに共通する遅延ではありません。テスト先のネットワーク、ノードからの経路、ローカルDNSが結果に影響します。あるノードのテスト値が低くても実際のダウンロードが遅い場合は、帯域幅、混雑、宛先サイトまでの経路、接続再利用の違いが原因かもしれません。速度の問題はノード、回線、ローカル設定の3層に分けて確認できます。

toleranceは、結果が近いノード間で頻繁に切り替わるのを防ぎます。新しい結果が現在のノードをわずかに上回るだけなら、接続を維持する方が再選択を繰り返すより安定します。intervalは定期チェックの間隔を制御し、lazyを使うと非アクティブなプロキシグループのテストを減らせます。デスクトップ端末の断続的な接続と、常時稼働するルーターではリソース予算が異なり、ノード数もヘルスチェックのリクエスト量を直接増やします。利用状況に合わせて調整してください。

fallbackとload-balanceの使い分け

fallbackは順序と可用性を重視します。先頭のメンバーが利用可能なら使い続けるため、主回線と予備回線が明確な構成に向いています。最低遅延だけを目標にするわけではないため、予備ノードの遅延が低くても選ばれるとは限りません。load-balanceは複数接続への分配を目的とし、1本のダウンロード接続を複数ノードへ分割するものではありません。通常、1つのTCPまたはUDPセッションは送信元アドレスの変化でセッションが壊れないよう、固定された出口を使います。

負荷分散では、同じ宛先に対して出口を固定する必要があるかも考慮します。ログイン、決済、認証コード、送信元アドレスに敏感なサービスでは、連続するリクエストが別ノードへ移ると再認証を求められることがあります。その場合は宛先との対応を維持できるポリシーを使うか、関連ドメインを固定ノードグループへ入れてください。一般ユーザーには、分かりやすい手動選択グループと自動速度テストグループを1つずつ組み合わせる方が、多層の負荷分散より管理しやすいことが多いです。

名前の設計が長期的な保守性を左右する

プロキシグループ名はルールの末尾にもクライアント画面にも表示されます。「ノード選択」「フェイルオーバー」「メディアサービス」「メッセージング」など、用途を基準に命名してください。ノードの地域、プロトコル、用途を1つの長い名前に詰め込むのは避けます。ルールプロバイダーとプロキシグループは1対多または多対1にできますが、名前は安定させてください。頻繁な改名は、古い上書き、スクリプト、ローカルルールを同時に壊します。

サブスクリプションが提供するプロキシグループは、更新時に再構築されることがあります。ローカルで長期的に保持したいグループは、クライアントが対応する上書き層に置き、挿入位置を明確にしてください。ルールがローカルグループを指していても、上書きの実行順がルールのマージより後だと、最終設定に一時的な未定義参照が生じることがあります。確認時は断片が存在するかだけでなく、最終ファイル内でプロキシグループが定義され、コアが同じ設定として読み込む範囲内にあることを確認してください。

06 / RULE ENGINE

ルール構文：上から照合し、最初の一致を適用

ルールの順序が実際の優先順位になる

rulesは順序付きリストです。接続は1行目から確認され、最初に一致したルールが指定するポリシーを直ちに適用し、後続のルールは処理されません。そのため、完全一致ドメインや個別対応が必要なサービスは前方に置き、広いドメインサフィックス、IP範囲、地域集合を中央に置き、MATCHを最後に置いて残りの接続を受けます。広範囲のルールを先頭に置くことが、「ルールを書いたのに効かない」主な原因の一つです。

ルールは通常、タイプ、照合値、ポリシー名で構成し、英語のカンマで区切ります。ポリシー名は定義済みのプロキシグループ、ノード、組み込みポリシーに対応している必要があります。ルールによってはオプションを追加でき、例えばIPルールのno-resolveは、照合のためにアドレスを取得する追加の名前解決を行わないことを示します。ルール内のカンマは構造上の区切り文字なので、特殊な内容をYAMLの引用符で囲んでもClashのルール解析方式は変わりません。

rules:
  - DOMAIN,api.example.com,ノード選択
  - DOMAIN-SUFFIX,example.com,ノード選択
  - DOMAIN-KEYWORD,example,ノード選択
  - PROCESS-NAME,example.exe,DIRECT
  - DST-PORT,22,DIRECT
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
  - GEOIP,CN,DIRECT
  - MATCH,ノード選択

ドメインルールの適用範囲

DOMAINは完全なドメイン名だけに一致し、単一のAPIやホストに適しています。DOMAIN-SUFFIXはドメインとそのサブドメインに一致し、サイト全体に向いています。DOMAIN-KEYWORDはドメインに指定文字列が含まれていれば一致する可能性があり、範囲が最も広く誤一致もしやすいタイプです。サフィックスルールで対応できる場合は、数行を省くためにキーワードルールへ置き換えないでください。短すぎるキーワードは、対象サービスと無関係なドメインにも一致することがあります。

ドメイン照合には、接続時にコアが元のホスト名を把握している必要があります。HTTPのホスト名、TLSのサーバー名、Fake-IPマッピング、スニッフィングなどからドメイン情報を取得できます。アプリがIPへ直接接続する場合、ドメインルールは当然一致しません。その場合は同じドメインの表記を追加し続けるのではなく、アプリ自体の動作を確認してください。トラフィックスニッフィングで一部の接続のドメイン識別を補えることもありますが、対応プロトコルとポートに限界があり、正しいDNSの取り込みを置き換えるものではありません。

IP、ポート、プロセスルール

IP-CIDRとIP-CIDR6は宛先アドレスの範囲で照合し、LAN、予約済みアドレス、明確なサービスネットワークに適しています。公開サービスのアドレスは変化したり複数のサービスで共有されたりするため、公開IPを大量に手動管理するより、ドメインやルール集合の方が安定することが多いです。GEOIPはアドレスデータベースで分類するため、結果はローカルデータに依存します。データが古いと新しく割り当てられたアドレスが想定外の分類になることがあり、データベース更新もルール保守の一部です。

DST-PORTは宛先ポートで照合するだけで、同じポート上の異なるサイトは区別できません。現代のWeb通信は443番ポートを共有することが多く、ポート全体を特定のポリシーへ送ると範囲が広すぎます。プロセスルールはプログラム名やパスで照合できますが、対応状況はOS、実行権限、取り込み方式に左右されます。ゲートウェイ機器から端末上のプロセスは見えず、一部のサンドボックスアプリも完全なプロセス情報を提供できません。クロスプラットフォーム設定の重要な振り分けを、プロセスルールだけに依存しないでください。

rule-providersで大規模なルール集合を分割

rule-providersはルール内容をローカルファイルまたはリモートリソースに分離し、メインのルール一覧からRULE-SETで参照します。プロバイダーには、動作タイプ、形式、キャッシュパス、更新間隔を指定します。domainはドメイン集合、ipcidrはアドレス範囲、classicalは複数の従来型ルールを扱います。動作タイプとファイル内容が一致していないと、ダウンロードに成功しても期待どおりに解析できません。

rule-providers:
  private-domain:
    type: http
    behavior: domain
    format: yaml
    path: ./rules/private-domain.yaml
    url: "https://example.com/rules/private-domain.yaml"
    interval: 86400

  private-ip:
    type: file
    behavior: ipcidr
    format: yaml
    path: ./rules/private-ip.yaml

rules:
  - RULE-SET,private-domain,DIRECT
  - RULE-SET,private-ip,DIRECT,no-resolve
  - MATCH,ノード選択

ルールプロバイダーの更新に失敗しても、コアが直ちに停止するとは限りません。既存のキャッシュが使われ続けることもあります。そのため「設定の読み込み成功」と「ルールの更新成功」は別の問題です。新しいドメインが一致しない場合は、プロバイダーの状態、キャッシュファイルの更新日時、ダウンロード内容、動作タイプを確認してください。リモートリソースがルールファイルではなくWebサイトのエラーページを返すと、ネットワーク要求は成功に見えても解析段階で失敗します。

末尾のポリシーは設定のデフォルト方針を示します。MATCH,ノード選択で終えると未分類の通信をプロキシ選択へ送り、MATCH,DIRECTで終えると明示した宛先だけをプロキシ経由にします。どちらも成立しますが、ルール集合の適用範囲がユーザーの想定と一致していることが重要です。末尾のポリシーを変更すると、すべての未一致接続に影響します。特定サイトを一時的に直すスイッチとして扱わず、個別に検証してください。

07 / MERGE LAYERS

上書きとマージ：サブスクリプション更新後もローカル設定を保持

まず設定のソース階層を把握する

GUIクライアントの最終設定は通常、複数のソースから構成されます。リモートサブスクリプションがノードと基本ポリシーを提供し、ローカル上書きが共通項目を変更したりルールを追加したりし、クライアント自体の設定がシステムプロキシ、TUN、制御ポートなどの実行パラメータを決めます。画面上の「サブスクリプション内容」は、多くの場合その一層にすぎません。項目がなぜ書き換えられたかを判断するには、マージ順序と、同名項目が衝突した際に上書き、追加、深いマージのどれが行われるかを把握する必要があります。

クライアントによって上書きの名称と機能は完全には同じではありません。YAML断片に対応するもの、スクリプトに対応するもの、前置ルールと後置ルールを区別するものがあります。クライアントを移行する際、以前の上書きがそのまま実行できるとは考えないでください。一般ユーザーの第一候補となるGUI入口にはClash Plusが適しています。別のクライアントへ移行する場合は、ダウンロードページでプラットフォームごとにClash Verge Rev、FlClash、Clash Nyanpasu、Clash Meta for Android、Surfboard、アーカイブ版クライアントを比較できます。

マッピングの上書きとリストへの追加は別の操作

mode、log-level、dns.enableのような単一値の項目では、上書きによって通常は新しい値が古い値を置き換えます。rules、proxies、proxy-groupsのようなリストでは、単純な上書きでサブスクリプションの既存内容が消え、単純な追加では新しいルールがMATCHの後ろに入り、永遠に一致しないことがあります。リストを変更するときは位置を明確にしてください。カスタムの詳細ルールは通常、広範囲のルールより前に挿入し、フォールバックルールは常に最後に残します。

マッピングの深いマージにも限界があります。fake-ip-filterを1項目だけ追加したいのに、マージャーがdnsオブジェクト全体を置き換えると、既存のnameserverや待受項目が消えてしまいます。逆にDNSを完全に置き換えるつもりでも、ツールが項目単位のマージを行うと、サブスクリプション由来の古いポリシー項目が残ります。上書きを使う前に、クライアントがオブジェクトと配列をどう処理するかを確認し、上書き断片の構文だけでなく最終設定で結果を検証してください。

# ローカル上書き断片の例
mode: rule
log-level: info

dns:
  enable: true
  fake-ip-filter:
    - "*.lan"
    - "+.local"

rules:
  - DOMAIN,internal.example,DIRECT
  - DOMAIN-SUFFIX,example.com,ノード選択

ルールの挿入位置が上書きの有効性を決める

サブスクリプションの末尾にMATCH,ノード選択があるとします。ローカルルールをそのままリスト末尾へ追加しても、実行されることはありません。フォールバックルールの前に挿入するか、上書きツールの前置ルール機能を使うのが正しい方法です。サブスクリプションに広範囲のDOMAIN-SUFFIX、GEOIP、ルールセットが含まれる場合、ローカルの詳細な例外ルールもそれらより前に置きます。ルールに明示的な優先順位番号はなく、位置が優先順位になります。

プロキシグループの上書きでは、メンバー参照も処理する必要があります。「開発サービス」というグループを追加するだけでは不十分で、ルールがそれを指し、内部で参照する「ノード選択」も最終設定に存在しなければなりません。サブスクリプション側がプロキシグループ名を変更すると、ローカル上書き自体は正常にマージされても、読み込み時に未定義ポリシーが発生することがあります。サブスクリプション独自の名前への依存を減らすか、構造が変わるたびに最終的な参照グラフを確認する方が安全です。

スクリプト上書きは条件付き変更に適するが、複雑にしすぎない

スクリプトを使えばノードを走査したり、プロキシグループを再構築したり、名前に応じてルールを挿入したりできます。更新のたびに内容が変わるサブスクリプションの処理に適しています。一方で、項目が存在しない、ノード名に特殊文字が含まれる、クライアント更新で入力構造が変わるなど、新たな失敗要因も増えます。スクリプトではオブジェクト型と配列の存在を先に確認し、すべてのサブスクリプションが同じ構造だと仮定しないでください。異常時には元の設定を保持して明確なログを出し、不完全な設定を返さないようにします。

複雑なスクリプトは通常のコードと同じようにバージョン管理し、テストしてください。変更1回につき1種類の問題だけを扱い、入力例を保存し、ノードリストが空、プロキシグループがない、同名ルールがすでにあるといった境界条件も処理します。ポート変更や2本のルール追加だけなら、YAML上書きの方が透明です。宣言的な断片ではどうしても表現できない繰り返し操作に限り、スクリプトを使いましょう。

コアを直接実行する場合のマージ戦略

mihomoを直接実行する場合は、デプロイ手順でテンプレートや設定生成ツールを使ってマージできます。ただし、生成結果は単独で検査できるYAMLにしてください。サービス起動前に一時ファイルへ生成し、検査に成功してから正式な設定へアトミックに置き換えると、マージ中断による不完全なファイルを防げます。ルーターや旁路ルーター環境では、ディレクトリ権限、永続化パーティション、起動順序もルールのダウンロードやキャッシュ復元に影響します。構成についてはルーターと旁路ルーターへのデプロイ概要を参照してください。

08 / VALIDATION

確認とトラブル対処：読み込み失敗から振り分け異常まで

まず静的チェックを行い、次に実行ログを確認する

設定障害は階層ごとに対処します。第1層はYAMLを解析できるかで、インデント、コロン、リスト、引用符を含みます。第2層はClashの設定セマンティクスが成立するかで、ノードタイプ、必須項目、ポリシー参照、ルール形式を確認します。第3層になって初めて、DNS不通、ノードのハンドシェイク失敗、システムプロキシ未有効化、透過プロキシのルート不足など、実行時のネットワーク問題を調べます。第1層を通過していない段階で、ノードの遅延を測ったりファイアウォールを変更したりする必要はありません。

コアを直接実行する場合は、設定チェック用のパラメータで指定ディレクトリ内の設定を検証できます。実際のコマンドでは、実行ファイルのパスと設定ディレクトリをデプロイ場所に合わせて変更してください。GUIクライアントにも通常、設定チェック、再読み込み、ログ表示の入口があります。画面に「読み込み失敗」としか表示されない場合は、詳細ログを開いて具体的な項目を特定します。チェック前にファイルを保存し、エディターがタブや不可視文字を書き込んでいないことを確認してください。

mihomo -t -d /path/to/config-directory
mihomo -d /path/to/config-directory

チェックコマンドが通るのは、設定構造をコアが受け入れられることを示すだけで、すべてのリモートノード、DNS上流、ルールプロバイダーへアクセスできるとは限りません。起動後はプロバイダーの更新、DNS問い合わせ、接続ダイヤル、ルール一致も確認してください。ログレベルを一時的にdebugへ設定すると文脈を増やせますが、分析時は1件の明確なリクエストに絞り、大量のバックグラウンド接続から手がかりを探さないようにします。

読み込み失敗でよくある分岐

エラーが特定の行を指していても、実際の原因は前の行にある場合があります。例えば引用符の閉じ忘れで後続内容が誤解析されたり、上位階層のインデントがすでにずれていたりします。エラー行から上へ、直近のトップレベル項目まで確認してください。「ポリシーが見つからない」類のエラーでは、まずルール末尾の名前を検索し、次にプロキシグループの定義を検索して、空白や記号まで比較します。重複名が出た場合は、手書きノードだけでなく、プロバイダー展開後に静的ノードと同名になっていないかも確認します。

あるクライアントでは動くのに別のクライアントで失敗する場合、対応項目、コアの機能、上書き形式の違いが原因であることが多いです。まず基本ノード1つ、選択グループ1つ、ルール2本だけの最小設定を出力し、対象クライアントが読み込めることを確認してから、ブロックごとに戻します。フィールドを無作為に削除して運任せにしないでください。各回で変更するブロックは1つだけにし、構文チェック、起動、実接続のどの段階で変化したかを記録します。

接続は成功するがページが開かない

ノードテストに成功しているのにWebページが開かない場合は、DNS、ルール、アプリの取り込みを分けて確認します。まずmixed-portを明示したコマンドで簡単なアドレスへアクセスし、プロキシポートが動作することを確認します。次にブラウザまたはシステムプロキシが同じアドレスを指しているか確認し、その後、対象ドメインがどのルールに一致したかを確認します。ログにそのアプリの接続がまったくなければ取り込み層、接続はあるがルールが想定と異なればルールまたはドメイン識別、ポリシーは正しいのにダイヤルに失敗するならノードとトランスポート層を調べます。

一部のサイトは正常なのに、別のサイトだけ長時間待たされる場合は、IPv6、UDP、HTTP/3、MTUに注意してください。アプリがIPv6やQUICを優先し、失敗後に別経路へフォールバックすることがあります。TUN環境でMTUが大きすぎると、小さなリクエストは正常でも大きな応答が停止することがあります。トラブル対処では、単一の機能だけを一時的に無効化して比較できますが、原因を確認したらネットワーク条件とプロトコル対応を修正し、矛盾する一時スイッチを長期的に積み重ねないでください。

TUNと透過プロキシの追加確認

TUNによる取り込みは、仮想NIC、ルート、権限に依存します。デスクトップOSでは、仮想NICを作成するためにクライアントへシステム権限を与える必要がある場合があります。Linuxではカーネル機能、転送設定、ポリシールーティングも関係します。TUNが有効と表示されているのにアプリの通信がログへ入らない場合は、コアを再起動するだけでなく、デフォルトルートと除外ネットワークを確認してください。LAN、仮想マシン、コンテナ、社内ネットワークは通常、明示的に直通設定しないとローカルサービスへのアクセスまで誤ってプロキシへ送られることがあります。

ゲートウェイの透過プロキシでは、コア自身の通信が再び転送されないようにする必要があります。ノード接続、DNS上流への問い合わせ、ルールのダウンロードが同じ透過プロキシチェーンへ戻ると、ループが発生します。一般的には実行ユーザー、プロセスマーク、ルーティングマークなどで除外しますが、具体的な方法はnftables、iptables、システムのルーティング設計によって異なります。設定ファイルで指定できるのは待受ポートやTUNパラメータまでで、OS側の完全なループ除外を代替するものではありません。

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

再現可能なトラブル対処記録を作る

有効なトラブル対処記録には少なくとも、使用中のクライアントまたはコアの実行方式、設定の取得元、どの段階で障害が起きたか、1回のリクエストに対応するログ、正常と確認できた箇所、直近の変更を含めます。設定断片を共有する前に、サブスクリプションURL、認証情報、制御用認証情報、ノードパスワードを削除してください。一方で、項目構造、ポリシー名、ルール順序は残します。「使えない」と無関係なログを大量に示すだけでは、エラーの階層を判断できません。

修正後は、一時的に上げたログレベル、テストルール、迂回設定を削除してから、再読み込みと再テストを行います。長期稼働するルーターやサーバーでは、サービスを再起動して起動経路、作業ディレクトリ、キャッシュ権限も確認してください。現在のターミナルセッションでは使えても、システムサービスでは失敗することがあります。LAN共有についてはmixed-portとallow-lanの設定ガイドも参照し、待受アドレス、ファイアウォール、端末のプロキシ設定が同じ経路上にあることを確認してください。