1 外部コントローラ（external-controller）とは
Mihomo／Clash 系のコアは、プロキシの実体としてポートを開きつつ、別ポートでREST 風の管理 APIを提供します。これがドキュメント上しばしば external-controller と呼ばれるエンドポイントで、接続してプロファイルの取得、セレクタ型プロキシグループの選択変更、ルールの一部操作、ログ参照などが可能になります。GUI クライアントが内部で同じ API を叩いていることも多く、Web ダッシュボードはその HTTP インターフェースにブラウザからアクセスする薄いフロントエンドと捉えると誤解が減ります。
secret は、その管理 API に対する共有鍵のようなものです。リクエストヘッダにトークンとして載せ、一致しないクライアントの操作を拒否します。公開インターネットに管理ポートを晒す構成では、推測されにくい長い secretとファイアウォールや VPN による到達制御の両方を検討するのが現実的です。逆に、同一マシンのループバックだけにバインドし、Yacd もローカルで開くなら、脅威モデルは「その PC にログインできる人」に近づきます。
2 設定ファイルでの external-controller と secret
典型的にはルート直下の config.yaml（またはクライアントがマージした最終設定）に、次のようなキーを置きます。ポート番号 9090 は慣例で、空いていなければ別の高位ポートに変えてください。secret は引用符で囲んだランダムな文字列にし、設定ファイルのパーミッションも他ユーザーから読めないようにします。
# External API for dashboards (Yacd, etc.)
external-controller: 127.0.0.1:9090
secret: "replace_with_a_long_random_string"
# Optional: TLS for controller (when supported by your build)
# external-controller-tls: ...
# secret: still required for Authorization in many setupsコアを再起動するか、ホットリロードに対応したクライアントなら「設定の再読み込み」を行うとリスナが更新されます。複数プロファイルを切り替える GUI では、どのプロファイルが実際にロードされているかを確認してから Yacd の接続先を合わせると、接続できない事象を減らせます。
external-controller が分かります。画面上のトグルと YAML の行き違いがあると、Yacd だけが別ポートを見に行く、というオチがよくあります。
3 待ち受けアドレス：127.0.0.1 と LAN・0.0.0.0
external-controller: 127.0.0.1:9090 は、同一端末上のブラウザやツールだけが接続できる最も閉じた形です。スマートフォンや別 PC のブラウザから見せたい場合は、ホストの LAN IP（例：192.168.1.10:9090）に届く必要があり、そのためには 0.0.0.0:9090 のようにすべてのインターフェースで聞くか、明示的に LAN アドレスを指定します。いずれの場合も、同じセグメントにいる機器からポートが見えることになり、家庭内とも職場 LAN とも信頼境界を取り違えないことが大切です。
VPS 上で Mihomo を動かし、インターネット側からダッシュボードを直に開けるようにするのは、認証と TLS、ソース IP 制限なしにはおすすめしにくい構成です。どうしても必要なら、リバースプロキシで HTTPS を終端し、Basic 認証や mTLS、許可 IP のリストなどを別層で足す、といった多層防御を検討してください。単に secret だけでは、ブルートフォースや中間者のリスク評価が変わります。
4 Yacd を開き、API ベース URL を合わせる
Yacd は静的なフロントエンドとして配布されており、ブラウザでページを開いたあと、設定画面で External Controller の URL（例：http://127.0.0.1:9090）と Secret を入力して保存します。ホスト版の Yacd をローカルに置いて file:// で開く方法や、公開されているホスト済みの Yacd を HTTPS で読み込む方法など、入手経路は複数あります。いずれの場合も、ブラウザが実際に到達できる URLを API 欄に書く必要があり、ループバックで動かしている Mihomo なら、原則として 127.0.0.1 系になります。
パネル上では、プロキシグループの一覧や遅延テスト、モード切替（クライアントが許可する範囲）などが操作できます。URL-Test や Fallback の戦略グループを YAML で定義しておけば、Yacd からもそのグループを選び直したり、遅延表示を確認したりしやすくなります。ここは「ブラウザで見える化するレイヤ」であり、ルールそのものの編集はクライアント側の機能や別途エディタに依存する点に留意してください。
http://127.0.0.1:9090 に接続できない場合があります。そのときはローカルで Yacd を配信する、ブラウザの設定を確認する、あるいは後述の SSH トンネルでポートを寄せるなど、経路を揃える必要があります。
5 secret を強くし、パネルの露出を抑える
推測されにくい secretを使うことは最低ラインです。短い英単語や既定値のまま、という状態で LAN 全体にポートを開くと、家族や同僚の端末から試行される余地があります。パスワードマネージャのジェネレータで十分な長さのランダム文字列を発行し、設定に貼り、古い値はログやバックアップからも消していく運用が無難です。
次に、本当にそのポートを広く聞かせる必要があるかを毎回問い直します。スマホだけ別ネットワークから操作したいなら、まず 127.0.0.1 に縛り、SSH のローカルポートフォワードで PC 側のブラウザから 127.0.0.1:9090 に届ける方が、意図しない公開を避けやすいです。ルーター越しにポート開放するより、VPN（WireGuard など）で家に入ってから LAN と同様に扱う、という選択肢もよく使われます。
OS のファイアウォールやクラウドのセキュリティグループで TCP 9090 を外向きに開けないことも重要です。設定ミスで 0.0.0.0 になっていても、パケットフィルタで遮断されていれば到達しません。逆に「テストのために一時的に開けた」まま放置、というのは現場でも起きがちなので、チェックリストに入れておく価値があります。
secret の漏えい・既定値のまま・過度な露出は、快適さとのトレードオフではなく、まず止めるべきリスクです。
6 リモート操作と SSH トンネルの例
例えば Linux サーバ上で Mihomo が 127.0.0.1:9090 だけを公開しているとき、手元の PC から Yacd を使うには、SSH クライアントでローカルフォワードを張る方法が定番です。イメージとしては、手元の 127.0.0.1:19090 へ入った TCP を、サーバ側の 127.0.0.1:9090 に中継します。ブラウザでは Yacd の API URL に http://127.0.0.1:19090 を指定し、secret はサーバの設定と同じものを入力します。
# Forward local 19090 to remote controller (run on your PC)
ssh -L 19090:127.0.0.1:9090 user@your-server
この形なら、インターネット上には SSH のポートだけが見え、Mihomo の管理口はサーバ内のループバックに留まります。鍵認証・AllowUsers・fail2ban など、SSH 側の硬さとセットで設計してください。Windows のクライアントから同様のトンネルを張る GUI もありますが、原理は「ローカルポートを遠隔のループバックに繋ぐ」点では同じです。
7 よくあるつまずき
- 接続拒否・タイムアウト：
external-controllerのアドレスとポートが実際のリスニングと一致しているか、ファイアウォールで遮断されていないかを確認します。 - 401 や Unauthorized：
secretの打ち間違い、旧値のキャッシュ、クライアントが別プロファイルを読んでいる場合に起きやすいです。 - LAN の別端末から届かない：
127.0.0.1バインドのままでは他ホストからは見えません。意図どおり0.0.0.0または LAN IP 待ち受けに変えたうえで、セキュリティを再評価します。 - Yacd だけ動かない： ブラウザのコンソールに CORS や混合コンテンツのエラーが出ていないか確認します。HTTPS 上の Yacd から HTTP API へ直結できないケースは §4 の注意に戻ります。
8 まとめ
Mihomo の external-controller は、ブラウザベースのダッシュボードや自動化スクリプトがコアと会話するための窓口です。secret はその窓口に錠をかける第一歩ですが、どの IP にバインドするかとネットワーク上どこから届くかをセットで設計しないと、意図せず第三者に操作面を晒すことになります。Yacd のようなパネルは学習コストが低く、スマホのブラウザからノードを切り替えたいときにも便利ですが、その便利さの裏にある API の性質を理解したうえで使うのが安全です。
ローカル専用なら 127.0.0.1 と強い secret、リモートなら SSH トンネルや VPN・ファイアウォールで届く範囲を絞る、という組み合わせが実務では再現性が高いです。サーバ常駐の Mihomo 全体の流れはLinux 向けの systemd ガイドと併読すると、設定ファイルの置き場所から一連の作業を追いやすくなります。
デスクトップでは、トレイから同じコアを扱える Clash 互換クライアントの方が、購読更新やプロファイル切替まで一画面にまとまる場合も多いです。ルールや DNS を深くいじる日はクライアント、外出先では Yacd で軽くノードだけ触る、といった棲み分けも現実的です。
