Clash のローカルコンソールが開かない？external-controller と external-ui を順に切り分けるチェックリスト

この記事で想定する症状

Clash／Mihomo コアのアプリ（Clash Verge 系など）では、ログや設定画面上で「REST API が有効」「外部コントローラーポートは 9090」といった表示が見えているにもかかわらず、ブラウザから localhost（例：http://127.0.0.1:9090/）や Yacd／Metacubexd が要求するベース URL に繋がらない。そのとき開発者ツールのネットワーク欄には (failed)、ERR_CONNECTION_REFUSED、あるいは「Mixed Content」の警告だけが並ぶ——といった場面です。別途取り上げている「ポートが競合してコアごと起動できない」問題はポート占有と mixed-port の記事に任せ、本稿ではプロセスは稼働しているのにコンソール層だけ届かないときの、external-controller と external-ui に絞って手順を積み上げます。

ユーザーの環境によっては LAN 側からのみ API を許可している、サブスクの YAML が GUI の上書きより後から読み込まれて待受が消えている、Docker や WSL の「中の 127.0.0.1」とホストのブラウザが一致していない、といったパターンが混ざります。いきなり「全体を入れ替え」ではなく、下のチェックを上から潰すと原因の切り分けが速くなります。

ステップ 1：external-controller の文字列と実効ポート

コアのバージョンやフロントエンドによって表記は揺れますが、実体は「どの IP／ポートで REST API を聴くか」です。多くの例では 127.0.0.1:9090 や 0.0.0.0:9090、シークレット付きなら 127.0.0.1:9090 に加えて別キーでトークンを渡す形になります。まずいま実際に読み込まれているプロファイル（GUI の「設定を開く」で辿れる実ファイル）をテキストで開き、external-controller の行を探してください。

確認ポイントは次のとおりです。（1）ポート番号が GUI の表示と一致しているか。（2）127.0.0.1 のみにバインドしている場合、同じマシン上のブラウザからなら通常は問題ありませんが、別 PC やスマホから叩こうとすると届きません。LAN 越しに見る意図なら 0.0.0.0 側の記述と OS のファイアウォールをセットで考える必要があります（LAN 専用の話題はAllow LAN とファイアウォールの記事で補足）。（3）コメントアウトや重複行がないか——最後に勝った行だけが有効、というのが一般的です。

ステップ 2：mixin とマージ後の上書き

Clash Verge 系では「ユーザールール」「上書き」や mixin 用の断片 YAML を合成して最終設定を作ります。このとき UI で触った external-controller が、サブスク更新後の巨大な config.yaml の末尾で空文字に戻る、といった合成順の落とし穴が起こり得ます。症状が「昨日まで開けたのに今日だけ開けない」なら、まず合成後の実体（ログに出る「loaded config path」や一時展開先）を開き、そこに期待した external-controller が残っているかを確認するのが近道です。

GUI に「外部コントローラーを有効化」のトグルがあっても、裏で参照しているのは別ファイルで、トグルは未反映——ということは珍しくありません。迷ったらテキスト一本に寄せてから再度試し、通るなら合成ルール側を直す、という順が安全です。

ステップ 3：external-ui と静的ファイルのパス

組み込みの Web パネルを配るための external-ui は、ローカルディレクトリを指す場合と、zip／リリース資産の展開先を指す場合があります。パスにスペースや日本語フォルダ名が入っていると、実装によっては読み込みに失敗し、ルート URL は返るがアセットが 404 になることがあります。またクライアントが配布する「同梱 UI」のバージョンとコアのバージョンの組み合わせで、API プレフィックスが合わず真っ白な画面のまま止まることもあります。

このときブラウザの開発者ツールで、index.html や *.js が 200 か 404 かを見ると切り分けが早いです。Yacd や Metacubexd を公開サイト上のビルドから開き、そこに「API のベース URL」として http://127.0.0.1:9090 を入力する運用にしている場合は、次節の Mixed Content がほぼ必ず絡みます。

ステップ 4：Mixed Content（HTTPS から HTTP API へ）

ブラウザはセキュリティのため、HTTPS で読み込んだページ上の JavaScript が、平文の http://127.0.0.1:… へ XHR／fetch するのをブロックします。オンラインの Yacd などが https:// で配信されている場合、API を http:// のまま指定すると、コンソールに Mixed Content 警告が出て通信が止まります。対策の筋の良い順は、（1）ローカルで配る UI を http://127.0.0.1 から開く（ブックマークも http に揃える）、（2）コア側で HTTPS ターミネーションを別途立てる（運用コスト高）、（3）開発用ブラウザ以外では推奨しませんが一時的に該当保護を弱める——のいずれかです。

ここでの誤検知ポイントは、「ブラウザのアドレスバーは file:// やアプリ内 WebView ではなく、普通のタブで http(s) を見ているか」です。Yacd を自分でホストするか、公式に案内されているローカル向けの読み込み経路と揃えると再現が減ります。

ステップ 5：Docker と WSL の「見えない 127.0.0.1」

コンテナ内のプロセスが 127.0.0.1:9090 だけで聞いていると、ホスト OS のブラウザから見た localhost は別名前空間を指します。-p 9090:9090 で公開しつつ、バインドを 0.0.0.0 に寄せる、あるいは host ネットワークモードを使う、といったのが典型的な処置です。Docker と Clash の併用ガイドで述べているとおり、プロキシとポート転送の関係を図に起こすと混乱が減ります。

WSL2 上でコアを動かし、Windows 側の Edge から叩く場合は、WSL の分配 IP やポートプロキシの仕様を踏まえ、待受を「Windows から届くインターフェース」に合わせる必要があります。ここで唐突に 127.0.0.1 拒否が出るなら、まず「聴いているのはどのゲストか」を疑ってください。

ステップ 6：ファイアウォールとセキュリティソフト

ループバック向けの待受は通常ブロックされにくいですが、企業端末の HIPS や「ローカルプロキシ禁止」ポリシーで localhost の特定ポートだけ拒否される例はあります。また初回起動時に表示されたファイアウォールの許可ダイアログを誤って拒否したまま、というケースもゼロではありません。OS の「受信の規則」と、サードパーティ製の「アプリ防火壁」の両方を確認してください。

ステップ 7：curl で API の生存確認

ブラウザ以前に、同じマシン上のターミナルで次のように叩いてみます（ポートとパスは環境に合わせて変更）。

curl -sS -o /dev/null -w "%{http_code}\n" http://127.0.0.1:9090/

200 や 401（要認証）なら少なくとも TCP は届いています。000 や接続拒否なら、まだ待受が立っていないか、番号が違います。認証付きの場合はドキュメントに沿って Authorization ヘッダーを付与した curl を試し、API 自体が生きているかを切り分けます。

まとめ

Clash のローカルコンソールが開けないときは、（1）実効 YAML 上の external-controller のアドレス・ポートとシークレット、（2）mixin 合成後の上書き、（3）external-ui のパスと 404、（4）HTTPS ページから HTTP API への Mixed Content、（5）Docker／WSL の名前空間、（6）OS の受信規則——の順に見ると迷子になりにくいです。Yacd／Metacubexd は UI が分離しているぶん、API のスキームとオリジンの組み合わせで詰まりやすい点に注意してください。

コアとクライアントの組み合わせは年々整理されており、ダッシュボードから遅延計測やプロファイル差し替えまで一気通貫で触れるのが魅力です。トラブル時もレイヤを分けて追えば、再現と修正が素直です。

安定版ビルドや各クライアントの入手先はダウンロードページにまとめています。API まわりを押さえたうえで、自分の環境に合うパッケージを選ぶと運用が楽になります。→ Clash を無料ダウンロードし、ローカル環境を整える