設定項目config.yaml

mihomo 設定項目リファレンス

まずは設定をインポートして接続を有効にし、入門ガイドの手順で動作を確認しましょう。接続できていて、特定のキーをどの階層に置くか知りたい場合や、サブスクリプション更新後に独自ルールを戻したい場合は、このリファレンスを確認してください。例は単体で起動できる DIRECT の最小設定から始まります。以降の設定例は、各章に沿って置き換えるか追加してください。同じトップレベルキーを複数まとめて貼り付けないようにしましょう。

YAML の構造と最小構成

マッピング・シーケンス・スカラーを見分ける

設定ファイルのトップレベルは項目の一覧です。コロンの左側がキー、右側には値か、さらに下の階層の構造が入ります。ポート番号、モード名、真偽値のスイッチは単一の値です。dns はマッピング、proxies、proxy-groups、rules は順序を持つシーケンスです。ノードの各要素はマッピングですが、ルールの各要素は通常、1 行の文字列です。ノードもルールもハイフンで始まるからといって、ノードの属性を別々のリスト項目として書かないでください。YAML としては有効でも、コアが期待する構造とは異なる場合があります。

インデントにはスペースを使い、階層ごとに 2 つ空けると揃えやすくなります。タブは使わないでください。コロンの後の空白と、引用符で囲まれた値の中にあるコロンを区別しましょう。値に「: 」を含む名前を使う場合は、値全体を引用符で囲みます。そうしないと、パーサーが別のキーと値の組み合わせと誤認することがあります。コメントは、引用符で囲まれておらず、区切りとなる空白の後にある # から始まります。名前に # が含まれる場合や先頭にゼロがある場合は、値を引用符で囲みましょう。一方、ポートは整数、スイッチは true または false のままにします。すべての値を機械的に文字列に変えないでください。

単体で動作する DIRECT の最小構成

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

proxies: []
proxy-groups:
  - name: LOCAL
    type: select
    proxies:
      - DIRECT
rules:
  - MATCH,LOCAL

この最小構成は、サブスクリプション、Geo データベース、リモートルールに依存しません。リクエストはローカルの混合ポートに入り、最後のルールで LOCAL に送られます。グループ内の出力先は DIRECT のみです。ここでいう DIRECT もローカルコアを経由しますが、外部プロキシには接続しません。まずこの構成で、リモートサービス、認証情報、速度測定用 URL の影響を切り分けられます。これすら起動しない場合は、実行ディレクトリ、設定ファイルのアクセス権、ポートの使用状況を確認してください。より長いサブスクリプションに替えるだけでは、問題の範囲が広がるだけです。

トップレベルキーの記述位置は、実行順序を表すものではありません。rules をファイルの先頭に移しても、ルールがノードより先に初期化されるわけではありません。順序が依存するのはリストの内部です。たとえばルールは上から順に評価され、手動選択グループのメンバーはリスト順に表示されます。参照は位置ではなく名前で行われます。例では、LOCAL の名前がルールとグループ定義で完全に一致している必要があります。編集時はエディターでこの名前を検索し、参照箇所をすべて確認してから一括で変更しましょう。表示名だけを変更して参照元を直さないと、設定内の参照が切れてしまいます。

空値・重複キー・エラー行番号

proxies: [] は空のリストを明示します。proxies: とだけ書き、子項目を付けない場合は、通常は空値として解析されます。空値、空リスト、キー自体の省略は同じ意味ではありません。上書き時には特に違いが表れます。ファイル末尾にもう一つ rules: を追加して、前のリストに行を足そうとしないでください。パーサーによっては重複キーを拒否し、別の実装ではどちらか一方だけが残ることがあります。リストを拡張する場合は、元のキーの下に項目を追加するか、クライアントのリストマージ機能を使って明示的に追加しましょう。

トラブルシューティングは最初のエラーから始めます。ある行でコロンが見つからないと表示された場合、直前の行で引用符が閉じていない、または前のブロックのインデントが不足している可能性があります。エラー行の前後数行を確認してください。構文解析が通った後も、コアはノードの種類、参照先の名前、各項目の内容を検証します。エディターで色分け表示されるからといって、コアが読み込めるとは限りません。読み込みに成功しても、通信がプロキシを経由しているとは限りません。動作する設定を一つ保存し、その後は一度に一つの項目ブロックだけを変更すると、「構造の記述ミス」と「構造は正しいが通信経路が通らない」を切り分けやすくなります。

ダウンロードしたものがサブスクリプション URL、エンコード済みテキスト、またはクライアント専用の共有リンクなら、まずインポート画面で種類を確認してください。拡張子を変えただけでコアに渡してはいけません。別のよくある形式として、payload だけ、またはノードリストだけを含むファイルがあります。これは他の項目から参照するリソースであり、完全な設定ではありません。ファイル冒頭の構造を確認してから、クライアントで新しい設定を追加するのか、サブテーブルを置き換えるのか、プロバイダーのソースにするのかを決めましょう。画面上の設定名はディスク上のファイルパスではありません。トラブルシューティングでは、編集しているファイルが正しいか確認してください。

共通項目:リスニングポートと実行モード

入口を決めてから、出力先を選ぶ

リスニングポートはアプリがリクエストを送る入口を決め、実行モードはコアが受け取ったリクエストをどこへ送るかを決めます。別々の設定です。よく使われる mixed-port は HTTP プロキシと SOCKS の両方を受け付けるため、ローカルアプリの入口を一つにまとめたい場合に便利です。port は HTTP プロキシ専用、socks-port は SOCKS 専用の入口です。呼び出し方法を分けたい場合に使いましょう。二つのリスナーに同じポートを指定すれば自動的に共有される、というわけではありません。クライアントがコアのポートを割り当てる場合は、起動ログと画面に表示される実際の値を確認してください。

項目役割確認のポイント
mixed-portHTTP と SOCKS 共通の受け付け口ポートが空いていることを確認し、アプリ側の設定を実際のリスナーアドレスに合わせる
allow-lan他の LAN 端末からプロキシ入口を利用できるようにするか同じ端末内で使う場合は無効のままにする
modeルール・グローバル・DIRECT モードを選択ルールの確認時はまず rule に戻す
log-levelログの詳細度を調整通常は info を使い、調査中だけ一時的に詳細度を上げる
external-controllerアプリのプロキシ入口ではなく、コントロール API必要な場合のみ有効にし、信頼できる範囲からのアクセスに限定する

ローカルアプリには通常、ループバックアドレス 127.0.0.1 と混合ポートを指定します。コントロール API のアドレスをシステムプロキシに設定しないでください。どちらもローカルポートで待ち受けることがありますが、役割はまったく異なります。コントロール API からは実行状態の取得や設定変更ができるため、外部に公開しないでください。ローカルでのみ使う場合はループバックアドレスにバインドし、アクセス認証情報はクライアントの方法に従って管理しましょう。他の端末からローカルプロキシを使う場合は、allow-lan、リスニングアドレス、ファイアウォール、アクセス制御をそれぞれ確認してください。この端末から接続できても、同じネットワーク上の他の端末から接続できるとは限りません。

3 つのモードと画面上の状態

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

rule はルールの順に出力先を判定します。global はグローバルポリシーで選択した出力先を使い、カスタムルールによる振り分けは行いません。direct はコアが受け付けたリクエストを直接送信します。DIRECT に切り替えてもクライアントを終了したことにはなりません。システムプロキシや仮想 NIC が引き続き通信を受け取る場合があります。グローバルまたは DIRECT で調査する際は、元のモードと選択内容を記録し、確認後に戻してください。それぞれの経路の違いは、ルール・グローバル・DIRECT モードの解説で具体例とともに確認できます。

設定ファイルの mode はファイル内の値であり、画面上の現在の状態と一致するとは限りません。クライアントが起動後に前回の選択を復元したり、中間設定を生成してからコアに渡したりすることがあります。ファイルを編集してもグローバルのままなら、編集したファイルが読み込まれているか確認し、画面上でもグローバルが選択されていないか確認しましょう。逆に、画面上で一時的にモードを切り替えても、元のファイルに反映されるとは限りません。サブスクリプション更新後や再起動後も変更を維持するには、実行時の状態だけでなく、クライアントが提供する永続化の設定箇所を探してください。

ポートの待ち受けに成功しても、システムの通信がすでに経由しているとは限らない

システムプロキシは、アプリがシステム設定を参照する仕組みです。ブラウザーなど、プロキシに対応したプログラムで使うのに適しています。仮想 NIC モードは、システムのルーティングを通じて対象の通信を受け取ります。クライアントのスイッチだけでなく、権限、ルートの競合、名前解決も考慮が必要です。両方を有効にすれば必ず広い範囲をカバーできるわけではありません。特定のアプリが通信できない場合は、まず一方だけを有効にし、入口・宛先・結果を記録してから、もう一方と比較してください。仕組みの違いはTUN とシステムプロキシの比較を参照してください。

デバイスによって通信を許可する方法は異なります。デスクトップのシステムプロキシ設定を、そのままスマートフォンに適用する必要はありません。初めてインストールする場合は、ダウンロードページでプラットフォームに合ったパッケージを選んでください。GUI から使い始めるなら、まず Clash Plus を試し、具体的な選択肢はクライアントが実際に対応している機能に合わせましょう。ポートが使用中でも、正体のわからないプロセスをすぐ終了しないでください。別のクライアントや古いコアが動いていないか確認しましょう。新しい設定でポートを変更した場合は、ブラウザー、ターミナル、システムに残っている古いポートの設定も更新してください。

一つのアプリだけを検証するなら、システム全体の設定を直接変えるより、そのアプリに混合ポートを指定するほうが元に戻しやすくなります。これでコアの入口からルール、出力先までの経路を確認できます。成功したらシステムの通信を経由させ、結果が異なる場合はアプリの設定かシステムルートに原因を絞り込みましょう。ログの詳細度を一時的に上げる場合は、対象を一つ決めてリクエストを再実行してください。入口、宛先、出力先を確認したら通常の詳細度に戻します。多数のリクエストを並行させると、必要なログが後ろに埋もれてしまいます。

DNS:上流サーバー・ドメイン別ポリシー・拡張モード

名前解決と接続リクエストを分けて考える

名前解決は「この名前に対応するアドレスは何か」、接続ルールは「今回のアクセスをどの出力先に送るか」を決めます。アクセス時に互いに影響しますが、同じ設定ではありません。dns.enable はコアの DNS モジュールを有効にしますが、これだけでシステム上のすべての名前解決を引き受けるわけではありません。ブラウザー独自の暗号化 DNS、システムキャッシュ、クライアントで設定した DNS ハイジャックによって、リクエスト経路が変わることがあります。トラブルシューティングでは、まず誰が名前解決を行い、どこに問い合わせ、コアがドメイン名と解決済みアドレスのどちらを受け取っているかを確認してください。

dns:
  enable: true
  enhanced-mode: redir-host
  default-nameserver:
    - 1.1.1.1
  nameserver:
    - https://dns.google/dns-query
  nameserver-policy:
    '+.example.org':
      - 1.1.1.1

この例では暗号化された上流 DNS を一般的なドメインに使い、example.org とそのサブドメインは別のリゾルバーに渡します。default-nameserver は DNS 上流サーバー自身のホスト名を解決するための設定で、通常は IP アドレスで指定します。一般ドメインの名前解決に失敗した際の汎用フォールバックではありません。実行環境から例示したパブリック DNS サービスに接続できない場合は、現在のネットワークから到達できる上流サーバーに変更して試してください。ポリシーが適用されたか確認するには、対象範囲に含まれるリクエストと含まれないリクエストを一つずつ比較します。

クライアント内蔵の DNS と、システムの「優先 DNS」は同じ設定ではありません。特定のアプリからコアの DNS リスナーに直接問い合わせたい場合は、別途 dns.listen を設定し、アプリ側でも実際にそのアドレスへ問い合わせるようにします。リスナーを設定しただけで、システムの問い合わせが自動的に転送されるわけではありません。共有ネットワークでは特に、手軽だからといってリスニングアドレスをすべてのインターフェースに設定しないでください。調査では、まず指定したリゾルバーに直接問い合わせ、その後、元のアプリからアクセスを再現します。二つの入口の結果を同じテストのものとして混同しないようにしましょう。

redir-host と fake-ip の選び方

redir-host は実際のアドレスを返すため、互換性の問題を調査する際の出発点として適しています。fake-ip は処理対象のドメインに合成アドレスを割り当てます。コアはそのアドレスへの接続を受け取ると、対応表からドメイン名を復元し、ルールに沿って処理できます。合成アドレスは接続先サーバーのグローバル IP アドレスではありません。静的ホストテーブルにコピーしたり、リモートサービスのアドレスが変わったかどうかの判断に使ったりしないでください。アプリが適切な経路を通らない場合や、対応表を持たない別の端末に合成アドレスを渡した場合は、名前解決は成功しても接続できないことがあります。

dns:
  enable: true
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  fake-ip-filter:
    - '+.local'
  nameserver:
    - 1.1.1.1

この設定ブロックは、前の例にある dns サブテーブル全体を置き換えます。フィルター項目を使うと、指定したドメインには合成アドレスを割り当てません。デバイス検出や、実アドレスを必要とするサービスなどで使われます。ただし、フィルターを設定してもドメインが DIRECT のルールに従うわけではなく、マルチキャスト名前解決が自動的に使えるようになるわけでもありません。LAN 内のサービスに接続できない場合は、サービス名を解決する実用的なローカル手段があるか、返されたアドレスが正しいネットワークへルーティングされるか確認してください。実アドレスを返すモードと比較する場合、アプリが以前のアドレスを保持している可能性もあります。必要に応じてアプリを再起動し、もう一度名前解決してください。

一般ドメインとノード用ドメインの名前解決を分ける

出力ノードの server にドメイン名を指定している場合、ノード接続の前にその名前を解決する必要があります。ノード名に対して proxy-server-nameserver を設定できます。特にルールに依存する DNS 経路を使う場合は、ノードの接続が確立していなくても使える名前解決の入口を用意してください。そうしないと、リクエストがノードを経由しないといけない一方で、ノードはそのリクエストが完了するまでアドレスを取得できない、という循環が起きます。すべてのノードが同時にタイムアウトする、IP アドレスを直接指定した接続は成功するのにドメイン名のノードだけ失敗する、といった場合は、グループのメンバーを一斉に削除して作り直す前に、この依存関係を確認してください。

同じ名前から複数のアドレスが返されても、必ずしも障害ではありません。アドレスは地域、キャッシュ、レコードタイプによって変わることがあります。より確実に検証するには、同じクライアント、同じ通信経路、同じドメイン名で条件を固定し、問い合わせ先、返されたレコードタイプ、アプリが実際に接続したアドレスを記録してください。IPv6 の結果だけ失敗する場合は、システムと出力経路の両方がそのアドレスファミリーに対応しているか確認しましょう。DNS オプションを無効にしても返答内容が変わるだけで、ネットワークに必要なルーティング機能があるかどうかの確認にはなりません。

プロキシノード:プロトコル・接続先アドレス・プロバイダー

ノードは出力先であり、ローカルのリスナーではない

proxies には、参照可能な出力先を定義します。各ノードの name は設定内での参照名、type は後続の項目をどのプロトコルとして解釈するかを指定します。server と port には実際に接続するリモートサーバーを記述します。ノードのポートとローカルの mixed-port に対応関係はありません。ノードにクライアントのローカルポートを書き写すと、接続できないだけでなく、自分自身を指してループすることもあります。設定に書き込む前に、プロバイダーからプロトコル、アドレス、ポートを確認してください。ノード名にある地域名やメモから項目の値を推測しないでください。

proxies:
  - name: LAB-SOCKS
    type: socks5
    server: 127.0.0.1
    port: 1080
    udp: false

proxy-groups:
  - name: LAB
    type: select
    proxies:
      - LAB-SOCKS
      - DIRECT

rules:
  - MATCH,LAB

この設定ブロックは、DIRECT の最小構成にある同名のトップレベル項目 3 つを置き換えます。ローカルで SOCKS5 サービスが 1080 ポートを待ち受けている必要があります。サービスがない場合は、グループ内の DIRECT と比較してテストしてください。テスト時は、そのサービスが現在のコアの別の入口ではないこと、また通信を現在のコアへ送り返さないことを確認します。最初のテストで TCP に絞れるよう、このノードでは UDP を無効にしています。アプリが UDP を必要とする場合は、プロトコルの対応状況、ノード設定、サーバー側の対応、入口の通信経路がすべて条件を満たす必要があります。

ノード名に日本語を使うこともできますが、トラブルシューティングでは安定していて短く、検索しやすい名前がおすすめです。同名のノードや、ノードとグループの名前が重複すると、参照が曖昧になり、設定をコアが拒否する場合もあります。同じサーバーをプロトコルやポートの違いで複数登録する場合は、それぞれ別の名前を付けましょう。リストの順番だけで見分けないでください。サブスクリプション更新で表示名が頻繁に変わる場合は、多数のルールから個々のノード名を直接参照するのも避けましょう。まず安定したローカルグループで受け、そのグループのメンバーを管理してください。

プロトコルごとのパラメーターを流用しない

プロトコルによって認証項目は異なります。たとえば SOCKS5 ではサーバーの設定に合わせてユーザー名とパスワードを入力します。Shadowsocks ノードでは、サーバー情報に従って暗号化方式とパスワードを設定します。項目を埋めるために、あるプロトコルの認証ブロックを別のプロトコルへそのままコピーしてはいけません。TLS を使うノードでは、サーバーが求める名前、トランスポート方式、関連オプションも確認してください。サーバーアドレスと、TLS で接続先を識別する名前が異なる場合もあります。ハンドシェイクに失敗したら、まずプロトコルとサーバー情報を確認し、証明書検証の緩和を恒久的な解決策にしないでください。

出力接続を確立できない場合は、3 種類の兆候を切り分けます。ノードのドメイン名解決に失敗すると、通常はハンドシェイク前にエラーが表示されます。接続先ポートに到達できない場合は、拒否やタイムアウトになることが多いでしょう。プロトコルや認証が一致しない場合は、接続後に失敗することがよくあります。ポートから応答があっても、何らかのサービスに到達したことしか分からず、現在のプロトコルが受け入れられたとは限りません。追加のトランスポート層を有効にしているノードでは、対応するパスやサービス識別子も確認してください。サーバー側が同じ設定を採用している場合にだけ、これらのオプションは意味を持ちます。

差し替え可能なノード一覧をプロバイダーで管理する

proxy-providers:
  lab:
    type: file
    path: ./providers/lab.yaml

proxy-groups:
  - name: LAB
    type: select
    use:
      - lab
    proxies:
      - DIRECT

rules:
  - MATCH,LAB

ローカルファイルプロバイダーを使うと、グループ定義とノードの取得元を分けられます。まずコアの作業ディレクトリに providers/lab.yaml を用意し、ファイルには前の例の proxies ブロックだけを記述します。メイン設定には共通項目を残し、上記のブロックでグループとルールを定義します。ここでの相対パスはコアの作業ディレクトリを基準にします。GUI で開いた YAML ファイルの隣とは限りません。パスエラーが出たら、まずクライアントがコアに指定している実際のディレクトリを調べ、コアの実行ユーザーにファイルの読み取り権限があるか確認してください。

リモートプロバイダーが取得する内容も、コアが期待する形式でなければなりません。任意の共有リンクをノード一覧の URL として使えるわけではありません。更新に失敗した場合は、取得処理のエラーなのか、取得した内容を解析できないのかを切り分けます。後者では、サーバーから通常の Web ページが返っている可能性があります。調査情報を共有する際は、エラーの種類と項目の構造を残しつつ、サブスクリプション URL、認証情報、接続ログに含まれる不要な個人アドレスは削除してください。用語の確認には、用語集のサブスクリプション、ノード、プロキシグループの項目を参照してください。

プロキシグループ:選択・速度測定・フェイルオーバー

ルールからは安定したグループ名を参照する

プロキシグループを使うと、「どのリクエストをここに送るか」と「現在どの出口を使うか」を分けて管理できます。ルールはグループ名を参照し、グループはノード、別のグループ、または組み込みの出力先を参照します。ノードを入れ替える場合はメンバーだけを変更すればよく、すべてのサイト向けルールを書き直す必要はありません。分かりやすい構成は、用途別グループと候補出口の 2 階層です。自動選択を挟む場合も、一方向の参照を保ってください。たとえば手動グループから自動グループを参照できますが、自動グループから手動グループへ逆参照すると、最終的な出力先を決められなくなります。

select は手動選択グループです。最初の動作確認、出口の固定、予備の確保に適しています。リストの順序は操作時の目安になりますが、「先頭に書いたものが起動ごとに必ず選ばれる」とは限りません。クライアントが前回の状態を復元する場合があります。トラブルシューティングではグループ画面でメンバーを明示的に選び、接続ログで実際に使われたノードを確認しましょう。グループに DIRECT を追加しても、自動的に DIRECT に切り替わるわけではありません。選択肢が一つ増えるだけです。

proxy-groups:
  - name: WEB
    type: select
    proxies:
      - LAB-SOCKS
      - DIRECT

rules:
  - DOMAIN-SUFFIX,example.org,WEB
  - MATCH,DIRECT

この設定は、前の章で定義した LAB-SOCKS ノードを使います。指定したドメインだけを手動選択グループに送り、それ以外のリクエストは直接送信します。メンバーを手動で切り替えたら、新しい接続で確認してください。既存のセッションが自動的に移行するとは限りません。ブラウザーが接続を再利用したり、アプリが長時間接続を維持したりする場合があります。画面では別のノードが選択されているのに動作が変わらない場合は、テスト対象のアプリの既存セッションを切断してから、新しい接続でルールの一致先と実際の出力先を確認してください。選択が保存されていないのか、接続がまだ作り直されていないのかを切り分けられます。

自動グループのプローブ結果は、あくまでプローブの結果

proxy-groups:
  - name: AUTO
    type: url-test
    url: https://www.gstatic.com/generate_204
    interval: 300
    tolerance: 80
    proxies:
      - LAB-SOCKS
      - DIRECT

rules:
  - DOMAIN-SUFFIX,example.org,AUTO
  - MATCH,DIRECT

url-test はプローブ用 URL を使って候補の出力先を比較し、自動選択を許容できる通信に適しています。interval の単位は秒、tolerance の単位はミリ秒です。小さな遅延の変動で頻繁に切り替わるのを抑えます。画面に表示されるのは、指定 URL に対する 1 回または複数回のプローブ結果です。実際のサービスへの遅延や通信速度ではありません。この例ではテストしやすいように DIRECT もグループに含めています。サービスでプロキシが必須なら、DIRECT を自動候補に入れないでください。プローブが速いという理由で選択される可能性があります。

fallback は、遅延が最も小さいメンバーを選ぶというより、優先順に使えるメンバーを選ぶ方式です。優先する出口を維持したい場合は、よく使うメンバーを先に、その後に予備を並べ、各メンバーから安定してアクセスできるプローブ URL を設定します。どちらの自動グループも、プローブ先、接続タイムアウト、実行間隔の影響を受けます。実際のサービスにはアクセスできるのに、プローブ先だけ開けない場合、グループの可用性判定が実際の要件とずれることがあります。プローブ URL を変更する際は、接続先ネットワークの安定性と、接続が確立したことを示せる応答かどうかを合わせて検討してください。

メンバーの取得元と復旧方法

proxies では、定義済みのノードや他の選択可能な出力先を個別に参照します。use では、プロバイダーのメンバーを取り込みます。サブスクリプション更新でノード名が変わる場合、グループに名前を長々と直書きするより use を使うほうが管理しやすいことがあります。二つの参照元は併用でき、固定のローカル予備と、更新されるリモート候補を同じグループにまとめられます。グループ名は表示されるのに選べるノードがない場合は、プロバイダーが読み込まれているか、一覧にノードが含まれているか、クライアント側で追加フィルターがかかっていないか確認してください。速度測定結果だけを更新しても解決しません。

特定の出口が不安定な場合は、まず許容する代替経路を決めてからグループの種類を選びます。ログインセッションや送信元アドレスの維持が重要なら、頻繁に遅延を比較するより手動グループが適しています。第一候補が使えなくなった場合にだけ切り替えたいなら、フェイルオーバーを使いましょう。行き先を判定できない通信に対して、「予備プロキシを使う」つもりが知らないうちに「直接接続する」ことにならないようにしてください。新しいノードは手動比較用のグループでテストし、接続、名前解決、アプリのリクエストを確認してから自動選択に加えます。問題が起きても、明確な直前の選択にすぐ戻せます。

プロバイダーのヘルスチェックと、グループ独自の速度測定設定は分けて確認しましょう。プロバイダーでノードが利用可能と表示されても、そのノードからグループのプローブ URL にアクセスできるとは限りません。反対に、一時的なエラーが出ても、そのノードをすべてのグループから削除すべきとは限りません。同じ対象と同じ通信経路を指定して再確認し、候補一覧、プローブ設定、実際の出力のどれを直すべきか判断してください。あるときの遅延値だけでなく、判断の根拠を記録しておくほうが役立ちます。

ルール構文:マッチ順・接続先・ルールセット

最初に一致したルールで接続先が決まる

ルールモードでは、コアは rules を上から順に確認します。最初に一致したルールの接続先を使い、さらに細かいルールを探し続けることはありません。多くのルールは、種類、マッチ対象、接続先を英語のカンマで区切って指定します。MATCH はマッチ対象を持たず、接続先だけを記述します。具体的な例外を広い分類より前に置き、最後にフォールバックを置いてください。ルールをアルファベット順に並べ替えたり、個別ルールをフォールバックの後に追加したりしないでください。記述されていても実行されません。

rules:
  - DOMAIN,api.example.org,DIRECT
  - DOMAIN-SUFFIX,example.org,LOCAL
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - MATCH,DIRECT

このルール一覧は、DIRECT の最小構成にあるルールを置き換えて使えます。LOCAL グループは残してください。先頭行は完全一致のドメインだけに適用され、2 行目はベースドメインとそのサブドメインを対象にします。どちらの接続先も最終的に DIRECT に進む場合でも、接続ログを見れば、完全一致ルールで DIRECT に進んだのか、サフィックスルールで LOCAL に進んだのかを区別できます。2 行の順序を入れ替えると、完全一致ドメインも先にサフィックスルールに一致します。単純な接続先を使って比較すれば、リモートネットワークの影響を除外して順序を確認できます。

ドメインルールに書くのは、完全な Web アドレスではありません。プロトコル、パス、ポート、クエリパラメーターは含めないでください。マッチ対象はコアが受け取るホスト名であり、ブラウザーのアドレスバーに表示される文字列全体ではありません。リダイレクト後は新しい接続先にアクセスし、ページが別ドメインへのリクエストを非同期で送ることもあります。画面上は同じページに見えても、ログには複数の接続が記録されます。確認する際は、対象のホスト名を一つに絞り、ログで接続先と一致したルールを確かめてください。他の場所からコピーしたルールを貼る場合は、全角カンマや見えない空白にも注意しましょう。

アドレスマッチングで名前解決が発生する場合がある

IP-CIDR は IPv4 アドレス範囲、IPv6 には IP-CIDR6 を使います。GEOIP はアドレスと地理データに基づいて判定するため、実行環境で該当データを利用できる必要があります。いずれもドメインのサフィックスルールではありません。接続先がドメイン名の場合、アドレスルールの判定前に名前解決が必要になることがあります。一部のアドレスルールでは末尾に no-resolve を付けて、ルール判定用の追加の名前解決を避けられます。ただし、取得済みの接続先アドレスを使わないという意味ではありません。マッチ対象のアドレスを取得できない場合、アドレスルールに必ず一致するとは限りません。後続のルールにも適切な接続先を用意してください。

同じサービスへの接続がドメインルールに一致したり、アドレスルールに一致したりする場合は、まず接続元のアプリが毎回同じ形式で接続先を渡しているか確認します。ドメイン名を渡すアプリもあれば、キャッシュしたアドレスへ直接接続するアプリもあります。同じドメイン名から複数のアドレスが返されることがあり、地理データによる判定も実際のアドレスやデータの内容によって変わります。業務用ドメインの一覧を地理ルールで代用しないでください。重要な接続先は明示的な例外として定義し、残りをアドレス範囲や地理分類で処理します。ログで、ルールが一致したときの接続先情報も確認してください。

外部ルールセットにはプロバイダーのタイプを指定する

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

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

続いて、コアの作業ディレクトリにある rules/local-domains.yaml に payload のリストを記述します。

payload:
  - '+.example.net'

domain のルールセットにはドメイン式を記述します。ipcidr はアドレス範囲、classical はマッチタイプを含む従来形式のルールに使います。動作タイプの指定はファイルの内容と一致させてください。プロバイダーファイル内の各項目に接続先を記述する必要はありません。接続先はメイン設定の RULE-SET で指定します。RULE-SET の位置も優先順位に影響します。ルールセットより優先する独自の例外は、リソースファイル内の順序を変えるのではなく、参照行より前に記述してください。

ルールセットの更新後に広い範囲で接続先が変わった場合は、リソースタイプ、更新前後のマッチ範囲、メインルール内の優先順位を確認します。作業ディレクトリにあるローカルリソースを一時的に使って比較すれば、ダウンロード失敗、形式の誤り、実際にマッチ範囲が広がった場合を切り分けられます。独自の振り分けルールを追加する場合は、最も狭く有効な条件を前のほうに挿入し、一致するリクエストと一致しないリクエストを一つずつテストしてください。両方が想定どおりになって初めて、境界を検証できたと言えます。「今回アクセスできた」だけでは不十分です。

設定の上書きとマージ:サブスクリプションから有効設定まで

変更する階層を見極める

GUI クライアントでは、リモートサブスクリプション、個人用の上書き設定、画面上の選択、最終的にコアへ渡すファイルが別々に保存されていることがよくあります。サブスクリプションのキャッシュを手動で編集すると一時的に有効でも、次の更新で上書きされる場合があります。一時的に生成された出力を直接編集しても、再読み込み時に失われることがあります。個人ルールを更新後も維持するには、クライアントが上書き、拡張設定、スクリプト用の入口を用意しているか確認し、適用順序も把握してください。コアが読み込むのは処理後の設定です。元ファイルに「上書き」と書かれているだけで、複数ファイルが自動的に結合されるわけではありません。

キーの値の型に応じてマージ方法を決めます。ポートやモードはスカラーなので、通常は最終的に一つの値だけが残ります。DNS はマッピングのため、サブキーだけを変更できる場合も、全体を置き換えるツールもあります。ルールやプロキシグループはシーケンスです。ツールによって、全体を置き換える、先頭に挿入する、末尾に追加する、名前で処理するなど挙動が異なります。YAML 自体は、クライアントが複数設定のシーケンスをどのように連結するかを定めていません。ツールを使う前に、ルールを 2 行だけ用意して試し、最終ファイルで順序を確認してください。別のクライアント向けの上書き項目を、そのまま流用しないようにしましょう。

上書き項目には、用途も合わせて記録しましょう。特定のドメインをローカルグループに送るだけなら、ポート、ログ、ノード一覧全体までコピーする必要はありません。無関係な項目まで上書きすると、後から上流の変更が反映されなくなります。一方、DNS 設定全体を置き換える場合は、必要な上流 DNS やポリシーを書き出してから、ノード名の解決に使う専用の入口まで削除しないようにしてください。上書きは短いほど確認しやすくなりますが、機能ブロック全体に必要な項目を省いてまで短くしてはいけません。

入力と出力を使ってマージ結果を確認する

# リモート設定に元からあるルール
rules:
  - DOMAIN-SUFFIX,example.org,LOCAL
  - MATCH,DIRECT
# 例外ルールを先頭に追加した後の有効ルール
rules:
  - DOMAIN,api.example.org,DIRECT
  - DOMAIN-SUFFIX,example.org,LOCAL
  - MATCH,DIRECT

この 2 つは入力と想定出力の例であり、同時に有効にする設定ではありません。例外ルールがサフィックスルールより前にあり、元のフォールバックが末尾に残っている点が重要です。クライアントがルール一覧の置き換えにしか対応していない場合は、出力例の一覧全体を使います。先頭への追加に対応している場合は、該当する入口に例外ルールだけを書きます。出力されたルールとログを照合し、LOCAL の定義が残っていることも確認してください。プロキシグループ名を変更した場合は、上書き処理によって元のグループが置き換えられず、同名グループが二つ追加されていないかも確認しましょう。

JSON 形式のインラインリストと複数行リストは、同じ値を表せることが多いですが、複数行に展開したほうが追加位置を比較しやすくなります。見た目を整えるために、ツールでルールを自動並べ替えしないでください。マッピングのキー順は読みやすさだけに影響しますが、リストの並べ替えは意味を変えてしまいます。項目を削除するときも、「元の値を引き継ぐ」のか「明示的に空にする」のかを区別してください。キーを省略すると上書きに参加しないことが多く、空リストを書くと 0 件で上書きする場合があります。実際の挙動はツールの仕様を確認しましょう。値のないキーを書くと、コアが想定外の空値として解釈することがあります。

アンカーの再利用と更新後の回帰テスト

YAML のアンカーとエイリアスは、同じファイル内で既存の構造を再利用するための機能です。別の設定ファイルを読み込む仕組みではありません。マッピングのマージ構文に対応するかどうかは、クライアントの前処理とパーサーによって異なります。特に、シーケンスも項目ごとにマージされると決めつけて使わないでください。他のクライアントでも使うファイルを作る場合は、展開済みで単体として読み込める形式を優先しましょう。ログにエイリアスが見つからないと表示されたら、まず前処理でアンカーが移動または削除されていないか確認します。ルールそのものを先に変更する必要はありません。

サブスクリプション更新前に、前回正常に使えたローカル設定を保存し、個人用の上書き設定も別に保管しておきましょう。更新後は、ノード名と対象グループの参照が有効か、候補一覧が空になっていないか、フォールバックルール、DNS、実行モードが変わっていないかの順に確認します。問題が起きたら、まず上書きを無効にして元のサブスクリプションだけで試し、次に上書きを有効にして比較します。どちらでも失敗するならマージ以外の原因かもしれません。上書き有効時だけ失敗する場合は、ブロックごとに戻し、最初に挙動が変わる箇所を特定してください。

有効な設定を比較用に保存する際、認証情報を含むファイル全体を公開のディスカッションに貼り付けないでください。ローカルファイルの比較では、変更されたパス、順序、参照関係に注目します。共有するのは必要な部分だけにし、定義と参照で同じ仮名に置き換えましょう。構造を再現しながら、調査を手伝う人が、配置ミス、名前の重複、生成後にファイルが再読み込みされていない、といった問題を見分けられます。

検証とトラブル対処:読み込み結果から接続ログまで

まず設定を検証し、次にリスナーを確認する

コマンドライン版のコアを使えば、現在の実行環境を置き換えずに設定をテストできます。作業ディレクトリをテスト用の場所に変更し、有効な設定を config.yaml として保存します。ローカルプロバイダーやルールセットを使う場合は、設定に合わせてテストディレクトリ内にサブディレクトリも用意してください。以下のコマンドは、mihomo が実行ファイルの検索パスにあり、curl を直接呼び出せることを前提としています。まず 1 つ目のコマンドを単独で実行します。成功したら別のターミナルで 2 つ目を起動し、もう一方のターミナルからリクエストを送ってください。

mihomo -t -d . -f ./config.yaml
mihomo -d . -f ./config.yaml
curl --noproxy "" --proxy http://127.0.0.1:7890 https://example.org/

GUI クライアントとテスト用コアが同じポートを同時に使わないようにしてください。起動前にポートを使用中のプロセスを終了するか、テスト設定で別の空きポートを選び、コマンドの数字も変更します。環境によっては curl がターミナル上のエイリアスになっていることがあります。その場合は、使用中のプラットフォームにある実際の実行ファイルを使ってください。明示的なプロキシオプションを付けるのは、このリクエストを指定した入口経由で送信し、システムプロキシ設定やプロキシ環境変数の影響を減らすためです。テストに成功しても、その入口が 1 件のリクエストを受け付けたことが分かるだけで、すべてのアプリが同じ設定を参照しているとは限りません。

設定テストが失敗した場合は、まずファイルが見つかったか、構文エラーがあるか、依存リソースを読み取れるか確認します。テストは通るのに起動できない場合は、ポートの競合、権限不足、テスト時と異なる実際の作業ディレクトリなど、実行環境を重点的に確認してください。起動できても接続できない場合に、初めて通信経路を調査します。この段階では、エラーを一件記録すれば十分です。同じ種類のエラーが繰り返し表示されても、多くの場合はアプリが再試行しているだけで、設定の十数か所が同時に壊れているわけではありません。

接続の証拠から問題の範囲を絞り込む

症状まず確認する項目次の確認手順
プロキシポートへの接続が拒否されるコアが想定したアドレスとポートで待ち受けているか起動ログとアプリの設定を照合する
アプリからリクエストはあるが、コアに記録されないアプリが実際にプロキシ入口を経由しているか明示的なプロキシ指定とシステム経由を個別に検証する
記録はあるが、接続先が想定と異なるモード、ルール順、実際の接続先グループの現在の選択と有効な設定を確認する
プロキシに一致してもタイムアウトするノードの名前解決、接続、リモート側のハンドシェイクメンバーを一つだけ切り替えて再試行し、失敗した段階を記録する

接続ログがない場合は、DNS ポリシーの編集やノードへの項目追加を急がないでください。入口を明示したリクエストを送って最初の比較を行います。ログに記録されるなら、アプリがシステムプロキシ設定を参照していないか、通信経由の入口がそのプロセスのトラフィックを受け取っていない可能性があります。ブラウザーとターミナルは別々に確認しましょう。ブラウザーにはプロキシ拡張機能があり、ターミナルは環境変数やツール独自の設定を参照することがあります。詳しくはブラウザーとターミナルでシステムプロキシが機能しない場合の対処を参照してください。

接続ログはあるのに接続先が違う場合は、モード、対象名、マッチしたルール、最終的な出力先の 4 点を記録します。たとえばルールが自動グループを指定していても、想定しているプロキシが必ず選ばれるとは限りません。候補として許可された DIRECT が選ばれている可能性もあります。既存セッションだけで問題が起きる場合は、そのセッションを閉じて再接続します。新しいセッションでも再現するなら、実行時オプションがファイルの設定を上書きしていないか確認しましょう。毎回、その接続のログを基準に判断してください。前回のテスト画面のスクリーンショットで結論を出さないでください。

再現可能な回帰テストを残す

設定を変更するたびに、少なくとも 3 種類の比較対象を用意します。DIRECT に送る対象、カスタムルールに一致させる対象、フォールバックに送る対象です。まず最小構成が動作することを確認し、その後でノード、プロキシグループ、DNS、外部リソースを順に戻します。各段階で失敗すれば、直前に追加したブロックまで原因を絞り込めます。断続的な障害では、発生時のネットワーク環境と入口の種類を記録してください。有線から無線へ、デスクトップからスマートフォンへ切り替えると、システム経由や上流 DNS が変わることがあります。条件の異なる 2 回の結果をそのまま比較しないでください。

初回インポート時に設定が失敗する場合は、入門ガイドに戻り、インポート、モード、接続の順に確認してください。特定の項目まで原因を絞り込めたら、想定した動作、実際の動作、最小限の設定例を記録し、単独で再現します。本番環境に戻す前に、一時的に有効にした詳細ログ、テスト用ポート、通信経由の設定を元に戻してください。そうすれば次に「変更後にインターネットへ接続できない」となった場合も、問題の推測をやり直すのではなく、最後に動作した設定と再現可能なリクエストから調査を始められます。

再読み込み後と再起動後の比較も忘れずに行いましょう。再読み込みではコアがファイルの変更を受け取ったかを確認でき、再起動ではクライアントが以前の選択を復元したか、設定を再生成したか、起動時にサブスクリプションを取得したかを確認できます。両者で結果が異なる場合は、変化が起きた段階を記録し、上書きとマージに戻って設定元を確認してください。長期的な運用で役立つのは、デバッグログを増やすことではありません。どのファイルに戻せるか、どのリクエストで再確認できるか、どのルールに一致するはずかを把握しておくことです。