はじめに
Clash Verge Rev には、内蔵の管理画面だけでなく、外部ツールやスクリプトからプロキシの状態を操作できる 外部コントローラー（External Controller） 機能があります。API に接続すると、現在選択されているプロキシの確認、プロキシグループの切り替え、接続情報の取得、トラフィック状況の確認などを、別の管理ツールから実行できます。
ただし、外部コントローラーは便利である一方、ポート番号やアクセス許可の設定を誤ると、同じネットワーク上の他の端末から管理 API に接続される可能性があります。本記事では、Windows 版 Clash Verge Rev を対象に、設定画面で入力する項目、YAML に記述する場合の形式、動作確認、接続できない場合の切り分けまでを順番に解説します。
この記事の目標
Windows 上の Clash Verge Rev で安全に外部コントローラーを有効化し、API の待ち受け状態と認証を確認できるようにします。
1外部コントローラーの仕組み
外部コントローラーは、Clash のコアが提供する HTTP API です。Clash Verge Rev の画面を直接操作する代わりに、指定したポートへ HTTP リクエストを送信して状態を読み取ったり、設定を変更したりします。代表的な接続先は 127.0.0.1:9090 のようなローカルアドレスです。
この機能では、次のような情報を扱えます。利用するクライアントやコアの種類によって、利用可能なエンドポイントや表示名が異なる場合があるため、すべての機能が同じように動作するとは限りません。
- プロキシグループ： 現在の選択ノードを確認し、別のノードへ切り替えます。
- 接続情報： 現在の接続数、アップロード量、ダウンロード量などを取得します。
- 設定状態： コアが起動しているか、現在のモードが Rule、Global、Direct のどれかを確認します。
- 外部ツール連携： デスクトップウィジェット、監視スクリプト、ローカルの操作パネルなどから状態を参照します。
公開範囲に注意
外部コントローラーは通常のウェブサイト閲覧用プロキシとは別の管理 API です。必要がなければ 127.0.0.1 のまま使用し、インターネット側のアドレスや無制限の LAN 公開には変更しないでください。
2Windows の設定画面で有効化する
最初は、設定ファイルを直接編集するよりも Clash Verge Rev の設定画面から確認する方法がおすすめです。バージョンや日本語化の状態によって項目名が少し異なることがありますが、通常は「Settings」「設定」「General」「外部コントローラー」に近い項目を探します。
- Clash Verge Rev を起動し、タスクトレイに常駐していることを確認します。
- 左側のメニューから Settings または 設定 を開きます。
- コア設定、詳細設定、Mihomo 設定などの中から External Controller または 外部コントローラー を探します。
- 待ち受けアドレスに
127.0.0.1:9090を入力します。別のアプリが使用している場合は127.0.0.1:9091など、空いているポートを選びます。 - API Secret、Secret、認証トークンなどの欄に、推測されにくい文字列を入力します。
- 保存後、Clash Verge Rev のコアを再起動します。設定画面を閉じただけでは反映されない場合があります。
ポート番号は、Windows の他のソフトウェアと重複しない番号を使用します。すでに同じポートを別のサービスが使っていると、設定を保存できても API が実際には起動しないことがあります。変更後は、必ずコアの再起動と接続テストを行ってください。
| 項目 | 設定例 | 役割 |
|---|---|---|
| 待ち受けアドレス | 127.0.0.1:9090 |
API を受け付ける IP アドレスとポート |
| Secret | ランダムな長い文字列 |
API 操作時の認証に使用するトークン |
| Allow LAN | OFF |
LAN 内の他端末からの接続を許可する設定 |
3YAML で設定する場合の書き方
GUI に該当項目が見つからない場合や、プロファイルを明示的に管理したい場合は、Mihomo の設定項目を確認します。一般的な設定名は external-controller と secret です。プロファイルの生成元によっては、アプリ側の設定が優先されることもあるため、編集前に現在のプロファイルをバックアップしてください。
external-controller は API の待ち受け先を指定します。127.0.0.1 は同じ Windows PC からのみ接続できるローカルアドレスです。secret は API リクエストの認証に使われ、allow-lan はプロキシの LAN 公開に関わる項目です。管理 API をローカルだけで利用する場合は、まずこの構成から始めると安全です。
LAN 上の別端末から操作したい場合は、外部コントローラーのアドレスを 0.0.0.0:9090 に変更する構成が使われることがあります。しかし、この設定は PC の全ネットワークインターフェースで API を待ち受けるため、Windows Defender ファイアウォール、ルーター、Wi-Fi の共有環境まで確認が必要です。単に接続できないからといって、無条件に 0.0.0.0 を指定するのは避けてください。
設定ファイル編集のポイント
YAML ではインデントやコロンの後の空白が意味を持ちます。Secret に記号や空白を含める場合は、値をダブルクォートで囲み、保存後に構文エラーがないか確認してください。
4API の接続を確認する
設定を保存してコアを再起動したら、まずポートが開いているかを確認します。Windows の PowerShell を起動し、次のコマンドを実行してください。ポート番号を変更した場合は、コマンド内の 9090 も同じ番号に置き換えます。
TcpTestSucceeded : True と表示されれば、指定したポートで何らかのサービスが待ち受けています。次に、Secret を HTTP ヘッダーへ渡して API の応答を確認します。
バージョン情報が JSON 形式で返れば、外部コントローラーは動作しています。認証を設定していない場合でも応答する構成はありますが、管理 API を保護するため、Secret を設定した状態でテストすることを推奨します。
確認結果の見方
- 接続成功・JSON が返る： ポート、アドレス、認証トークンが正しく設定されています。
- 接続拒否： コアが停止している、ポートが違う、または設定が反映されていない可能性があります。
- 401 Unauthorized： Secret が違う、または
Bearerの書式が正しくありません。 - タイムアウト： LAN 経由の場合、ファイアウォールや待ち受けアドレスを確認します。
5つながらない場合の見直しと安全対策
外部ツールから接続できない場合、最初から複数の項目を変更するのではなく、ローカル接続に戻して一つずつ確認します。まず Clash Verge Rev のコアが起動しているか、設定したポートと外部ツールのポートが一致しているか、Secret の前後に余分な空白がないかを確認してください。
- Clash Verge Rev を再起動する： プロファイルを更新した後は、古いコアプロセスが残っていることがあります。
- ポートの使用状況を確認する： PowerShell で
Get-NetTCPConnection -LocalPort 9090を実行し、別のプロセスが使用していないか確認します。 - アドレスを統一する： Clash 側が
127.0.0.1なのに、外部ツールが PC の LAN IP に接続していると通信できません。最初は同じ PC から127.0.0.1へ接続します。 - 認証ヘッダーを確認する： API クライアントによっては Secret 欄に文字列だけを入力し、別の設定で
Bearerを自動付与します。二重に付けないよう注意してください。 - ファイアウォールを確認する： LAN 接続が必要な場合だけ、該当ポートへの受信規則を限定的に作成します。
Secret を共有しない
外部コントローラーの Secret は、単なる閲覧用パスワードではなく、プロキシグループを変更できる管理用トークンです。スクリーンショット、公開ログ、Git リポジトリ、チャットへの貼り付けは避け、漏えいした場合はすぐに新しい値へ変更してください。
外部コントローラーを一時的に使うだけであれば、作業後に機能を無効化するか、待ち受けを 127.0.0.1 に戻しておくと安心です。複数の PC から操作する必要がある場合も、可能なら VPN や安全なリモートネットワークを経由し、API ポートを直接インターネットへ公開しないでください。
以上の手順で、Clash Verge Rev の外部コントローラーを Windows 上で設定し、ローカル API の動作まで確認できます。まずは読み取りテストから始め、プロキシ切り替えなどの変更操作は、認証とアクセス範囲を十分に確認してから利用しましょう。