Clash Verge Revの「外部コントローラー」は、プロキシ通信を受け付けるポートとは別に用意された管理用インターフェースです。Webパネルから現在の接続、ルール、プロキシグループ、トラフィック情報を確認したり、API経由で選択中のノードを変更したりできます。Windowsで設定するときは、外部コントローラーのアドレス、管理ポート、認証用のSecretを正しくそろえることが重要です。
Clash Verge Revの外部コントローラーをWindowsで設定する方法
外部コントローラーとプロキシポートを区別する
Clash Verge Revには、通常の通信を受け付けるプロキシポートと、クライアントやWebパネルから管理操作を受け付ける外部コントローラーがあります。たとえば mixed-port: 7890 はブラウザーやアプリのHTTP・SOCKS接続に使うポートです。一方、external-controller: 127.0.0.1:9090 は、管理画面がClashの状態を読み取るためのAPIポートです。
この2つは用途が異なるため、ブラウザーのプロキシ設定を9090番へ向けてもWebサイトは開けません。逆に、管理用Webパネルを7890番へ接続しても、コントローラーAPIとして応答しないか、通常のプロキシ通信として扱われます。接続テストを始める前に、どのポートが何の目的で動作しているかを整理しておきましょう。
| 項目 | 主な用途 | 設定例 |
|---|---|---|
| mixed-port | HTTP・SOCKSプロキシとしてアプリの通信を受け付ける | 7890 |
| external-controller | WebパネルやAPIからClashを管理する | 127.0.0.1:9090 |
| secret | コントローラーAPIへのアクセスを認証する | 長いランダム文字列 |
Windowsで設定を変更する前の準備
設定を変更する前に、Clash Verge Revが起動しており、使用するコアが正常に動作していることを確認します。画面を閉じただけではバックグラウンドプロセスが残る場合があるため、タスクバーの通知領域にClash Verge Revが存在するか、アプリのログにコア起動エラーがないかを確認してください。設定を保存する前に、現在のYAMLファイルやプロファイルを複製しておくと、入力ミスがあった場合に元へ戻せます。
Clash Verge Revの画面構成や項目名は、リリース時期、使用するコア、表示言語によって多少異なります。「設定」「Profiles」「General」「Core」などの画面を確認し、外部コントローラーに関する項目を探してください。GUIに専用欄がない場合は、プロファイルまたはローカル設定のYAMLに記述します。ただし、サブスクリプションから取得した設定を直接編集すると、次回更新時に変更が失われることがあります。
設定をバックアップする
バックアップ対象は、サブスクリプションURLだけではありません。現在使っているプロファイル、ローカルオーバーライド、コア設定、プロキシグループの選択状態を確認します。外部コントローラーの secret は認証情報にあたるため、公開フォルダーや共有ドライブへ無防備に保存しないでください。設定を質問サイトやチャットに貼り付けるときも、Secret、サブスクリプションURL、ノードのパスワードは削除または置換します。
最初はローカル接続に限定する
Windows上のClash Verge Revだけから管理するなら、外部コントローラーは 127.0.0.1 または localhost で待ち受けさせるのが安全です。これにより、同じPC上のアプリからは接続できますが、同じWi-Fiに接続したスマートフォンや他のPCからは直接アクセスできません。LAN上の別端末から操作する必要がない限り、待受アドレスを 0.0.0.0 に変更しないでください。
外部コントローラーを有効にする設定例
設定項目の名称はコアによって異なる場合がありますが、基本的な構造は次のようになります。管理ポートには、プロキシポートと重複しない未使用の番号を指定します。9090番が別のアプリで使われている場合は、9091や19090など別のポートを選びます。ポート番号を変更したら、Webパネル側の接続先も同じ番号へ変更してください。
mixed-port: 7890
mode: rule
allow-lan: false
external-controller: 127.0.0.1:9090
secret: "replace-with-a-random-secret"
external-controller の値は、一般に IPアドレス:ポート番号 の形式で指定します。ローカル専用なら 127.0.0.1:9090 を使用します。secret が設定されている場合、Webパネルはリクエストの認証ヘッダーにこの値を付けて接続します。Secretを設定したのにWebパネル側で空欄にすると、ポートが開いていても認証エラーになります。
YAMLではインデントだけでなく、コロン、引用符、特殊文字にも注意してください。Secretに記号を含める場合はダブルクォートで囲み、タブ文字は使用しない方が安全です。保存後は、Clash Verge Revでプロファイルを再読み込みするか、コアを再起動します。単にファイルを保存しただけでは、実行中のコアへ変更が反映されないことがあります。
LANから接続する場合の追加設定
別の端末からWebパネルへ接続したい場合は、外部コントローラーをWindowsのLANアドレスで待ち受けさせる方法があります。ただし、単純に 0.0.0.0:9090 を設定すると、同一ネットワーク上の広い範囲から管理APIへ到達できる可能性があります。強力で推測しにくいSecretを設定し、Windows Defenderファイアウォールの受信規則をプライベートネットワークだけに限定してください。公共Wi-Fiや信頼できないネットワークで管理ポートを公開するのは避けます。
Webパネルから接続して動作を確認する
コアを再起動したら、Webパネルの接続設定を開きます。接続先には、外部コントローラーのホストとポートを入力します。ローカル設定なら、通常は http://127.0.0.1:9090 のようなアドレスになります。パネルによってはURLの末尾にパスを追加する場合があるため、入力欄の説明に従ってください。Secretの入力欄にはYAMLに設定した値をそのまま入力します。
接続に成功すると、現在のモード、プロキシグループ、接続一覧、メモリ使用量、アップロード・ダウンロード量などが表示されます。まず表示だけを確認し、その後にプロキシグループの一覧を開きます。グループ名とノード名が正しく表示され、選択状態がClash Verge Revの画面と一致していれば、APIが実行中のコアへ接続できています。
管理操作をテストするときは、いきなり複数の設定を変更せず、プロキシグループの選択を一度だけ切り替えます。Clash Verge Rev本体の画面で選択状態が変わるか、接続ログに新しい通信が表示されるかを確認してください。Webパネル上で変更した内容が画面に反映されても、元のYAMLファイルへ永続保存されるとは限りません。再起動後も維持したい設定は、プロファイルやオーバーライド側で管理します。
curl http://127.0.0.1:9090/version
curl -H "Authorization: Bearer replace-with-a-random-secret" ^
http://127.0.0.1:9090/proxies
WindowsのPowerShellやコマンドプロンプトからAPIの応答を確認することもできます。Secretを設定していない場合は、1つ目のような公開エンドポイントが応答することがあります。Secretを設定している場合は、2つ目のように Authorization: Bearer ヘッダーを付けます。バージョン情報が返ればポートまで到達できています。プロキシ一覧がJSONで返れば、認証を含むAPI接続も確認できます。
接続できないときの切り分け
Webパネルに接続できない場合は、エラーメッセージを「ポートへ到達できない」「認証に失敗した」「API形式が合わない」の3種類に分けて確認します。最初にClash Verge Revのログでコアが起動しているか、設定エラーで停止していないかを調べます。YAMLの読み込み失敗があると、設定に外部コントローラーを書いていても待受ポート自体が開きません。
| 症状 | 主な原因 | 確認方法 |
|---|---|---|
| 接続が拒否される | コア停止、ポート違い、待受アドレス違い | 設定値とコアのログ、待受状態を確認する |
| 401や認証エラー | Secretの不一致、Bearer認証の不足 | Secretを再入力し、余分な空白を削除する |
| ページは開くが情報が表示されない | APIパスやコアの互換性の違い | Webパネルが想定するコアとAPI形式を確認する |
| 別PCから接続できない | 127.0.0.1待受、ファイアウォール、LAN制限 | LANアドレス、受信規則、ネットワーク種別を確認する |
Windowsで待受ポートを確認する
9090番を設定した場合、PowerShellまたはコマンドプロンプトで待受状態を確認できます。何も表示されなければ、指定したポートでコアが待ち受けていない可能性があります。別のプロセスが同じポートを使っている場合は、Clashのポートを変更してからコアを再起動します。
netstat -ano | findstr :9090
Test-NetConnection 127.0.0.1 -Port 9090
Test-NetConnection の TcpTestSucceeded が False なら、Webパネルの入力内容を変更する前に、Clash Verge Rev側の待受状態を確認してください。True なのに認証エラーが出る場合は、ポートではなくSecret、APIパス、またはWebパネルの互換性が問題になっている可能性が高いでしょう。
Secretとファイアウォールを再確認する
Secretの前後に空白が入っていないか、引用符を値の一部として入力していないかを確認します。YAMLの secret: "abc" で実際のSecretは abc であり、ダブルクォート自体は含みません。設定を変更した後は、実行中のコアを再起動してからテストします。
Windows Defenderファイアウォールの警告が表示された場合、内容を確認せずにすべてのネットワークで許可しないでください。ローカル専用なら外部からの受信許可は不要です。LAN接続が必要な場合だけ、プライベートネットワークと指定したポートに限定します。外部コントローラーは強い権限を持つため、インターネットへ直接公開したり、SecretをURLや公開ログへ記録したりしないようにしてください。
安定して運用するための確認項目
設定が完了したら、Clash Verge Revを一度終了して再起動し、外部コントローラーのポートが毎回同じ番号で開くかを確認します。動的なポートや別のプロファイルを使っていると、再起動後にWebパネルの接続先が変わることがあります。使用するプロファイル、コア、管理ポートを固定し、不要な古い設定を整理すると切り分けが容易になります。
- 待受アドレス:同じWindows PCだけで使うなら
127.0.0.1を維持する。 - 管理ポート:7890などのプロキシポートと分け、他のアプリと重複させない。
- 認証:推測しにくいSecretを設定し、公開画面や共有ログに残さない。
- 反映方法:YAMLを保存した後、プロファイルの再読み込みまたはコア再起動を行う。
- 永続化:サブスクリプション更新で消えないオーバーライドやローカル設定を使用する。
- 確認:Webパネルの表示だけでなく、API応答とClashの接続ログも確認する。
外部コントローラーは、ノードの切り替えや接続状況の確認を便利にする一方、設定情報を読み取り、管理操作を実行できるインターフェースでもあります。Windowsでの基本構成は「ローカルアドレスで待ち受ける」「管理ポートをプロキシポートと分ける」「Secretを設定する」「再起動後にAPI応答を確認する」の4点です。この順番で確認すれば、Webパネルへ接続できない場合も、コア、ポート、認証、ファイアウォールのどこに問題があるかを段階的に特定できます。