Clash 本機控制台打不開？external-controller 與 external-ui 逐項排查步驟

先釐清：您要連的是「靜態頁」還是「REST API」？

在 Clash／mihomo（Clash Meta）生態裡，瀏覽器裡常見的 Yacd、Metacubexd 或自架儀表板，本質上多數是前端單頁：它們透過 HTTP 去呼叫核心暴露的 REST API。核心是否在正確的 監聽位址與埠號上提供 API，由設定裡的 external-controller（以及部分版本／衍生核對應的 UI 路徑選項，如 external-ui）決定。若這一步沒對上，畫面會出現連線被拒絕、一直轉圈、或主控台裡看到被瀏覽器擋下的混和內容（Mixed Content）請求。

本文與Rule Provider 更新失敗、Sniffer 深度設定角度不同，專注在「本機 localhost 為什麼開不了面板」這條路徑；若您懷疑是埠被其他程式占用，請先並行參考 Windows 埠占用與 mixed-port 排查，因為 API 埠與混合代理埠是兩個常見的獨立數字，日誌裡要分開看。

第一步：確認核心真的在「您以為的那個埠」上 LISTEN

打開用戶端日誌或圖形介面中「目前生效設定」頁，抄下 external-controller 的完整字串（含 IP 或主機名與埠）。接著在同一台執行核心的機器上，用瀏覽器試 http:// 加上該位址，或先用命令列探測。以常見本機 API 埠 9090 為例（請替換成您的實際埠）：

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

若這裡就失敗，問題多半還在「核心沒聽」或「聽在別的介面」，而不是 Yacd 本身壞掉。curl 能回傳版本 JSON，代表 TCP 層已通，再談瀏覽器與前端設定才有意義。若您用的是圖形殼（例如 Clash Verge Rev），也請確認「服務／核心程序」確實已啟動，而不是僅開著設定視窗、內部 mihomo 尚未載入完成。

第二步：綁定位址——127.0.0.1、0.0.0.0 與「您輸入的網址」要一致

external-controller 常見寫法有兩類：只允許本機迴環的 127.0.0.1:埠，或讓區網內其他裝置也能連的 0.0.0.0:埠（實際產品文案可能寫「綁定所有介面」）。若設定為 127.0.0.1，您卻用手機或另一台電腦打主機的區網 IP，連線會失敗，這是預期行為，不是 bug。相反地，若您只在本機瀏覽器開面板，卻把核心綁在特定網卡位址或僅 IPv6，而您一直用 localhost（在部分系統上解析到 ::1）去連 IPv4 監聽，也可能出現「以為沒開、其實是走錯門」的情況。

實務上建議：本機除錯時明確寫 IP，例如一律用 http://127.0.0.1:9090/ui 這類路徑（實際路徑依版本與是否啟用內建 UI 而定），減少 localhost 雙堆疊解析造成的混淆。需要讓平板手機連線時，再改 0.0.0.0 並搭配Allow LAN、防火牆與區網政策一併檢查，避免只改 API 綁定卻沒開放入站規則。

第三步：檢查 YAML——欄位名、縮排、以及是否被「另一份設定」蓋掉

手寫 YAML 時，最常見的是縮排錯誤導致整段不生效，或把鍵名打成近似字（例如舊文件與新核心的差異）。請在圖形介面中找「合并／產生的完整設定」或日誌裡「實際載入」路徑，確認最終檔案裡確實出現預期的 external-controller。若您使用 mixin、訂閱覆寫、或 GUI 的「覆寫檔」功能，優先順位可能讓您在主檔看到一行、實際執行時卻被另一段蓋掉；這時要以執行中設定為準，而不是您磁碟上第一份開啟的檔案。

下列為示意（埠與密鑰請勿照抄，需依您環境調整）：

# Example only — replace port and secret
external-controller: 127.0.0.1:9090
secret: "change-me"

若啟用了 secret，前端面板通常要在設定裡填相同的金鑰才能通過驗證；空白或打錯會變成 401 或前端一直顯示未授權。若您暫時為了除錯而拿掉 secret，請務必只在可信本機環境操作，並在確認無誤後恢復，以免 API 暴露在區網或公網時被任意操作。

第四步：external-ui 與內建靜態路徑——別把「API 埠」和「靜態檔案路徑」搞混

在 mihomo 等分支中，external-ui 常用來指定內建儀表板靜態檔所在目錄，讓您用單一 external-controller 埠下的子路徑開啟 UI。不同版本文件路徑可能顯示為 /ui 或類似約定；若您升級核心後書籤仍指舊路徑，會得到 404 或空白頁。此時應對照目前版本文件或直接在瀏覽器試探根路徑與常見子路徑，並以日誌確認 HTTP 伺服器是否真的在該埠提供靜態服務。

相對地，Yacd／Metacubexd 也可以託管在純靜態伺服器或官方演示站上：這種模式下，頁面是 HTTPS 或另一個網域，API 卻在您的 http://127.0.0.1:9090。這會觸發瀏覽器的混和內容限制——安全網頁可能禁止主動請求不安全的本機 HTTP。解法包括：改用本機開啟的 http:// 版面板、使用支援的瀏覽器旗標（僅限您了解風險時）、或透過反向代理為 API 提供同源 HTTPS（進階）。許多使用者「面板突然全壞」其實是瀏覽器升級後規則變嚴，而非 Clash 設定被清空。

第五步：Docker、WSL 與「誰才是 localhost」

當核心跑在容器裡，而您在 Windows 或 macOS 主機的瀏覽器輸入 127.0.0.1，連到的可能是主機迴環，而不是容器內的 mihomo。需要映射埠（publish port）或改打 Docker Desktop 提供的主機側對應埠。若您同時使用 Docker Desktop 與 Clash 同機，請把「容器內 external-controller」「對外映射」「主機防火牆」三點畫成一條線對齊。

WSL2 場景下，Linux 分發版裡的 127.0.0.1 與 Windows 主機的迴環並非同一個位址空間；在 Windows 瀏覽器要連 WSL 內服務，常需使用 WSL 回傳給主機的 IP，或透過 localhost 轉發機制（依版本與組件而定）。若您只在 WSL 裡 curl 成功、在 Windows Edge 失敗，幾乎可以鎖定在這一層。

第六步：本機防火牆與安全軟體——與「拒絕連線」的差異

若 TCP 連線在送出後立即被拒絕或逾時，除了沒聽埠之外，也可能是防火牆攔截入站。這與代理規則無關，而是作業系統是否允許本機處理程序接受連入。Windows Defender、第三方防毒、公司政策套件都可能攔截「某執行檔首次開埠」。簡易判斷方式：暫時關閉測試規則或新增允許規則後，curl 與瀏覽器是否同步恢復。若只有區網連線失敗、本機永遠正常，則要回到第二節的綁定位址與 Allow LAN。

建議核對清單（可列印或存成備忘）

• 埠一致：日誌、生效設定、瀏覽器網址列三處的數字是否完全相同。
• 協定一致：API 多為 HTTP；誤打 HTTPS 會憑證錯誤或連不上。
• secret：前端是否填入與 YAML 相同的金鑰。
• 混和內容：HTTPS 頁是否被允許存取 HTTP 本機 API。
• 覆寫來源：GUI mixin、訂閱模板、遠端覆寫是否改掉 controller。
• 虛擬化邊界：Docker／WSL 的 localhost 是否指同一層。

結語

Clash 的 Web 控制台問題，十之八九可以濃縮成一句話：瀏覽器連到的位址，必須與核心實際監聽的 external-controller 一致，並在啟用 secret、HTTPS 前端、或容器網路時多跨一兩道門檻。依本文順序從 curl、綁定位址、YAML 與 mixin、external-ui 路徑、混和內容，再到 Docker／WSL 與防火牆，通常能在短時間內縮小範圍，而不必重裝或盲目重置訂閱。

相較於四處下載來路不明的「一鍵魔改版」，使用持續更新的官方或主流圖形殼、並從可信來源取得安裝檔，較能避免 API 埠與內建 UI 路徑在版本之間悄悄改動。若您正在找各平台合適的用戶端入口，可先從本站 下載頁面 取得一致說明，再回頭對照設定與本機除錯步驟。