Clashの応用設定ガイド：プロキシグループ・DNS・TUN

プロキシグループの種類と活用

プロキシグループは、ルールと実際の接続先の間にある中間層です。ルールにノード名を一つずつ直接指定する代わりに、安定したグループ名を指定し、グループ内で手動選択、自動選択、フェイルオーバーを設定します。サブスクリプションの更新でノード名が変わっても、グループ名とプロバイダーへの参照が維持されていれば、振り分けルールを書き直す必要はありません。設計を始める前に、ノードは接続先、プロバイダーはノードの収集元、プロキシグループは接続先の選択を担うという違いを把握しましょう。名前は自由に付けられますが、参照先と完全に一致させる必要があります。スペースや大文字・小文字にも注意してください。

手動選択と自動切り替えを使い分ける

selectは接続先を固定したいサービスに適しています。プロキシ画面でグループ内のメンバーを選ぶと、コアはその接続先を使用します。url-testはテスト用URLへ定期的にアクセスし、利用可能なメンバーの中から応答の速い接続先を選びます。toleranceはわずかな差による頻繁な切り替えを抑えるための設定で、ノードの品質を評価するものではありません。fallbackはメンバーの順に利用可能な接続先を探すため、メイン回線と予備回線の構成に適しています。load-balanceは複数の接続に接続先を振り分けますが、単一接続の帯域を合算するものではなく、リクエストごとに同じ接続先を使う保証もありません。

ログイン、決済、セッションの維持が必要なサービスでは、毎回の測定結果を追うより手動選択グループを優先しましょう。自動グループが切り替わっても、確立済みの接続は通常すぐには移行せず、新しい接続から切り替え後の接続先が使われます。そのため、ブラウザーで同じページを開いていても、一部のリソースが一時的に異なる接続先から読み込まれることがあります。このような場合は、まず接続先を一つに固定し、既存の接続を閉じてページを開き直してから、サービス側が接続先の変更を制限しているか確認してください。ページの読み込みに一度失敗しただけで、ルールの構文が原因と決めつけないようにしましょう。

日常的な選択と自動候補を2段構成にする

以下の例では、proxy-providersにprimaryという名前のプロバイダーが設定済みであることを前提とします。具体的な追加方法は設定の上書きの章をご覧ください。自動グループはプロバイダーのメンバーを参照し、上位の手動グループでは自動選択の結果と直接接続を選べます。テストURLは接続確認用の接続先であり、サブスクリプションのURLではありません。アクセスの成否は、接続先、DNS、アクセス先サービスの方針に左右されます。intervalの単位は秒です。短くしすぎると測定リクエストが増えるため、特にバックグラウンド動作に制限のあるモバイル端末では注意してください。

# 設定例：既存のprimaryノードプロバイダーを使用
proxy-groups:
  - name: 自動候補
    type: url-test
    use:
      - primary
    url: https://www.gstatic.com/generate_204
    interval: 300
    tolerance: 50
    lazy: true
  - name: 通常の接続先
    type: select
    proxies:
      - 自動候補
      - DIRECT

rules:
  - MATCH,通常の接続先

グループは相互に参照できますが、循環参照は作れません。たとえば、通常の接続先が自動候補を含み、自動候補が通常の接続先を参照すると、最終的な接続先を決定できません。確認するときはルールの参照先からたどり、実際のノードまたはDIRECTまで追跡します。クライアントにグループのメンバーが表示されない場合は、まずプロバイダーの読み込み状況を確認し、次にフィルターですべてのノードが除外されていないか調べてください。メンバー不足を隠すために、グループをさらに多段にしないでください。クライアントによっては前回の選択を記憶しますが、名前が変わると既定のメンバーに戻る場合があります。サブスクリプション更新後は重要なグループを再確認しましょう。

測定結果と実際のアクセスを分けて確認する

プロキシ画面の測定結果から分かるのは、特定の接続先から指定されたテスト先へアクセスしたときの状態だけです。実際のアプリでは異なるドメインやポート、UDPを使う場合があるため、すべての通信が使えるとは判断できません。プロキシグループを検証するときは、接続画面で適用されたルール、最終的な接続先、宛先ホストを確認してください。自動グループは正常でも動画やゲームに問題がある場合は、メンバーを固定してから、対応プロトコルやサービスの地域制限を確認します。画面上の操作はプロキシ選択ガイドをご覧ください。接続先を長期的に固定するグループは、多段の自動選択を増やすより、明確な手動選択経路を残すほうが管理しやすくなります。

ルールセットのサブスクリプション管理

ルールをrule-providersにまとめると、ルールの内容と通信の振り分けを分けて管理できます。プロバイダーはドメイン、IPアドレス、クラシックルールのリストを読み込みます。rulesではRULE-SETを使い、ルールに一致した場合の接続先を指定します。ルールセット自体がプロキシ接続か直接接続かを決めるわけではありません。同じリストを異なる設定で別々のプロキシグループに割り当てることもできます。管理では、ファイル形式が正しく解析されるか、更新が安定しているか、全体のルール一覧で優先順位が適切かを確認しましょう。サブスクリプション化で編集の重複は減らせますが、ルールの競合が自動的に解決されるわけではありません。

behaviorとformatをファイルの内容に合わせる

behavior: domainはドメインルールの集合、ipcidrはIPアドレス範囲の集合、classicalはルール種別を含むクラシックルールの集合を表します。formatはファイル形式を示し、一般的にはYAMLまたはプレーンテキストを指定します。YAMLでは通常、payload階層が必要です。ファイル名が.yamlで終わるからといって、内容も条件を満たすとは限りません。ノードやプロキシグループを含む完全なサブスクリプションをルールプロバイダーに指定することもできません。読み込みエラーが出たら、拡張子だけを変更するのではなく、実際のファイルを開いて先頭行、インデント、各項目を確認してください。

まずローカルルールセットで、動作を検証できる最小構成を作りましょう。以下の2つの例は、メイン設定ファイルと独立したルールファイルに分かれています。パスはコアの設定ディレクトリを基準に解決されます。GUIクライアントで実際に使われるディレクトリは、設定管理画面や実行ログで確認してください。このルールセットには、直接接続にするドキュメント用ドメインのみを記載しています。ルール全体では、ローカルネットワーク向けのルールと最後のフォールバックも残します。例にある「通常の接続先」は前章のプロキシグループを使用します。グループがない場合は先に追加してください。このコードだけを完全なサブスクリプションとして読み込むことはできません。

# メイン設定の例
rule-providers:
  local-domains:
    type: file
    behavior: domain
    format: yaml
    path: ./rules/local-domains.yaml

rules:
  - IP-CIDR,127.0.0.0/8,DIRECT,no-resolve
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - RULE-SET,local-domains,DIRECT
  - MATCH,通常の接続先

# 独立ファイル：rules/local-domains.yaml
payload:
  - '+.example.com'
  - '+.example.org'

リモート更新に備えて、元に戻せるローカル設定を残す

リモートプロバイダーではtype: httpを使用し、url、path、intervalを設定します。URLは内容の形式を確認できるルールソースを指定してください。キャッシュ用パスを別のプロバイダーと共有すると、ダウンロード内容が互いに上書きされることがあります。初回起動時、ルールセットのダウンロードにプロキシが必要で、そのプロキシの確立には未読み込みのルールが必要だと、起動時に依存関係の問題が生じる可能性があります。重要な初期接続先への経路を確保し、基本的なローカルルールも残してください。更新失敗後にキャッシュが使われ続けるかどうかは、ログとファイルの状態で確認します。クライアントの更新ボタンの表示だけで判断しないでください。

更新間隔を短くしても、ルールの品質が保証されるわけではありません。分類の境界が曖昧な出所不明のリストを頻繁に取得すると、ログイン用APIと静的リソースが別々の接続先を使うことがあります。ルールセットを追加する前に、対象とする通信の範囲を書き出し、代表的なドメインが含まれているか確認しましょう。大規模なクラシックルールセットでは、読み込み時間と端末のリソース消費に注意してください。ルーターではストレージへの書き込み回数と空き容量も考慮します。リモートの内容を更新した後は、新しい接続で検証してください。長時間維持されている既存の接続では、新ルールの反映状況を判断できません。

競合時の結果はルールの順序で決まる

ルールは上から順に評価され、一致すると通常はその時点で処理が終わります。特定ドメインの例外は対象範囲の広いルールセットより前に置き、フォールバックのMATCHは最後に配置してください。アドレスルールにno-resolveを指定すると、そのルールのためにドメインをIPアドレスへ積極的に名前解決しません。接続情報がドメイン名しかない場合、そのアドレスルールには一致しないことがあります。ドメインルール、地理情報ルール、IPアドレスルールは目的に応じて組み合わせます。数を増やせば網羅性が高まるわけではありません。中国本土のサイトを直接接続にする設定については、ルールによる通信振り分けの実例もご覧ください。

DNS設定の最適化

DNS設定は、名前解決サーバーのアドレスを入力するだけではありません。一つの接続でも、プロキシノードのドメイン、アプリが接続するドメイン、DNS上流の接続先を解決するための問い合わせが発生することがあり、それぞれが異なる経路を使う場合があります。まずアプリがどこにDNSクエリを渡すか、次にコアが上流へどう接続するか、最後に返されたアドレスが後続のルーティングに適しているかを確認しましょう。ブラウザーのセキュアDNS、システムの暗号化DNS、アプリ内蔵のDNS機能は、クライアントのDNS入口を迂回することがあります。nameserverを変更しただけでは、すべてのアプリの問い合わせがコアを経由しているとは確認できません。

初期接続用、ノード用、アプリ用の名前解決を区別する

default-nameserverは主にDNS上流のホスト名解決に使うため、直接到達できるアドレスを指定します。nameserverは通常のアプリの問い合わせ先です。proxy-server-nameserverはプロキシノードのドメインを個別に処理し、確立前のプロキシ経路にノード接続が依存するのを防ぎます。nameserver-policyでは特定のドメインに専用のDNSサーバーを割り当てられるため、内部ドメイン、特定のネットワークサービス、明確に分けたい名前解決に適しています。それぞれ異なる段階の問題を解決するため、すべての項目に同じアドレスをコピーしないでください。

以下は、アプリの接続先ドメインをFake-IPでマッピングするDNS設定例です。記載したDNSサーバーのアドレスは一例で、すべてのネットワークから到達できるとは限りません。使用前に、現在のネットワークから接続できるか確認してください。待ち受け先はループバックアドレスに限定しており、ローカル端末からの問い合わせのみを受け付けます。ルーターでLAN内の端末にも提供する場合は、待ち受け先、ファイアウォール、アクセス範囲を別途設計してください。デスクトップ向けの例を全インターフェース待ち受けに変更しただけで、導入が完了したと考えないでください。

# 設定例：プロキシとルールの定義は含みません
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
    - 1.1.1.1
  proxy-server-nameserver:
    - 223.5.5.5
  nameserver:
    - https://dns.alidns.com/dns-query
    - https://cloudflare-dns.com/dns-query
  fake-ip-filter:
    - '*.lan'
    - '*.local'

DNSサーバーを増やすのではなく、用途に合わせて設定する

内部ドメインは通常、ローカルゲートウェイや組織が提供するDNSサーバーに問い合わせる必要があり、パブリックDNSでは名前解決できないことがあります。内部ドメインを確認したら、nameserver-policyで社内DNSに振り分け、必要に応じて該当ドメインをFake-IPの適切な例外に設定します。ここでは、マッピングアドレスを返すかどうかと、実際の名前解決をどの上流に任せるかを個別に決める必要があります。ドメインをフィルターに追加しても、拡張モードでの処理方法が変わるだけです。問い合わせ先が正しい内部DNSに自動で切り替わるわけではありません。

fallbackとfallback-filterは、複数の上流からの応答を選別・比較するための設定で、単純なプライマリー／セカンダリーの順序指定とは異なります。明確な選別方針がない場合は、説明できる少数の上流を使うほうが、多数のアドレスを並べるよりトラブル対処が容易です。respect-rulesを使うとDNS上流への接続にルーティングルールを適用できますが、有効にする前にノードの名前解決経路を分け、適切なproxy-server-nameserverを設定してください。設定が不適切だと、「DNS上流への接続にはプロキシが必要で、そのプロキシへの接続にはDNSが必要」という循環依存が起きる場合があります。

名前解決の結果と問い合わせ経路を別々に確認する

ローカルのDNS待ち受けにはnslookup example.com 127.0.0.1で問い合わせられます。ただし、このコマンドは標準のDNSポートを使用するため、上の例で使っている1053番ポートは直接テストできません。ポートを指定できるツールでは、dig @127.0.0.1 -p 1053 example.comを実行できます。マッピングアドレスが返されたことから分かるのは、その問い合わせがFake-IP処理を通ったことだけで、すべての問い合わせが同じ経路を通るとは限りません。アプリの実際の動作を判断するには、ブラウザーのDNS設定、TUNのDNSハイジャック、ログに記録された上流への接続も確認してください。

DNSを変更しても、古いキャッシュがシステム、ブラウザー、コアの各層に残っていることがあります。まず新しい接続で試し、必要に応じてキャッシュを削除してください。クライアントを再起動しても、ブラウザーのキャッシュが消えるとは限りません。ドメインを解決できても接続できない場合は、マッピングが有効か、対象のプロキシグループが利用可能か、IPv6が別の経路を作っていないか確認しましょう。検査方法と設定項目の組み合わせは、DNSリークの確認と設定方法をご覧ください。診断時は特定のアプリと問い合わせ経路を明示し、一つの検査サイトの結果だけで全体を判断しないでください。

TUNとFake-IP

システムプロキシは、システムのプロキシ設定に従うアプリを主に対象とします。一方、TUNは仮想ネットワークインターフェースとルーティングを使ってIP通信を処理します。制御できる範囲は異なるため、システムプロキシを有効にしただけですべてのアプリが対象になるわけではありません。Fake-IPはDNSでドメインをアドレスにマッピングする仕組みであり、TUNの別名ではありません。両者が併用されるのは、受信したIPパケットから元のドメインを復元し、ドメインベースの振り分けを続けられるためです。ただし、TUNはほかのDNSモードとも組み合わせられ、Fake-IPも適切な非TUN環境で使用できます。

有効にする前に権限と現在のネットワーク環境を確認する

デスクトップクライアントでは、まず設定画面でサービスモードや関連するシステム権限を確認してからTUNを有効にします。Windowsでは仮想ネットワークアダプターとルートを管理するサービス権限、macOSではシステムの許可、Linuxでは必要なネットワーク管理権限が通常必要です。具体的な操作はクライアントによって異なります。AndroidとiOSでは通常、システムのVPN機能を使って通信を制御するため、同じ端末で別のVPNを同時に使えない場合があります。社内ネットワーク、セキュリティソフト、既存のトンネルもルートに影響します。まず現在の状態を記録し、影響範囲が分からないままルートを追加しないでください。

以下はネットワーク制御の設定例です。auto-routeは必要なルートをコアに設定させ、auto-detect-interfaceは接続先インターフェースの識別を補助します。複数のネットワークアダプター、ブリッジ、既存VPNがある場合は実環境で検証してください。dns-hijackは条件に合うDNS通信を捕捉する機能で、暗号化DNSをすべて自動検出するものではありません。HTTPSで独自のDNSサーバーに接続するアプリの通信は、ポート53をここに記載しても、通常のDNS問い合わせとしてコアに処理されるとは限りません。

# 設定例：dns設定が有効であることを前提とします
tun:
  enable: true
  stack: mixed
  auto-route: true
  auto-detect-interface: true
  dns-hijack:
    - any:53
    - tcp://any:53

dns:
  enable: true
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16

stackとマッピングアドレスの役割を理解する

stackはTUNのパケットが通るプロトコルスタックを指定します。system、gvisor、mixedの対応状況や動作は、コアとプラットフォームによって異なります。設定名だけを見て性能が高いと判断しないでください。まずはクライアントの既定値を維持し、再現性のある互換性の問題が起きた場合に限って個別に切り替えて比較します。同じアプリ、接続先、ネットワークを使い、TCP、UDP、LAN内通信が変化するかを確認してください。スタック、DNS、ルールを同時に変更すると、結果の原因を特定しにくくなります。

Fake-IPが返すのはマッピング用のアドレスです。これをWebサイトの実サーバーのアドレスとして地理的な判定に使うことはできません。アプリからの接続は、マッピング情報を保持するコアに再び届く必要があります。そうでなければ、そのアドレスは通常のネットワーク上で実際の接続先として使えません。クライアントを終了した、マッピング情報が消えた、アプリが古いキャッシュを使い続けているといった場合、「設定を切り替えた直後から接続できない」ことがあります。まずアプリの既存接続を閉じて名前解決し直し、必要ならキャッシュを削除してください。マッピング用のアドレス範囲全体を直接接続ルールに追加しないでください。

LAN内の例外と接続できない場合の切り戻し

プリンター、ネットワークストレージ、画面ミラーリング、LAN内のデバイス検出では、サービスごとに異なるプロトコルが使われるため、ドメインの除外だけでは不十分な場合があります。まず内部ドメインと固定アドレスのどちらを使うか確認し、サブネットのルート、DNSの名前解決、マルチキャストによる検出を調べてください。実アドレスが必要なドメインはfake-ip-filterに追加し、確認済みの内部ネットワークは直接接続に設定します。TUNのルートからローカルインターフェースにアクセスできることも確認しましょう。ドメインカテゴリ全体を無条件に除外しないでください。例外の範囲が広すぎると、ドメインルールに必要な情報が失われます。

有効にすると完全に通信できなくなる場合は、権限、仮想ネットワークアダプター、デフォルトルート、DNS上流、ノードへの接続の順に確認します。まずTUNを無効にしてシステムプロキシを残してください。システムプロキシで復旧するなら、問題は主にネットワーク制御層にある可能性があります。どちらも失敗する場合は、サブスクリプション、プロキシグループ、基本ネットワークを確認します。エラーログを記録し、一度に一つの設定だけを元に戻してください。必要であれば有効化前に保存した設定へ戻します。プラットフォーム別の操作はTUNモードの有効化ガイド、一般的な問題はトラブル対処をご覧ください。

ドメインスニッフィング

ドメインスニッフィングは、接続にドメイン情報が含まれていない場合に、対応プロトコルの特徴からホスト名を取得しようとする機能です。代表的な情報源にはHTTPリクエストのHost、TLSハンドシェイクで確認できるサーバー名、一部のQUICハンドシェイク情報があります。これは通信の復号機能ではなく、コアがHTTPSの内容をすべて読み取れるわけでもありません。また、すべての接続からドメインを取得できる保証もありません。アプリがIPアドレスを直接指定している場合や、DNSが現在のコアを経由していない場合に、ドメインルールを適用できる可能性を高める補助機能として使います。

本当にドメイン情報が不足しているか確認する

接続画面に正しいドメインが表示され、意図したルールに一致しているなら、スニッフィングを有効にしても効果がない場合があります。まず、安定して再現できるケースを選び、表示がIPアドレスだけなのか、IPルールに一致しているのか、フォールバックに流れているのか確認しましょう。有効にした後、同じ通信の新しい接続で正しいホスト名を取得できるか比較します。スニッフィングをすべての振り分け問題に対する万能策と考えないでください。ルールの順序、メンバーのいないプロキシグループ、接続先への到達性、DNS上流の障害は、それぞれの設定箇所で対処する必要があります。

以下の設定例では、HTTP、TLS、QUICを識別対象にします。ポート配列の文字列範囲は設定の構文であり、ネットワークスキャンではありません。parse-pure-ipを有効にすると、IPアドレスのみの接続先もスニッフィングを試みます。force-dns-mappingは、DNSマッピングに関係する状況でのスニッフィング処理を強化します。使用前に、現在のmihomoコアが各項目を認識することを確認してください。起動時に未知の設定や非対応プロトコルの警告が出たら、ほかの項目を追加するのではなく、クライアントが実際に使用しているコアを確認します。

# 設定例
sniffer:
  enable: true
  force-dns-mapping: true
  parse-pure-ip: true
  override-destination: false
  sniff:
    HTTP:
      ports:
        - 80
        - 8080-8880
    TLS:
      ports:
        - 443
        - 8443
    QUIC:
      ports:
        - 443

ドメインの識別と接続先の書き換えは別の設定

override-destinationは、スニッフィングで得た情報を元の接続先に代えて使用するかどうかを指定します。初回のテストでは無効のままにし、取得したドメインがルールの適用にどう影響するか確認してください。スニッフィングしたドメインに基づいて接続先を改めて決める必要がある場合にのみ、有効化を検討します。アプリが特定のアドレスに接続するのは、内蔵のロードバランサー、特殊な名前解決、固定のサーバー要件などが理由かもしれません。安易に接続先を書き換えると、アプリが本来選んだ経路が変わります。取得したホスト名が正しく見えても、再解決した接続先が互換性を保つとは限りません。

一つのIPアドレスで複数のドメインが提供されている場合があるため、接続ログのアドレスだけで通信先のサービスを特定することはできません。反対に、ハンドシェイクに含まれるホスト名が、ユーザーに表示されるWebサイトではなく、ゲートウェイ、共有の入口、中継サービスを示す場合もあります。検証では、元の接続先、スニッフィングした名前、一致したルール、最終的な接続先をあわせて記録してください。確立済みの長時間接続で設定を切り替えても、最初のハンドシェイク情報を再取得することは通常できません。比較するには、一度切断して新しい接続を作成してください。

プロトコルの制限と互換性の確認

暗号化されたクライアントハローなどを使う接続では、通常確認できるサーバー名が隠れる場合があります。標準外のプロトコル、特殊なハンドシェイク、早期に失敗する接続でも、識別に必要な情報が得られないことがあります。QUICはUDPを使用するため、利用できるかどうかは接続先がUDPをサポートしているか、ネットワーク経路が適切かにも左右されます。QUICでのアクセス失敗をすべてスニッフィングの問題と考えないでください。比較テストでは、アプリを一時的にTCPで接続できる経路に切り替えて、ドメインの識別状況が変わるか確認できます。ただし、この結果だけを根拠に、すべてのアプリでQUICを無効にすべきだと判断しないでください。

有効化後に特定のサービスだけで問題が起きる場合は、まず接続先の書き換えを無効にし、対象プロトコルとポートの範囲を絞ります。特定ドメインが原因と確認できた場合は、コアがサポートするskip-domainで除外し、除外のパターンが意図どおりか検証してください。キーワードだけを見て、範囲の広すぎるワイルドカードを追加しないでください。新たに取得したドメインが上位のルールに一致して、問題が起きている可能性も確認します。スニッフィング成功後にルーティング結果が変わったなら、以前はIPルールを使っていた通信にドメインルールが適用された可能性があります。スニッフィングが失敗したと決めつけず、ルール設計を見直しましょう。

ドメイン、IPアドレス、ルールの用語の違いは用語クイックリファレンスをご覧ください。日々の運用では、スニッフィングは明確な目的がある場合に使う補助機能です。接続の問題が起きるたびに最初に有効にする設定ではありません。設定項目を増やすより、接続がそのルールに一致する理由を説明できることが重要です。

ローカル設定の上書きと複数サブスクリプションの統合

リモートサブスクリプションはノードや設定全体を配布し、ローカル設定の上書きは端末固有のポート、DNS、ルールの例外、プロキシグループの構成を保持します。ダウンロードしたサブスクリプションを直接編集すると、次回更新時に変更が置き換わることがあります。まずクライアントが対応している上書き方法を確認してください。YAMLのマージ、設定の拡張、スクリプト処理、独立したローカル設定などがあります。マージの順序は方式によって異なり、同名の項目が常に深くマージされるとも限りません。あるクライアント向けの操作手順を、別のクライアントにそのまま適用しないでください。

最終的に読み込まれる設定ファイルを確認する

設定画面で現在のサブスクリプションを選び、拡張または上書きの設定を開きます。メニュー名はクライアントの実際の画面で確認してください。保存して再読み込みしたら、実行中の設定、設定プレビュー、コアのログから最終的な内容を確認します。元ファイルにmixed-port: 7890と書かれていても、クライアントの全体設定で上書きされていれば、実際のポートは7890ではありません。「リモートの元設定」「ローカルの上書き」「最終設定」を分けて保存し、編集画面だけを見て反映済みと判断しないようにしましょう。クライアントにコア設定の検証機能がある場合は、再読み込みの前に実行してください。

複数のサブスクリプションを使う場合は、完全なYAMLを直接つなぎ合わせるのではなく、複数のproxy-providersとしてノードの取得元を整理し、プロキシグループから参照する方法を優先してください。完全なサブスクリプションにはdns、rules、同名のプロキシグループが含まれる場合があり、テキストを単純に連結するとトップレベルのキーが重複したり、参照が競合したりします。以下はローカルノードプロバイダーの例です。各ファイルには有効なproxies配列が必要で、ルールや設定を含む完全な設定ファイルではありません。ファイルはコアがアクセスできる設定ディレクトリに置いてください。

# メイン設定の例：2つのローカルノードファイルを使用
proxy-providers:
  primary:
    type: file
    path: ./providers/primary.yaml
  backup:
    type: file
    path: ./providers/backup.yaml

proxy-groups:
  - name: 複数サブスクリプションの接続先
    type: select
    use:
      - primary
      - backup
    proxies:
      - DIRECT

rules:
  - MATCH,複数サブスクリプションの接続先

配列のマージでは結果が変わりやすい

スカラー項目の最終値は通常一つですが、ルール、ノード、プロキシグループは配列です。上書きツールによって配列全体を置き換える場合と、末尾に追加する場合があり、rulesへの影響は大きく異なります。ローカルの例外が既存のMATCHの後に追加されると、意図したとおりに適用されません。保存後に最終的なルール一覧を開き、例外がフォールバックより前にあることを確認してください。プロキシグループの配列も、既存の参照が残っているか確認しましょう。新しいグループが表示されることだけを確認し、元のグループが丸ごと置き換わっているのを見落とさないようにしてください。

複数の接続元に同じ名前のノードがある場合があります。表示名が同じでも接続先のサーバーまで同じとは限らず、選択状態やルールからの参照が曖昧になることもあります。クライアントの名前変更機能やプロバイダーごとの名前管理を使う場合は、変換ルールを一定に保ち、どの段階に適用されるか記録してください。一時的な状態に合わせて頻繁に名前へ接頭辞を追加すると、更新後に手動選択が無効になる場合があります。フィルター式は狭い範囲でテストしましょう。誤ってすべてのノードが一致したり、すべて除外されたりすると、グループの動作が設計から外れる可能性があります。

サブスクリプション形式とリモートプロバイダーの制限

リモートプロバイダーでHTTPを使う場合、URLからコアが解析できる形式のノード一覧を取得できる必要があります。Base64形式のリンク一覧、単一のプロトコルリンク、完全なClash YAMLはそれぞれ別の形式です。URLをproxy-providersに置き換えただけで、自動変換されるわけではありません。形式の見分け方と変換方法はサブスクリプション形式の比較をご覧ください。サブスクリプションURLにアクセス認証情報が含まれることがあります。ログ、スクリーンショット、設定ファイルを共有する前に該当部分を削除してください。取り扱い方法を確認できないオンライン変換サービスに実際のURLを渡さないでください。

運用時は、動作確認済みの最終設定と対応する上書き設定を保存してください。更新のたびに、プロバイダーのメンバー数と重要なグループのメンバーを確認し、次に重要なルールとDNS項目を確認します。問題が起きたら、最近追加した上書き設定をまず無効にし、元のサブスクリプションで動作する状態に戻してください。すべての接続元を同時に削除しないでください。特にスクリプトによる上書きでは、入力構造が変わった場合の異常処理に注意します。スクリプトは明確にエラーにするか元の結果を維持し、ノードが不足した設定を黙って返さないようにしてください。ポートの変更やルールの例外を少数追加するだけなら、複雑なスクリプトより単純なYAMLの上書きのほうが確認しやすくなります。

外部コントローラー

外部コントロールAPIでは実行状態の取得、プロキシグループの切り替え、接続情報の確認、設定の管理ができます。コントロールパネルは、このAPIにアクセスするためのWebフロントエンドです。アプリのプロキシポートとは別のサービスなので、ブラウザーでパネルを開けてもブラウザーの通信がプロキシ経由とは限らず、プロキシポートに接続できてもAPIが正常とは限りません。設定前に、パネルがローカル端末、LAN内の端末、サーバーのどこで動作するかを決め、APIの待ち受け先を定めてください。通常のデスクトップ利用では、ローカルのループバックアドレスだけで待ち受けるほうがアクセス範囲を管理しやすくなります。

APIのアドレスと静的ファイルのディレクトリを区別する

external-controllerはコントロールAPIの待ち受けアドレスを指定し、external-uiはパネルの静的ファイルが置かれたディレクトリを指定します。ディレクトリ内には実際のエントリーファイルと関連リソースが必要です。空のフォルダーを作っただけではパネルは利用できません。入手元を確認した静的パネルのファイルをコアの作業ディレクトリに置き、相対パスを設定できます。クライアントにパネルが組み込まれている場合は、管理用の入口を使うことを優先し、場所の異なるフロントエンドを二重に管理するのは避けてください。相対パスの基準は、実際の実行ディレクトリで確認します。

# 設定例：uiディレクトリにパネルの静的ファイルが必要です
external-controller: 127.0.0.1:9090
external-ui: ./ui
secret: "your-controller-secret"

例のキーは設定項目の説明にのみ使用します。実際に使う場合は、十分な長さがあり、使い回しせず、公開されていない値を自分で設定してください。キーを一般公開される記事、スクリーンショット、リポジトリに記載したり、パネルを共有しやすくするためにページのURLへ埋め込んだりしないでください。コントロールAPIは実行状態を変更できるため、読み取り専用の情報ページと同じ扱いで公開してはいけません。クライアントがsecretを自動管理している場合は、指定された認証方法で接続してください。クライアントが生成した値を上書きすると、内蔵画面から接続できなくなることがあります。

まずローカル端末から確認し、その後にLAN接続を検討する

まず同じ端末からポートが待ち受けているか確認し、設定済みの静的パネルにアクセスしてAPIアドレスとキーを入力します。ページは開くのに接続できない場合は、静的ファイルとAPIが別々の通信経路であることを踏まえ、アドレス、認証、ブラウザーのエラーを確認してください。以下のコマンドは認証付きでローカルに問い合わせる例です。例のキーはローカル設定と一致させてください。テスト後は、実際のキーが含まれるコマンドの記録を外部に共有しないようにしましょう。

curl --header "Authorization: Bearer your-controller-secret" \
  http://127.0.0.1:9090/configs

別の端末でパネルを開く場合、127.0.0.1が示すのはブラウザーを使っている端末であり、コアが動作するホストではありません。コアのホストから到達できるアドレスを指定し、待ち受け設定とファイアウォールの範囲を明確にしてください。allow-lanはプロキシサービスへのLANアクセスを制御する設定で、コントロールAPIを公開するかどうかを一括で切り替えるものではありません。APIの待ち受けアドレスは別途確認してください。プロキシの利用がローカル端末だけに限られていても、APIのバインド先を誤ると管理機能が外部に公開されるおそれがあります。

ブラウザーのセキュリティ制限とリモート環境

HTTPSのパネルからHTTPのAPIにアクセスすると、混在コンテンツとしてブロックされる場合があります。異なるオリジンのページでは、クロスオリジンアクセスの制限も発生することがあります。ブラウザーの保護機能を無効にしてエラーを回避するのではなく、同一オリジンでのアクセスや安全なリバースプロキシを実際の構成に合わせて選んでください。コントロールAPIのクロスオリジン設定を変更する場合は、パネルのオリジンを確認したうえで必要なものだけを許可し、すべてのオリジンを既定で許可しないでください。ページに接続エラーが表示されるときは、ブラウザーのコンソールでネットワーク到達性、認証失敗、セキュリティポリシーによるブロックを切り分けられる場合があります。

コントロールAPIをインターネットへ直接公開することは推奨しません。リモート管理が必要な場合は、アクセス制御付きのプライベートネットワークや認証済みの安全な入口を使い、接続元を制限し、暗号化通信と切り戻し用の経路を確保してください。キー認証だけではネットワーク境界の代わりになりません。ルールやプロキシグループをリモートで変更する前に、変更後も管理中の接続が維持されることを確認してください。サーバーでは特に、ローカルまたは別の保守経路を確保し、設定の再読み込み後に操作できなくなる事態を避けましょう。

外部パネルはルールや接続を詳しく確認したい方向けで、基本的な接続に必須ではありません。サブスクリプションを追加して接続先を選ぶだけなら、まずクライアント内蔵の画面を使ってください。画面ごとの役割はクライアント画面の詳しい解説をご覧ください。トラブル対処では、まずコアが正常に動作していることを確認し、その後でパネルのファイル、APIへのアクセス、ブラウザーの制限を調べます。フロントエンドの接続エラーをノードの障害と取り違えないようにしましょう。

ポート設定と設定の検証

ポートはアプリがコアのサービスに接続する入口であり、リモートのプロキシノードが待ち受けるポートではありません。mixed-portはHTTPとSOCKSの両方の接続を受け付けます。portとsocks-portでは、それぞれ対応するサービスを個別に提供できます。コントロールAPI、DNSの待ち受け、プロキシの入口は用途が異なるため、すべてローカルアドレスだからといって相互に置き換えることはできません。よくある間違いは、ブラウザーのプロキシ設定に9090を指定したり、7890をDNSのポートと考えたりすることです。数字を何度も変えるより、まずプロトコルを確認してからアドレスとポートを照合しましょう。

設定項目とサービスの対応を確認する

設定項目	主な用途	確認するポイント
`mixed-port`	HTTP・SOCKSプロキシの入口	アプリのプロトコル、待ち受けアドレス、ポートの競合
`external-controller`	コアのコントロールAPI	認証、アクセス範囲、ブラウザーの制限
`dns.listen`	DNS問い合わせの入口	UDPまたはTCP、実際の問い合わせポート
`allow-lan`	プロキシへのLANアクセス設定	バインドアドレス、ファイアウォール、アクセス許可

ローカル端末だけで使う場合はallow-lan: falseを維持し、アプリからループバックアドレスへ接続します。LAN内の端末にもプロキシを提供する場合は、待ち受けアドレス、端末ごとのアクセス権、ファイアウォールのルールを明確にしてください。プロキシの共有とコントロールAPIの共有は別々に設計します。ルーターとデスクトップOSではローカルファイアウォールの動作も異なります。設定ボタンが有効になっていることを確認するだけでは不十分です。実際にプロキシを使う端末から接続し、端末間の通信経路を検証してください。

# 設定例：ローカル端末用プロキシの入口
mixed-port: 7890
allow-lan: false
bind-address: 127.0.0.1
mode: rule
log-level: info

変更は一度に一つずつ検証する

変更前に動作する設定を保存し、現在のネットワーク、プロキシグループの選択、クライアントの動作モードを記録してください。クライアントから実行中の最終設定をエクスポートできる場合は、あわせて保存します。サブスクリプションの元設定にクライアント独自の追加設定が含まれているとは限らないためです。変更後は構文と参照先を確認してから再読み込みします。ネイティブのコアでは、該当する作業ディレクトリでmihomo -t -f config.yamlを実行して設定を検証できます。このコマンドは通信テストの代わりにはならず、リモートのルールソース、ノード、DNS上流に接続できることも保証しません。

設定の読み込みを確認したら、ポートが実際に待ち受けているか調べます。WindowsではGet-NetTCPConnection -LocalPort 7890でローカルのTCP待ち受けを確認できます。Linuxではss -lntp、macOSではlsof -nP -iTCP:7890 -sTCP:LISTENを使用します。コマンドによっては適切な権限やシステムツールが必要です。ポートが別のクライアントに使われている場合は、競合するプロセスを停止するか、別のポートを選び、システムプロキシとアプリの設定もあわせて変更してください。YAMLだけを変更して古いポートへ接続し続けないようにしましょう。

明示的なプロキシを使ったテストでは、システムプロキシの影響を一時的に除外できます。以下のコマンドはHTTPプロキシの入口を指定して、例のドメインにアクセスします。成功しても、今回のリクエストがその入口を通ったことしか分からず、TUN、すべてのルール、UDPの動作まで確認できたわけではありません。SOCKSのテストでは、リモート側でドメインを解決する形式を使うと、ローカルでの名前解決とプロキシ経由の名前解決の違いを切り分けやすくなります。テスト先は検証対象の正当な接続先に置き換え、ログに認証情報などの非公開パラメーターを残さないようにしてください。

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

通信経路のどの層に問題があるか切り分ける

入口への接続が拒否される場合は、プロセス、待ち受けアドレス、ポートを確認します。コアには届くものの正しいドメインを取得できない場合は、DNS、アプリの名前解決方法、スニッフィングを確認してください。ドメインは正しいのに接続先が違う場合は、ルールの順序とプロキシグループの選択を確認します。接続先が正しいのに通信できない場合は、ノードのプロトコル、対象サービス、ネットワーク経路を調べてください。一時的にログの詳細度を上げると確認に役立ちますが、トラブル対処後は適切なレベルに戻し、接続情報を長期間記録しすぎないようにしましょう。ログを共有する前に、サブスクリプションURL、認証情報、個人用ドメインを削除してください。

設定の検証では、固定のテストケースを用意すると効果的です。直接接続するサイト、プロキシ経由にするサービス、LAN内の接続先、実際に必要なUDPアプリを一つずつ確認します。変更する設定は一度に一種類に絞り、新しい接続の結果を確認してから次に進みましょう。起動後だけ問題が起きる場合は、サービスの起動と設定の読み込み順を確認し、起動時の自動開始ガイドをご覧ください。特定のアプリだけで問題がある場合は、使い方のヒントを確認してください。安定した設定は項目の多さではなく、一つひとつの項目に明確な役割があり、各例外を再現可能な方法で検証できる状態です。