Clash Verge Revの外部コントローラー設定方法｜Windows入門

外部コントローラーとは何かを先に理解する

Clash Verge Revの外部コントローラーは、mihomoなどのカーネルを外部から操作するためのHTTP APIです。ブラウザーでWebパネルを開いて現在のプロキシ状態を確認したり、プロキシグループの選択を変更したり、接続一覧やログを確認したりできます。Windowsのシステムプロキシを設定するためのポートや、実際にWebサイトへ接続するための混合ポートとは役割が異なります。

127.0.0.1は同じWindowsパソコンからだけ接続できるループバックアドレスです。自宅LAN上の別の端末から管理する必要がなければ、まずこのアドレスを使ってください。0.0.0.0やパソコンのLANアドレスで待ち受けると、同じネットワーク上の端末からAPIポートへ到達できる可能性があり、認証設定やWindowsファイアウォールの管理が必要になります。

Windowsで設定する前の確認項目

設定を変更する前に、Clash Verge Revが起動していること、mihomoカーネルが正常に動作していること、現在使用中のプロファイルが読み込まれていることを確認します。画面が表示されていてもカーネルが停止していれば、外部コントローラーはポートを開きません。プロファイルを切り替えた直後は設定の再読み込みが行われるため、数秒待ってから状態を確認してください。

• Clash Verge RevをWindowsのスタートメニューまたはインストール先から起動する。
• トレイアイコンが表示され、カーネルが実行中であることを確認する。
• 現在のプロファイルにexternal-controllerまたは同等の外部コントローラー設定があるか確認する。
• 外部コントローラーのポート番号が、ほかのアプリケーションと重複していないことを確認する。
• 設定変更前に、購読URLや手動編集したYAMLをバックアップする。

プロファイル側に外部コントローラーを記述する場合、基本的な構造は次のようになります。Clash Verge Revの画面で設定を管理している場合は、同じ項目を画面から入力できることがあります。YAMLを直接編集する場合は、タブではなく半角スペースを使い、キー名の綴りとインデントを確認してください。

external-controller: 127.0.0.1:9090
secret: change-this-secret

すでに設定ファイルにexternal-controllerがある場合は、同じキーを2回追加しないでください。後から記述した値が採用されるとは限らず、クライアントの生成処理によって上書きされることもあります。Clash Verge Revがプロファイルを自動生成している場合は、プロファイルの編集内容とクライアント側の一般設定のどちらが優先されるかを確認する必要があります。

Clash Verge Revで外部コントローラーを設定する手順

設定画面を開く

Clash Verge Revを起動し、左側または上部にある設定画面を開きます。バージョンや表示言語によって項目名は「Settings」「設定」「General」「一般」など異なる場合があります。外部コントローラー、API、Controller、Web UIに関係する項目を探してください。プロファイルの編集画面にある場合と、アプリケーション全体の設定画面にある場合があるため、見つからないときは両方を確認します。

アドレスとポートを入力する

外部コントローラーのアドレスには、まず127.0.0.1:9090を入力します。9090が使用中の場合は、たとえば127.0.0.1:9091へ変更できます。ただし、ポート番号を変更した場合は、Webパネル側の接続先も同じ番号に合わせなければなりません。入力欄がアドレスとポートに分かれている場合は、アドレスへ127.0.0.1、ポートへ9090を指定します。

認証欄には、設定ファイルのsecretと同じ文字列を入力します。secretを設定している場合、WebパネルはAPIリクエストに認証情報を付けて送信します。アドレス、ポート、secretのいずれか1つが違うだけでも、外部コントローラーへ接続できません。secretに日本語や前後の空白を含めると入力ミスを見つけにくいため、半角英数字と記号を組み合わせた十分に長い文字列を使用してください。

保存してカーネルを再読み込みする

1. 外部コントローラーのアドレス、ポート、secretを入力します。
2. 「保存」「Apply」「適用」などのボタンをクリックします。
3. 必要に応じてプロファイルを再読み込みします。
4. カーネルを再起動し、ログにポートの待ち受け開始が表示されるか確認します。
5. Webパネルを開き、接続先と認証情報を入力します。

設定を保存しただけでカーネルへ反映されない場合があります。その場合はClash Verge Revを完全に終了するのではなく、まずプロファイルの再読み込み、カーネルの再起動、アプリの再起動の順に試してください。WindowsのタスクトレイにClash Verge Revが残っていると、ウィンドウを閉じただけではプロセスが動作し続けることがあります。

WebパネルとAPIの接続を確認する

Webパネルを開いたら、接続先に外部コントローラーのURLを入力します。一般的な形式はhttp://127.0.0.1:9090です。Webパネルによっては、APIのURLだけでなく、Web UIのパスや管理画面の入口を個別に指定する場合があります。Clash Verge Revに内蔵された画面を使う場合は、アプリ内のWebパネル起動ボタンを優先してください。

接続に成功すると、プロキシグループ、現在の選択ノード、カーネルのバージョン、接続一覧などが表示されます。最初にノードを切り替えるのではなく、次の順番で読み取り確認を行うと安全です。

1. カーネルのバージョンまたは稼働状態が表示されるか確認する。
2. プロキシグループの一覧が取得できるか確認する。
3. 現在のモードがrule、global、directのどれかを確認する。
4. テスト用のWebサイトを開き、接続ログに通信が表示されるか確認する。
5. 必要な場合だけプロキシグループの選択を変更する。

WindowsのPowerShellからAPIの応答を確認する方法もあります。secretを設定している場合は、Authorizationヘッダーを付けます。次の例では、APIが稼働しているかだけを確認します。実際のポート番号が9090以外なら置き換えてください。

curl.exe -H "Authorization: Bearer change-this-secret" `
  http://127.0.0.1:9090/version

正常に応答すれば、Clash系カーネルのバージョン情報を含むJSONが返ります。401や403が返る場合はsecretが違う、ヘッダーの形式がWebパネルと一致していない、または別のAPIポートへ接続している可能性があります。接続拒否やタイムアウトの場合は、認証より前に、カーネルが起動しているか、ポート番号が正しいかを確認してください。

つながらない場合のWindows確認手順

外部コントローラーに接続できないときは、Webパネルを何度も再読み込みするより、アドレス、プロセス、ポート、認証の順に確認すると原因を絞り込めます。最初にブラウザーでhttp://127.0.0.1:9090を開き、WebパネルではなくAPIの接続先を入力していないか確認してください。APIポートは通常のWebページを表示するためのサーバーとは異なるため、ブラウザーにJSONやエラーが表示されても、それだけで異常とは限りません。

ポートの使用状況を確認する

PowerShellで次のコマンドを実行すると、9090番ポートを待ち受けているプロセスを確認できます。

Get-NetTCPConnection -LocalPort 9090 -State Listen

何も表示されない場合は、mihomoが9090番で待ち受けていません。Clash Verge Revの設定が別ポートになっている、プロファイルが読み込まれていない、カーネルが起動していない、別の設定が外部コントローラーを無効にしている、といった可能性があります。別のプロセスが9090番を使用している場合は、Clash Verge Revのポートを9091などへ変更し、アプリとWebパネルの両方を更新してください。

アドレスとファイアウォールを確認する

同じWindowsパソコンから127.0.0.1で接続できるのに、スマートフォンや別のパソコンから接続できない場合は、外部コントローラーがループバックだけで待ち受けている可能性があります。LAN内の別端末から接続するには、Clash Verge Rev側の待ち受けアドレス、Windowsファイアウォールの受信規則、ルーターのクライアント分離設定を確認します。

ただし、Windowsファイアウォールを一時的に無効化して原因を調べる方法は推奨しません。必要であればTCPの対象ポートだけを許可し、プロファイルをプライベートネットワークに限定します。インターネット側から管理ポートを公開するポート転送は行わないでください。外部コントローラーは管理APIであり、通常のプロキシ接続用ポートとして公開するものではありません。

設定を初期化する前に確認する

secretを忘れた場合や設定を何度も変更して状態が分からなくなった場合でも、最初からアプリのデータフォルダーを削除する必要はありません。まずClash Verge Revを終了し、購読URL、プロファイル、手動オーバーライドをバックアップします。その後、外部コントローラーを127.0.0.1:9090へ戻し、単純な半角英数字のテスト用secretで起動確認を行います。接続できたら、強度のあるsecretへ変更し、Webパネル側にも同じ値を再入力してください。

日常利用で守るべき安全な運用方法

外部コントローラーは便利ですが、接続できる端末からプロキシグループの切り替え、接続の終了、設定状態の確認などを実行できます。secretをサブスクリプションURLと同じ文字列にしたり、スクリーンショットへ表示したまま共有したりしないでください。購読URLと外部コントローラーのsecretは別々に管理し、ログやPowerShellの履歴に完全な値を残さないことも重要です。

• ローカル操作だけなら、待ち受けアドレスは127.0.0.1にする。
• 外部コントローラーのポートをインターネットへ公開しない。
• secretは短い文字列や購読トークンの使い回しを避ける。
• Webパネルを使い終わったら、共有パソコンではログアウトまたは画面を閉じる。
• 設定変更後は、WindowsのシステムプロキシとTUNの状態を確認する。
• プロファイル更新後に外部コントローラーのアドレスやsecretが変わっていないか確認する。

最初の設定では、システムプロキシを有効にする前にWebパネルとAPIの接続だけを確認するのがおすすめです。外部コントローラーが正常に応答し、プロキシグループが表示され、テスト通信がログに記録されてから、必要に応じてWindowsのシステムプロキシやTUNを有効にします。こうすると「APIが動かない問題」と「通信転送の問題」を分けて調べられます。