Clash 本地控制台打不开？external-controller 与 external-ui 逐项排查步骤

先把现象说清楚：多半是「看得到配置、打不开页面」

当你在 Clash／Mihomo 系客户端里已经勾选了外部控制／API，甚至拷贝了自带的 Yacd、Metacubexd或第三方 Web UI 链接，却在浏览器里遇到localhost 拒绝连接、一直转圈、或开发者工具中报Mixed Content，这通常不等于「节点全红」类问题。external-controller只负责在本机某个地址:端口暴露 REST/WebSocket；打不开时，应先核对三件事：内核有没有真的在LISTEN、你浏览器访问的是不是同一条地址：端口、页面是否在以HTTPS嵌入明文 HTTP控制台。下文与站内「端口被占用」「Rule Provider」「Sniffer」等文不重写同一套段落：若你连核心都启动失败并报 bind 端口冲突，请先对照 Clash 端口被占用 一篇；本篇专注控制台 API 与 Web UI这条链。

读懂 external-controller：不是「写一个 9090」就结束

在 Mihomo／Clash Meta 的常见 YAML 里，external-controller 通常写成形如 127.0.0.1:9090或':9090'这一类「监听地址加端口」的字符串。含义很具体：只向该地址上的 TCP 连接开放控制面。若写成了 127.0.0.1，那么从局域网里另一台手机去扫你电脑的 IP:9090 会失败，这是预期行为，不是 bug；若你希望手机走「填电脑 IP」的方式打开面板，往往需要把监听改到0.0.0.0并同时开启防火墙与安全配置（例如secret）。相反，若在 Docker／WSL 里跑内核，宿主浏览器访问时没有做端口发布，也会出现「容器里监听正常、宿主永远连不上」——这类与 localhost转发相关的坑，在下面「容器与局域网」小节单独说。

请在你当前生效的那份配置里查 external-controller：若使用图形客户端自带的「配置编辑器」，注意 mixin、profile 或订阅合并的末尾覆盖：有时你在主文件改了 9091，但被另一段 mixin 静默改回 9090。合并后的结果以运行时日志或客户端「端口」一栏为准，而不要只信磁盘上第一眼看到的那一行 YAML。

第一步：在同一台机器上用 curl／浏览器极简验证

在排错顺序上，先排除「浏览器插件 / 书签写错」，用系统自带方式访问控制面根路径试一下。例如在 Windows PowerShell、macOS「终端」，把地址与端口换成你配置里的 external-controller（若监听写成 IPv6，例如 [::]:9090，可配合 curl -g 试连；多数用户仍以 127.0.0.1为准）：

curl -v http://127.0.0.1:9090/

若这里就连接被拒绝，说明问题在「内核没监听／监听在别的口／被防火墙拦在更前面」，而不是 Yacd 本身。若 curl 能返回一段 JSON 或 401，再谈 Web UI。若 curl 通、浏览器不通，再查扩展或系统代理是否把对 127.0.0.1的请求也送进了代理链（可临时关掉「对 localhost 旁路」类选项或直接关系统代理试一次）。

第二步：YAML 写法、secret 与控制台鉴权

许多发行版要求在 YAML 中设置secret后才能改规则或内核模式。若配置了secret而你访问的控制台 URL没有把密钥带在查询参数或通过面板登录框输入，可能看到空白或持续性 401。不同 Web UI（Yacd、Metacubexd 等）在「填入 API Base」与 secret 的流程上略有差异：请确认你给面板的是形如 http://127.0.0.1:9090的基址而不是误把订阅链接粘进去。

安全配置提示：把 external-controller 暴露到0.0.0.0且无secret（或弱口令暴露在公网环境里）有被扫描与滥用的真实风险；仅在可信局域网内使用，并优先保持绑定 127.0.0.1或通过 SSH 端口转发远程使用。以下内容仅供你在自有设备上排障。

第三步：external-ui 与内置静态资源路径

部分内核／发行版还支持 external-ui 字段：指向静态资源文件夹的路径，从而在控制 API 同源路径下提供面板。若该路径在磁盘上不存在、或客户端沙箱读不到，会出现「API 能返回、打开 /ui 却 404」。此时你仍可能通过单独的Yacd／Metacubexd静态页连接到同一 external-controller 端口；两条路二选一即可，不必执着于某个路径打不开就重装。

若使用「在线托管的Yacd镜像」连接本地 API，请确认页面是http 还是 https：见下一节的 Mixed Content。

第四步：Mixed Content（HTTPS 页不能随意调 HTTP API）

这是最容易被误判为「控制台坏了」的情况：你在浏览器打开了HTTPS页面的 Yacd／Metacubexd 镜像，而它尝试请求http://127.0.0.1:9090。现代浏览器会拦截这种「安全页面上的明文子资源／XHR」，控制台里可见 blocked mixed content。localhost上的 API 多数是 HTTP明文——解决思路包括：改用本地 file 或 localhost 打开的 http版面板、换用支持你环境的桌面客户端内嵌控制台、或通过本地反向代理在同一源上终结 TLS。不要把secret暴露在公网仅以「绕过 mixed content」为名——那是在换一个问题。

第五步：Docker 与 WSL：谁身上的「localhost」

在 Docker Desktop（Windows／macOS）里，若内核跑在容器而你在宿主浏览器里敲 127.0.0.1:9090是否命中，取决于端口映射是否已经 -p 9090:9090 等价发布。宿主与容器中对「监听地址」的配置要一致：常见做法是让容器内 external-controller 监听 0.0.0.0:9090 再映射到宿主 loopback。若你把地址写死在容器内的 127.0.0.1 却从外连，行为会与预期不符。更完整的代理链与路由关系另见 Docker Desktop 与 Clash及 WSL2 路由一文；本篇只钉住控制台端口是否在你当前这一层网络空间可达。

第六步：本机防火墙、Allow LAN 与「以为开了其实没开」

若 external-controller 绑定在 0.0.0.0 且你从另一设备访问，宿主操作系统防火墙可能对入站 TCP 首次询问；这与「局域网共享代理」的语境有关，但更完整的叙述在 Allow LAN 与防火墙。仅对本机环回地址 127.0.0.1做自检时一般不会触发「跨网卡入站」，但若安全软件劫持了localhost回路，仍可尝试暂时排除 Clash／内核二进制或把规则改为仅环回放行。别把这一步当成首选：大多数面板问题仍回到地址、端口、mixin 三者之一。

第七步：客户端「一键打开控制台」与你的书签是否同源

图形客户端有时内置「浏览器打开控制台」——它使用的端口从运行中实例读取。若你曾经手动书签过http://127.0.0.1:9090后来在 YAML 改成了 9091，书签不会自动升级。核对方式依然简单：回到客户端显示的外部控制端口数字，再与 curl 验证一致。

可打印检查顺序（从快到慢）

  1. 在生效配置中确认 external-controller 的完整「地址:端口」，并排除 mixin 合并覆盖。
  2. 在同一系统上用 curl 或浏览器访问与 external-controller 一致的 URL（地址与端口与第一步抄写相同，示例见上文单独代码块），先得到非「拒绝连接」的响应。
  3. 若配置了 secret，在 Web UI 中正确填写 API 与密钥；避免把订阅 URL 误当 API Base。
  4. 若用在线 Yacd／Metacubexd，检查是否因 HTTPS 页调 HTTP API 触发 Mixed Content，改用 http 打开或本机静态页。
  5. 若在 Docker／WSL，核对端口发布与「哪一层算 localhost」。
  6. 仍异常时，再对照防火墙、Allow LAN 与跨设备访问需求，并复习 订阅与基础启停是否已稳定。

小结

external-controller与external-ui解决的是「控制面从哪里进」：把监听地址、端口、YAML与mixin合并结果、以及浏览器侧的Mixed Content一次对齐，大多数「面板再也不出来」会消失。相比反复切换节点，这类问题更吃「配置链条是否闭合」；把 curl 验证放在最开始，能少改十次无效选项。若你需要换用另一款带图形界面的客户端但仍走同一套内核能力，可从本站 下载页选择适合自己系统的版本，再按上表顺序对照。相比在搜索引擎里零散搜报错原文，先固定localhost可达性再谈 Web UI，会省不少时间。→ 立即免费下载 Clash，开启流畅上网新体验