一、典型现象：先分清是「页面」还是「API」没通
Yacd 一类面板本质是静态前端，真正读写策略、看连接的是你配置里的 Clash／Mihomo REST API。因此浏览器报错时要先问自己：是加载面板 JS/CSS 失败，还是面板已显示却一直转圈、无法拉取版本或日志？前者多见于 CDN、离线包路径；后者几乎总是 API 地址或鉴权不对。
常见体感包括：本机访问 http://127.0.0.1:9090 直接 connection refused；或本机能开，换成笔记本通过 http://192.168.x.x:9090 却不行；又或 curl 返回 401／控制台里请求带红字。把症状对应到「监听地址」「端口是否一致」「secret 是否匹配」三件事，比反复重装面板更有效。
二、external-controller：API 究竟绑在哪、监听了没有
在 config.yaml（或 GUI 里同步出来的等效配置）中，external-controller 指定 REST API 监听套接字，格式通常是 主机:端口，例如 127.0.0.1:9090 或 0.0.0.0:9090。只有这一行存在且内核已成功启动对应监听，外置控制台才能连上。若你用的是非默认端口，却在 Yacd 里仍填 9090，就会表现为「内核明明在跑，面板永远连不上」。
注意部分发行版或客户端会把该项写在「高级 YAML」与 UI 数值框两处，以实际落盘生效的那份为准；改完后需要重载配置或重启内核，否则旧监听不会消失。无图形界面的环境可参考《Linux Mihomo 与 systemd》确认服务单位读的是哪份配置路径。
三、bind-address：和 external-controller 一起读，别拆成两本账
bind-address（以及个别内核版本里与控制器相关的绑定项）约束「默认监听在哪些地址上」。当 external-controller 主机写 0.0.0.0 时，通常表示在所有 IPv4 接口上开放该端口；写 127.0.0.1 则仅本机回环可连——这时换电脑访问一定会失败，这不是 bug，而是刻意的暴露面控制。
若你希望局域网管理，需要同时想清楚两件事：API 是否绑定到 LAN 可达地址（常见做法是 0.0.0.0:端口 再配合防火墙收紧来源），以及是否接受内网其他设备能改你的策略。家庭实验与办公网络的安全边界不同，务必在路由器或系统防火墙上限制谁可以访问该 TCP 端口。
四、本机实测：用 curl 验收 127.0.0.1，比只看浏览器靠谱
在运行内核的同一台机器上打开终端，先确认端口与配置一致。若未设 secret，可尝试（示例端口为 9090，请替换为你的 external-controller）：
curl -sS "http://127.0.0.1:9090/version"若配置了 secret，许多版本需要带 Bearer 头（将 你的密钥 换成真实值）：
curl -sS -H "Authorization: Bearer 你的密钥" "http://127.0.0.1:9090/version"能返回 JSON 版本信息，说明本机到 API 的链路已通；若此处仍 connection refused，请先回头查：内核进程是否存活、端口是否被其它程序占用、YAML 是否拼写错误。此处不要跳到「换节点」或「改规则」，否则只是在噪音里打转。
五、secret 与安全头：401、空白策略列表多半在这里
配置里的 secret 用于保护 REST API。面板通常在设置里让你填「API Base」和「Secret」——任何一位抄错空格、多换行，或一侧仍用旧密钥，都会变成401 Unauthorized 或前端无限重试。若你从网上复制了别人的 docker-compose 片段，记得三处同源：内核 YAML、面板表单、以及你自己 curl 测试时用的头。
个别面板或反向代理还会涉及CORS与HTTPS 混合内容：https 页面去请求 http API 可能被浏览器拦下，需要统一部署协议或本地信任。若你只做本机调试，用 http://127.0.0.1 往往最省事。
六、局域网访问：为什么「同一 Wi‑Fi」仍然打不开
当 external-controller 绑定在 127.0.0.1 时，局域网设备访问宿主 IP 永远不会成功——操作系统根本不会把外来 SYN 交给回环口。要 LAN 管理，需要把主机部分改为 0.0.0.0（或具体网卡地址），并放通系统防火墙入站规则中对该 TCP 端口的访问。
另一常见误会是混淆 allow-lan（或其它「允许局域网连接代理端口」的选项）与 API 暴露：前者让别的设备走你的 mixed／HTTP 代理端口，并不自动等价于「外置控制台可连」。两类端口可以并存，要分别核对。更多接线级别的说明见《局域网代理教程》。
七、Yacd／metacube 填表：Base URL、端口与路径
在面板里填 API 地址时，建议只填到协议 + 主机 + 端口，例如 http://127.0.0.1:9090，不要让多余路径干扰首包探测。若你挂在反向代理子路径下，再按面板文档追加前缀。metacube 等托管页面若要连你内网 API，需想清楚：浏览器跑在你电脑上还是公网服务器上——只有页面执行环境与 API 网络可达一致时才会成功。
多份配置档切换时，记得面板侧也切到当前生效档的端口与密钥；GUI 客户端常在「配置集」之间切换，最容易出现「界面显示 A、内核实际跑 B」的漂移。
八、端口占用与安全：9090 不是魔法数字
9090只是社区习惯，并不保证空闲。可以用系统工具查看该端口是否已被其它 Mihomo 实例、旧进程或测试程序占用；占用时的表现有时是偶发能连、重载后失效。与其硬抢 9090，不如在 YAML 里统一改成一个你确认空闲的端口，并三路同步：内核、面板、书签。
把 API 暴露到 0.0.0.0 后，务必把 secret 设为强随机值，并限制来源 IP。外置控制台拥有与本地 GUI 几乎同等的管理能力，不要等价于「只是看个网速」。
九、图形客户端里去哪里找这两项
Clash Verge Rev 等客户端通常在「内核设置 / 外部控制 / External Controller」一类页面暴露端口与密钥，底层仍写回 YAML。若你不熟悉纯文本编辑，可以先用 GUI 生成一版，再「查看当前配置」核对 external-controller 行是否与心理预期一致。新手安装流程也可对照《Clash Verge Rev 入门》完成首启，再回到本文细调 API。
十、可复印的自检清单
- 确认当前生效的配置与 GUI 所选配置集一致，并已重载或重启内核。
- 读出 external-controller 的主机与端口，与面板填写逐项对照。
- 本机执行 curl /version；若设了 secret，则附上正确的 Authorization: Bearer。
- 需要局域网管理时，把绑定从
127.0.0.1改为0.0.0.0（或等价选项），并检查防火墙入站。 - 401 时优先核对 secret 三处同源；混合内容时统一 http/https。
- 仍拒绝连接时查端口占用与是否连错机器（Docker、WSL、虚拟机各有独立 IP）。
十一、合规提示
代理与 API 调试须在当地法律法规及服务条款允许范围内进行。本文仅讨论本地与局域网网络参数，不提供任何违法用途指引。
十二、小结
Yacd 与同类外置控制台，本质是REST API 的前端壳：external-controller 决定内核在哪里监听，bind-address 与主机写法决定本机还是局域网能连，secret 决定请求会不会在 401 上撞墙。先在本机用 curl 把 /version 跑通，再打开面板，比反复刷新网页省太多时间；需要给家里其它设备开放管理接口时，务必同时改绑定、防火墙与密钥强度。图形化 Clash 客户端把 YAML 与连接日志放在一起时，这类「只听 localhost」的配置漂移也更容易一眼看见。若你还没有顺手的桌面客户端，可从本站获取安装包后再按上文顺序自证。相比零散搜索报错代码，把 API 当作地面真相才是长期最省时间的习惯。→ 立即免费下载 Clash，开启流畅上网新体验