一、外部控制台在做什麼：REST API 與網頁前端

Yacd、Yacd.Meta、metacube這類「面板」本質是靜態網頁或託管在本機／CDN 的前端；它們不內建核心，而是透過瀏覽器向你的Clash／Mihomo程序發 HTTP 請求，讀寫外部控制器（external-controller）暴露的REST API。因此「打不開面板」常常可翻譯成「瀏覽器連不到 API 的位址與埠」或「API 回了 401，前端卡在授權」。

預設慣例埠號常見為9090（實際以你的 config.yaml 或圖形客戶端產生的設定為準）。許多教學會寫 127.0.0.1:9090：這代表僅本機迴環可連；若你改成從區網另一台裝置用 http://192.168.x.x:9090 存取，核心卻仍只聽在 127.0.0.1，就會得到標準的connection refused——因為作業系統層根本沒有在那個介面開聽該埠。

二、實測前先確認三件事

第一件事：確認Mihomo／Clash 核心或含核心的客戶端確實在跑，且載入的是你想編輯的那份設定（訂閱覆寫、多顆設定檔時尤易搞錯）。第二件事：在設定裡找到 external-controller 的完整字串（含 IP、埠；有些版本另拆 external-controller-pipe，與本文網頁面板無關者略過）。第三件事：若你希望「同一台電腦的瀏覽器」連線，請先用本機終端機對同一個 URL 做探測，避免瀏覽器快取或擴充套件干擾判讀。

圖形介面使用者請注意：Clash Verge Rev等客戶端可能在 UI 裡覆寫external-controller或監聽埠，與你手動編輯的 YAML 不一致；可優先以客戶端「開放外部控制／API」相關選項與連線測試為準，必要時參考《Clash Verge Rev 設定教學》完成基礎對齊。

三、connection refused 與 ERR_CONNECTION_REFUSED 的快速對照

這類錯誤幾乎清一色代表「TCP 連線在目標 IP:埠 無人接聽或被防火牆丟棄」。在 API 場景下，優先懷疑：埠寫錯、程序沒起來、bind 在 127.0.0.1 卻用區網 IP 連、或埠被別的程序占用導致核心改埠／啟動失敗（後者要回看客戶端日誌）。

若瀏覽器顯示逾時而非立即拒絕，則要往防火牆、跨網段路由、或連到錯誤的閘道 IP方向查；與「拒絕連線」的收斂順序略有不同。全文級的埠與服務異常仍可查《Clash 常見報錯與排除》，但本文表格與步驟專注於控制 API，不展開訂閱拉取或 TUN 啟動失敗。

四、external-controller：格式、埠與常見誤解

典型寫法為「監聽位址:埠號」，例如 127.0.0.1:9090 或 0.0.0.0:9090。重點是：這裡的位址是核心要綁定的介面，不是代理伺服器對外的「出口 IP」。把 external-controller 想像成「給本機工具與網頁面板用的管理後台埠」即可。

常見誤解是把面板裡填的「後端 URL」設成代理埠（如混和埠 7890）；那個埠提供的是代理協定，不是 JSON 控制 API，請求過去通常也會失敗或得到非預期回應。務必以設定檔中的 external-controller 為準。

五、bind-address 與 allow-lan：本機與區網的分水嶺

僅在產生面板的那台電腦、用本機瀏覽器開 http://127.0.0.1:9090 時，將 API 綁在 127.0.0.1 就夠。若你要用手機或另一台桌機，透過 Wi‑Fi 區網打這台電腦的 192.168.*.*:9090，核心就必須監聽在可從地端網路抵達的位址（常見為 0.0.0.0 或該機之區網 IP），並搭配allow-lan: true（依版本與客戶端，選項名稱可能寫「允許區域網路連線」）。否則就算通訊埠開著，仍可能只接受本機，或乾脆無法從外援連入。

開放區網 API 等同於讓同一個區網內的任何人在未授權情況下試圖操作你的代理核心——風險極高。實務上務必啟用secret、僅在受信任的家用內網短暫測試，並在完成後改回僅本機或加上防火牆規則限制來源 IP。更完整的區網情境（混合埠、手機 Wi‑Fi 代理）請讀《Clash 開啟區域網路代理》。

六、secret 與 Authorization：401 不是「連不上」

若瀏覽器或面板能連上埠，但回401 Unauthorized，代表 TLS/TCP 已通，問題反而是金鑰不一致。Mihomo／Clash API 通常以 Authorization: Bearer <secret> 承載密碼字串；Yacd等面板會有獨立欄位讓你填「Secret」或「API Token」。

排查順序：先在設定檔確認 secret 的值（區分空白字元、引號是否被客戶端轉義）；再確認面板是否要求填寫完整字串而非只填前半段；若曾用圖形介面改過密鑰但未重載核心，請重啟服務或套用設定。把 401 誤當成「網路斷線」會讓你在錯誤方向調整 bind 位址，浪費時間。

七、本機實測：用 curl 打 REST API

在裝核心的那台機器上開終端機，優先測版本端點（不同核心版本路徑可能為 /version 或相容路徑，請以官方文件為準）。若未設 secret，可嘗試：

curl -sS http://127.0.0.1:9090/version

若有 secret：

curl -sS -H "Authorization: Bearer YOUR_SECRET" http://127.0.0.1:9090/version

curl 若同樣 connection refused，問題在核心或埠設定，與 Yacd 無關；若本機成功、瀏覽器失敗，再檢查是否用了https去連只提供 http 的 API、或填錯IPv6與 IPv4。在無圖形介面的伺服器上，這條路徑也與《Linux Mihomo 與 systemd》的「遠端僅 SSH、本機測 API」流程一致。

八、圖形客戶端覆寫：實際生效的是哪一份設定？

許多使用者同時擁有「訂閱產生的完整設定」與「客戶端 UI 開關」。當兩者衝突時，以執行中程序實際載入的 merged 設定為準。若你在 UI 關閉了外部控制，YAML 裡仍寫著 external-controller，最終行為取決於合併規則與客戶端實作，請以連線日誌或「關閉 UI 覆寫、重載」的方式驗證。

建議養成習慣：每次修改後，用同一個 curl 指令做探針；通過後再打開 Yacd，在設定頁一次性填好 Base URL 與 Secret，避免快取舊的 WebSocket 連線位址。

九、防火牆與埠占用：排除「其實沒在聽」的假象

Windows 上若允許了區網連入，請在「具有進階安全性的 Windows Defender 防火牆」檢查輸入規則是否放行該埠（僅限信任網路）。macOS 可能跳出對mihomo或客戶端二進位的連入允許對話框，若先前按拒絕，之後要進「系統設定 → 網路 → 防火牆」調整。

另可用系統工具檢查埠是否由預期程序持有；若 9090 已被其他服務占用，核心可能自動換埠或啟動失敗——這時再貼 127.0.0.1:9090 到面板當然連不上。請回頭閱讀啟動日誌中的listen或RESTful API字樣確認實際埠。

十、Yacd／metacube 介面該怎麼填

開源面板通常提供「API Base」輸入框：填 http://127.0.0.1:9090（或你的實際 IP 與埠），協定選http除非你真的在核心前套了反向代理＋TLS。跨裝置時填執行核心那台電腦的區網 IP，並已按第五節放寬監聽與 allow-lan。

若面板支援透過訂閱 URL 載入遠端前端、卻在本機連 API，瀏覽器可能觸發CORS或混合內容限制；碰到 API 請求被擋時，可改將 Yacd 託管在簡易本機靜態伺服器或改用客戶端內建面板，再把 API 指向迴環位址，減少跨來源問題。這類前網頁問題與核心 bind 無關，但症狀同樣是「面板一片空白或無節點」。

十一、實測勾選表（濃縮）

  1. 核對執行中設定的 external-controller 位址與埠。
  2. 本機 curl 測 /version（或相容端點）是否回 JSON。
  3. 區網存取時改 bind-address／監聽介面並開 allow-lan；確認防火牆。
  4. 401 時先對齊 secret 與面板的 Bearer 字串。
  5. 排除代理埠與控制埠混淆、以及埠占用與啟動失敗。

十二、小結

Yacd與同類工具只是殼，真正的外部控制台資料來自Mihomo／Clash REST API。connection refused時，請先把external-controller與bind-address理解成「誰可以從哪張網卡敲這個埠」，再決定要不要為區網暫開allow-lan並以secret把風險壓住。相較一口氣背誦所有錯誤碼，這條鏈路收斂成少數幾個可複製的終端機步驟，維護成本會低很多。若你希望圖形客戶端一站式處理訂閱、規則與連線觀測，可先從本站整理的安裝包著手，再回頭用 curl 驗證 API 是否如預期開放。相較封閉黑箱工具，開源核心的好處在於每個請求與回應都可對照文件與日誌；當環境就緒後，不妨透過本站下載頁取得適合的客戶端，把面板與規則一起跑穩。→ 立即免費下載 Clash，開啟流暢上網新體驗