⚙️ 設定 ⏱ 約19分で読めます

Windows 11 で Clash Verge Rev の external-controller を有効化する：Web ダッシュボードと secret の安全な設定（2026）

「Clash Web パネルをブラウザで開きたい」「接続一覧やノード切替を PC 横の別画面で見たい」「external-controller と secret の意味が分からない」——そんな検索で辿り着いた方向けに、Windows 11 上の Clash Verge Rev で管理 API を立て、Web ダッシュボードから観測・操作する手順を整理します。LAN への不用意な公開を避ける secret 設定もセットで扱い、スマホへのプロキシ共有（allow-lan）とは役割を分けた記事です。

この記事で扱うこと・扱わないこと

external-controller（外部コントローラ）は、Mihomo コアが提供する REST API の待ち受け先です。ここ経由で接続セッションの一覧取得、proxy-groups の選択変更、ログレベル調整などが可能になり、yacd や metacubexd といったサードパーティの Web UI が「Clash ダッシュボード」として動きます。

本稿は同一 PC または信頼できる環境からブラウザで管理したいケースが主眼です。スマホを同じ Wi‑Fi のプロキシに載せる手順は LAN 許可とファイアウォールの別記事 が担当しており、本稿では管理ポート（例：9090）を LAN に晒す必要はない——という前提で進めます。初回インストールからモード選択まで未着手の方は、先に Win11 初回セットアップ を読んでから戻るとスムーズです。

3 つのポート概念を混同しない

検索や設定画面で数字が並ぶと混乱しやすいので、役割だけ先に固定します。

  • mixed-port / socks-port：ブラウザやアプリがプロキシとして使う入口。allow-lan をオンにすると LAN 内の他端末からもここへ接続できます。
  • external-controller：管理用 REST API。接続の可視化やノード切替はこちら。通常は 127.0.0.1:9090 のようにループバック限定に留めます。
  • secret：管理 API への認証パスワード。空のまま LAN 公開すると、同一ネットワーク上の誰でも設定を読み書きできるリスクがあります。

「Web パネルが見たいから 0.0.0.0:9090 を開放した」という設定は、プロキシ共有とは無関係なのにセキュリティだけ下げる典型パターンです。まずは127.0.0.1 + secret で同一 PC のブラウザから触れるか確認し、リモートから見る必要が出た段階で SSH トンネルなど別経路を検討する方が安全です。

💡 ひとこと CentOS や VPS 向けのサーバー構築記事でも external-controller は登場しますが、Linux サーバーでは systemd とファイアウォールの話が中心です。本稿はデスクトップ GUI クライアントに絞った設定手順です。

ステップ 1：Verge Rev がコアを握っているか確認

トレイアイコンが緑系で、有効なプロファイル名が表示されている状態を確認します。購読 URL を入れた直後でまだコアが起動していない場合、後続のポート確認はすべて空振りになります。接続が不安定なときは ログパネルでの切り分け記事 と併用してください。

複数プロファイルを使い分けている場合、いま有効なカードに対して external-controller を足す必要があります。Mixin がプロファイル単位かグローバルかはビルドで揺れますが、「どの YAML が実際にロードされているか」を意識するのが共通のコツです。

ステップ 2：GUI から external-controller を有効化

Clash Verge Rev の設定画面には、ビルドによって External Controller、API Port、Secret といった項目がまとまっていることがあります。見つかった場合は次の方針で入力します。

  1. アドレス：127.0.0.1（または UI が localhost と表示する同等の意味）
  2. ポート：9090 がデファクトですが、他アプリと競合する場合のみ変更（変更したら Web UI 側の URL も合わせる）
  3. secret：英数字記号を混ぜた長い乱数（後述の生成例を参照）

メニュー名はリリースごとに変わるため、Settings → Clash / Core / Advanced あたりを横断して「controller」「API」「9090」のキーワードで探すと早いです。項目が見当たらないバージョンでは、次の Mixin 手順に進んでください。

ステップ 3：Mixin で追記する（購読を触らない方法）

購読 YAML を直接編集すると更新で消えるため、Mixin（プロファイル覆写） に差分だけ載せるのが定石です。Mixin の概念と GUI の辿り方は Mixin 設定の別記事 で詳述しています。ここでは external-controller 用の最小断片だけ示します。

# Mixin 断片 — 管理 API（ループバック限定 + secret 必須）
external-controller: 127.0.0.1:9090
secret: "ここに推測困難な長い文字列を貼る"

保存後、Verge の Apply / Reload / Restart Core のいずれかでコアへ反映させます。反映前にブラウザで試しても API は応答しません。

既存の購読側ですでに external-controller がコメントアウトや別ポートで定義されている場合、Mixin の値が優先されることが多いです。意図しない二重定義を避けるため、反映後は生成 YAML（プレビュー）で最終行を一度目視してください。

⚠️ セキュリティ external-controller: 0.0.0.0:9090 のように全インターフェースへバインドすると、同一 LAN 上の任意端末から管理 API に到達できる可能性があります。secret を必ず設定し、不要なら 127.0.0.1 のままにしてください。リモート管理が必要なら、裸の 9090 公開より SSH ポートフォワードや VPN 内限定の方が現場では安全です。

ステップ 4：secret の作り方と保管

secret は Web UI が API へ送る Authorization ヘッダ相当の共有鍵です。短い単語や購読 URL の一部を流用するのは避け、32 文字以上のランダム文字列を推奨します。Windows 11 の PowerShell なら次の一行で生成できます（表示された文字列を Mixin か GUI に貼り付け）。

# PowerShell — ランダム secret の例
-join ((48..57 + 65..90 + 97..122 | Get-Random -Count 40 | ForEach-Object { [char]$_ }))

secret はパスワードマネージャやローカルの暗号化メモに保管し、スクリーンショットやチャットログに載せない運用が無難です。Web UI の設定画面に secret を保存させる機能はフロントエンド依存なので、共有 PC ではブラウザの自動保存に注意してください。

ステップ 5：LISTEN とファイアウォールの確認

反映後、PowerShell で次を実行し、127.0.0.1:9090（または設定したポート）が LISTEN しているか確認します。

netstat -ano | findstr :9090

何も出ない場合は、(1) コア再起動が未完了、(2) 別プロセスがポートを占有、(3) YAML 構文エラーで設定が丸ごと拒否、のいずれかが多いです。構文エラーは Verge のログや通知に出ることがあるので、インデントと引用符を先に疑ってください。

127.0.0.1 限定なら、通常 Windows Defender ファイアウォール で 9090 をわざわざ開く必要はありません。逆に 0.0.0.0 へ広げた場合は LAN 記事と同様に受信規則の追加が絡みますが、本稿の推奨構成ではその必要はありません。

ステップ 6：Web ダッシュボード（フロントエンド）に接続

http://127.0.0.1:9090 をそのままブラウザのアドレスバーに入れても、多くの環境では JSON だけが返り「画面がない」ように見えます。これは正常で、Clash 用 Web UI を別途使います。

  • yacd：定番のダッシュボード。設定画面で API Base URL に http://127.0.0.1:9090、secret に設定した文字列を入力。
  • metacubexd：Mihomo 向けに更新された UI 系。接続先の指定方法は同様。
  • Clash Verge Rev 内蔵：ビルドによっては「ダッシュボード」「接続」タブがすでに同 API を叩いているため、内蔵 UI だけで足りる場合もあります。

接続に成功するとConnections にリアルタイムでセッションが流れ、Proxies からノードやポリシーグループを切り替えられます。ルールの当たり方を確認したいときは、対象サイトへ一度アクセスしてから Connections のルール名・ポリシー名列を見ると、GUI ログより俯瞰しやすいことがあります。ルール設計の基礎は カスタムルールの記事 と チュートリアル を参照してください。

ステップ 7：運用時の安全習慣

管理 API を有効にしたあとも、次の習慣を守ると事故が減ります。

  • バインドは 127.0.0.1 デフォルト：「とりあえず全部開く」0.0.0.0 は避ける。
  • secret は常に非空：空 secret + LAN 公開は最悪の組み合わせ。
  • 管理ポートをプロキシ共有と混同しない：スマホ用は mixed-port と allow-lan の話（別記事）。
  • 不要になったら無効化：長期間 Web UI を使わないなら Mixin から行を外すかコメントアウト。
  • 購読 URL と secret を同じメモに書かない：漏洩時の被害範囲を分離。

開発者が curl で API を叩く場合も、secret はヘッダ Authorization: Bearer <secret>（ビルドにより形式が異なる場合あり）で送り、ターミナル履歴に残さないよう注意します。詳細な API 仕様は利用中の Mihomo リリースノートを参照してください。

うまくいかないときの切り分け

Web UI が「Unauthorized」や接続拒否

secret の typo、Mixin と GUI の二重設定で古い secret が残っている、Web UI 側に secret 未入力、が典型です。コア再起動後に Web UI の secret 欄を空にして再入力し、Mixin の引用符の有無も確認してください。

9090 が別アプリに取られている

netstat の PID からタスクマネージャでプロセスを特定し、競合するなら 9091 などへ変更。Mixin・GUI・Web UI の三か所でポート番号を揃えます。

接続一覧は出るがノード切替が効かない

プロファイル名の typo や、購読側 proxy-groups の型（select 以外）により API が拒否することがあります。Verge 内蔵 UI では切替できるか比較すると、API 側か UI 側か切り分けられます。ポリシーグループの読み方は ポリシーグループ選択の記事 も参考になります。

よくある質問

external-controller をオンにすると速度は落ちますか？

通常は体感差ありません。API は管理トラフィック用で、プロキシ転送経路とは別です。ただし debug ログを常時大量出力する設定と混在するとディスク I/O が増えることはあるので、ログレベルは必要時だけ上げてください。

タブレットから同じ Wi‑Fi 経由でダッシュボードを見たい

推奨は PC 上で SSH やリモートデスクトップ経由でブラウザを見る方法です。どうしても LAN 直公開するなら 0.0.0.0 + 強い secret + ファイアウォールで送信元 IP を限定するなど多層防御が必要です。プロキシ共有だけが目的なら管理ポートは開けないでください。

購読 YAML にすでに external-controller があります

プロバイダが 127.0.0.1:9090 を既に書いている場合、secret だけ Mixin で上書き追加できることがあります。逆に 0.0.0.0 になっていたら Mixin で 127.0.0.1 に差し替え、secret を必ず足してください。

まとめ

Windows 11 の Clash Verge Rev で Web ダッシュボードを使う要点は、(1) external-controller を 127.0.0.1 に立てる、(2) secret を長い乱数で必ず設定、(3) yacd 等の Web UI に API アドレスを教える、(4) allow-lan やプロキシポートと混同しない、の四点に集約されます。Mixin で差分を書けば購読更新後も設定が残りやすく、トラブル時は netstat と Verge の再読み込みから確認してください。

一方、スイッチ一つで完結する従来型 VPN クライアントの多くは、接続セッションやルール命中の詳細をユーザーに見せないため、ノードや DNS の問題が起きても「国を変える」以外の手がかりが少ないことがあります。Mihomo ベースのスタックは external-controller 経由で観測・操作の自由度が高く、開発者やルールをいじる利用者に向いています。CLI やサーバー運用と同じ API 思想をデスクトップ GUI から受け取れるのも強みです。環境に合うビルドを選び、安全な secret 運用から試したい方は ダウンロードページ で最新版を確認し、本稿の手順と Mixin 記事 を組み合わせてみてください。