Clash設定ファイル
YAMLの構造と各項目

YAMLの構造

設定ファイルは、項目名を並べただけの一覧ではなく、階層を持つテキストです。YAMLではインデントで親子関係を示し、コロンで項目と値を区切り、ハイフンでリストの要素を表します。初めて見る設定ファイルは、まず左端にあるトップレベルの項目を探し、その下のインデントされた部分を確認しましょう。どれが共通設定で、どれが特定のノードだけに属するのかを把握でき、正しい値を誤った場所に書くのを防げます。

インデントからオブジェクトとリストを読み取る

インデントは半角スペース2つに統一し、タブを混ぜないようにしましょう。同じ階層の項目は左端をそろえ、子項目は親より1段深くします。通常、コロンの後にはスペースを1つ入れ、リスト項目のハイフンの後にもスペースを入れます。エディターで空白文字を表示すると、見えにくいインデントを確認できます。エラーが出た行だけでなく、その数行前も見直してください。引用符の閉じ忘れやインデントの誤りは、後の行でエラーとして現れることがあります。

# これらの項目に対応する mihomo コアで読み込めます
mixed-port: 7890
allow-lan: false
mode: rule
log-level: info

proxies: []

proxy-groups:
  - name: 手動選択
    type: select
    proxies:
      - DIRECT

rules:
  - MATCH,手動選択

この例は階層を示すためのもので、接続先はすべてDIRECTです。利用可能なリモートプロキシは含まれていません。トップレベルの proxy-groups はリストで、その各要素がプロキシグループのオブジェクトです。オブジェクト内の proxies もリストで、候補となる出口の名前を並べます。一方、トップレベルの proxies にはプロキシノードの定義を記述します。同じ名前の項目でも、階層が異なれば役割も異なります。

設定は参照の連鎖として見ると理解しやすくなります。プロキシノードで接続方式を定義し、プロキシグループでノード名を参照し、ルールでグループ名を参照します。DIRECT は組み込みの直接接続先なので、プロキシ一覧に同じ名前のノードを追加する必要はありません。参照名は大文字・小文字、空白、句読点も含めて完全に一致させてください。「手動選択」を「通常の選択」に変更した場合は、ルール側の参照先も変更が必要です。書式が正しくても、読み込み時に参照先が見つからないというエラーになることがあります。

文字列・真偽値・空の値

特殊文字を含む値、特にパスワード、#を含む名前、日付のように見える値には、引用符を使うのがおすすめです。#は位置によってコメントの開始と解釈され、引用符がないと値の一部が切り捨てられることがあります。真偽値には true と false、ポートには数値を使います。見た目をそろえるために、すべての値を文字列にする必要はありません。[] は空のリストを表し、項目名だけで値がない状態とは異なります。機密情報を含む値は、内部の空白も含めてそのまま保ち、勝手に削除しないでください。

同じオブジェクト内で同じキーを重複して定義しないでください。トップレベルに rules を2つ書いても、ルールが連結されるわけではありません。パーサーによって読み込みが拒否されたり、片方だけが残ったりします。人から受け取った設定の一部を貼り付けるときは、まずそれが完全なファイルなのか、親項目の下に置く内容なのかを確認してから場所を決めましょう。nameserver の子項目だけを受け取った場合、それをファイルの左端にそのまま置くことはできません。

編集を始める前に、元のファイルをコピーし、用途がわかる名前で保存してください。まずは上の最小構成でインデントを練習し、その後に実際のサブスクリプションを確認しましょう。練習用ファイルをそのまま本番設定に置き換えないでください。項目を追加するたびに読み込んで確認すれば、数百行を一度に貼り付けてからエラーを探すより効率的です。設定ファイル全体を順に読みたい場合は、config.yamlの読み進め方もご覧ください。このページの以降の章では、各項目の意味と注意点を解説します。

ポートと動作モード

共通項目では、クライアントがどこで通信を受け付け、受け取った通信をどう処理するかを設定します。「ローカルの入口」と「リモートの出口」を分けて考えましょう。ローカルポートはブラウザーやシステムプロキシから接続するためのもの、リモートノードのポートはサーバーへの接続に使うものです。数字が同じでも関係はありません。アプリが実際にローカルの入口へリクエストを送って初めて、その後のルールが判定に使われます。設定が正しくても、すべてのアプリが自動でプロキシに接続するわけではありません。

入口を選び、待ち受け範囲を設定する

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

allow-lan: false は、この端末だけで使う場合に適しています。bind-address は待ち受けアドレスを指定します。ループバックアドレス 127.0.0.1 は現在の端末だけを指します。LANからの接続を許可する設定に変える場合も、待ち受けアドレス、ファイアウォール、クライアント側の上書き設定を確認してください。プロキシの入口をインターネットに直接公開してはいけません。同じLAN内の端末から使う必要がある場合は、まずアクセス範囲を限定し、使用するコアが対応している入口の認証方式を確認しましょう。

ルールモードは接続のオン・オフではない

mode: rule はルール一覧に基づいて通信を振り分けます。global は通常、接続を全体用のプロキシグループに渡します。direct は直接接続として処理します。全般モードへの切り替えは、ルールがリクエストに影響しているかを切り分けるのに役立ちますが、あらゆる問題を解決する設定ではありません。アプリがプロキシの入口を通っていない場合や、ノード自体に接続できない場合は、モードを切り替えても前提となる問題は解消されません。

システムプロキシとTUNモードは、仕組みが異なります。システムプロキシは、プロキシアドレスをシステムに登録する方式で、アプリ側がそれを使うかどうかを選べます。TUNは仮想ネットワークインターフェースで、ルーティングによって条件に合うパケットをコアに渡します。TUNでは管理者権限やルート、DNSの制御が関係し、設定項目もプラットフォームによって異なります。初めての切り分けでは、まずシステムプロキシで特定のリクエストが通ることを確認してから、使い方ガイドに沿ってTUNを有効にしましょう。入口を2種類同時に調べずに済みます。

クライアント画面のポートやモードが、設定ファイルの内容より優先されることがあります。ファイルではルールモードなのに画面が全般モードを示している場合は、元ファイルを何度も編集するのではなく、実行中の最終設定を確認してください。クライアントによってはポートをアプリ単位で管理しており、サブスクリプションを再読み込みしても変わりません。実際に待ち受けているポートを確認したうえで、ブラウザーやコマンドが使用している接続先を調べれば、別のプロキシプログラムに接続してしまう事態を避けられます。

ログレベルは通常 info で十分です。問題の切り分け中だけ debug に変更しましょう。詳細なログは出力量が増えるほか、接続先のドメインやアドレス、接続経路が記録される場合があります。共有する前に機密情報が含まれていないか確認してください。調査後は普段使うレベルに戻し、不要なログが長期間たまらないようにします。コントローラーはコアを管理するためのインターフェースであり、インターネット接続の入口ではありません。システムプロキシにコントローラーのポートを設定したり、管理しやすくするために待ち受け範囲をむやみに広げたりしないでください。

最後にIPv6を確認します。トップレベルの ipv6 とDNSセクションの同名項目は、それぞれ接続と名前解決に影響し、具体的な動作はコアの実装によって異なります。例では初歩的な切り分けの範囲を絞るために無効にしていますが、すべてのネットワークで常に無効にすべきという意味ではありません。ネットワークとプロキシ出口がIPv6に対応している場合は、基本接続が安定してから個別に有効化してテストし、AAAAレコードの解決結果と実際の送信元アドレスを確認しましょう。画面上のスイッチだけが変わっていないかも確認してください。

DNSと名前解決

DNSはドメイン名をネットワークアドレスに変換する仕組みです。ルールにドメイン名が書かれていても、通信経路全体で名前解決が不要とは限りません。プロキシサーバーへの接続、Webサイトへの接続、アドレスの地域判定などでDNSが使われることがあります。問題を調べるときは、「どこで、どのDNSサーバーに問い合わせ、どのような結果が返ったか」を確認し、すぐにノードの障害と決めつけないでください。ブラウザー内蔵の暗号化DNSがシステムの名前解決経路を迂回し、同じ端末のアプリでも挙動が異なる場合があります。

通常の名前解決とFake IP

enhanced-mode で拡張DNSモードを選択します。fake-ip はアプリに対応付け用の仮想アドレスを返し、コアがその対応関係から元のドメイン名を特定します。これはWebサイトの実際のアドレスではありません。ルールで使うドメイン情報を保ちやすい一方、その後のリクエストが同じコアに届く必要があります。redir-host は主に実際に解決したアドレスを返し、従来型の名前解決に近い動作をします。入口の仕組みを理解しないまま、どこかのサイトの推奨だけを根拠に切り替えるのは避けましょう。

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
    - 119.29.29.29
  nameserver:
    - https://dns.alidns.com/dns-query

この設定はローカルでDNSを待ち受けますが、listen を指定しただけでシステムのDNS設定が変わったり、TUNによる通信の取り込みが自動で有効になったりするわけではありません。システムが引き続きルーターへ問い合わせている場合、コアの設定はまだ使われていない可能性があります。入口を確認するには、クライアントのDNS取り込み設定、システムのネットワーク設定、ログをあわせて確認してください。標準以外のポートで待ち受ける場合、一般的なシステムDNS設定にはそのポートを直接指定できないことがあります。対応するアプリや取り込み機能を使いましょう。

default-nameserver は、暗号化DNSサービス自体のドメイン名を解決するために使われます。そのため例ではIPアドレスを指定し、DNSサーバーを探すために先にドメインを解決するという循環を避けています。nameserver は通常の上流DNSサーバーです。例ではHTTPS経由で問い合わせるDoHを使っています。暗号化DNSでもネットワークから到達できる必要があり、どの環境でも必ず接続できるわけではありません。また、プロキシノードの代わりにもなりません。上流サーバーを変更する際は、現在のネットワークから到達できるかを先に確認してください。

ドメインごとにDNSサーバーを指定する

社内ドメインのように、特定の名前解決経路が必要なドメインもあります。mihomoでは nameserver-policy を使い、ドメインごとに上流DNSサーバーを選択できます。以下の内部ドメインとDNSアドレスは構造を示す例にすぎません。実際に使うときは、利用中のネットワークから提供された値に置き換え、この設定を同じ dns オブジェクト内に追加してください。トップレベルに2つ目のDNS項目を作らないようにしましょう。

# 既存の dns オブジェクト内に統合
nameserver-policy:
  "+.corp.example.com":
    - 192.168.1.1

Fake IPのフィルターリストは、指定したドメインに仮想アドレスの割り当てを行わないためのもので、ルールの直接接続リストとは異なります。ドメインを追加しても、その通信は引き続き振り分けルールの対象です。LAN内のデバイス検出、特定のゲーム、実アドレスを必要とするアプリに問題が出た場合は、原因を確認したドメインだけを対象にテストしてください。すべてのドメインを追加すると、本来利用したかった仕組みを無効にすることになります。

対応するmihomo設定では、proxy-server-nameserver を使ってプロキシサーバーのドメイン名を解決するDNSサーバーも指定できます。Webサイトのドメイン解決とは目的が異なり、プロキシ接続の確立前にサーバーのアドレスを調べるための設定です。DNS接続にも振り分けルールを適用する respect-rules などのオプションを使う場合は、循環が生じないか特に注意してください。DNSサーバーへの接続にプロキシが必要で、そのプロキシサーバーのアドレス解決にも同じDNSサーバーが必要になることがあります。明確な理由がなければ、まずはシンプルな名前解決経路を保ちましょう。

DNSを検証するときは、問い合わせがコアに届いているか、その結果が後続の接続に使えるかを分けて確認します。Fake IPモードで仮想アドレスが表示されても正常な場合があり、そのアドレスをリモートサーバーのアドレスとして使うことはできません。問題が1つのアプリだけなら、まず内蔵DNS、キャッシュ、接続方法を確認してください。すべてのアプリで同時に問題が起きる場合は、上流DNSへの到達性とDNSの取り込み経路を調べます。結果から効果のあった設定を特定できるよう、変更は一度に1項目に絞りましょう。

プロキシノードの項目

プロキシノードには、リモート接続に必要なパラメーターを記述します。名前を入力するだけで使えるラベルではありません。必要な項目はプロトコルの種類、サーバー側の設定、クライアントコアの対応状況によって決まります。サブスクリプションにノードが含まれている場合は、元のパラメーターを保ち、プロキシグループやルールだけを調整するのがおすすめです。暗号化方式、通信方式、認証情報を手動で変えても、通常は接続が速くなりません。クライアントとサーバーの設定が食い違う原因になります。

まず共通項目を確認する

name はプロキシグループから参照するローカル名、type はプロトコル名、server はリモートサーバーのドメイン名またはIPアドレス、port はサーバーの待ち受けポートです。名前は用途に合わせて付けられますが、一意にし、プロキシグループや組み込みの接続先と重複しないようにしましょう。ドメイン欄にはホスト名だけを書き、https:// やページのパスは付けません。ポートもローカルの混合ポートをそのまま使わず、サーバーの情報に従って入力してください。

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

proxy-groups:
  - name: 手動選択
    type: select
    proxies:
      - サンプル出口
      - DIRECT

この例では、予約済みのテスト用ドメインとダミーのパスワードを使い、Shadowsocksノードの構造を示しています。実際に利用できるプロキシサービスではありません。接続するには、正当に取得したサーバーアドレス、ポート、暗号化方式、パスワードが必要です。cipher はサーバー側の設定と一致させる必要があり、任意に選べるセキュリティレベルではありません。パスワードをコピーするときは、引用符内の空白や特殊文字、改行に注意してください。画面上で同じように見えても、実際の文字列が一致するとは限りません。

プロトコルのパラメーターを混在させない

認証項目はプロトコルごとに異なり、互換性があるとは限りません。たとえば、パスワードを使うプロトコルもあれば、UUIDを使うものもあります。通信層もTCP、WebSocketなどさまざまです。複数の解説にある項目を混ぜても、コアが自動で判断してくれるわけではありません。まずプロトコルを確認し、現在のコアで使える項目を調べましょう。別のクライアントで使える項目でも、現在のコアで同じ書き方ができるとは限りません。未対応の項目が無視され、明確なエラーにならない場合もあります。

TLSは接続を暗号化し、相手の身元を検証する仕組みです。servername はハンドシェイク時のサーバー名を指定するために使われることがあり、ノードの表示名とは別の項目です。証明書エラーが出たら、サーバー情報、端末の時刻、指定した名前が一致しているかを確認してください。証明書検証を無効にする方法を、恒久的な対処として使わないでください。誤った接続先や信頼設定の問題を隠してしまうおそれがあります。WebSocketのリクエストパスやヘッダーもサーバー側の設定に合わせる必要があります。WebサイトのトップページURLだけから推測しないでください。

udp: true は、そのノードでUDPを利用できるようにする設定です。もともとUDPに対応していないサーバーに機能を追加するものではありません。Web閲覧は正常でもゲームや音声通話に問題がある場合は、ローカルの入口でUDPが取り込まれているか、プロトコルとサーバーが対応しているか、ルールが想定した出口に振り分けているかを個別に確認してください。HTTPの接続テストだけでは、UDP経路全体が正常とは判断できません。「ノードは利用可能なのにアプリが動かない」という問題のよくある原因です。

ノード数が多い場合は、proxy-providers でプロキシの集合を管理し、プロキシグループから use で参照できます。完全な設定ファイルを返すサブスクリプションとは別の仕組みです。プロキシプロバイダーには、対応する形式のノード一覧が必要で、任意のサブスクリプションURLをそのまま指定できるわけではありません。リモートURLにアクセス用の認証情報が含まれる場合もあるため、設定を共有する前に削除してください。まずはクライアントに備わっているサブスクリプション管理機能を使い、ノード群を個別に管理する必要があるとわかってからプロバイダーを導入しましょう。

クライアントを変更する場合は、設定のコピーを保存し、使用するコアと対応プロトコルを確認してください。クライアント選びは、まずダウンロードページのClash Plusを候補にできます。他のクライアントも端末の要件に合わせて選びましょう。ノード情報をサービス提供元から受け取っている場合、接続に失敗したときは、ノード名をすべて変更するのではなく、まず元の情報と照合してください。わかりやすい名前はログの確認に役立ちますが、接続性能は変わりません。複雑な命名より、項目間の参照が正しく保たれていることが重要です。

プロキシグループと選択

プロキシグループは、複数の接続先から選択するための中間層です。ルールから特定のリモートノードへ直接接続するのではなく、リクエストをグループに渡し、グループ側で出口を選べます。そのため、ノードを変更するときも、通常は各ルールを書き換えずにグループの選択だけを調整できます。グループを理解するには、まず候補となるメンバー、次に選択方式、最後にそのグループを参照するルールを確認してください。名前だけを見ても、通信が最終的にどこへ向かうかはわかりません。

手動選択・自動選択・フォールバック

select は手動選択で、出口を明確に制御したい場合に適しています。url-test は指定したテスト先への接続結果に基づいて選択しますが、その結果が示すのはテスト対象とテスト方法における状態であり、すべてのアプリの使用感ではありません。fallback は候補を順に確認して利用可能なものを探す方式で、明確なプライマリー・バックアップ構成に向いています。それぞれ用途が異なるため、「自動」という言葉だけを理由に、すべての通信を同じグループへ任せないようにしましょう。

proxy-groups:
  - name: 自動候補
    type: url-test
    proxies:
      - サンプル出口
    url: https://www.gstatic.com/generate_204
    interval: 300
    tolerance: 50

  - name: 通常の出口
    type: select
    proxies:
      - 自動候補
      - サンプル出口
      - DIRECT

この設定を使う前に、proxies で「サンプル出口」を定義してください。この断片だけでは完全な設定ファイルとして読み込めません。テスト間隔の単位は秒、tolerance は小さな変動による頻繁な切り替えを抑えるための許容差で、単位はミリ秒です。テスト先には、安定して接続でき、現在のネットワークに適したものを指定しましょう。例のアドレスを使う必要はありません。テスト先自体にアクセス制限がある場合、グループ内のすべての候補が失敗しても、別の接続先にも使えないとは限りません。

「通常の出口」で「自動候補」を選ぶと、リクエストは内側のグループに渡され、ノードが選択されます。「サンプル出口」を選ぶとそのノードが直接使われ、DIRECT を選ぶと直接接続になります。グループ内に直接接続の候補があれば、単なる予備の説明ではなく、実際に選択可能な出口です。特定の通信でプロキシの使用が必須なら、その経路に選択可能な直接接続を不用意に残さず、現在どの候補が選ばれているかを必ず確認しましょう。

参照関係と安定性

グループから別のグループを参照できますが、循環参照は作れません。たとえば「通常の出口」に「メディア用出口」が含まれ、その「メディア用出口」が再び「通常の出口」を含むと、選択を終えられません。用途別グループから選択グループへ、選択グループからノードまたは組み込みの接続先へ向かう、一方向の流れを考えて設計しましょう。階層を増やすなら、その理由が必要です。画面の分類を整えるためだけに深く入れ子にすると、問題が起きたときに実際の候補を何段も確認することになります。

自動切り替えが主に影響するのは、切り替え後に新しく確立される接続です。既存の接続がすぐに移行するとは限りません。Webページの接続再利用や動画の長時間接続では、切り替え後も以前の出口が使われることがあります。ログイン、決済、出口アドレスが重要な通信では、テスト結果を頻繁に追いかけるより、安定した選択を使うほうが適しています。切り替えを確認するには、古い接続を閉じて新しいリクエストを送り、グループのボタンの色だけでなく、接続詳細のプロキシ経路を確認してください。

load-balance は設定した方式に従って接続を複数の候補に振り分けますが、1つのダウンロード接続の帯域を単純に合算する仕組みではありません。接続ごとに出口が異なると、Webサイトで再認証が求められる場合もあります。明確な負荷分散の要件がなければ、まずは手動選択かシンプルな自動候補グループを使いましょう。複雑なグループにはコアの対応だけでなく、候補の利用可否、接続の維持、業務で出口の一貫性が必要かどうかの理解も必要です。

プロバイダー経由でノードを追加する場合、プロキシグループでは通常のノード名ではなく、use でプロバイダー名を参照します。フィルター設定によって実際の候補は変わるため、正規表現を誤るとグループが空になることがあります。サブスクリプションの更新後にノードがグループから消えた場合は、プロバイダーの更新が成功したか、フィルターに一致するか、ノード名が変わっていないかの順に確認してください。ルールを先に削除しないでください。ルールはリクエストをグループへ渡すもので、グループのメンバーを生成するものではありません。

クライアントが手動選択の結果を保存している場合、設定を再読み込みしてもリストの先頭に戻るとは限りません。問題を調べる際は現在の選択を記録し、必要であれば明示的に選び直してから新しいリクエストを送ってください。ルール、上書きファイル、クライアントの選択履歴から参照されている場合があるため、プロキシグループの名前は安定させましょう。構成を見直すときは、元の名前を保ったまま新しい候補を検証し、参照先を段階的に変更してください。すべてのグループ名を一度に変えるより、元に戻しやすくなります。

ルールの書き方と順序

ルールは通常、上から順に判定され、最初に一致したルールで処理先が決まります。「より詳しい」ルールを自動で選び直すことはありません。そのため、ルールは内容だけでなく順序も正しくする必要があります。振り分けの分岐が続く道のように考えてください。リクエストは上から順に通り、上流で振り分けられた通信は下のルールまで進みません。よくある誤りは、上にある範囲の広いルールに先に一致し、下にある具体的なルールが使われないことです。

ドメイン・アドレス・最終フォールバック

多くのルールは「種類、マッチ対象、処理先」の形式で記述します。たとえば DOMAIN-SUFFIX,example.com,通常の出口 のようになります。ドメインルールにはURLではなくドメイン名を書き、プロトコル、ポート、パスは含めません。DOMAIN は完全一致、DOMAIN-SUFFIX はドメインとそのサブドメイン、DOMAIN-KEYWORD はドメイン文字列に含まれるキーワードで判定します。キーワードの範囲は想定より広くなることがあるため、対象ドメインがわかっている場合は完全一致かサフィックス一致を使いましょう。

rules:
  - DOMAIN,router.lan,DIRECT
  - DOMAIN-SUFFIX,example.com,通常の出口
  - DOMAIN,ads.example.net,REJECT
  - 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-CIDR はアドレス範囲、GEOIP はアドレスデータベースに基づいて地域を判定します。MATCH はマッチ対象を指定せず、最後のフォールバックとして使います。MATCH を先頭に置くと、その後のルールは判定されません。プライベートアドレスの例は2つの範囲だけで、すべてのローカルアドレスを網羅しているわけではありません。実際のネットワークでは、ほかの範囲、IPv6、内部ドメインのルールが必要になる場合もあります。

名前解決とルールプロバイダー

no-resolve は、対応するIPアドレス系ルールの末尾によく使われ、そのルールの判定だけを目的とした名前解決を行わないようにします。「この接続ではDNSが一切不要」という意味ではありません。リクエストに実際のIPアドレスがあれば、そのままアドレス判定に使われる場合があります。ドメイン名しかなく、利用可能なアドレスがない場合は、ルールに一致しないことがあります。すべてのアドレスルールに追加すると、マッチする機会が変わるため、前にあるドメインルールや最後のフォールバックとあわせて確認しましょう。

GEOIP,CN が判定するのは、アドレスデータベース上の地域です。Webサイトの言語やドメインの登録地を判定するものではありません。CDNを利用するサイトでは、異なる地域のアドレスが返されることがあり、データベースの更新が遅れている場合もあります。特定のサービスに安定した出口を使いたい場合は、地域判定だけに頼らず、明示的なドメインルールを検討してください。Clash GeoIPの更新が必要な場合は、使用中のコアが対応するデータ形式とパスを確認してから、クライアントの更新機能を使いましょう。

ルールが多い場合は、rule-providers で一覧を個別に管理し、RULE-SET から参照できます。プロバイダーの動作タイプと内容の形式は対応している必要があります。たとえば、ドメイン一覧とクラシック形式のルール一覧を自由に混在させることはできません。リモートルールの更新には、ダウンロード先と接続可能性も関係します。ローカルに常に存在するテキストと同じようには扱えません。まず数個のローカルルールで振り分けを確認し、順序が正しいとわかってからルールセットを導入すると、内容の誤りと更新の失敗を切り分けやすくなります。

プロセスルールでは、プログラム名やパスを指定して判定できます。ただし、対応状況はOS、コアの権限、通信の取り込み方法に左右されます。プロセス情報が取得できない状態では、ルールを追加しても機能しない場合があります。モバイル端末とデスクトップOSで同じプロセス識別ルールをそのまま使うことはできません。アプリがコアに取り込まれているか確認するには、まず接続記録にプロセス情報が実際に表示されているかを見てから、この種類のルールを使うか判断してください。

ルールを検証するときは、対象ドメイン、マッチしたルール、プロキシグループ、最終的な出口の4点を記録します。Webサイトはメインページだけでなく、画像、ログイン、APIなどのドメインにもアクセスするため、メインドメインだけではページ全体をカバーできない場合があります。「ページは開くが画像が表示されない」ときは、失敗したリソースの実際のリクエストを確認し、無関係なキーワードにまでルールを広げないでください。よくあるマッチの問題は、FAQのトラブル対処カテゴリも参照できます。症状から原因を絞ってからルール一覧を変更しましょう。

設定の上書きと統合

上書きは元の設定を残したまま別の設定を適用し、最終結果を変更する方法です。統合は複数の設定元をまとめ、コアが実際に読み込む設定を作る処理です。いずれもYAML形式に共通の機能として備わっているわけではなく、クライアントによって処理方法が異なります。ファイル自体にはオブジェクトやリストを記述できますが、「リストの先頭に追加」「ノードを維持」「スクリプトで加工」といった処理は通常、クライアントが実装します。他人の上書き設定を使う場合は、対応クライアントと実行タイミングを確認してください。すべてのソフトが同じ方法で処理するとは限りません。

元の設定と有効な設定は異なる

サブスクリプションの設定は、ダウンロード後にクライアントの基本設定による上書き、ユーザー上書き、スクリプト処理などを経て、最後にコアへ渡されることがあります。処理順序はクライアントの説明で確認してください。変更内容が画面とファイルで一致しない場合は、「実行中の設定を表示」「最終設定をエクスポート」などの機能を探しましょう。ダウンロードした元ファイルを何度開き直しても、クライアントが最後に追加したポート、DNS、ルールの変更を確認できないことがあります。

サブスクリプションのダウンロードファイルを直接編集すると、次回の更新で内容が取得し直され、ローカルの変更が上書きされるおそれがあります。より管理しやすい方法は、サブスクリプションでリモートノードを管理し、個人用のルールやローカル設定は上書きファイルで別に管理することです。クライアントが必要な上書き機能に対応していない場合は、ローカル設定としてコピーできますが、元のサブスクリプションの更新は自動反映されません。どちらを選ぶかは、画面の操作数ではなく、継続的な更新が必要かどうかで判断しましょう。

# 元の設定
dns:
  enable: true
  enhanced-mode: fake-ip
  nameserver:
    - 223.5.5.5

# 期待する最終結果：ほかのキーは維持し、上流リストだけを置き換える
# ここに示すのは結果であり、汎用的な上書き指示ではありません

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

上の例のポイントは、「オブジェクト内のほかのキーを維持する」ことです。クライアントが浅い置き換えを行う場合、nameserver だけを含む新しい dns オブジェクトを適用すると、元の enable や拡張モードまで失われることがあります。再帰的に統合する場合は、それらが維持される可能性があります。断片の見た目だけで統合後の結果を判断しないでください。実際に適用した後、最終的なDNSオブジェクトを展開し、変更していない必要な項目が残っていることを確認しましょう。

リストの置き換えと挿入位置

リストの扱いには特に注意が必要です。rules、proxies、プロキシグループ内の候補はいずれもリストです。統合ツールによって、リスト全体を置き換える場合、連結する場合、名前を基準に要素を処理する場合があります。ルールリスト全体が置き換わると、サブスクリプションにもともと含まれていた振り分けルールが消えることがあります。単純に末尾へ追加するだけでは、カスタムルールが既存の MATCH の後ろに置かれ、一度も一致しない場合があります。必要なのは単に「追加する」ことではなく、「フォールバックを残したうえで、決めた位置に挿入する」ことです。

たとえば docs.example.com を直接接続にする場合、先に一致する可能性のある広範囲なルールより前に、DOMAIN,docs.example.com,DIRECT を挿入します。挿入機能の名称はクライアントによって異なります。「prepend」のようなツール用の設定を、コアの rules リストに直接書かないでください。操作後は最終リストの先頭と末尾を確認し、対象ルールの位置、想定したフォールバックだけがあること、参照先のプロキシグループが残っていることを確認しましょう。

プロキシグループのリストも、配列内の位置だけを基準に上書きしてはいけません。サブスクリプションの更新でメンバーの順序が変わると、以前の2番目のグループが同じ用途とは限りません。名前を基準にした上書き方法のほうが管理しやすいことが多いものの、上流でグループ名が変更された場合への対応は必要です。更新のたびに、重要なグループに候補が残っているか、個人ルールの参照先が有効かを確認してください。候補に固定のノード名を追加した場合は、上流でノードが削除または改名されたときに、設定も更新する必要があります。

ローカルでの管理には、元のサブスクリプションのコピー、個人用の上書きファイル、動作確認済みの最終設定スナップショットの3つを用意するのがおすすめです。問題が起きたら、まず直近の上書きを無効にし、検証済みの設定に戻してから、項目を1つずつ追加し直します。同じタイミングでノード、DNS、ルールをすべて変更すると、どの層が違いを生んだのか特定できません。変更理由は日付だけでなく、「内部ドメインを直接接続」のように具体的に記録しておくと、後で理解しやすくなります。

統合が終わったら、サブスクリプションの更新も一度テストしてください。手動で読み込めたことからわかるのは、現在のファイルが使えるという点だけです。次回のリモート更新後も個人設定が維持されるとは限りません。更新後に対象ルール、DNS、プロキシグループの選択を確認し、想定したタイミングで上書きが実行されたことを確かめましょう。更新後に動作が変わった場合は、クライアントをすぐ再インストールせず、まず最終設定の差分と上流の内容を確認してください。多くの統合問題は、この段階で不足または重複した項目を特定できます。

検証とトラブル対処

設定の検証は、テキストを解析できるか、参照先を読み込めるか、実際の接続が想定どおりか、という3段階で行います。YAMLの構文チェックに通っても、わかるのはインデントや基本的な形式が正しいことだけです。存在しないノード名や未対応のプロトコル項目があれば、コアの読み込み時に失敗することがあります。読み込みに成功しても、アプリがプロキシに接続されていない場合もあります。タイムアウトが起きたときにファイル全体を変更するより、この3段階に分けて調べるほうが確実です。

まず検証してから読み込む

編集後はコピーを保存し、クライアントに設定チェック機能がある場合はそれを使いましょう。コマンドラインを利用でき、mihomoがインストールされている場合は、コアのテストコマンドも使えます。コマンド中のパスは例示用のファイル名なので、実際のファイルがあるディレクトリで実行してください。Windowsでは、インストール先に合わせて対応する実行ファイルを指定します。相対パスで参照されるリソース、ルールファイル、データディレクトリもそろっているか確認しましょう。メインファイルだけをコピーしても、クライアントと同じ環境とは限りません。

mihomo -t -f ./config.yaml

YAMLの解析エラーが出たら、エラー位置の周辺でインデント、コロン、引用符、ハイフンを確認してください。プロキシやプロキシグループが存在しないというエラーなら、名前の参照をたどって定義箇所を探します。項目やプロトコルが未対応と表示された場合は、手当たり次第に削除するのではなく、使用中のコアを確認してください。テストコマンドに通ってから設定を読み込み、起動ログで実際にこのファイルが使われていることを確かめます。コピーを検証している一方で、別のProfileが実行されている事態を防げます。

明確なリクエストで入口を確認する

繰り返しアクセスできるテスト先を1つ選び、ローカルポートを確認したら、プロキシを明示してリクエストを送ります。以下のコマンドでは、例示したポートでローカルの混合ポートが待ち受けており、環境にcurlがインストールされている必要があります。HTTPプロキシ経由でHTTPSサイトにアクセスするため、リクエストがローカルの入口に届くかを確認できます。コマンドが成功しても、システム上のほかのアプリがプロキシを使っているとは限りません。

curl --proxy http://127.0.0.1:7890 --head https://example.com

同時にクライアントの接続記録も確認してください。新しいリクエストがまったく表示されない場合は、ポート、待ち受けアドレス、プログラムの実行状態、別のプロキシに接続していないかを確認します。リクエストが表示されたら、マッチしたルールとプロキシ経路を続けて確認しましょう。ルール、グループの選択、出口が想定どおりの場合に限り、ノードやリモート接続の問題を調べます。ステータスコードは接続先とあわせて判断してください。すべてのサイトがHEADリクエストに通常のページアクセスと同じ応答を返すわけではありません。

ログの「接続拒否」「名前解決失敗」「ハンドシェイク失敗」「タイムアウト」は、それぞれ異なる段階の問題を示します。接続拒否ならポートを待ち受けるサービスがない可能性があります。名前解決に失敗したら、まずDNSの経路を確認します。ハンドシェイク失敗ではプロトコル、認証、TLSを見直してください。タイムアウトは発生した段階をもとに、ネットワークへの到達性を確認します。エラーの最後の行だけでなく、前後の関連ログも残しましょう。共有する前には、サブスクリプションURL、認証情報、公開したくない接続先を必ず削除してください。

Windowsストアアプリだけで問題が起き、同じ入口を使うブラウザーは正常な場合は、UWPのループバック制限を解除する手順をご確認ください。クライアントを起動するとすぐ終了する場合は、起動時のクラッシュを調べるメモに沿って、ログと設定のロールバックを確認しましょう。症状が異なれば対処方法も異なります。問題が起きるたびに再インストールするのは避けてください。古い設定が残る場合がある一方、原因を調べるための情報を失うこともあります。

検証が終わったら、一時的なデバッグ設定を元に戻し、正常に動作する最終設定を保存して、テスト先と変更内容を記録しましょう。次に問題が起きたら、直近で変更した項目から元に戻します。操作の流れを確認し直す場合は使い方ガイドへ、よくある症状を調べる場合はFAQへ、端末に合うクライアントを選び直す場合はダウンロードページへ進んでください。このページでは、入口を確認してから、名前解決、ルール、出口の順に追うのが基本です。