Clash YAML設定ガイド

SECTION 01 / DOCUMENT MODEL

YAMLの構造と設定の読み込み元

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

Clashの設定は、行ごとに実行するスクリプトではありません。待ち受けポートや名前解決の方法、通信の転送先を記述する構造化ドキュメントです。トップレベルの項目が全体の動作を決め、入れ子のマッピングには各機能の設定値を、リストには順序を持つ要素を記述します。読むときは、まずインデント、次に項目名を確認してください。コロンの後の値はその項目に属し、次の行でインデントされた項目は親マッピングの一部です。ハイフンで始まる項目はリスト要素なので、同じ階層のマッピングに置き換えることはできません。

インデントは半角スペース2つに統一し、タブは使わないでください。同じ階層の項目は位置をそろえますが、インデントの深さ自体に優先順位はありません。たとえばdns.enableはdnsの下に置いて初めて意図した意味になります。enableをトップレベルに移すと、ファイルを読み込めてもDNSの設定にはなりません。エラー調査では構文だけでなく、項目がコアの認識する階層にあるかも確認しましょう。

mixed-port: 7890
mode: rule
dns:
  enable: true
  enhanced-mode: fake-ip
  nameserver:
    - https://dns.alidns.com/dns-query
proxies: []
proxy-groups:
  - name: PROXY
    type: select
    proxies:
      - DIRECT
rules:
  - MATCH,PROXY

上の例は構造の確認用です。プロキシグループにはDIRECTしか含まれておらず、リモートプロキシへの接続はできません。proxies: []は空のリストであり、文字列でも項目の欠落でもありません。真偽値にはtrueとfalse、ポートには通常整数を使います。シャープ記号や、コロンの後にスペースが続く文字列、アスタリスクなどの特殊文字を含む値は、引用符で囲むのがおすすめです。数字に見えるパスワードも文字列として保存し、パーサーによる型変換を防ぎましょう。

Profile・サブスクリプション・実行時設定

クライアント上のProfileは設定情報の単位で、ローカルファイルまたはリモートサブスクリプションに関連付けられます。サブスクリプションから取得するYAMLには通常、プロキシ、プロキシグループ、ルールが含まれますが、クライアントが待ち受けポートやシステム連携の設定、上書き結果を加える場合もあります。コアが実際に読み込むのは、これらの入力を処理した後の実行時設定です。サブスクリプションのキャッシュ、元ファイル、上書き内容のどれを編集するかで、影響範囲は異なります。

リモートサブスクリプションの更新時に、キャッシュへ直接加えた変更が置き換えられることがあります。そのため、サブスクリプションで更新する内容と、継続して使いたい設定は分けて管理しましょう。共通のポートやログレベルはクライアント側で一元管理し、個人ルールは継続的に適用できる上書きレイヤーに置くのが適しています。具体的なマージ方法はクライアントの実装によって異なるため、ファイル名だけで設定元を判断できません。差分を比較する場合は、編集画面で開いている内容だけでなく、元のサブスクリプションと最終出力を両方保存してください。

ファイル編集の基本ルール

同じマッピング内で同じキーを重複して定義しないでください。dnsを2つ記述しても、確実に自動マージされるわけではありません。解析方法によってはエラーになったり、一方だけが残ったりします。リゾルバーを追加する場合は、ファイル末尾に同名の項目を追加するのではなく、既存のリストを編集してください。ルールリストも設定元を1つに明確化し、サブスクリプションとローカル変更でトップレベルのrulesが二重に生成されないようにしましょう。

ファイルはUTF-8で保存し、通常の半角コロンとハイフンを使ってください。日本語の句読点は説明文には使えますが、YAMLの構造記号の代わりにはなりません。コメントはシャープ記号から始まり、実行時の項目にはなりません。ただし、引用符の内側にあるシャープ記号は文字列の一部です。例をコピーしたら、まず空白文字、次に内容の参照関係を確認しましょう。画面上の見た目だけでは、エディター内の実際のスペース数は判断できません。

設定ファイルの場所はOS、インストール方法、クライアントの設定によって異なるため、このガイドでは特定のユーザーディレクトリを共通パスとして示しません。クライアントの設定ディレクトリを開く機能やログから場所を確認してください。複数の設定を使う場合は、用途が分かる名前をProfileに付け、現在有効な項目を記録しておきましょう。ローカルファイル、リモートサブスクリプション、設定切り替えの関係は、Profileの基本と複数設定の管理もご覧ください。

SECTION 02 / LISTENERS AND MODE

待ち受けポートと動作モード

プロキシの入口プロトコルと待ち受けアドレス

プロキシポートは、アプリからコアへ接続を渡すための入口です。portはHTTPプロキシ、socks-portはSOCKS、mixed-portは同じポートでHTTPとSOCKSの両方を受け付けます。一般的なデスクトップ利用なら混合ポートで十分ですが、クライアントが実際にどの項目を書き込んでいるか確認してください。Webサービスのアドレスをプロキシポートに設定したり、コントローラーの接続先をプロキシの入口として使ったりすると、プロトコルが一致しません。

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

この設定では、プロキシとコントローラーへの接続をローカルホストに限定しています。他のデバイスから使う場合は、待ち受けアドレス、allow-lan、OSのファイアウォール、アクセス制御をまとめて検討してください。1つの設定だけを変えても不十分です。すべてのネットワークインターフェースで待ち受けると、より多くの接続元からサービスにアクセスできるようになります。特にコントローラーをインターネットに直接公開しないでください。遠隔管理が必要な場合は、認証を設定し、アクセス可能なネットワークを制限しましょう。

ルール・グローバル・ダイレクトの違い

mode: ruleはルールリストに従って接続先を決めます。ドメインやアドレス、ルールセットごとに通信を振り分けたい場合に適しています。mode: globalは、コアに入った接続をグローバルポリシーで処理しますが、システム上のすべてのアプリを自動的に経由させるわけではありません。mode: directは、コアに入った接続を宛先へ直接送ります。プロキシの入口を通る処理は行われるため、クライアント自体を終了するモードではありません。

モードとシステムプロキシは別の設定です。モードは接続がコアに入った後の転送方法を決め、システムプロキシはOSの設定に従うアプリから入口へリクエストを送るかどうかを決めます。独自のプロキシ設定を使うアプリや、システムプロキシを無視するアプリもあります。特定のアプリだけ挙動が異なる場合は、まず入口がそのアプリを対象にしているか確認し、その後にルールを確認してください。ブラウザーでアクセスできても、他のアプリが同じ経路を通っているとは限りません。

ポート変更とプロセスごとの設定

混合ポートを変更したら、アプリ側のプロキシアドレスも更新してください。クライアントがシステムプロキシを管理していても、ブラウザー拡張、ターミナルの環境変数、開発ツールに固定したポートまで自動で変わるとは限りません。クライアントは正常に動作しているのに、ターミナルだけ旧ポートへ接続するケースもあります。HTTP_PROXY、HTTPS_PROXY、ALL_PROXYの実際の値と、アプリ内に個別保存されたプロキシ設定をそれぞれ確認してください。

ポート競合は、指定したローカルアドレスとポートの組み合わせがすでに使われている状態です。終了していない古いコアプロセスが原因の場合もあります。まず重複して起動したクライアントを終了し、使用中のプロセスを確認してください。すべての待ち受けポートを手当たり次第に変更するのは避けましょう。ログに権限エラーが明記されている場合は、実行権限やOSによるポート予約を確認します。ポート番号に接続品質の優劣はありません。アプリ間の設定の一致と、ローカル環境での利用可否を基準に選びましょう。

ログレベルは通常infoにし、ルールのマッチ状況を追うときだけ短時間debugに切り替えるのがおすすめです。詳細ログにはアクセス先が含まれる場合があります。共有する前に、サブスクリプションのURL、認証情報、個人のアクセス履歴を削除してください。初回インストール時のポートやシステムプロキシの確認は、初回インストールと初期設定を参考にしてください。ローカルの入口の問題に対処するために、サブスクリプション全体を置き換える必要はありません。

SECTION 03 / NAME RESOLUTION

DNS名前解決とFake-IP

DNS項目の役割

DNS設定は、ドメイン名を接続やルール判定に利用できる情報へ変換します。dns.enableはコアのDNS機能を有効にし、listenは問い合わせを受け付けるローカルアドレスを指定、nameserverは通常の上流DNSを列挙します。DNSを有効にしただけで、システム内の問い合わせがすべてコアへ送られるわけではありません。システムDNS、アプリ内蔵の暗号化DNS、TUNのDNSハイジャック設定などによって、問い合わせ経路は変わります。

default-nameserverは、DNS上流のドメイン名を解決し、依存関係を起動するためによく使われます。たとえば上流をHTTPSのドメイン名で指定する場合、まずそのドメイン名のIPアドレスが必要です。すべての問い合わせで優先される万能な項目ではありません。混同しやすいproxy-server-nameserverは、プロキシサーバーのドメイン名解決に使います。プロキシ接続に必要な名前解決の経路を分けて指定できます。

dns:
  enable: true
  listen: 127.0.0.1:1053
  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"
    - localhost

この例はローカルDNSサービスの設定であり、システム全体の通信を取り込む設定は含みません。上流アドレスは、利用するネットワークから到達できるものを選んでください。暗号化通信を使うアドレスでも、すべてのネットワークから接続できるとは限りません。ローカルの待ち受けポートを変更した場合は、OSや転送プログラムもそのポートへ問い合わせを送れる必要があります。一般的なシステムDNS設定では、アドレスだけを指定し、独自ポートを設定できない場合があります。

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

Fake-IPモードでは、ドメイン名にコアが識別する仮想アドレスを割り当て、対応関係を保持します。例にあるアドレス範囲は内部マッピング用で、実際のWebサイトの接続先やリモートサーバーとして使うものではありません。リクエストがコアに入ったとき、ドメイン名と安定して関連付けられるのが利点です。ただし、アプリとシステムの名前解決が同じコアインスタンスを通っている必要があります。

redir-hostモードは実際の名前解決結果を返すため、Fake-IPとは処理経路が異なります。実IPアドレスを必要とするローカルサービスにはこちらが向く場合もありますが、モードの切り替えはDNS障害全般に使える解決策ではありません。まず、問い合わせ自体の失敗、マッピングの不整合、アプリによるコアの迂回のどれが原因かを確認しましょう。切り替え後はOSやアプリに残ったDNSキャッシュも確認してください。以前の結果が新しい接続に影響することがあります。

fake-ip-filterは、特定のドメインに仮想アドレスを割り当てないための設定です。互換性に問題があるローカルドメインやサービス検出用ドメインなどに利用します。広範囲に設定するとドメイン名のマッピング効果が弱まるため、影響が確認できたドメインから追加し、一般的なサフィックスをまとめて登録するのは避けてください。フィルターのマッチ条件は、利用中のコアのドキュメントで確認しましょう。通常のドメイン一覧が、任意形式のルールセットとして使えるとは限りません。

名前解決から通信振り分けまでの経路

DNSリクエスト自体もルールに従わせる場合は、上流への接続がどの経路で送信されるかも確認してください。respect-rulesはDNS接続にルーティングルールを適用しますが、プロキシサーバーの名前解決方法も明確にする必要があります。さもないと、プロキシ接続に名前解決が必要なのに、その名前解決にはプロキシが必要という循環依存が起きることがあります。この項目を追加する前に、上流DNSの名前解決、プロキシのハンドシェイク、接続先へのアクセスの順序を整理しましょう。

nameserver-policyでは、ドメインの条件に応じて使用するDNSを指定できます。これは名前解決の経路を選ぶ設定であり、該当サイトへのアクセスルールを自動的に作るものではありません。DNSの振り分けと接続の振り分けは別の段階です。前者はDNSサーバー、後者は通信の出口を選びます。あるドメインの名前解決に特定のDNSを使っていても、接続が同じ出口を通るとは限りません。一貫した動作が必要なら、両方の設定を確認してください。

調査では、まず到達可能な上流DNSを1つだけ設定して基本的な問い合わせを確認し、その後にポリシーやフィルターを段階的に追加してください。LAN内の名前を解決できない場合は、ルーターやローカルDNSの役割を確認しましょう。すべての問い合わせをパブリックDNSに送るのは適切とは限りません。ブラウザーとコマンドラインで結果が異なるときは、それぞれのキャッシュを消去し、独自の名前解決設定も確認してください。DNSはポートやモードと同時に変更せず、段階を分けましょう。ログと挙動の変化を設定変更に対応付けやすくなります。

SECTION 04 / OUTBOUND DEFINITIONS

プロキシ項目とリモートプロバイダー

共通項目とプロトコル項目を分けて確認

proxiesには、選択可能な送信先プロキシを定義します。通常は名前、プロトコルの種類、サーバーアドレス、ポートが必要で、プロトコルに応じてパスワードやユーザーID、トランスポート設定を追加します。名前は設定内で参照するための識別子なので、プロキシグループのメンバー名と一致させてください。サーバー項目は実際の接続先を示し、名前の代わりにはなりません。説明用の情報を実際に使えるサービスと誤認しないよう、この節ではプロトコル項目の例のみを示し、接続用の完全な項目は掲載しません。

typeによって、コアが後続の項目をどのプロトコルとして解釈するかが決まります。複数のプロトコルでserverとportを共用できても、認証項目は使い回せません。パスワードが必要なタイプ、ユーザーIDが必要なタイプ、暗号化方式の指定が必要なタイプなどがあります。別のプロトコル用の項目をそのまま残すと、無視されたり、設定の読み込みに失敗したりすることがあります。

# Shadowsocksのプロトコル項目のみを表示。完全なプロキシ設定ではありません
type: ss
server: proxy.example.com
port: 443
cipher: aes-128-gcm
password: "your-password"
udp: true

ドメイン名とパスワードは説明用です。実際に使う場合は、サービス提供元が指定するプロトコルと設定値をそろえてください。ポート番号だけでプロトコルを推測することはできません。443はよく使われるサーバーポートの1つですが、TLSが有効とは限りません。udp: trueは関連機能を許可する設定です。利用可否はプロトコル、サーバーの実装、通信経路にも左右され、すべてのアプリのUDP通信が使えることを保証するものではありません。

TLSとトランスポートの設定

TLSに対応したプロトコルでは、接続先アドレスと証明書の検証に使う名前が異なる場合があります。servernameは通常、ハンドシェイクで使用するサーバー名を指定します。サービスの設定と証明書に合わせてください。skip-cert-verifyは証明書の検証を制御しますが、接続できないときの常用の回避策ではありません。証明書エラーの原因には、ドメイン名の誤り、システム時刻のずれ、サーバー側の証明書チェーンの不備などがあります。検証を無効にすると、こうした問題を隠してしまいます。

WebSocketやHTTPなどのトランスポート設定は、通常、プロトコルが対応する入れ子の項目に記述します。パス、リクエストヘッダー、ハンドシェイク名はそれぞれ別の項目であり、ドメイン名のように見えるからといって置き換えることはできません。サービス提供元から元のYAMLを受け取った場合は、まずプロトコル部分の構造を保ち、次にコアが各オプションに対応しているか確認してください。サブスクリプションの変換時に拡張項目が欠落することがあるため、元のリンクでは接続でき、変換後に失敗する場合は構造を比較しましょう。

proxy-providersの役割と適用範囲

proxy-providersはリモートのプロキシ項目を独立したリソースとして管理し、プロキシグループからuseで参照します。完全なProfileのサブスクリプションとは異なる階層です。完全な設定にはDNS、ルール、グループなども含まれますが、プロキシプロバイダーのデータは指定された形式に従う必要があります。完全なサブスクリプションのURLをそのままプロバイダーに指定しても、コアがプロキシ一覧として読み込めるとは限りません。

proxy-providers:
  REMOTE:
    type: http
    url: "https://example.com/proxies.yaml"
    path: ./providers/remote.yaml
    interval: 86400
proxy-groups:
  - name: PROXY
    type: select
    use:
      - REMOTE

ここでのREMOTEはプロバイダーの識別子であり、個別のプロキシ項目ではありません。例のURLから実際の設定は取得できません。自分がアクセス権を持ち、対応する形式のリソースに置き換えてください。intervalの単位は秒で、リソースの更新間隔を表します。プロキシグループの疎通確認間隔とは役割が異なります。pathはキャッシュの保存先です。アクセス可能な範囲はコアの作業ディレクトリやパスのセキュリティ制限にも左右され、デスクトップクライアントがファイルを別途管理する場合もあります。

プロバイダーのダウンロードに失敗した場合は、まずURLにアクセスできないのか、認証が無効なのか、Webページが返っているのか、YAMLの構造が要件に合わないのかを確認してください。キャッシュが残っていると古い内容が使われるため、画面にメンバーが表示されていても更新に成功したとは限りません。リモートサブスクリプションのURLにはアクセス情報が含まれることが多いため、スクリーンショットや公開ログに載せないでください。インポート形式の違いと操作手順は、サブスクリプションURLのインポートと形式をご覧ください。

SECTION 05 / POLICY GRAPH

プロキシグループの項目と参照関係

プロキシグループは通信を取り込む入口ではない

proxy-groupsは、利用可能な出口をまとめて参照できるようにします。ルールの接続先にプロキシグループを指定し、そのグループからプロキシ、組み込みアクション、または参照可能な別のグループへ接続できます。ここで決めるのは、接続がグループに到達した後の次の経路です。アプリからプロキシを使い始める設定ではありません。アプリのリクエストがコアに入っていなければ、グループを詳しく設定しても効果はありません。

各グループには重複しない安定したnameを付け、typeで選択方式を指定します。selectは手動選択で、出口を明示的に制御したい場合に適しています。url-testは疎通確認の結果に応じてメンバーを選択し、fallbackはメンバーの順序に沿って利用可能な出口を維持します。load-balanceは指定した方式で接続を振り分けます。選択の仕組みは、画面上の並び順だけでは判断できません。

proxy-groups:
  - name: PROXY
    type: select
    proxies:
      - DIRECT
      - REJECT
rules:
  - DOMAIN-SUFFIX,example.com,PROXY
  - MATCH,DIRECT

これは参照関係を理解するための例です。DIRECTは直接接続、REJECTは拒否を表し、後者を選ぶとこのグループに一致したリクエストが拒否されます。どちらもコアの組み込みターゲットなので、proxiesに追加で定義する必要はありません。実際の設定では、使用可能なプロキシをグループに追加できます。ただし、未定義の名前をリストに書いても、コアが自動的に作成することはありません。

メンバーの参照元と疎通確認の設定

proxiesはメンバーを直接列挙し、useはプロキシプロバイダーを参照します。固定された構成には直接指定が、独立して更新するリソースにはプロバイダーが適しています。両方を組み合わせる場合は、使用中のコアがどのようにグループメンバーを処理するか確認し、プロバイダーの読み込みも確かめてください。グループが画面に表示されていても、選択可能なメンバーがあるとは限りません。プロバイダーが空、絞り込み条件が厳しすぎる、リソースを読み込めないといった理由で、グループが空になることがあります。

自動選択タイプでは通常、urlやintervalなどの疎通確認用項目が必要です。確認先には、安定していて応答が軽く、目的の経路からアクセスできるHTTPサービスを指定してください。確認結果が示すのは、そのURLへのリクエスト状況だけです。すべてのWebサイト、認証フロー、アプリのプロトコルが使えることを保証するものではありません。確認先がネットワークポリシーでブロックされると、実際には使えるメンバーが利用不可と判定されることもあります。

toleranceなどの項目は頻繁な切り替えを抑えるために使いますが、適切かどうかはグループの種類と使用中のコアによって異なります。画面の表示を素早く変えるために、確認間隔を短くしすぎないでください。高頻度の確認は余計なリクエストを発生させ、不安定なネットワークでは選択が頻繁に揺れることもあります。調整前に、自動で最適な出口を選びたいのか、予備の出口を維持したいのか、接続を振り分けたいのかを明確にしましょう。細かな値の調整より、まず選択方式を決めることが重要です。

グループの階層化と循環参照

グループを階層化すると、ユーザーによる出口選択とルール分類を分けられます。たとえば、ルールから安定した用途別グループを参照し、そのグループから共通の手動選択グループへ接続できます。リモートリソースが変わっても、ルールを1つずつ変更せずに済みます。ただし階層が深いほど原因の特定は難しくなります。各階層の役割を明確にし、同じ転送を繰り返すだけのグループを重ねないようにしましょう。

グループ同士を循環参照させないでください。グループAがグループBを参照し、グループBがAに戻ると、出口までの経路を確定できません。大規模な設定では、直接参照していなくても第三のグループを介して循環することがあります。ルールの接続先から順に参照をたどり、実際のプロキシまたは組み込みアクションに到達するか確認しましょう。すべての経路に終点があり、通過済みのグループへ戻らないことが必要です。

ログイン状態を維持するサービスで新しい接続を分散すると、出口が変わり、追加認証が求められることがあります。接続の振り分けを標準的な最適化と考えず、アプリの要件に応じて安定した経路を選んでください。グループの選択を変更しても、既存の接続は通常自動で移行しません。変更後の選択は新しい接続から使われます。検証時は対象アプリの既存接続を閉じて再試行し、ルールのマッチ結果と最終的な出口も確認してください。古いセッションを設定未反映と誤認しないようにしましょう。

SECTION 06 / FIRST MATCH

ルール構文とマッチ順序

先に一致したルールを適用し、最後にフォールバック

ルールモードでは、コアがrulesを上から順に確認します。最初に一致したルールの接続先が使われ、後続のルールとの精度比較は行われません。そのため、優先順位を決めるのは位置であり、ルール名やドメインの長さではありません。明確な例外を先頭、一般的な分類を中ほど、フォールバックを最後に置く構成がよく使われます。

多くのルールは、種類、条件、接続先をカンマで区切って記述します。MATCHにはマッチ条件がなく、残りの接続に適用する接続先を指定します。その前にあるルールで個別の分類を行い、後ろのルールは通常マッチする機会がありません。特定のルールが効かない場合は、同じルールを追加するのではなく、前にあるルールが先に一致していないか確認してください。

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

このルールは、PROXYという名前のプロキシグループがすでに存在することを前提としています。LANアドレスの例は、すべてのプライベートネットワーク範囲を網羅していません。実際のネットワークに応じて追加してください。GEOIPは対応する地理データが利用可能である必要があり、分類はサービス運営主体の所在地と一致するとは限りません。明確な用途がある場合は、地理情報だけに頼らず、説明しやすいドメインやアドレスのルールを優先しましょう。

ドメインルールとIPアドレスルールの違い

DOMAINは完全一致で、特定のホストに例外を設ける場合に適しています。DOMAIN-SUFFIXは指定したドメインとそのサブドメインに一致し、サービス全体を対象にできます。DOMAIN-KEYWORDはキーワードで判定するため、意図した範囲を超えやすく、慎重に使う必要があります。ルール条件には通常、プロトコル、URLパス、ポートは指定しません。完全なWebページのURLをドメイン条件に書いても、パス単位のマッチにはなりません。

IP-CIDRとIP-CIDR6は、接続先アドレスが指定範囲に含まれるかで判定します。ドメイン名で開始されたリクエストでは、IPルールによって名前解決が行われる場合があります。no-resolveは、そのルールが名前解決を開始するのを防ぐ設定であり、通信経路全体でDNSを使わなくするものではありません。接続先IPがすでに分かっていればアドレスを照合できますが、ドメイン名しか分からない場合は、このルールでは判定できないことがあります。

同じサイトでも複数のドメインを使うことがあり、静的リソース、ログイン、APIのリクエストで共通のサフィックスを使うとは限りません。トップページのドメインだけにルールを追加しても、利用中のすべての通信が同じ経路を通るとは限りません。調査時は、Webページが表示できたかだけでなく、失敗したリクエストを確認してください。IPアドレスへ直接接続するアプリでは、ドメインルールに必要な情報がない場合があります。実際の接続先に応じてポリシーを決めましょう。

ルールプロバイダーとデータ形式

rule-providersは個別に更新できるルールセットを管理し、メインのルールリストからRULE-SETで参照します。プロバイダーはマッチ条件を保持し、メインルールは適用する位置と接続先を指定します。ダウンロードに成功しても、メインルールから参照されなければマッチには使われません。フォールバックより後ろに参照を置いた場合も、意図した動作にはなりません。

rule-providers:
  LOCAL-DOMAINS:
    type: inline
    behavior: domain
    payload:
      - "+.example.com"
rules:
  - RULE-SET,LOCAL-DOMAINS,DIRECT
  - MATCH,PROXY

この例では外部ファイルへの依存を避けるため、ドメイン集合を設定内に記述しています。behavior: domainのデータはドメイン条件を表し、接続先まで含む完全なルール行をそのまま入れるものではありません。ipcidrとclassicalではデータの形式が異なります。リモートリソースの内容を宣言した形式に合わせてください。プロバイダーの種類や形式を変更する場合は、項目名だけでなくデータの中身も確認しましょう。

ルールを整理する際は、ローカルで追加した各ルールの理由を記録し、上位のルールに覆われた重複項目を定期的に削除しましょう。複数の上書き処理でメインルールを順不同に追加すると、最終的な順序が分かりにくくなります。ルールの種類、並べ替え例、マッチ状況の詳しい解説は、Clashカスタムルールの構文と優先順位をご覧ください。このページの後半では、サブスクリプション更新後も個人ルールを維持する方法を説明します。

SECTION 07 / CONFIGURATION PIPELINE

設定の上書き・マージ・更新時の注意

クライアント処理とコアの設定項目を区別

上書きとは、元の設定に変更を適用するクライアント側の処理であり、すべてのYAMLファイルに共通するトップレベル項目ではありません。Clash Nyanpasuでは、設定生成時にクライアント管理項目、設定のマージ、スクリプト処理などが行われる場合があります。上書きの画面、実行順序、利用できる構文はクライアントごとに異なります。あるクライアント独自の拡張設定を、そのままmihomoの設定としてコアに渡すことはできません。

上書きの仕組みを理解するには、入力、変換、出力を分けて考えます。入力はサブスクリプションやローカルProfile、変換は項目の上書き、リストの操作、スクリプトによる変更です。出力された設定がコアに読み込まれます。調査時には変更がどの段階で行われるかを確認し、最終出力を見てください。上書きの編集欄に目的の項目があっても、後続の処理で再び上書きされていないとは限りません。

# 通常の項目マージに対応する上書き機能向け
mode: rule
log-level: info
dns:
  enable: true
  enhanced-mode: fake-ip

この例は、指定した項目値を維持する方法を示していますが、すべてのクライアントが同じマージ方法を採用するとは限りません。マッピングを再帰的にマージする実装もあれば、オブジェクト全体を置き換える機能もあります。dns全体が置き換わると、サブスクリプションにある上流リスト、フィルター、ポリシーも消えることがあります。適用後はenableが有効になったかだけでなく、最終的なdnsオブジェクト全体を確認してください。

リストの追加・先頭挿入・置き換え

マッピングのマージとリストのマージは分けて理解しましょう。待ち受けポートは単一の値なので、通常はそのまま上書きできます。一方、ルールやプロキシグループは構造を持つリストです。全体の置き換え、追加、先頭への挿入、スクリプトによる処理など、実際の動作は機能によって異なります。短いrulesリストを書いても、サブスクリプションの残りの項目が自動で保持されるとは限りません。置き換え方式の場合、元の分類ルールがすべて消える可能性があります。

ルールでは順序が特に重要です。個人用の例外は通常、一般ルールより前に置きます。MATCHの後ろに追加しても、期待どおりにはマッチしません。プロキシグループを変更するときは、重複した名前を追加するのではなく、一意な名前で対象を特定してからメンバーを編集してください。自動更新する設定の上書き処理は、同じ入力に繰り返し適用しても重複ルールやメンバーが増えないよう、冪等に設計する必要があります。

サブスクリプション更新と個人設定を分ける

サービス提供元が管理するプロキシ項目やリソースは、サブスクリプション側に任せるのが適しています。ローカルのポート、ログの設定、用途が明確な個人ルールはローカルで管理しましょう。ただし、すべてのローカル設定でサブスクリプションを上書きする必要はありません。サービス提供元のプロトコル設定を古い値で固定すると、更新後に認証やトランスポートの互換性が失われることがあります。上書きは必要な差分だけに限定してください。

スクリプトによる変更は通常の項目マージより柔軟ですが、適用範囲の確認も重要です。処理前に対象の配列が存在するか確認し、目的のグループを見つけてから変更してください。対象が見つからない場合に、不完全なオブジェクトを黙って作成してはいけません。リモート設定の更新では、グループ名の変更がよく起こります。スクリプトは分かりやすいエラーを返すか安全に処理をスキップし、読み込めない実行時設定を生成しないようにしましょう。処理順を変更した場合は、参照関係も再検証してください。

変更前に、正常に動作するProfileと上書き設定のバックアップを保存してください。サブスクリプションの認証情報を含むファイルを公開リポジトリへコミットしないように注意しましょう。バックアップには設定の読み込み元、個人ルール、必要なクライアント設定を含めてください。一時生成された実行時ファイルだけでは、元の更新関係まで復元できない場合があります。「DNSだけを変更する」「ルールを1つだけ先頭に追加する」など、変更の目的を記録しておくと、問題が起きたときに戻す範囲を絞れます。

上書きを適用した後は、3段階で検証します。まずYAMLを解析できるか、次にグループとプロバイダーの参照関係が正しいか、最後に新しい接続で実際の動作を確認してください。更新後に突然動作しなくなった場合は、リソースの変更点と上書きの対象が現在も存在するかを比較します。すべての個人設定をすぐに削除する必要はありません。処理を1つずつ無効にして競合箇所を特定する方が、サブスクリプション、コア、クライアントを同時に置き換えるより有効な情報を残せます。設定元の基本については、Profileの管理ガイドもご覧ください。

SECTION 08 / VALIDATE AND ISOLATE

設定の検証とトラブルシューティング

出力設定を検証してから通信を確認

設定は構文、意味、実行時の動作の3段階で確認します。構文チェックではインデント、引用符、リスト構造を確認します。意味のチェックでは項目の対応状況、プロキシグループの参照、リソース形式を確認します。実行時のチェックではポート、ネットワークの到達性、実際のルールマッチを確認します。1段階を通過しても、次の段階を省略できるわけではありません。特にリモートリソースが未読み込みの場合や、システムプロキシが有効でない場合は、ファイルを読み込めてもアプリが使えるとは限りません。

mihomoを直接実行できる場合は、テスト用の引数で指定ファイルを検証できます。クライアントで実際に使っているコアを使用し、相対パスのリソースを正しく参照できるよう、同じ作業ディレクトリか明示したデータディレクトリでテストしてください。デスクトップクライアントに設定のテスト機能や実行時設定の表示機能がある場合は、そちらを優先しましょう。別のプロセスを起動して、稼働中の待ち受けサービスと競合させるのを避けられます。

# 設定ファイルのあるディレクトリで実行し、実行ファイルの場所に合わせてコマンドを調整してください
mihomo -t -f ./config.yaml

# Windows PowerShell。カレントディレクトリに実行ファイルがある場合
.\mihomo.exe -t -f .\config.yaml

テスト出力の行番号は、通常、解析に失敗した箇所を指します。ただし、実際の原因が直前の行にあることもあります。たとえば、引用符の閉じ忘れやインデントの誤りです。最初に表示された明確なエラーを確認して再テストし、同じ問題が引き起こした複数のメッセージを見て何度も修正しないようにしましょう。項目が未対応と表示された場合は、別の階層へ移して試すのではなく、コアの種類とオプションの対応状況を確認してください。

接続経路に沿って原因を絞り込む

まずクライアントとコアが正常に起動し、ログに待ち受けエラーがないことを確認します。次に、アプリが正しいプロキシアドレスへ接続しているかを確認し、必要なら明示的なプロキシ設定でテストします。続いてDNSが想定した経路で接続先を解決できるかを調べます。その後、ルールとプロキシグループの最終的な判定を確認します。最後にリモートプロトコルのハンドシェイクとサーバーの応答を調べます。この順序なら、ローカル設定の問題とリモート接続の問題を切り分けやすくなります。

# ローカルのHTTPプロキシ入口と、その後のリクエスト経路だけを確認
curl --proxy http://127.0.0.1:7890 --head https://example.com

# SOCKSテストでは、接続先ドメインの名前解決をプロキシ側で行う
curl --proxy socks5h://127.0.0.1:7890 --head https://example.com

このコマンドを実行するにはcurlがインストールされており、ポート番号が実行時設定と一致している必要があります。テスト用サイトはリクエスト経路の確認に使います。コマンドに失敗しても、その情報だけで設定全体が無効だと判断しないでください。接続拒否ならまずローカルの待ち受けを、名前解決エラーならDNSを確認します。プロキシのハンドシェイクエラーなら、入口のプロトコルと認証を確認してください。エラーが起きる段階によって対処方法は異なります。

OSごとの違いと最小限のロールバック

Windowsのシステムプロキシやファイアウォール、macOSのサービス権限、Linuxデスクトップ環境のプロキシ設定は、通信を取り込める範囲に影響しますが、YAMLの基本階層は変わりません。OSから通知が表示された場合は、ルールリストではなくインストールや権限の問題を確認してください。macOSの設定手順は、インストール許可とキーチェーンの通知への対処を参考にしてください。必要な権限はインストール方法によって異なります。

最小限のロールバックは、すべての設定を削除することではありません。直近の変更だけを戻し、問題の手がかりを残すことです。まず追加した上書き処理を無効にし、次に項目を1つずつ元に戻します。最後に必要な場合のみ、バックアップしたProfileへ切り替えてください。変更する変数は毎回1つにし、新しい接続で同じテストを繰り返します。クライアント、コア、サブスクリプションを一度に更新すると、どの変更が結果に影響したのか判断しにくく、問題を再現することも難しくなります。

トラブルシューティング情報を共有する際は、エラーメッセージ、項目の階層、操作の順序を残し、サブスクリプションURL、パスワード、認証情報、個人のアクセス先は削除してください。スクリーンショットだけではエラーの内容を正確に伝えられませんが、設定全体をそのまま公開するのも避けましょう。原因の特定後は通常のログレベルに戻し、一時的なテストルールを削除して、最終的に有効だった変更を記録してください。項目の概念は用語ガイドで確認できます。インポートから検証までやり直す場合は、クイックスタートガイドへ戻り、設定リファレンスと初回利用の手順を混同しないようにしましょう。