外部コントローラーとは：Clash Verge RevをWebパネルから操作する仕組み
Clash Verge Rev の「外部コントローラー」は、Clash コアが提供する管理用 API を、ブラウザの Webパネルや別の管理ツールから操作するための待ち受け設定です。通常の利用では Verge Rev の画面だけでプロキシグループ、モード、接続状況を変更できますが、外部コントローラーを有効にすると、同じ Windows PC 上のブラウザから API の状態を確認したり、対応するダッシュボードでノードを切り替えたりできます。
ここで混同しやすいのが、外部コントローラーのポートと mixed-port です。mixed-port はブラウザやアプリがプロキシ通信を送るためのポートであり、外部コントローラーのポートは設定 API にアクセスするためのポートです。たとえば mixed-port が 7890、外部コントローラーが 9090 なら、前者へブラウザのプロキシ通信を送り、後者へ管理画面の HTTP リクエストを送ります。目的も認証方法も異なるため、同じ番号を何となく入力しないことが重要です。
Windowsで設定する前の確認事項
設定を始める前に、Clash Verge Rev が正常に起動し、実際に mihomo などのコアが動作していることを確認します。タスクトレイのアイコンだけが表示されていても、コアの起動に失敗していれば管理 API は待ち受けません。まず Profiles または設定画面でアクティブなプロファイルを確認し、画面内のログに YAML の構文エラー、ポート競合、コア起動失敗が出ていないかを見ます。
次に、Windows のファイアウォールやセキュリティソフトがローカル通信を遮断していないかを確認します。外部コントローラーを 127.0.0.1 または localhost だけで待ち受ける場合、同じ PC のブラウザから接続する限り、LAN 上の別端末には公開されません。一方、待ち受けアドレスを 0.0.0.0 にすると、設定によっては同じネットワーク上の他端末から到達可能になります。便利ですが、Secret を設定しないまま公開すると、第三者にプロキシ設定を変更される危険があります。
企業ネットワークや共有 Wi-Fi で利用する場合は、外部コントローラーを LAN 全体へ公開しない方が安全です。ルーターのポート転送は不要であり、管理 API をインターネットへ直接公開する構成も避けてください。必要なのは、まずローカルホストから接続できる最小構成を完成させ、その後にどうしても必要な範囲だけアクセス元を限定することです。
Clash Verge RevでポートとSecretを設定する手順
Clash Verge Rev の設定画面はビルドや日本語化の状態によって項目名が少し異なりますが、探す場所はおおむね Settings、General、Core、またはコア設定に近い領域です。「External Controller」「外部コントローラー」「Controller」「API」などの名称を探してください。購読プロファイル内の proxy 設定と、GUI がコアへ渡すランタイム設定が別管理になっている場合もあるため、編集した値が実際の起動コアへ反映される画面を選びます。
- Clash Verge Rev を起動し、使用中のプロファイルとコアの状態を確認します。
- 設定画面で外部コントローラーのホストとポートを開きます。
- 同じ Windows PC だけから使うなら、ホストは
127.0.0.1またはlocalhostにします。 - 未使用のローカルポートを選び、例として
9090を入力します。 - Secret に十分長いランダムな文字列を設定し、保存または適用します。
- コアを再起動するか、設定の Reload を実行して、実際に待ち受けが始まったことを確認します。
Secret は短い単語や Windows のユーザー名ではなく、推測しにくい文字列を使います。Web パネルによっては Secret を HTTP ヘッダーの Authorization: Bearer として送信しますが、入力欄へ貼り付ける形式や URL の末尾へ指定する形式もあります。Secret を設定した直後に管理画面が「Unauthorized」や「401」と表示される場合、ポートが間違っているとは限りません。API へ到達しているものの、認証情報の形式または値が一致していない可能性があります。
| 項目 | 役割 | ローカル利用の例 |
|---|---|---|
| mixed-port | アプリやブラウザのプロキシ通信 | 7890 |
| external-controller | 設定・状態を操作する API | 127.0.0.1:9090 |
| secret | 管理 API の認証 | ランダムな長い文字列 |
| 待ち受け範囲 | 接続できる端末の範囲 | 127.0.0.1 に限定 |
Webパネルへの接続と動作テスト
設定後は、対応する Web パネルをブラウザで開き、接続先として http://127.0.0.1:9090 のようなアドレスを指定します。実際のポートは自分で設定した値に置き換えてください。パネル側に「Controller URL」「Backend URL」「API Host」などの欄がある場合、そこへホストとポートを入力し、Secret 欄には Clash Verge Rev 側と完全に同じ値を貼り付けます。前後に空白が入ると認証に失敗するため、パスワード管理ツールから貼り付けた後に不要な改行がないか確認します。
接続できたら、いきなりプロキシグループを変更するのではなく、まずコアのバージョン、現在のモード、プロキシグループ一覧、接続一覧が読み込めるかを確認します。読み取りだけ成功して変更操作が失敗する場合は、API の権限ではなく Web パネルとコアの互換性を疑います。mihomo 向けに作られたパネルを別系統の Clash コアへ接続すると、基本情報は表示されても、プロバイダーやルール操作だけが利用できないことがあります。
テストは次の順序で行うと、問題の場所を絞りやすくなります。まずブラウザで API のアドレスへ到達できるか、次に Secret を正しく送信できるか、最後にグループ切り替えなどの書き込み操作が反映されるかを確認します。管理画面が真っ白な場合はブラウザのキャッシュやパネル側の JavaScript エラー、ページ自体が開かない場合はポートまたは待ち受け、401 が返る場合は Secret、404 が返る場合は API パスやコアの対応を確認します。
Windowsで待ち受けを確認する
GUI で状態が分からないときは、PowerShell から TCP ポートを確認できます。次のコマンドは Windows PC のローカルポートへ接続できるかを調べるだけで、設定変更は行いません。
Test-NetConnection 127.0.0.1 -Port 9090
TcpTestSucceeded : True なら、そのポートへの TCP 接続は成立しています。False の場合は、コアが起動していない、ポート番号が違う、別のアプリが設定を占有している、またはセキュリティソフトが遮断している可能性があります。PowerShell の結果が True でも Web パネルが認証エラーになることはあるため、TCP 接続の成功を Secret の検証結果と混同しないでください。
アクセスできないときの切り分け
最も多いのは、設定を書き換えた場所と実際に起動しているコアが参照する場所が違うケースです。購読 URL から取得したプロファイルを直接編集しても、次回更新で元へ戻ったり、GUI が別のローカル設定を優先したりします。設定を保存した後に再起動し、画面へ戻って値が残っているかを確認してください。値が消える場合は、編集対象が一時生成ファイルでないか、プロファイルのオーバーライド機能が有効でないかを調べます。
次に、ポートの衝突を確認します。9090 がすでに別サービスで使われていると、Clash コアが起動時に失敗するか、設定が反映されないことがあります。別の番号へ変更する前に、ログで bind error や address already in use に相当する表示を探します。Windows のファイアウォール許可ダイアログが出た場合は、接続元を確認したうえで、必要以上にパブリックネットワークへ公開しないようにします。
Web パネルへ接続できるのにノード切り替えが反映されない場合は、パネルのバックエンド種別を確認します。Clash API、mihomo API、別クライアント向け API では、似た名前でも利用できるエンドポイントが異なります。また、外部コントローラーの値に 127.0.0.1:9090 と書くべきところへ、mixed-port の 7890 を指定していると、ブラウザは応答を待ち続けます。接続先を表にして、各ポートの用途を一つずつ照合すると混乱を減らせます。
安全上の注意：外部コントローラーは管理権限に近い機能を持つため、Secret を公開スクリーンショット、共有ログ、購読 URL、チャットへ貼り付けないでください。LAN 公開が必要な場合も、まずローカル限定で動作を確認し、信頼できるネットワークだけに限定します。確認が終わったら不要な LAN 待ち受けを閉じる運用が安全です。
Clash for Windows の古い手順はメニュー名や API の前提が異なることがあり、単純に画面を置き換えると Secret やコア互換性の確認が抜けがちです。手動で YAML を編集する方法も再現性はありますが、購読更新で上書きされやすく、初心者には反映箇所の追跡が難しくなります。その点、Clash V.CORE は Windows 上でのプロファイル管理、mihomo 系コアの運用、ポート確認、管理 API の設定を一つの流れで扱いやすく、設定画面から状態を確認しながら外部コントローラーを組み立てられます。古いクライアントの画面差分や手動編集の不安を減らしたい方は、Windows向けの Clash V.CORE をダウンロードして、自分の環境で安全なローカル管理から始めてみてください。