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

01 · YAMLの構造と設定ファイルの入口

Clashの設定ファイルには通常YAMLが使われます。行ごとに実行されるスクリプトではなく、階層構造を持つデータです。トップレベルのキーでコアの動作を定義し、ネストしたマッピングに各機能の設定を、リストに複数のノード、プロキシグループ、ルールを記述します。読むときはまず左端の位置がそろった項目を見つけ、次にその下に属する内容を確認しましょう。前の行と近い位置にあるというだけで、親子関係があるとは限りません。

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

マッピングではコロンでキーと値を区切り、コロンの後には通常スペースを1つ入れます。リスト項目はハイフンで始めます。インデントにはスペースを使い、タブは混在させないでください。このガイドでは保守しやすい慣例として2文字分のインデントを使いますが、これはフィールド名の一部ではありません。同じ階層の項目は位置をそろえ、特にノード一覧の2つ目のノードと、1つ目のノードに属する追加パラメーターを区別してください。

mixed-port: 7890
mode: rule
allow-lan: false

proxy-groups:
  - name: PROXY
    type: select
    proxies:
      - DIRECT

rules:
  - DOMAIN-SUFFIX,example.com,DIRECT
  - MATCH,PROXY

ここでの proxy-groups はリストで、最初の項目には名前、種類、選択可能な出力先が含まれています。その中の proxies もリストです。トップレベルの proxies はプロキシノードの定義を表し、グループ内の同名フィールドは参照する出力先を指定します。意味は階層によって異なります。グループ内の参照をトップレベルに置くと、テキストを解析できても、型や参照のエラーにつながることがあります。

文字列、真偽値、キーの重複

ポートには通常整数を指定し、オン・オフの設定には true または false を使います。パスワード、ドメイン、ノード名などは文字列として扱います。シャープ記号やコロンの後のスペースなど、誤解を招きやすい文字を含む場合は、引用符で囲むのがおすすめです。シャープ記号は適切な位置にあるとコメントとして解釈され、引用符で囲んでいないパスワードが途中で切れることがあります。二重引用符ではエスケープ文字が処理されます。一般的なテキストには、バックスラッシュによる誤解を避けるため、単一引用符を使うとよいでしょう。

同じマッピング内で同一のキーを重複して定義しないでください。たとえばファイルの先頭に dns を記述し、末尾にも dns を追加しても、2つのブロックが必ずマージされるわけではありません。パーサーが重複キーを拒否する場合もあれば、一方の値だけを残す場合もあります。子項目を追加するときは、元のブロックを編集してください。リストは複数行でも角括弧形式でも記述できますが、トラブルの切り分けでは複数行のほうが所属関係を把握しやすくなります。

元ファイルと実行用ファイルの違い

デスクトップクライアントでは、サブスクリプションの元データ、編集用コピー、上書きルール、コアに渡す実行設定がそれぞれ存在することがあります。エディターで保存できても、そのファイルに書き込まれたことしかわかりません。実際に反映されるかは、クライアントがそのファイルを使っているか、後続の生成処理で変更が上書きされないかによって決まります。まず現在有効な設定名を確認し、実行設定やコアのログを調べてください。選択されていないコピーを編集し続けないよう注意しましょう。

mihomoをコマンドラインから実行する場合は、mihomo -t -f ./config.yaml で設定をテストできます。コマンド内の実行ファイル名とパスは、実際のインストール先に合わせてください。テストに成功すれば、主に構造や一部の参照が受け入れられたことを示します。リモートサーバーに接続できることや、すべてのルールが意図どおりに動くことを保証するものではありません。クライアント内蔵のテストとターミナルで使うコアが異なる場合もあるため、実際に読み込まれる設定を確認しましょう。

問題発生時に戻せる基準を用意しておきましょう。元ファイルを保管し、変更は一度に1つの機能ブロックに限定して、目的も記録します。エラーが出たら今回の変更を戻し、項目を1つずつ追加し直してください。DNS、TUN、ルールの順序を同時に変えると、接続失敗の原因を特定しにくくなります。初回のインポートが目的なら、まずサブスクリプションの追加手順に沿って動作を確認してから、設定を拡張しましょう。

02 · ポート、モード、共通設定

共通設定では、コアがどのように接続を受け付け、どこに入口を公開し、どのモードで出力先を選ぶかを指定します。トップレベルの設定であり、ファイルの前半や後半にあるかによって意味は変わりません。初めて変更する場合は、まず待ち受け範囲を最小限にし、ローカルアプリだけがプロキシを使える状態にしましょう。接続が正常に動作することを確認してから、LANアクセスやコントロールインターフェースなどを検討してください。有効にする機能が増えるほど、切り分け時に確認すべき範囲も広がります。

プロキシポートと待ち受けアドレス

port はHTTPプロキシ用、socks-port はSOCKS用の入口です。mixed-port では同じポートで両方のプロキシリクエストを受け付けます。一般的なデスクトップ環境では、まず混合ポートを1つ設定するとよいでしょう。ポート番号に決まった値はありません。ローカルで実際に空いているポートと、アプリに設定したプロキシアドレスを一致させてください。番号を変えても、古いアドレスが新しいポートに自動で切り替わるわけではありません。

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

上の例はローカルでの使用を想定しています。アプリにプロキシを手動設定する場合、アドレスには 127.0.0.1、ポートには対応する番号を指定できます。アドレスが使用中と表示されたら、2つ目のクライアントや別のコアプロセスが起動していないか確認してから、競合するプログラムを終了するかポートを変更してください。何度も再起動するだけではポートの競合は解消されず、複数のバックグラウンドプロセスを見分けにくくなることがあります。

allow-lan と bind-address はあわせて確認しましょう。前者はLANからのアクセスを許可するか、後者は待ち受けるアドレスを指定します。さらにOSのファイアウォールも影響します。LANアクセスを許可するだけで、ほかの端末から接続できるとは限りません。共有する場合は、適切な認証とアクセス範囲も設定し、信頼できるネットワーク内だけで使うプロキシの入口を公共ネットワークに公開しないようにしてください。

ルールモード、グローバルモード、DIRECTモード

mode: rule はルール一覧に従って出力先を決めます。グローバルモードではグローバルに選択された出力先を使い、DIRECTモードでは通常のプロキシルールによるリモートプロキシの選択を行いません。グローバルモードでも、端末のすべての通信が自動的に転送されるわけではありません。コアに入った接続だけが対象です。システムプロキシが設定されていない、アプリ個別のプロキシもない、TUNでも捕捉されていないプログラムの通信は、コアを経由しない場合があります。

クライアントのモード切り替えボタンからコントロールインターフェース経由で実行状態を変更しても、設定ファイルの mode は以前の値のままの場合があります。ファイルを変更した後も画面がグローバルモードを示している場合は、クライアントが前回の選択を復元していないか、別の設定項目が優先されていないか確認してください。ルールが適用されない原因を調べる前に、実際にルールモードで動いているか確認しましょう。誤った前提でルール一覧全体を変更するのを防げます。

ログ、コントロールインターフェース、状態の保持

log-level は通常 info を使い、詳細な調査が必要なときだけ一時的に debug に上げます。詳細なログにはアクセス先ドメイン、ノード名、ローカルアドレスが含まれることがあります。共有する前に機密情報を削除してください。コントロールインターフェースとプロキシポートは役割が異なります。前者はコアを管理し、後者はアプリの接続を中継します。管理ポートをブラウザーのHTTPプロキシ設定に入力しないでください。また、接続失敗を解決するために管理インターフェースの待ち受け範囲を広げないようにしましょう。

コントロールインターフェースが必要な場合は、待ち受け先をループバックアドレスに制限し、十分に強力な secret を設定してください。実際のキーは自分の端末だけに保存します。クライアントによっては、これらの項目を自動生成・管理します。手動で上書きすると、画面からコアに接続できなくなることがあります。クライアントの設定とコアのファイルの両方に関わる項目は、まずクライアントが提供する設定画面を使い、その後、実行設定で反映結果を確認してください。

状態の保存設定も、見えている結果に影響します。たとえばプロキシグループの選択状態を保存すると、設定を再読み込みした際にリストの先頭ではなく、以前選択したノードが復元される場合があります。反映状況を判断するには、実行モード、グループの現在の選択、接続履歴をあわせて確認してください。ファイルの先頭にある名前だけでは判断できません。ポート競合やシステムプロキシの設定残りなどはヘルプセンターもご覧ください。

03 · DNS、Fake-IP、名前解決の経路

DNS設定はドメイン名をIPアドレスに変換し、ルール判定に必要なドメイン情報をコアが保持できるかにも影響します。次の3点を分けて考えましょう。アプリがどこに問い合わせるか、問い合わせを受けたコアがどの上流DNSに転送するか、リモートノードへの接続時にノードのホスト名をどこで解決するかです。これらの経路は異なることがあります。ブラウザーでサイトのアドレスを解決できても、プロキシサーバーのホスト名も解決できるとは限りません。

基本項目と上流DNSの役割

dns.enable は内蔵DNSを有効にし、listen は待ち受けるアドレスとポートを指定します。待ち受けが成功しても、OSが自動的にその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
  default-nameserver:
    - 223.5.5.5
  nameserver:
    - https://dns.alidns.com/dns-query
  proxy-server-nameserver:
    - 223.5.5.5
  fake-ip-filter:
    - '*.lan'
    - '*.local'

nameserver は通常の名前解決に使う上流DNSです。一般的なDNSのほか、対応している暗号化DNSのアドレスも設定できます。暗号化DNSの上流自体がドメイン名を使う場合、コアは先にそのアドレスを解決する必要があります。このとき default-nameserver を初期解決に利用できます。初期解決用DNSの接続に、まだ確立していない同じ経路が必要なアドレスを指定すると、プロキシとDNSのどちらを先に確立するかという循環が起こりやすくなります。

proxy-server-nameserver はプロキシサーバーのホスト名解決に使い、ノードのアドレスと通常のWebサイトのアドレスを別々に扱うのに適しています。設定しても、使用するDNSサーバーに現在のネットワークから到達できる必要があります。ログにノードのホスト名を解決できないと表示された場合は、まずノードのドメイン名とこの項目の上流DNSを確認してください。Webサイトのドメイン用フィルターに項目を追加しても解決しません。名前解決の対象に応じて設定箇所も変わります。

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

Fake-IPモードでは、ドメイン名に予約済みアドレスを割り当て、コアがドメイン名とアドレスの対応を保持します。アプリがそのアドレスへ接続すると、コアは元のドメイン名を特定し、ルールに従って出力先を決めます。この予約アドレスはリモートサイトの実際のグローバルIPアドレスではありません。表示されても、サイトのDNS設定が誤って変更されたわけではありません。この仕組みを理解しておくと、正常なマッピングを名前解決の異常と誤認せずに済みます。

一方、redir-host はアプリに実際の名前解決結果を返す方式に近いものですが、ドメイン情報を完全に関連付けられるかは、接続がコアに入る経路やほかの識別方法にも左右されます。どの環境でも一方が優れているとは限りません。LAN内サービス、実アドレスを使った探索が必要なアプリ、特殊なネットワーク検出処理などは、実アドレスでの応答が必要な場合があります。すべての上流DNSを一律に変更せず、必要な箇所だけ調整してください。

フィルター、振り分け、トラブルの切り分け

フィルター項目は、原因が確認できた問題に対して追加しましょう。例にあるLAN用のサフィックスは一般的な方法の一つであり、すべてのネットワークに適するとは限りません。ルーターが独自の内部ドメインを使う場合は、その問い合わせに応答できるローカルDNSへ送る必要があります。内部ドメインをフィルターに加えても、パブリックDNSがそのレコードを認識するわけではありません。切り分けではフィルター結果と、実際に使われた上流DNSをあわせて確認してください。

ドメインごとに上流DNSを指定する場合は nameserver-policy、DNS通信にもルーティングルールを適用する場合は respect-rules とノードのホスト名解決設定を検討できます。これらは問い合わせ結果だけでなく、名前解決の通信経路を変えます。有効にする前に依存関係を整理してください。特に、プロキシ接続の確立に必要な名前解決が、まだ接続していないプロキシに依存しないよう注意しましょう。

DNSをテストするときは、「応答がない」「アドレスは返るが接続できない」「特定のアプリだけ失敗する」を区別します。1つ目は待ち受け、通信の取り込み、上流DNSへの到達性を確認します。2つ目はルール、出力先、IPv6を調べます。3つ目はアプリのキャッシュ、内蔵の暗号化DNS、システムDNSを迂回する経路を確認してください。マッピング方式を変更しても、既存の接続やキャッシュに古い結果が残る場合があります。テスト用の接続を作り直してから確認しましょう。

トップレベルの ipv6 と dns.ipv6 は別の設定です。前者はコア全体のIPv6動作、後者はDNSのIPv6応答処理に関わります。一方を無効にしても、システムのIPv6通信すべてが適切に処理されるわけではありません。予約アドレスのマッピングやフィルターの範囲についてはFake-IPモードの解説もご覧いただき、実際のネットワークに合わせて設定してください。

04 · プロキシノードの項目とプロバイダー

プロキシノードの定義では、コアがリモートサーバーへ接続する方法を指定します。プロキシグループとは役割が異なり、ノードにはプロトコル、サーバー、認証情報を設定し、グループでは出力先をまとめて選択します。構文テストに通ったノードでも、認証情報の不一致、サーバーへの接続不可、通信パラメーターの誤りなどで接続できないことがあります。まず単一ノードで動作を確認してから複雑なプロキシグループに追加すると、選択ロジックが判断の妨げになりません。

名前、プロトコル、サーバーの項目

一般的な共通項目は name、type、server、port です。名前はグループやルールから参照するため、一意で識別しやすいものをおすすめします。プロトコルの種類はサーバー側と一致させてください。サーバーにはアドレスまたはドメイン名を指定し、ポートにはリモートサービスが実際に待ち受ける番号を指定します。ローカルの混合プロキシポートとリモートノードのポートは別のものです。数値が違うという理由だけで無理にそろえる必要はありません。

proxies:
  - name: SS-DEMO
    type: ss
    server: proxy.example.com
    port: 443
    cipher: aes-128-gcm
    password: 'your-password'
    udp: true

これは設定項目の形式を示す例であり、ドメイン名とパスワードは説明用の仮値です。リモート接続には使用できません。実際の項目は利用権限のあるサーバーの設定を確認してください。Webページにアクセスできてもプロキシポートが使えるとは限りません。また、HTTPSでよく使われるポートだからといって、TLSを勝手に追加しないでください。暗号化方式、パスワード、プロトコルの種類は一組で一致させる必要があり、どれか1つの誤りでもタイムアウトやハンドシェイク失敗につながります。

対応する項目は、クライアント名だけでなく実際に動いているコアによって決まります。同じクライアントでもビルドが異なれば、利用できるコアの機能が違う場合があります。古い設定にあるプロトコルが新しい例と互換性を持つとも限りません。未対応のプロトコルや項目が見つかったら、設定を変更する前に実行中のコアとそのドキュメントを確認してください。各系統の違いはmihomoとオリジナル版の機能比較をご覧ください。

TLS、トランスポート層、UDP

TLSを使うプロトコルでは、サーバーアドレス、証明書の検証名、トランスポート層のホスト項目がそれぞれ異なる役割を持つことがあります。servername は通常TLSハンドシェイク時の名前に関係し、WebSocketのパスやリクエストヘッダーはトランスポート層の設定です。サブスクリプション内のドメイン名をすべて同じ値に置き換えたり、項目が重複しているように見えるという理由だけで削除したりしないでください。サーバー側の実際の設定と照らし合わせて確認しましょう。

証明書検証の無効化を、一般的な解決策として使わないでください。証明書エラーが出たら、まず端末の時刻、サーバー名、証明書の有効性、接続先ポートが正しいかを確認します。検証を無効にすると安全性が損なわれ、接続先サーバーや設定の不一致を一時的に見えにくくすることもあります。具体的なテスト環境とリスクを理解している場合に限って検討し、通常の設定では適切な検証を維持してください。

udp: true はそのノードで対応するUDPリクエストを処理できるようにしますが、サーバー、プロトコルの実装、ネットワーク経路全体でUDPが使えることを保証するものではありません。HTTPプロキシを経由した通常のブラウザー通信では、UDPのテストになりません。通話、ゲーム、一部のDNSリクエストに問題がある場合は、アプリがどの経路でコアに接続するか、ノードが必要な通信に対応するか、サーバーのファイアウォールで許可されているかを確認しましょう。スイッチがオンかどうかだけでは判断できません。

プロキシプロバイダーとヘルスチェック

proxy-providers を使うと、ノード一覧をメイン設定から分離できます。ファイルプロバイダーはローカルファイルを、HTTPプロバイダーは指定したアドレスから内容を取得します。メイン設定のプロキシグループから use で参照します。ノード更新時にルール全体を編集せずに済みますが、プロバイダーファイルには独自の構造要件があります。モード、ルール、DNSを含む完全なサブスクリプションを、どの形式のプロバイダーとしてもそのまま使えるわけではありません。

proxy-providers:
  local-nodes:
    type: file
    path: ./providers/local-nodes.yaml

proxy-groups:
  - name: PROXY
    type: select
    use:
      - local-nodes

上の例は実在するローカルファイルを前提としており、その内容には proxies のリストと有効なノードが必要です。相対パスはコアの作業ディレクトリを基準に解決され、エディターで現在開いているファイルの場所とは限りません。ログにファイルが見つからないと表示されたら、まずクライアントの作業ディレクトリとアクセス権を確認し、その後でパスを調整してください。パスの問題を覆い隠すために、すべてのノードを手動でメイン設定にコピーする必要はありません。

ヘルスチェックでは、選択した出力先からアクセスできるテスト用アドレスが必要です。測定結果が示すのはその経路からテスト先への状態であり、インターネット全体の通信品質を保証するものではありません。チェックに失敗する原因には、テスト先の制限、DNS、タイムアウト、ノードの問題などがあります。サブスクリプションのURLにはアクセス情報が含まれることも多いため、完全なリンクを公開ログやスクリーンショットに貼らないでください。設定を共有する前に構造は維持しつつ、パスワード、サブスクリプションのパラメーター、個人を特定できる情報を置き換えましょう。

05 · プロキシグループ、参照、選択状態

プロキシグループは複数の出力先をまとめ、ルールから参照できる名前を付けます。ルールから接続を渡された後、グループは現在の選択やテスト結果に従って実際のノードを決めます。PROXYという名前でも、必ずリモートプロキシを経由するとは限りません。一般的なカスタムグループ名のDIRECTを、組み込みの直接接続出力先と混同しないでください。名前の字面ではなく、参照関係から動作を判断しましょう。

手動選択と参照先の確認

select は利用者が出力先を手動で選択するグループです。グループ内の proxies には、定義済みノード、ほかのグループ、対応する組み込み出力先を指定できます。use はプロバイダーを参照します。名前は完全に一致させてください。空白、大文字・小文字、日本語の句読点にも注意が必要です。ノード名を変更する場合は、すべての参照箇所も確認しましょう。設定の構文が正しくても、コアが参照先を見つけられないエラーが起きることがあります。

proxy-groups:
  - name: PROXY
    type: select
    proxies:
      - DIRECT

  - name: MEDIA
    type: select
    proxies:
      - PROXY
      - DIRECT

rules:
  - DOMAIN-SUFFIX,example.com,MEDIA
  - MATCH,PROXY

この例はDIRECTとグループ間の参照だけを使った構造例で、実際のプロキシノードは含みません。サンプルのドメインへの接続は、まずMEDIAへ渡されます。MEDIAでPROXYを選択している場合は、さらにPROXYで現在選択されている出力先が使われます。グループを階層化することはできますが、循環参照は避けてください。たとえばAグループがBグループを参照し、BグループがAグループを参照すると、出力先の決定ができません。いわゆる相互の予備経路として使うことはできません。

自動テストとフェイルオーバー

url-test はテスト結果に応じて出力先を選ぶため、自動選択によく使われます。fallback は候補を順に確認し、利用可能なものを探す方式です。load-balance は対応する方式に従って接続を振り分けます。これらは同じ意味の書き方ではありません。優先順位を安定させたい場合は、テスト結果を頻繁に追うよりフェイルオーバーグループのほうが動作を把握しやすいでしょう。業務の出力先を手動で固定したい場合は、外側に選択グループを置く方法もあります。

自動選択グループでは、テスト用アドレスや確認間隔などを設定することがよくあります。アドレスはネットワーク環境に合わせて選び、安定した応答が得られることを確認してください。テスト結果が示すのはそのアドレスまでの経路であり、すべての通信の速度ランキングではありません。テストサイトへの接続が速いノードでも、長時間の接続、動画配信、ほかの宛先には適さない場合があります。自動テストの結果だけでなく、実際の用途での使い勝手もあわせて判断しましょう。

確認間隔は短ければよいというものではありません。間隔を短くするとリクエストや端末の復帰が増えるため、特にモバイル端末ではバックグラウンド動作の制限も考慮してください。確認の仕組みによっては、必要なときだけテストします。長く使われていないグループは、結果が更新されていない可能性があります。古い状態が表示されたら、ノードの異常と判断する前に、そのグループでテストが実行されたかを確認しましょう。

選択状態の保存と用途別グループ

動画配信、開発ツールなど用途ごとにグループを作り、それぞれ異なるルールから参照できます。これにより「どのリクエストを分類するか」と「その用途にどの出力先を使うか」を分けられ、ノードを変更してもドメインルール全体を書き直す必要がありません。グループを細かく分けすぎると、選択状態の管理が増え、接続の切り分けでも多くの参照階層を確認することになり、かえって構造がわかりにくくなります。

profile:
  store-selected: true

選択状態を保存すると、再起動や再読み込み後に以前の状態が復元されることがあります。ノードの順序を変えても現在の選択は変わらない場合があり、グループ名を変更すると保存済みの状態が対応しなくなることもあります。新しい既定順を試す場合は、保存された状態とクライアント側に別途選択が記録されていないかを確認してください。ノードを先頭に移動するだけで、インストール済みのすべてのクライアントが次回そのノードを使うとは限りません。

プロキシグループの表示に問題がある場合は、名前の定義、参照元、候補一覧、現在の選択の順に確認しましょう。プロバイダーの読み込みが終わっていないと候補一覧が不完全になることがあり、フィルター条件が厳しすぎるとノードがすべて除外される場合もあります。グループが空なら、まずプロバイダーの更新ログとフィルター式を確認してください。エラーの原因を残したまま、ルールの参照先を別のグループに変えて回避しないようにしましょう。

「現在選択されている」と「現在接続できる」は別です。手動選択グループには使えなくなったノードが残ることがあり、自動選択グループもすべての候補が利用できないと正常に接続できません。グループ構造に問題がないことを確認したら、単一ノードの接続ログに戻り、サーバー、プロトコル、DNSを調べましょう。クライアント画面の違いについては選び方ガイドも参考に、自分に合った設定管理方法を選んでください。

06 · ルールの書き方、優先順位、ルールセット

ルールモードでは、ルール一覧を上から順に評価し、通常は最初に一致したルールの出力先が使われます。複数の一致結果を集計するわけではなく、後により具体的なルールがあっても、自動的に戻って選び直すことはありません。設定を読むときは、まず順序を確認してから各ルールの式を見ましょう。最も広い条件を先頭に置くと、後続のルールの多くが機能しなくなります。

ドメイン、IPアドレス、最後のフォールバック

DOMAIN は指定したドメインと一致し、DOMAIN-SUFFIX はドメインとそのサブドメインに一致します。DOMAIN-KEYWORD は指定したキーワードで判定します。広く一致するキーワードより、サフィックス指定のほうが通常は対象範囲を制御しやすくなります。ドメインルールが照合するのはホスト名であり、ページの完全なURLではありません。ドメイン項目にプロトコル、パス、クエリパラメーターを入れると、正しいURLをコピーしたように見えても一致しません。

rules:
  - DOMAIN,router.example.com,DIRECT
  - DOMAIN-SUFFIX,example.com,PROXY
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
  - MATCH,PROXY

この例では、完全一致するドメインのDIRECTルールがサフィックス指定のプロキシルールより前にあるため、例外として適用されます。LANのアドレス範囲は実際のネットワークに合わせて追加してください。この例はすべての範囲を網羅しておらず、ネットワーク境界を設計するものでもありません。MATCH には照合内容を指定せず、残りの接続に対する最後のルールとして使います。その後ろに指定するのは出力先の名前です。その名前が存在しないと、最後の判定も正常に行えません。

ドメイン名を対象とする場合、IPアドレス用のルールは判定のために名前解決が必要になることがあります。no-resolve は、そのIPアドレスルールのためだけにドメイン名を解決する処理を避ける設定です。すべてのDNSを無効にするわけでも、接続で一度も名前解決が行われていないことを保証するものでもありません。接続先がすでにIPアドレスなら、そのままアドレスで照合できます。デバッグではログにあるドメイン名と接続先アドレスを照らし、コアがどの情報を受け取ったか確認しましょう。

プロセスルールとコアへの通信経路

一部の環境ではプロセス名やパスで照合できますが、プロセス情報を取得できるかはOS、権限、通信の取り込み方法によって異なります。ほかの端末からLAN経由で来た接続は、通常、ローカルの接続のように相手側アプリのプロセスと関連付けられません。ルールが一致しない場合は、まずプロセスを識別できる条件がそろっているか確認してください。メタデータが取得できていない状態を補おうとして、似たプロセス名のルールを増やし続けないようにしましょう。

コアに入っていない接続は、ルールでは処理できません。システムプロキシを無視するプログラムの場合、プロセス名を正確に指定しても照合される機会がないことがあります。まず接続ログにリクエストが記録されているか確認してください。記録がなければアプリのプロキシ設定やTUNによる取り込み経路を調べます。記録があり、出力先が違う場合は、現在のモード、ルールの順序、ドメイン情報を確認しましょう。こうすることで通信の入口の問題とルール式の問題を切り分けられます。

ルールプロバイダーと形式の対応

rule-providers を使うと、ルールを独立したファイルやリモートリソースに分け、メインのルール一覧から RULE-SET で参照できます。behavior はドメイン、アドレス範囲、クラシックルールなどの内容の種類を示します。format はファイルの形式を指定します。どちらも実際のリソースに合わせてください。拡張子だけを見て、一般的なWebページ、完全な設定ファイル、ルール一覧を互換性のあるものとして扱うことはできません。

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

rules:
  - RULE-SET,local-domains,DIRECT
  - MATCH,PROXY

対応するドメインルールファイルは、下記のような構造にできます。正しく読み込めるかはファイルの内容とメイン設定のプロバイダー定義の両方で決まります。メインファイルだけを確認してリソースの内容を見ないと、形式の不一致を見落としやすくなります。ファイルのパスもコアの作業ディレクトリを基準にします。初めて使うときは、リソースが存在し、読み取り可能で、読み込み済みであることを確認してから、ドメインが一致するかテストしてください。

payload:
  - '+.example.com'
  - 'router.example.net'

サブスクリプションの更新とルールセットの更新は別々の処理です。ノードが更新されても、ルールリソースの更新が成功したとは限りません。古いキャッシュが使われ続けることもあります。一部のWebサイトだけ振り分けがおかしい場合は、該当するプロバイダーの読み込みログを確認し、具体的なドメインで一致結果を追跡してください。キーワードの対象範囲をむやみに広げてリソースの問題を回避すると、気づきにくい誤一致が発生します。

最終確認には新しい接続を使いましょう。既存の長時間接続は元の出力先を維持することがあり、ブラウザーの接続再利用によってルールの変更が反映されていないように見える場合があります。テストするドメインを決め、関連する古い接続を閉じてから再アクセスし、適用されたルール、プロキシグループ、最終ノードを確認してください。ログの見方は実行ログからの原因特定をご覧ください。

07 · TUN、ルーティング、通信の取り込み範囲

TUNは仮想ネットワークインターフェースを使い、ルーティング条件に一致した通信をコアへ送ります。システムプロキシに従わないアプリにも対応できます。TUNとルールモードは異なる階層の機能です。TUNは通信をどう取り込むか、ルールは取り込んだ通信をどこへ送るかを決めます。TUNを有効にしても、すべての通信がリモートプロキシを経由するわけではありません。ルールに従ってLAN内の通信や特定の用途をDIRECTにしたり、特定の接続を拒否したりできます。

基本構成と権限

デスクトップOSでは、通常、管理者権限、サービスモード、または適切なネットワーク権限が必要です。モバイルOSでは、プラットフォームが提供するVPNインターフェースを通じて通信を取り込みます。GUIでの切り替え機能やサービスの自動インストールの有無は、プラットフォームごとに異なります。有効化に失敗した場合は、まず仮想インターフェースと権限に関するログを確認してください。画面上のスイッチがオンでも、通信がTUNに入っているとは限りません。

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

これは一般的な項目の組み合わせであり、すべての端末でそのまま使える設定ではありません。auto-route は関連するルートを自動設定し、auto-detect-interface は出力インターフェースの選択を補助します。複数のネットワークアダプター、リモートデスクトップ、コンテナー、ほかのトンネルが同時に動いている場合、自動選択が期待どおりにならないことがあります。ルーティングを変更する前に、復旧方法を確保してください。特に、唯一のリモート接続で未検証の通信取り込み設定を直接試さないでください。

ネットワークスタック、DNSハイジャック、実際の動作

stack では、コアの対応状況に応じて system、gvisor、mixed などを選べます。OSとの互換性、処理方法、リソース使用量はそれぞれ異なります。mixed は複合的な処理方式を使うもので、「新しいほど速い」という意味ではありません。まずはクライアントの推奨値を使い、互換性の問題を確認してから調整してください。スタック、ルーティング、DNSモードを同時に変更すると、比較が難しくなります。

dns-hijack は、対象となる従来型DNSリクエストをコアのDNS処理に転送します。例にあるポート指定で、あらゆる暗号化DNSを識別してリダイレクトできるわけではありません。HTTPSで送信されるアプリのDNS問い合わせは通常のWeb通信と同じ入口を使うため、従来型DNSのポートだけで処理することはできません。ブラウザー独自の名前解決機能によって、ドメイン情報の見え方が変わる場合もあります。テストではアプリがどの経路で名前解決するかを確認してください。

TUNを有効にした後も、内蔵DNSが正しく動作する必要があります。DNSリクエストを取り込んでも利用できる上流DNSがなければ、多くのアプリで名前解決が終わるまで待たされます。想定した経路を迂回していれば、一部のドメインルールに必要な情報が届かないことがあります。切り分けは仮想インターフェース、ルーティング、DNS、ノード、ルールの順に行い、Fake-IPと実アドレスのモードを何度も切り替えるだけで済ませないでください。

LAN、ほかのトンネル、トラブルの切り分け

LANへのアクセスにはルーティングとルールの両方が影響します。プライベートネットワーク向けにDIRECTルールを追加しても、コアに入った接続の出力先が決まるだけであり、すべてのシステムルートの競合が解消されるとは限りません。TUNを有効にしてプリンター、共有フォルダー、社内管理ページにアクセスできなくなった場合は、有効化前後のルート、接続先アドレス、接続ログを比較してください。すべての通信を許可するのではなく、必要なルート除外を検討しましょう。

企業VPNや別のネットワークトンネルと併用すると、デフォルトルート、DNS、インターフェースの優先順位が互いに影響することがあります。原因を切り分けるには、まず通信を取り込むツールを1つだけ有効にし、名前解決と接続先へのアクセスを個別に確認します。単独で正常に動作することを確かめてから、ルートの分割方法を検討してください。すべてのインターフェースを除外したり、一括で取り込んだりする極端な設定は、コア自身の外部接続を妨げることがあります。

TUNを無効にした後もネットワークに問題が残る場合は、クライアントがインターフェース、ルート、システムプロキシを正常に解除したか確認し、ほかのネットワークツールが動作していないかも調べてください。まずクライアント内の該当設定を元に戻して正常に終了します。内容がわからないシステムルートを直接削除するのは避けましょう。有効化手順、権限、ネットワークスタックについてはTUNモードの設定ガイドをご覧ください。

08 · 上書き、マージ、設定の検証

サブスクリプションの設定は定期的に更新したい一方、ローカルのポート、DNS、個人用の振り分けルールは維持したいことがあります。上書き機能では、元の設定とは別に変更内容を保存し、クライアントが実行設定を生成します。これはYAMLに共通する標準機能ではありません。マージ順、リストの処理方法、スクリプト機能はクライアントごとに異なる場合があります。画面上のボタン名を覚えるより、最終的に生成された設定を確認することが重要です。

置き換え、再帰的マージ、追加の違い

mixed-port の変更など、単一のスカラー値を上書きする方法は比較的わかりやすいでしょう。マッピングは再帰的にマージされる場合も、全体が置き換わる場合もあります。リストの挙動はさらに異なり、元のリストを上書きする、末尾に追加する、専用機能で先頭に挿入するなどの方法があります。両方のファイルに rules があるからといって、クライアントがすべてのルールを自動で保持するとは限りません。

# 上書きの例：具体的なマージ方法はクライアントによって異なります
mixed-port: 7890

dns:
  enable: true
  enhanced-mode: fake-ip

profile:
  store-selected: true

クライアントが dns ブロック全体を置き換える場合、上の例ではサブスクリプションに含まれていた上流DNSが失われることがあります。再帰的にマージする場合は、例にない子項目が保持される可能性があります。このテキストだけでは結果を判断できません。保存後に実行設定を開き、上流DNS、待ち受け、フィルター一覧がそろっているか確認してから、名前解決をテストしてください。マージ方法が不明な場合は、元に戻せるテスト用コピーで先に検証しましょう。

ルールの配置とサブスクリプション更新

個別の例外ルールは通常、広い範囲に一致するルールより前、特に最後のフォールバックより前に置く必要があります。クライアントが既存の MATCH の後に新しいルールを追加するだけの場合、設定ファイルにルールが存在しても、ほとんど照合されません。設定画面にある「先頭に追加」「末尾に追加」「置き換え」は使い分け、意図する優先順位に合わせて選択してください。

サブスクリプションの元ファイルを直接編集すると、次回の更新で変更が上書きされることがあります。ノードの参照元、用途別ルール、ローカル環境の設定を分けて管理し、クライアントが明示的に対応する上書き機能や設定の組み合わせを使うほうが安全です。必要な機能がクライアントにない場合は、手動で管理するコストを考慮したうえで、別の設定ファイルとして保存しましょう。自動更新に依存しながら手動変更がずっと保持されると考えるのは避けてください。

ノード名やプロキシグループ名の変更も、更新時のリスクになります。個人用ルールがサブスクリプション内のグループ名を参照している場合、更新後にその名前が変わると、個人用ルールに変更がなくても機能しなくなります。自分で管理する安定した用途別グループを使い、更新されるノードをそこから参照する方法がおすすめです。更新後はクライアントに成功と表示されただけでなく、カスタムルールの出力先がすべて残っているか確認してください。

実行設定を使って検証する

検証は4段階で行います。ファイルを解析できるか、参照先を解決できるか、外部リソースを読み込めるか、接続が意図どおり動くかです。最初の2段階は設定テスト、3段階目はプロバイダーとノードに関するログ、最後の段階は実際のリクエストと接続記録で確認できます。どれか一つに成功しても、ほかの段階の確認にはなりません。テストコマンドが成功しても、サーバーの認証情報が有効であることや、ルールが意図した出力先を選ぶことは保証されません。

mihomo -t -f ./config.yaml

クライアントが生成した実行ファイルは、できるだけクライアントが実際に使うコアでテストしてください。別途インストールしたコマンドラインツールでは、対応する項目が異なり、ローカルのテスト結果と画面の動作が一致しない場合があります。実行ファイルには、自動生成されたコントロールアドレス、インターフェース名、キャッシュ用パスが含まれることもあります。区別せずに別の端末へコピーしないでください。移行時は必要な設定だけを移し、新しい環境で再生成しましょう。

変更履歴と安全な共有

変更のたびに、変更理由、変更した階層、有効性の確認方法を記録しましょう。説明のないコピーを大量に残すより、復元できる旧設定を保管するほうが役立ちます。問題が起きたら、まず直近の正常な状態に戻し、変更を1つずつやり直してください。クライアントの更新とルールの変更を同時に行った場合は、コアの違いと設定ミスを混同しないよう、別々に検証しましょう。

サポートを依頼する際は、エラーが起きた時刻、必要な部分だけに絞った設定例、実際の実行モード、再現手順を伝えてください。サブスクリプション情報、パスワード、管理用キーは必ず置き換えましょう。公開するスクリーンショットでは、ノードのメモ、内部ネットワークのアドレス、アクセス履歴も確認してください。インストール、設定の読み込み、接続までの流れを確認するには使い方ガイドへ。よくあるエラーの種類を調べるにはヘルプセンターをご覧ください。問題が起きるたびに設定ファイル全体を書き直す必要はありません。