症状の整理：プロキシは動くのにパネルだけ失敗する理由

Clash Meta（Mihomo コア）を使っていて、ブラウザで Yacd や metacubexd などの Web ダッシュボードを開こうとすると、いきなり 401 Unauthorized が返る、ずっと読み込みのまま、あるいは「接続できません」と出る——それでもシステムプロキシや TUN 経由の通常ブラウジングは通る、というパターンは珍しくありません。データ面（実トラフィックの転送）と制御面（設定の読み書き・接続一覧・ルール切替のための HTTP API）は別物だからです。前者が動いていても、後者の待ち受けポート・認証ヘッダ・バインドアドレスが噛み合っていなければパネルは何も表示できません。

多くの初心者向け記事は TUN や DNS、サブスクリプション、ポリシーグループに紙面を割きがちで、コントローラー（external-controller）と API セキュリティ（secret）の説明が薄いままになりがちです。本稿はそのギャップを埋めるため、実際に手を動かせる順序で書きます。コアのバージョンや GUI ラッパー名は製品ごとに違いますが、考え方は共通です。全体像は Clash Meta へのアップグレードと設定の考え方 と併読すると、どのファイルが「実行中のコア」に渡っているかも追いやすくなります。

ℹ 先に決めること：パネルに入力する URL のホスト・ポート・https か http か、そしてトークン（secret）の三つは、設定ファイル側の external-controller / secret と文字どおり一致させます。空白や末尾改行、別プロファイルを編集している勘違いが最頻出です。

external-controller と secret が担う役割

external-controller は、コアがローカル（または指定したインターフェース）で待ち受ける REST 風 HTTP API のアドレスです。典型値は 127.0.0.1:9090 のように「IP:ポート」の形で書きます。ここへブラウザ上のパネルや自作スクリプトがアクセスし、実行中のプロキシ一覧やルール、接続ログの参照、場合によっては設定の再読込などを行います。mixed-port（クライアントが実際にトラフィックを流し込む HTTP/SOCKS 入口）とは別ポートである点に注意してください。パネルが「mixed の番号」へ API リクエストを送っても応答しない、という単純ミスはよくあります。

secret はその API への簡易的な共有鍵です。リクエストヘッダ Authorization: Bearer <secret> として送られた値が、設定の secret と一致しなければ 401 になります。空文字にしているのにパネル側だけ古いトークンが残っている、逆にサブスク由来の巨大設定で secret が上書きされている、GUI が別ファイルを書いている——どれも現場でありがちです。トークンは推測されにくい長さにし、スクリーンショットやログに載せない運用を推奨します。

さらに external-controller-pipe（Windows 名前付きパイプ）のような別経路を使うクライアントもありますが、Web パネルから直接触る場合は external-controller の TCP 待ち受けが主役です。どちらを有効にしているかは、実行中の設定（実ファイルではなくコアにロードされた内容）で確認するのが確実です。

おすすめの既定：本機（127.0.0.1）だけに bind する

セキュリティ上の第一歩は、コントローラーを 127.0.0.1 または ::1 に限定することです。これにより、同じ PC 上のブラウザやローカルツールからだけ API に届き、LAN やインターネットからのスキャンに晒されにくくなります。「とりあえず 0.0.0.0 にしてスマホからも見たい」は、トークン漏洩とセットで非常に危険です。どうしても別端末から触る必要がある場合は、少なくとも強い secret、ファイアウォールでの送信元制限、可能なら SSH トンネルや VPN 内だけに閉じる、の順でリスクを下げてください。LAN 共有全般の整理は LAN 共有と bind アドレス の記事も参考になります。

allow-lan を true にしたとき、コントローラーまで広がってしまう構成になっていないかも確認します。プロキシ入口だけ LAN に開き、API は localhost のまま——という分離が理想的です。クライアントの GUI に「外部コントロールを許可」系のチェックがある場合、それが external-controller のバインドやファイアウォール例外まで一括で変えていることがあるため、変更後は必ず実際の YAML を開いて値を目視してください。

⚠ 注意：コントローラーを WAN 側に晒す・トークンなしで公開する構成は、第三者にプロファイル取得や接続操作を許すのと同義になり得ます。チュートリアルでそう書かれていても、自宅・会社環境では採用しないでください。

設定ファイルに書く例（Clash Meta / Mihomo）

次のブロックは説明用の最小例です。実際のファイルでは他セクション（proxies、rules など）と共存します。ポート番号は環境で空いているものに変えてください。

config.yaml excerpt (example) 
# External REST API — bind to loopback only
external-controller: 127.0.0.1:9090
secret: "replace-with-a-long-random-token"

# Optional: if your UI shows a separate field, keep controller in sync
# external-ui: ui

変更したらコアを再読み込みするか、クライアントに付属する「設定を再適用」操作を実行します。反映されていないと、パネルは古いポートへ叩き続けます。複数プロファイルを切り替える製品では、いまアクティブなプロファイルの YAML を編集しているか再確認してください。

Yacd・metacubexd へ渡す API アドレスとトークン

ブラウザでホストされるパネルは、一般に フロントエンドだけが静的ファイルであり、実データ取得先としてあなたの PC 上の http://127.0.0.1:9090（例）を指定します。入力欄のラベルは「API」「Backend」「Controller」など様々ですが、意味は同じです。https で書くべきかはパネルとコアの組み合わせ次第ですが、典型的なローカル HTTP 待ち受けなら http:// から試し、ブラウザの混合コンテンツ警告に注意します。

トークン欄には設定ファイルの secret と同じ文字列を貼ります。401 が続くときは、まず開発者ツールのネットワークタブで API リクエストに Authorization: Bearer … が付いているか、付いていても 401 かを見ます。付いていないならパネル側の保存不備、付いているのに 401 なら secret の不一致か、別プロセスのコアへ当たっている可能性が高いです。

パネルを「オンラインのデモ URL」から開いている場合、そのオリジンからローカル API へのリクエストはブラウザの CORS やプライベートネットワークアクセス制限に阻まれます。症状はコンソールに理由が出ることが多いです。対策は、パネルをローカルで配信する、拡張やブラウザ設定で開発用に緩める（リスク理解の上）、あるいは公式にバンドルされたパネル機能をクライアントから開く、のいずれかです。状況別の切り分けは FAQ の接続・プロキシ項目 と併せて読むと早いです。

典型トラブル：401、接続拒否、別マシンから見えない

401 Unauthorized：ほぼ確実にトークン不一致です。secret を変えた直後にブラウザの自動補完が古い値を載せている、別ユーザープロファイルのパネルが別トークンを記憶している、などを疑います。コア側で secret を空にした場合、パネルも空に揃える必要があるかは実装依存なので、公式ドキュメントかクライアントの挙動を確認します。

接続拒否・タイムアウト：ポート違い、コア未起動、external-controller 行自体がコメントアウト、別コンテナ／VM 内でコアが動いていてホストの 127.0.0.1 が別名前空間を指している、が典型です。Docker や WSL を跨ぐときは「ブラウザが動いている側」から見た正しい IP（ブリッジ IP やホストゲートウェイ）へ向ける必要があり、単純に localhost と書けないことがあります。Windows と WSL2 の相互参照は WSL2 とホストのプロキシ記事 が参考になります。

LAN の別 PC からパネルは開けるが API だけ失敗：コントローラーが 127.0.0.1 のままなら、他機からは届きません。意図的に LAN に出すならバインドとファイアウォールをセットで設計し直す必要がありますが、まずは問題を分離するため、トラブルシュート中はブラウザとコアを同一マシンに寄せるのが安全で確実です。

curl で REST API を素早く確認する

GUI より先に、ターミナルで生の応答を見ると切り分けが速いです。次の例ではバージョン相当の情報が返れば、待ち受けとトークンは少なくとも一致しています（実際のパスはコアのバージョンで異なる場合があります）。

curl example (replace port and token) 
curl -sS -H "Authorization: Bearer replace-with-a-long-random-token" \
  http://127.0.0.1:9090/version

ここで 401 ならトークンかヘッダ形式が誤り、接続できなければポートかバインドかプロセス生存を疑います。同様に /configs や /proxies など、環境に合わせた読み取り専用エンドポイントを叩いてもよいです。本番運用では、トークンをシェル履歴に残さないよう注意してください。

まとめ：コントロール面を安全に使いこなす

Web パネルは見た目は華やかですが、裏側はごく普通の HTTP API です。external-controller で「どこに聞くか」、secret で「誰を信頼するか」が決まり、この二つがパネル入力と一致しなければ 401 や接続エラーは当たり前に起きます。まず本機ループバックに固定し、トークンを明示的に設定し、curl で応答を確認してからブラウザに進む——この順序なら、暗い「とりあえず 0.0.0.0」に頼らずに済みます。

データ面が安定したあとでコントロール面を整えると、ノード切替やルール確認が格段に楽になります。GUI クライアントによってはパネルが同梱され、トークンやポートを自動で合わせてくれるものもありますが、トラブル時に読めるのは常に「コアが読んでいる設定テキスト」です。メンテの行き届いた Clash Meta 系スタックは、長期運用での透明性と安心感のバランスが取りやすい選択肢です。

→ 設定とパネルを一度に揃えたら、Clash を無料ダウンロードし、日々の運用を軽くしてみてください。