Clash Verge Revの外部コントローラーをMacで設定する方法

外部コントローラーとは何か：Clash Verge RevをWeb画面で管理する仕組み

Clash Verge Rev の「外部コントローラー」は、Clashコアが持つ管理用APIを、同じMac上のブラウザや別の管理ツールから利用するための入口です。通常のGUIでは、プロファイルの切り替え、現在の接続、プロキシグループ、ログなどをアプリ内で操作します。一方、外部コントローラーを有効にすると、指定したアドレスとポートへHTTPリクエストを送り、Web画面から状態を確認したり、プロキシグループを切り替えたりできます。

ここでいう「外部」は、必ずしもインターネット上の公開サーバーを意味しません。Mac上で動いているClash Verge Revへ、同じMacのブラウザからアクセスするだけでも外部コントローラーの機能を使っています。重要なのは、APIがどのアドレスで待ち受けているか、アクセス時にどのAPIシークレットを送る必要があるか、そして他の端末から到達できる状態になっていないかを把握することです。

Clash Verge Revのビルドやコアの種類によって、メニュー名は「External Controller」「External Controller API」「Controller」「API」など少し異なる場合があります。画面のラベルが完全に一致しなくても、探す対象はコントローラーのアドレス、ポート番号、シークレット、アクセス制御の四つです。本稿ではmacOS上のClash Verge Revを前提に、設定、接続確認、失敗時の切り分けまでを順番に整理します。

事前確認：macOSの権限、Clashコア、ポートの競合

作業前に、Clash Verge RevがMacで正常に起動し、少なくとも一つのプロファイルが読み込まれていることを確認します。プロファイルの読み込みに失敗している状態では、API設定だけを変更してもコアが再起動を繰り返し、Web画面から接続できないように見えることがあります。まずアプリのホーム画面でコアが実行中であること、エラー表示が残っていないことを確認してください。

次に、Clash Verge Revが実際に使用しているコアを確認します。現在のビルドではmihomo系コアが使われることが多いものの、配布版や更新時期によって機能名と設定ファイルの扱いが変わります。外部コントローラーの設定項目が見当たらない場合、一般設定だけでなく「Profiles」「Mihomo」「Core」「Advanced」といったセクションも確認します。検索結果にある古いClash for Windowsや別クライアントの手順をそのまま適用すると、設定場所が一致しないことがあります。

ポート番号は、混合ポートやSocksポートと同じである必要はありません。たとえばブラウザ用のmixed-portが7890でも、外部コントローラーAPIは9090や別の番号で待ち受けます。両者を同じ番号にすると、すでに別サービスがポートを使用している場合や、HTTPプロキシとAPIの通信形式が衝突する場合があります。API用ポートは専用にし、既存のポートと重ならない値を選ぶのが安全です。

ポートが使われているかを確認する

設定を保存しても接続できない場合は、Macのターミナルで対象ポートを確認できます。たとえばAPIポートを9090にした場合は、次のように実行します。

lsof -nP -iTCP:9090 -sTCP:LISTEN

Clash Verge Revまたはmihomoに該当するプロセスが表示されれば、何らかのサービスが待ち受けています。何も表示されない場合は、設定がコアへ反映されていない、コアが停止している、あるいは指定したポートが別の設定で上書きされている可能性があります。なお、企業管理Macではファイアウォールやネットワーク拡張のポリシーにより、ローカル通信にも制限がかかることがあります。

Clash Verge Revで外部コントローラーを有効にする手順

Clash Verge Revを開き、まず設定画面へ移動します。バージョンによって場所は異なりますが、「Settings」「General」「Core」「Mihomo」の順に探すと見つけやすいです。設定画面内で外部コントローラーに相当する項目を開き、待受アドレスとポートを入力します。Mac上のブラウザだけで使うなら、アドレスは127.0.0.1、ポートは他のサービスと重ならない9090などに設定します。

アドレス欄が単に「Controller」と表示されている場合は、127.0.0.1:9090のようにアドレスとポートを一続きで入力する形式が一般的です。反対に、アドレスとポートが別欄になっている場合は、アドレスへ127.0.0.1、ポートへ9090を入力します。先頭にhttp://を付けるべきかどうかはUIの説明に従ってください。入力形式を間違えると、保存自体は成功してもコアが起動時に設定を拒否することがあります。

外部コントローラーを有効にした後は、設定を保存してコアを再起動します。Clash Verge Revの画面で「Restart Core」「Reload」「Apply」などのボタンが表示される場合は、変更を反映するために実行してください。再起動後、設定画面をもう一度開き、アドレス、ポート、シークレットが空欄に戻っていないか確認します。アプリが設定を保持しない場合は、権限不足やプロファイル側の上書きが疑われます。

APIシークレットを設定し、安全に保存する方法

APIシークレットは、外部コントローラーへ送る認証用の文字列です。設定欄が「Secret」「Secret Token」「API Secret」と表示されている場合は、推測されにくい長いランダム文字列を登録します。Macのログイン名、端末名、誕生日、購読URLの一部など、他人から推測できる文字列は使わないでください。Clash Verge Revの画面で生成機能が用意されている場合は、それを利用するのが簡単です。

シークレットを登録したら、設定ファイルやスクリーンショットを第三者へ共有する際に値が写り込んでいないか確認します。購読URLとAPIシークレットは役割が異なりますが、どちらも漏洩すると望ましくない操作や情報取得につながる可能性があります。チャットへログを貼り付ける場合も、Authorizationヘッダー、URLのクエリ、設定ファイル中のトークンを伏せ字にしてください。

シークレットを変更した後は、以前の値を使っているブラウザ拡張や管理ツールが接続できなくなります。これは故障ではなく、古い認証情報が拒否されている正常な状態です。新しい値を管理ツール側へ登録し直し、それでも接続できなければ、アドレスとポートが同じコアを指しているかを確認します。複数のClash系アプリをMacへ入れている場合、別アプリのAPIポートを見ているケースが特に多くあります。

認証ヘッダーとブラウザ画面の違い

APIクライアントは、一般にシークレットを認証用ヘッダーへ入れてリクエストします。ツールによっては設定画面へ値を入力するだけで自動処理されますが、単純にURLの末尾へシークレットを追加する方式とは限りません。認証に失敗したとき、ブラウザが空白ページを表示しても、実際には401 Unauthorizedや403 Forbiddenが返っていることがあります。Web画面の見た目だけで判断せず、開発者ツールや管理ツールの接続ログでHTTPステータスを確認してください。

Macのブラウザから接続し、APIが動くか確認する

設定を保存してコアを再起動したら、まず同じMacのブラウザでコントローラーのURLを開きます。ローカル設定が127.0.0.1:9090なら、管理画面を提供するWeb UIのURLは、そのツールの説明に従って開きます。APIポートそのものへアクセスしてJSONやエラーが表示されても、必ずしもWeb管理画面が同じ場所に存在するとは限りません。コントローラーAPIと、そこへ接続するWeb UIは別コンポーネントとして動く場合があります。

ブラウザ画面が表示されたら、接続中のプロキシ、現在のモード、プロキシグループ、通信ログが読み込めるかを確認します。単にトップ画面が開くだけではなく、実際にAPI経由でデータを取得できることが重要です。プロキシグループの切り替えを行う場合は、最初から本番用の設定を変更せず、影響の小さい検証用グループで操作し、Clash Verge Rev本体の画面にも変更が反映されるかを見ます。

ターミナルから疎通を確認する場合は、シークレットを履歴へ残さない方法を選びます。値を直接コマンドへ書くと、シェル履歴やプロセス一覧に残る可能性があります。まずは管理ツール側の接続テストを使い、必要な場合だけ公式ドキュメントに記載されたAPIエンドポイントへ、環境変数や対話入力を利用してリクエストします。応答が返っても、目的のコアを見ているか、ポート番号が想定どおりかを必ず照合してください。

接続できないときの切り分けとLAN利用時の注意

最初に確認するのは、ブラウザがアクセスしているアドレスと、Clash Verge Revの設定画面に表示されているアドレスが完全に一致しているかです。localhostと127.0.0.1は多くの環境で同じMacを指しますが、IPv6の::1へ解決される場合や、別のコンテナ・仮想環境へ向かう場合があります。検証中はアドレスを一つに固定し、まずIPv4のローカルアドレスで試すと判断しやすくなります。

次に、Clash Verge RevのログとmacOSのアクティビティを確認します。設定を保存した直後にコアが再起動していない、設定エラーが出ている、別のプロファイルへ切り替わっているといった状態では、APIの問題に見えても根本は設定の読み込み失敗です。プロファイルを更新するサービスを使っている場合、外部コントローラーの設定が購読更新で置き換えられていないかも確認してください。購読由来の設定とローカル設定の優先順位を把握しておくと、再発防止につながります。

同じMacでは接続できるのにiPhoneや別のMacから接続できない場合、待受アドレスが127.0.0.1になっている可能性が高いです。LAN内で使う必要がある場合だけ、MacのプライベートIPアドレスまたは適切なLANインターフェースで待ち受ける構成を検討します。その際は、macOSのファイアウォールで受信を許可し、ルーターのポート転送は設定せず、信頼できるネットワークに限定します。ゲストWi-Fiや公共ネットワークでは、APIポートを開いたままにしないでください。

使い終わったら外部コントローラーを無効にする、待受を127.0.0.1へ戻す、シークレットをローテーションする、といった後処理を行います。常時Web管理が必要でない人は、必要なときだけ有効にする運用が最も分かりやすいでしょう。アクセスログに見覚えのない操作がある場合は、直ちにシークレットを変更し、LAN上の不要な待受を停止してから原因を調べます。

よくある質問：Clash Verge Revの外部コントローラー

APIポートはmixed-portと同じにすべきですか？

いいえ、通常は別のポートを使います。mixed-portはブラウザやアプリのプロキシ通信を受ける入口で、外部コントローラーは管理APIの入口です。役割が違うため、API専用の空きポートを設定してください。

127.0.0.1で設定すると別のMacから使えませんか？

使えません。127.0.0.1は設定したMac自身を意味します。別端末から管理するにはLANから到達できる待受が必要ですが、セキュリティ上のリスクが増えるため、シークレット、ファイアウォール、信頼できるネットワークを必ず組み合わせてください。

APIは動いているのにWeb画面が開きません。なぜですか？

外部コントローラーAPIとWeb管理画面が別の機能である可能性があります。APIがJSONを返すことと、対応するWeb UIが表示されることは同じではありません。Clash Verge Revのビルドが提供する管理画面のURLと、利用しているWeb UIの互換性を確認してください。

シークレットを忘れた場合はどうしますか？

既存の値を推測し続けるより、Clash Verge Revの設定画面で新しいシークレットを生成して登録する方が安全です。変更後は、接続していたブラウザや管理ツールへ新しい値を再登録し、古い値がログや共有ファイルに残っていないか確認します。

旧来の軽量なメニューバー型クライアントは操作が手早い一方、外部APIの場所や認証状態を画面上で確認しにくく、別のWeb UIを組み合わせると互換性の切り分けが増えます。逆に汎用的なAPI管理ツールは柔軟ですが、ポートやシークレットを手作業で管理する負担があります。Clash V.COREなら、macOS向けの導入手順と設定確認をまとめて進めながら、Clash Verge Revとmihomoの動作を整理しやすく、外部コントローラーを安全に試すための土台も作れます。MacでWeb管理まで一度に整えたい方は、環境に合う版をダウンロードページから確認してください。