Clash 高度な設定ガイド

プロキシグループの種類と実践

プロキシグループは Clash 設定の中核です。すべての通信は最終的に「どの出口を通るか」という問いに答える必要があります。rules は通信をプロキシグループに振り分け、プロキシグループは出口間の選択を担います。サブスクリプションに付属するプロキシグループは「ノード選択」と「自動選択」の2種類だけの場合が多く、使えるものの融通が利きません。5つの種類を理解しておくことで、「動画は香港経由、ダウンロードは日本経由、失敗時は自動でバックアップ回線に切り替え」といった用途別振り分け構成が組めるようになります。

5つの種類を一覧で

5つの種類は互いに入れ子にできます。あるプロキシグループの proxies に別のプロキシグループの名前を書くことも可能です。実践で最も安定するのは3層構成——業務用プロキシグループ(「動画配信」「ダウンロード」など)が出口用プロキシグループを指し、出口用プロキシグループがノードや url-test グループを指し、rules は業務用グループだけを参照します。こうすることで出口を変更してもルールは変わらず、ノードを変更しても出口は変わらないため、保守コストが最も低くなります。

select と url-test:手動決定と自動最適選択

select は検知を一切行わず、フロントエンドで選んだものがそのまま使われるため、最終決定層として適しています。url-test は interval に従って定期的にグループ内ノードへ遅延テストを行い、出口を現時点で最速のノードに切り替えます。使い勝手を決める2つのパラメータがあります。tolerance は切り替えの閾値(単位はミリ秒)で、候補ノードが現在のノードよりわずか数十ミリ秒速いだけでは切り替えず、近い性能の回線間で出口が頻繁に揺れ動くのを防ぎます。lazy を true にすると、グループ内に通信が流れていない間は速度計測を一時停止し、無意味な探測リクエストを省けます。

proxy-groups:
  - name: "最終出口"
    type: select
    proxies: ["自動最適選択", "手動指定", "DIRECT"]

  - name: "自動最適選択"
    type: url-test
    use: ["airport-a"]
    url: "https://www.gstatic.com/generate_204"
    interval: 300
    tolerance: 80
    lazy: true

  - name: "手動指定"
    type: select
    include-all: true
    filter: "香港|HK"

use は proxy-providers 内のサブスクリプションを参照し、include-all: true は設定内の全ノードを取り込み、filter は正規表現でさらに絞り込みます。3つのフィールドは重ねて使えます。まず全体を取り込み、正規表現で絞り、サブスクリプションと統合します。速度計測用アドレスには generate_204 のような応答が極めて軽い探測用アドレスを使えば十分です。interval は120秒未満にしないことを推奨します——頻繁な速度計測自体が相当な通信量を消費し、一部の業者ではそれが原因で速度制限を受けることがあります。

fallback と load-balance:メイン/バックアップと並行利用

fallback はリストの順序をそのまま優先順位として扱います。ヘルスチェックは先頭から行われ、最初に使えたものが採用されます。メインが落ちれば自動でバックアップに切り替わり、メインが復旧すれば元に戻ります。「メイン専用線1本とバックアップ回線1本」という構成に適しており、url-test よりも人為的な順序を尊重します。load-balance はこれとは逆で、単一回線の最適化を目指すのではなく、グループ内の健全なノード全体に接続を分散させます。strategy を consistent-hashing にすると、同じ宛先ドメインは常に同一ノードにハッシュされ、ログイン状態やセッションが保持されます。round-robin にすると接続ごとに順番に切り替わり、スループットは最大になりますが、同一サイトでも IP が変わる可能性があります。mihomo には両者の折衷案として sticky-sessions もあり、同一の発信元デバイスをできるだけ同じノードに固定します。

  - name: "メイン/バックアップ回線"
    type: fallback
    proxies: ["専用線入口", "自動最適選択"]
    url: "https://www.gstatic.com/generate_204"
    interval: 180

  - name: "複数回線並行"
    type: load-balance
    use: ["airport-a"]
    strategy: sticky-sessions
    url: "https://www.gstatic.com/generate_204"
    interval: 300

relay:チェーン型プロキシ

relay は通信をグループ内の各ノードに順番に通してから出口へ送ります。典型的な使い方は「前置中継とエグジット」の組み合わせです。ローカルから前置ノードへは最適化された回線を使い、前置ノードからエグジットへは通常の国際出口を使うことで、安定性と目的地域の出口特性を両立できます。チェーン内の各ホップはそれぞれ帯域を消費し、合計遅延は各ホップの合計になるため、ノード数は2つを超えないことが望ましいです。mihomo にはより軽量な等価記法があり、単一ノードに dialer-proxy を指定して経由する前置ノードを指定すれば、別途グループを作る必要はありません。

  - name: "中継エグジット"
    type: relay
    proxies: ["前置中継", "米国エグジット"]

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

rules から rule-providers へ

初期の設定では数百から数千件のルールを rules フィールドに直接並べていました。読みにくく編集しにくいうえ、サブスクリプションが更新されるとファイル全体が上書きされ、自分で追加したルールも一緒に消えてしまいます。rule-providers はルールを設定から切り離し、URL でサブスクリプション可能な独立したルールセットファイルとして扱えるようにします。カーネル起動時にダウンロードしてローカルにキャッシュし、周期的に更新し、rules 側には1行の参照だけを残します。これにより設定は2層に分かれます——戦略構造は手書きの YAML に残り、ルールデータは自動更新可能なルールセットに任せます。

広告ブロック、動画配信の振り分け、内部ネットワークの許可といった定番のニーズには、コミュニティが長年メンテナンスしているルールセットがすでに存在し、直接サブスクライブするほうが自分で一件ずつ書くよりはるかに信頼できます。ローカル固有のルール(社内ネットワーク、自前サービスなど)は file タイプの provider にローカルファイルを置き、同様に RULE-SET で参照することで管理方法を統一できます。

宣言形式とフィールド

rule-providers:
  adblock:
    type: http
    behavior: domain
    format: yaml
    url: "https://example.com/rules/adblock.yaml"
    path: ./ruleset/adblock.yaml
    interval: 86400

  lan-local:
    type: file
    behavior: classical
    path: ./ruleset/lan.yaml

type を http にすると url でサブスクライブし、file にするとローカルファイルを読み込みます。path はローカルキャッシュの保存場所で、ダウンロードに成功するとルールセットがディスクに保存され、次回起動時はまずキャッシュを読みます。interval は更新周期(単位は秒)で、86400 は1日1回に相当します。format はファイル形式を宣言し、yaml は一般的なリスト形式、text は1行1件のプレーンテキスト、mrs は mihomo 専用のバイナリ形式で、サイズが最小・読み込みが最速のため、大規模なルールセットにはこちらを優先すべきです。

3種類の behavior の違い

behavior はカーネルがそのファイルをどう解析するかを決めるもので、間違えるとルールセット全体の読み込みに失敗します。domain 用ファイルに IP レンジが含まれていたり、ipcidr 用ファイルにドメインが含まれていたりすると、いずれもエラーになります。サードパーティのルールセットをサブスクライブする際は、まず配布ページに記載されている種類を確認し、behavior と format をそのまま踏襲してください。ファイル名から推測してはいけません。

rules での参照と更新の仕組み

rules:
  - RULE-SET,lan-local,DIRECT
  - RULE-SET,adblock,REJECT
  - GEOSITE,cn,DIRECT
  - GEOIP,CN,DIRECT
  - MATCH,最終出口

RULE-SET の2つのパラメータは順に provider 名と振り分け先(プロキシグループまたは DIRECT、REJECT)です。rules は上から下へ1件ずつマッチングし、最初に命中したものが適用されます。順序がそのまま優先順位になります——ローカルルールとブロック系は先頭、振り分け系は中間、GEOSITE・GEOIP・MATCH は最後の受け皿として配置します。位置を誤ることがルールが効かない最大の原因です——MATCH より後に置かれたルールは決して評価されません。

更新はバックグラウンドで行われます。起動時に各 http provider のキャッシュの経過時間をチェックし、interval を超えていれば非同期で取得し直します。取得に失敗した場合は既存のキャッシュを継続利用し、ルールが消えたり通信が途切れたりすることはありません。すぐに更新したい場合は、パネル内の該当 provider の更新ボタンを押すか、path が指すキャッシュファイルを削除してから設定を再読み込みしてください。GEOSITE と GEOIP は別のデータベースファイルを使用しており、更新方法はブログ記事『Clash GeoIP・GeoSite データベースの更新方法と振り分けルールの組み合わせ』を参照してください。RULE-SET と混同しないよう注意してください。

DNS 設定の最適化

プロキシクライアントが DNS を制御下に置く理由

OS 標準の DNS は通信事業者の UDP 53 番ポートを経由し、平文で改ざん可能な状態です。これは2つの問題を直接引き起こします。1つは汚染で、クエリが途中で不正な結果を注入され、得られる IP がそもそも接続できないケース。もう1つは漏洩で、どのドメインにアクセスしたかが通信事業者に把握され、振り分け設定自体の意味が失われるケースです。さらに見えにくい第3の問題があります——DNS の結果はルールマッチングを左右します。ドメイン単位で書かれたルールは、カーネルがそのドメインを取得できる正しい解決経路がまず必要になります。

Clash 内蔵の DNS サーバーは、解決処理を振り分け体系に統合するために存在します。中国本土のドメインは中国本土の DoH で直接解決し、プロキシ対象のドメインはリモートノード側で解決し、ノードサーバー自体のドメインは専用のリゾルバーで処理することで、「プロキシに接続してからでないとプロキシのアドレスが解決できない」というデッドロックを避けます。dns フィールドを有効化すれば、解決経路全体がカーネルの制御下に入ります。

フィールドの役割分担

そのまま使える dns 設定例

dns:
  enable: true
  listen: 0.0.0.0:1053
  ipv6: false
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  fake-ip-filter:
    - "*.lan"
    - "*.local"
    - "time.*.com"
    - "ntp.*.com"
    - "+.stun.*.*"
  default-nameserver:
    - 223.5.5.5
    - 119.29.29.29
  proxy-server-nameserver:
    - https://doh.pub/dns-query
  nameserver:
    - https://doh.pub/dns-query
    - https://dns.alidns.com/dns-query
  nameserver-policy:
    "geosite:cn":
      - https://doh.pub/dns-query
    "geosite:geolocation-!cn":
      - https://1.1.1.1/dns-query

この設定の考え方は次の通りです。default-nameserver は純粋な IP で兜底し、doh.pub や dns.alidns.com といったリゾルバー自体のドメインをまず解決します。nameserver-policy は geosite に基づいてドメインを2系統に振り分け、中国本土のドメインは中国本土の DoH、それ以外はプロキシ側の DoH で処理し、ノードのリモート側で解決を完了させます。proxy-server-nameserver はノードのドメイン解決を単独で処理し、通常の解決処理と干渉しません。listen によりカーネルが 1053 番ポートで DNS サービスを外部に提供し、TUN の dns-hijack がシステムクエリをここへ誘導します。

enhanced-mode:redir-host と fake-ip

redir-host は実際の解決を行い、クエリを上流に転送してから本当の IP を返します。互換性は最も高いものの、DNS の往復が1回増え、カーネルが見るのは IP になるため、ドメインベースのルールはキャッシュを逆引きする必要があります。fake-ip は 198.18.0.1/16 範囲内の仮アドレスを直接返し、アプリはその結果を受け取った瞬間に接続を開始します。カーネルは事前に記録した「仮アドレスとドメインの対応」からドメインを復元してルールにマッチングします——実際の往復が不要になり、初回接続が速くなり、ルールはドメイン単位で正確にマッチします。大多数のデスクトップ・モバイル環境では fake-ip がより優れた選択であり、実際の IP が必須のサービスは fake-ip-filter に登録して除外してください。ipv6 は、契約回線に IPv6 が割り当てられていない環境では無効化を推奨します。AAAA クエリが解決全体を遅らせるのを避けられます。

dns フィールドを変更しても反映されないというのはよくある疑問です。設定の再読み込みは最初の一歩にすぎません。OS とブラウザはそれぞれ古い解決結果をキャッシュしているため、システムの DNS キャッシュをクリアするかブラウザを再起動して初めて新しい経路が実際に有効になります。

TUN と Fake-IP

TUN が解決する課題

システムプロキシの本質は「アプリにプロキシアドレスを伝える」ことであり、アプリがそれに従う場合にのみ制御下に入ります。ブラウザや大半のオフィスソフトは問題ありませんが、ゲーム、コマンドラインツール、多くのデスクトップアプリはシステムプロキシの設定を無視し、直結のまま通信してしまいます。TUN は別の道を用意します。カーネル内に仮想ネットワークカードを作成し、ルーティングテーブルを通じてマシン全体の TCP・UDP 通信をすべて引き込みます。アプリ側は完全に無自覚のまま処理されます——プロキシ対応が必要なく、個別設定も不要です。

代償は権限です。仮想ネットワークカードとルーティングテーブルはいずれもシステムレベルのリソースです。Windows ではカーネルサービスのインストールが必要、macOS では一度の認可が必要、Linux では capabilities または root 権限が必要です。Clash Plus、Clash Verge Rev などのクライアントはこの手順を設定内のスイッチひとつにまとめており、案内に従って一度認可するだけで済みます。Android クライアントはそもそも VPNService 形式であり、TUN 層で動作するのが標準です。iOS はシステムのネットワーク拡張機能が処理するため、ユーザー操作は不要です。各プラットフォームのクライアントはダウンロードセンターから OS 別に入手できます。

tun フィールド

tun:
  enable: true
  stack: mixed
  device: Meta
  mtu: 1500
  dns-hijack:
    - any:53
    - tcp://any:53
  auto-route: true
  auto-detect-interface: true

stack は3択です。system はOSのプロトコルスタックを直接利用して転送し、パフォーマンスが最も高くなります。gvisor はユーザー空間のプロトコルスタックで接続を再構築し、互換性が最も広く、一部の厳しいネットワーク環境でより安定します。mixed は TCP を system、UDP を gvisor で処理し、両者のバランスを取るため、多くのクライアントのデフォルトとなっています。auto-route と auto-detect-interface は同時に有効化する必要があります。前者は通信を引き込み、後者はカーネル自身の発信が物理ネットワークカードを経由することを保証します。後者を欠くとループが発生し、TUN 有効化後に全面的な通信断が起きる症状として現れます。

Fake-IP の動作原理

Fake-IP と TUN は組み合わせて使うものです。アプリがドメインを問い合わせると、内蔵 DNS は実際の解決を行わず、fake-ip-range(198.18.0.1/16)から仮アドレスを1つ割り当てて返し、仮アドレスとドメインの対応を記録します。アプリはすぐにその仮アドレスへ接続を開始し、TUN がそれを捕捉して対応関係からドメインを復元し、ドメインでルールをマッチングして直結にするかノードに渡すかを決定します。ノードに渡す場合はドメインをそのまま送り、リモート側で解決させるため、ローカルでは実際の DNS 結果が一切不要になります。

この仕組みには2つの直接的なメリットがあります。初回接続が速くなること(実際の DNS 往復が1回省ける)と、振り分けが正確になること(ルールマッチングで得られるのは常にドメインであり IP ではない)です。代償は「仮アドレスしか見えない」という副作用です。LAN 内サービス、NTP 時刻同期、STUN によるNAT越え、一部のゲームの不正対策やバンキング系のセキュリティモジュールは実際の IP が必須であり、これらのドメインは fake-ip-filter に記載する必要があります。filter はワイルドカードに対応しており、*.lan はすべての .lan で終わるものにマッチし、+.example.com は主ドメインと全サブドメインにマッチします。

各プラットフォームでの導入ポイント

Windows ではクライアントのサービスモードがカーネルをシステムサービスとして登録し、TUN のスイッチは設定ページにあります。macOS では増強モードを初めて有効化する際にパスワード入力による一度の認可が必要です。Linux デスクトップクライアントも同様にスイッチを提供しますが、コマンドラインで mihomo を直接実行する場合は setcap で権限を付与する必要があります。

sudo setcap 'cap_net_admin,cap_net_bind_service=+ep' /usr/local/bin/mihomo

権限付与後は一般ユーザーでも TUN を起動でき、常時 root 権限で動かす必要はありません。サーバー側での完全な導入手順はブログ記事『Linux で Clash を導入する:デスクトップクライアントのインストールと mihomo コマンドライン設定』を参照してください。

ドメインスニッフィング

ルールにはドメインが必要だが、接続には必ずしもドメインが付いていない

Clash のルール体系はドメインを主軸としていますが、カーネルに到達する接続には必ずしもドメインが付いているとは限りません。アプリが独自に DNS を処理していたり、DoH を内蔵していたり、以前の解決結果をキャッシュしていたり、あるいは IP を直接ハードコーディングしていたりするケースがあり、これらの接続がカーネルに入ってくる際には宛先 IP しか持っていません。ドメインがなければ、DOMAIN、DOMAIN-SUFFIX、GEOSITE はすべて空振りとなり、通信は GEOIP や MATCH まで転がり落ちるしかなく、振り分け精度が大きく損なわれます。

ドメインスニッフィングは、接続そのもののハンドシェイクデータからドメインを読み取ります。TLS 接続の ClientHello には SNI フィールドがあり、平文の HTTP リクエストには Host ヘッダーがあり、いずれも暗号化されていない明示的な情報です。カーネルは転送前にハンドシェイクパケットを一目確認し、ドメインを抽出してその接続に再び紐づけ、以降のルールマッチングはドメインベースで行われます。TUN がマシン全体の通信を制御下に置くと、システム DNS を回避する接続もすべてカーネルの前に露出するため、スニッフィングはほぼ TUN の定番の相棒になっています。

設定の書き方

sniffer:
  enable: true
  parse-pure-ip: true
  override-destination: true
  sniff:
    HTTP:
      ports: [80, "8080-8880"]
      override-destination: true
    TLS:
      ports: [443, 8443]
    QUIC:
      ports: [443, 8443]
  skip-domain:
    - "Mijia Cloud"
    - "+.push.apple.com"

parse-pure-ip は純粋な IP 接続に対してもスニッフィングを試みる、スニッフィングの主戦場です。override-destination はスニッフィングで得たドメインで接続の宛先アドレスを置き換え、redir-host モードの接続でもドメイン単位の振り分けを可能にします。sniff の下ではプロトコルごとにポート範囲を宣言し、QUIC が単独項目になっているのは、その SNI 抽出方法が TCP 上の TLS とは異なるためです。skip-domain は免除リストで、スニッフィング後に異常が発生することが分かっているサービス(一部のプッシュ通知チャネルやスマートホームのクラウドサービスなど)を記載しておくと、カーネルはこれらのドメインに対してスニッフィングをスキップします。

境界ケースとトラブルシューティング

スニッフィングは万能ではありません。ECH(Encrypted Client Hello)を有効化した接続は SNI が暗号化されているためドメインを取得できず、IP ベースのルールにフォールバックするしかありません。一部の環境では QUIC のスニッフィングが動画サイトの読み込み異常を引き起こすことがあり、その場合は QUIC の設定部分だけを削除して検証できます。スニッフィングはハンドシェイク段階でいくつかのフィールドを読むだけで通信を復号しないため、パフォーマンスへの影響は無視できます。

Fake-IP との関係を整理しておきます。fake-ip モードでは、ドメインは DNS の段階で既にカーネルの手元にあるため、スニッフィングの出番は「アプリがシステム DNS を回避する」ごく少数のケースに限られます。redir-host モードや純粋な IP 直結のケースでは、スニッフィングが振り分け精度の主要な保証手段になります。スニッフィングを有効化した後に特定のサービスに接続できなくなった場合は、まずそのドメインを skip-domain に追加して検証し、それから他の方向を調査してください。

ローカルオーバーライドと複数サブスクリプション統合

避けられない矛盾

サブスクリプションは丸ごと1本の YAML で、クライアントは周期的に更新し、更新時はまるごと置き換えられます。手動で追加したノード、変更したプロキシグループ、調整した DNS 設定は、次回更新ですべて消えてしまいます。ローカルでの変更とサブスクリプションの内容を分離しておくことが、長期的に Clash を使いこなすための前提です。手段は2層に分かれます。複数サブスクリプションは proxy-providers で集約し、ノードとサブスクリプションファイルを分離します。ローカルでの変更はクライアントのオーバーライド機構で処理し、パッチとサブスクリプションファイルを分離します。オンラインのサブスクリプション変換サービスで複数のサブスクリプションを1本にまとめる方法もありますが、その代償はサブスクリプションアドレスを第三者に渡すことです。proxy-providers はローカルで同じことを実現し、アドレスが本機の外に出ることはありません。

proxy-providers:複数サブスクリプションをノードプールに統合

proxy-providers:
  airport-a:
    type: http
    url: "https://example.com/sub-a.yaml"
    path: ./providers/airport-a.yaml
    interval: 86400
    health-check:
      enable: true
      url: "https://www.gstatic.com/generate_204"
      interval: 300
    override:
      additional-prefix: "[A] "

  airport-b:
    type: http
    url: "https://example.com/sub-b.yaml"
    path: ./providers/airport-b.yaml
    interval: 86400
    override:
      additional-prefix: "[B] "

  self-hosted:
    type: file
    path: ./providers/self.yaml

各 provider は個別にダウンロード・キャッシュ・ヘルスチェックされます。override.additional-prefix は該当サブスクリプションの全ノード名にプレフィックスを付与するもので、2つの業者でノード名が重複する場合(「香港01」はどこにでもある)、互いに上書きされることがなくなり、パネル上でも所属が一目で分かります。filter フィールドは正規表現で必要なノードだけを取り込む用途に使い、例えば家庭用回線のノードだけを取得するといった使い方が可能です。file タイプの self-hosted には自前で立てたノードをローカルに置き、サブスクリプションと同列でプールに加わります。

統合後は、プロキシグループで use を使い provider を参照し、proxies と混在させます。

  - name: "自動最適選択"
    type: url-test
    use: ["airport-a", "airport-b", "self-hosted"]
    url: "https://www.gstatic.com/generate_204"
    interval: 300

クライアントオーバーライド:サブスクリプションにパッチを当てる

主流のクライアントはいずれもオーバーライド層を提供しており、原理は共通です。サブスクリプション YAML をダウンロードした後、まずユーザー定義のパッチを通し、それをカーネルに渡して反映させます。Clash Plus はサブスクリプション設定内にオーバーライドの入口を用意しています。Clash Verge Rev は Merge(YAML パスに基づくフィールド統合)と Script(スクリプトによる任意の書き換え)の2段階を提供します。FlClash はオーバーライド設定内でルールとプロキシグループの追加をサポートします。パッチでできることには、前置ルールの挿入、プロキシグループの追加、dns の変更、ipv6 の無効化などがあります——サブスクリプションを100回更新しても、パッチは変わらず有効です。

オーバーライドで最もよく使われるのは前置ルールです。クライアントは通常「rules の先頭に追加する」というスロットを用意しており、先頭に書かれたルールが最も高い優先度を持つため、「社内ドメインは直結」「特定サイトは強制的に特定出口を経由」といった個人向けの条項に適しています。サブスクリプションに付属のルールはそのまま保持され、読み込みも変更もされません。問題が起きたらオーバーライドを無効化するだけでサブスクリプション本来の状態に戻せるため、トラブルシューティングの経路が非常に短くて済みます。基本的なサブスクリプションのインポートとモード選択は依然として前提であり、主な手順は使い方ガイドを参照してください。

統合時の競合と運用ルール

複数サブスクリプションの統合で問題が集中するのは3か所です。命名の競合:異なるサブスクリプションの同名ノードは重複除去されるか、後から読んだものが先のものを上書きします。additional-prefix が最も安定した解決策です。プロキシグループの同名:オーバーライドで追加したプロキシグループがサブスクリプション付属のグループと同名の場合、オーバーライドが優先され、サブスクリプション側のグループは置き換えられます——意図的なら機能ですが、意図しない重複なら事故です。ルールの順序:前置ルールはサブスクリプションのルールより優先されるため、あまりに広範な前置ルール(大量の IP 直結など)を書くと、サブスクリプションの振り分けが機能しなくなります。前置項目は必ず精密に書く必要があります。

運用面では、ローカルでの変更を1つのオーバーライドに集約し、ルール・プロキシグループ・DNS を一元管理し、変更にはコメントを残すことを推奨します。サブスクリプションの更新に失敗しても既存のキャッシュは残るため、ノードが突然消えることはありません。更新失敗時の調査順序と自動更新の設定方法はブログ記事『Clash サブスクリプション更新失敗のよくある原因と自動更新の設定方法』を参照してください。

外部コントロールパネル

external-controller とは

カーネル起動後、external-controller で指定したアドレスに一連の RESTful API と WebSocket インターフェースが公開されます。プロキシの照会、ノードの切り替え、ルールの読み取り、アクティブな接続の確認、リアルタイムログの取得などが可能で、クライアントのグラフィカルインターフェースは本質的にこの API 群を呼び出しているだけです。これを有効化して Web パネルを設定すれば、特定のクライアントに依存せず、任意のブラウザから稼働中のカーネルを管理できます——ルーター上の mihomo やサーバー上の無人運用インスタンスも、この経路で管理されています。

有効化の方法

external-controller: 127.0.0.1:9090
external-ui: ui
secret: "your-password"

external-controller は API のリッスンアドレスです。external-ui はパネルの静的ファイルディレクトリを指し、設定後に http://127.0.0.1:9090/ui にアクセスすればパネルが表示されます。secret はアクセストークンで、パネルへのログインと API リクエストの両方で必要です。パネルのファイルはコミュニティ製の配布パッケージをそのまま使えば十分です。metacubexd、zashboard、yacd はいずれも実績のある選択肢で、配布パッケージをダウンロードして ui ディレクトリに解凍するだけです。ローカルにファイルを配置しない場合は、パネルのオンライン版を直接開き、API アドレスと鍵を入力すれば、ブラウザが本機の API に直接接続します。

よく使う API 一覧

パネルのすべての機能はこれらのエンドポイントの上に成り立っており、自作スクリプトでも同様に呼び出せます——定期的に速度を計測して回線を切り替える、接続数でアラートを出す、通信を監視システムに取り込むなど、よく行われる使い方です。コマンドラインでの動作確認にはリクエストヘッダーが1つあれば十分です。

curl -H "Authorization: Bearer your-password" http://127.0.0.1:9090/proxies

セキュリティの境界

バインドアドレスはまず 127.0.0.1 にし、本機からのみアクセスを許可するのが、デフォルトかつ最も安定した形です。どうしても LAN からのアクセスが必要な場合——例えばスマートフォンでルーター上のカーネルを管理する場合——バインド先を内部ネットワークのアドレスに変更する際は、必ず secret を設定してください。トークンによる保護がない API は、同一ネットワーク上の誰にでもプロキシの制御権を渡すのと同じです。いかなる場合でも 9090 番ポートを公開ネットワークにマッピングしてはならず、0.0.0.0 にバインドしてファイアウォールの設定に頼ることも避けてください。

secret には十分に長いランダムな文字列を使い、設定に書き込んだ後カーネルを再起動すれば反映されます。リクエストヘッダーで渡され、パネル側が記憶するため、日常使用では意識する必要はありません。パネルのオンライン版はブラウザが直接、入力した API アドレスに接続する仕組みで、鍵が第三者のサーバーを経由することはありませんが、それでも信頼できるネットワーク内でのみ操作し、使用後はタブを閉じることを推奨します。