本稿でできるようになること
作業のゴールは、コアが Listen している API エンドポイントが分かり、ブラウザ上の Yacd から /proxies や /connections 相当の情報を読み、ポリシーグループの選択や接続状況の確認ができる状態です。external-controller に書く文字列が「ホスト部＋ポート」で何を意味するか、127.0.0.1 に縛るか 0.0.0.0 に広げるかで誰から届くかが変わること、secret を付けたときパネル側でどう渡すか、スマホや別PCから触るには ファイアウォールと bind まで含めて揃える必要があること、を押さえられれば十分です。GUI 付きクライアント（Verge 系など）を使っている場合も、裏で同じ API が動いていることが多く、本稿の理解はトラブル時のログ読みに直結します。
external-controller とは何か
external-controller は、Mihomo／Clash 系コアが外部から制御・観測するための HTTP API を載せる設定項です。典型ポートは 9090 ですが未使用なら別番号でも構いません。ここが無効／到達不能だと、Yacd や他のダッシュボード、スクリプトから 購読の再取得やプロキシ切替 を送れません。プロキシのトラフィック出口（7890 などの mixed-port）とは別物で、混同すると「ブラウザのプロキシは通るのにパネルだけ真っ白」という型の混乱が起きます。
整理：mixed-port／port／socks-port はクライアントアプリの通信用、external-controller は管理用API用。セキュリティ上、API 側に secret を付け、LAN に開くときは信頼できるセグメントだけに限定するのが無難です。
config.yaml での最小例
まずは同一マシン上のブラウザからだけ触りたい場合、Listen をループバックに閉じるのが簡単です。以下は説明用の骨子であり、実際のキー名や追加オプションは利用中のバージョンのドキュメントに合わせてください。
# Minimal sketch — align keys with your Mihomo version
external-controller: 127.0.0.1:9090
# secret: "your-long-random-string" # recommended when exposing beyond localhost
127.0.0.1:9090 は「そのPC自身からだけ」API に届きます。別PCのブラウザやスマホから同じAPIを使いたいときは、0.0.0.0:9090 のようにすべてのインタフェースでListenさせ、あわせて OS やルーターの受信許可を確認する必要があります。クライアントアプリが設定GUIで「外部コントロール」を有効化する場合、実質的にはこの項目を書き換えているだけ、という理解で大丈夫です。
本機アクセスと LAN アクセス
同じデスクトップで Yacd を開くなら、パネルの「API」欄に http://127.0.0.1:9090 のような到達可能なベースURLを入れます。LAN 内の別端末から操作する場合、127.0.0.1 はその端末自身を指すため、Mihomo が動いているマシンのLAN IP（例: 192.168.1.10）を書きます。ここでよくある落とし穴は、コアは 0.0.0.0 でListenしているのに、Docker の publish が 127.0.0.1:9090:9090 のように狭いため、ホスト以外から見えないパターンです。Docker での Mihomo 記事で触れた ports と allow-lan の話とセットで頭に入れておくと切り分けが速くなります。
secret と認証ヘッダ
API を LAN に晒すなら secret の設定を強く推奨します。パネル側では、Yacd の設定画面にトークンを入力し、リクエスト時に Authorization: Bearer … として付与される想定で動きます（画面文言はビルドにより多少異なります）。secret を YAML に追加した直後にパネルが 401 になるのは、ブラウザをリロードしていないか古いタブが空のトークンでキャッシュしていることが多いです。開発中だけ一時的に secret を外すのは理解しやすい一方、公開Wi‑FiやゲストLANに同じ構成を持ち込むと危険なので、試行錯誤が終わったら必ず戻してください。
Yacd との接続手順
Yacd は、Clash 系 API を前面に出した静的Web UIの代表例です。一般的な流れは次のとおりです。(1) ブラウザで Yacd を開く（公式にホストされたものでも、releases の静的ファイルをローカルに置いても可）。(2) 初回または設定画面で、API のベース URL に http://<到達可能なホスト>:9090 を指定する。(3) secret がある場合は同画面で入力する。(4) 接続テストのあと、プロキシ一覧・ルールヒット・接続テーブルが読み込めるか確認する。ここでHTTPS のページから http://127.0.0.1 へブラウザがブロックする（mixed content）場合があります。そのときは http で配布された Yacd を使うか、ローカルにファイルを置いて file://／ローカルHTTPサーバ経由で開くなど、スキームを揃える必要があります。細部はブラウザの開発者ツールのコンソールにエラーが出るので、真っ白な画面のときの第一歩になります。
REST API で何ができるか
パネルは裏で REST API を叩いています。例として、実行中のプロキシ一覧やポリシーグループの現在選択は /proxies 系、接続の列挙は /connections 系（実装名はバージョンで確認）を想定すると理解しやすいです。自分で curl から叩く場合も、ベースURLと secret ヘッダを揃えれば、スクリプトからノード切替やメトリクス取得が可能です。運用では、過度に頻繁なポーリングはCPUとログを食うため、更新間隔はパネル設定で控えめにするか、必要時だけ手動リロードする癖がよいです。
# Example: version check (replace URL and token)
curl -sS -H "Authorization: Bearer YOUR_SECRET" http://127.0.0.1:9090/version
デスクトップGUIとの棲み分け
Clash Verge Rev などのGUIは、内部で同じAPIや同等機能を持ち、ログやルール編集まで一体で提供します。Yacd は軽量でブラウザさえあればよい反面、クライアント固有のトグル（システムプロキシ、TUN）までは担いません。したがって「パネルでノードは切れたがアプリの通信が変わらない」場合は、実際にトラフィックが通っているポートとモードをGUI側で確認する必要があります。macOS のシステムプロキシ周りは 別稿、DNS と名前解決の整合は Meta コア DNS ガイド が補完になります。
パネルが開けない・繋がらないとき
- ポート違い：
config.yamlの番号と、ブラウザに打った番号が一致しているか。 - Listen 範囲：127.0.0.1 のみなのに別端末から試していないか。逆に LAN 向けに広げたのにファイアウォールで落ちていないか。
- secret 不一致：401 や空レスポンス。YAML 変更後にコアをリロードしたか。
- Docker：
portsのマップ漏れ、ホスト束縛、別コンテナから127.0.0.1を叩いていないか（同一compose内ならサービス名と内部ポート）。 - Mixed content：HTTPS 上の Yacd から http API へのアクセスがブラウザに拒否されていないか。
- プロセスが別：古いコアが残り、別の設定ファイルで別ポートをListenしていないか。
注意：認証なしの external-controller をインターネット側に露出しないでください。必要なら VPN 内や SSH トンネル越しに限定し、ルーターのポート開放とセットで誤公開しないよう運用ルールを決めます。
ドキュメントとクライアント入手
API の正式なパス一覧は、利用中の Mihomo リリースのドキュメントを参照するのが確実です。日々のクライアント本体の入手は 公式ダウンロードページ から行い、用語やモードの整理は ドキュメント・チュートリアル も併せて読むと、パネルで見た項目と設定ファイルの対応が早く掴めます。ソースや Issue は GitHub が適していますが、インストーラの取り違えを防ぐ意味でも、配布物の第一選択肢はサイト側に寄せるのがおすすめです。
まとめ
Mihomo でブラウザから運用したいときの要は、external-controller で REST API を意図した相手だけに届けることです。127.0.0.1 は自分用、0.0.0.0 ＋ LAN は家族端末や別PCからの Yacd 用、Docker なら publish と compose の数字合わせ、と型を覚えるとトラブルが減ります。secret とブラウザの HTTPS／HTTP 混在は実務で最後にハマりやすいので、開発者ツールで一度確認する癖が効きます。内核のルーティングやDNSを深掘りする場合は本稿以外の記事へ、管理UIだけサッと足したい場合は本稿の手順をそのまま適用してください。
GUI クライアントと組み合わせれば、ログの見え方も豊かになり、パネルで切ったポリシーが実トラフィックに反映されているかを二画面で照合しやすくなります。安定志向なら、エコシステム全体を公式ページから揃え、API は必要最小限の公開に留めるのが2026年現在も変わらない良いバランスです。