為什麼「能上網」卻開不了 Web 面板

Clash Meta 同時有兩條讀起來很像、實際上完全不同的通道：資料面負責把瀏覽器與應用程式的流量依規則送到對的出口；控制面則是對核心下指令、讀狀態的 REST API，通常由設定檔裡的 external-controller 決定「在哪個 IP／埠上聽」。Yacd、metacubexd 這類 Web 面板並不是「另一個代理埠」，它們只是瀏覽器裡的介面：本質上仍要向 http://<controller-host>:<port> 發送 API 請求。

因此常見現象是：網頁與通訊軟體已經能走代理，但面板顯示連線失敗、載入停住、或直接 401 Unauthorized。這通常代表「資料面 OK、控制面沒對齊」：要嘛 API 根本沒聽在你以為的位址；要嘛聽在 127.0.0.1 但你卻用別台裝置的 IP 去連；要嘛設了 secret 但面板沒帶對 token／Authorization。先把這三件事分開看，排查會快很多。

external-controller：本機綁定與埠號

external-controller 的字面容易誤導：它叫「外部」，但在預設安全模型裡，最常見、也最該優先採用的寫法其實是只綁本機迴環，讓只有同一台電腦上的瀏覽器與腳本能碰到 API。典型範例如下（埠號僅示意，請避免與你機器上既有服務衝突；註解使用英文）。

external-controller localhost bind (recommended baseline) 
external-controller: 127.0.0.1:9090
secret: "replace-with-a-long-random-string"

當你把位址寫成 127.0.0.1（或等價的「只聽 loopback」語意）時，代表區網手機／另一台筆電用 http://192.168.x.x:9090 來連，會直接被作業系統拒於門外——這不是 Clash「壞掉」，而是綁定介面本來就限制連線來源。若你確實要在區網管理，必須改成綁 0.0.0.0 或特定區網 IP，並搭配防火牆與強密碼；這類拓樸與風險取捨可延伸閱讀 區網分享與防火牆綁定 專文。

另一個高頻錯誤是埠號抄錯：圖形客戶端可能顯示「外部控制埠」與「混合埠／HTTP 代理埠」兩組數字，Web 面板要對的是 external-controller 那一個，不是 mixed-port。升級或還原設定後數字漂移時，先用實際 config.yaml 對照最保險；流程也可與 Clash Meta 升級指南 一起檢查。

secret、token 與 401 授權標頭

設定檔中的 secret，語意上就是 API 的共享金鑰：啟用後，未帶憑證的請求往往會拿到 401。多數面板在 UI 裡把它叫做 token、Secret、或 Bearer，但你要對齊的是同一段字串：與 config.yaml 完全一致，包含大小寫、引號外是否留空、以及有沒有多餘空白。

ℹ 實務習慣：把 secret 想成「等同於能遠端改你代理策略的密碼」。寧可稍長、隨機，也不要用短口令或預設值；若曾外洩設定檔，應一併視為密碼洩漏並立即更換。

在純 curl 測試時，常見做法是帶 Authorization: Bearer <secret>（實際標頭格式請以你所用核心版本文件為準；少數工具亦支援在 query string 附帶 token，但較容易進入瀏覽器紀錄與反向代理日誌，不建議當成首選）。若面板一直 401，請先確認「設定檔真的已重載」：有些客戶端需要你按「重新載入」或重啟核心後，secret 才會生效。

Yacd、metacubexd 與 API 基底網址怎麼填

這類面板通常會問你兩件事：API Base（或稱後端位址）與密鑰。對本機最直覺的組合是：

若你使用「線上託管的面板頁」（例如從 CDN 開啟的靜態站），瀏覽器端的 JavaScript 會從使用者的電腦去連你填的 API。此時若填 127.0.0.1，語意仍是「瀏覽器那台機器的本機」，通常符合「同一台電腦開面板」的場景；但若你把頁面嵌在不安全的環境、或混用 http／https 造成混合內容阻擋，介面可能會表現成「連不上」而非清晰的錯誤訊息。遇到這類情況，可先改用最單純的本機開啟方式對照：確認問題是 API 還是瀏覽器安全策略。

相對地，若你在手機上開面板，卻填 http://127.0.0.1:9090，那會變成「手機自己的本機」，當然找不到電腦上的核心——這時要嘛改填電腦的區網 IP 並讓 controller 真的聽在可達的介面上，要嘛用手機透過 SSH 隧道等方式把遠端埠轉成本機（進階題，且仍應優先考慮金鑰與來源限制）。站內 常見問題 亦整理多則與埠號、權限與安全相關的說明，可作為延伸閱讀。

external-ui（可選）與靜態面板路徑

有些使用者會在設定檔看到 external-ui：它指向一個本機目錄，讓核心能直接提供內嵌的靜態面板資源。這與「你自己開 Yacd／metacubexd 網頁再去連 API」是兩種部署路徑，容易搞混。若你啟用 external-ui，請確認目錄存在、版本與核心相容，且你實際開啟的 URL 與文件描述一致；若未使用該欄位，則專注把 external-controller 與 secret 對齊即可。

無論走哪條路，請記住：面板只是皮，真正決定能不能讀到狀態的，仍是 REST API 是否可達、以及授權是否通過。

先用 curl 驗證 REST API 再開面板

當 Web UI 讓你摸不著頭緒時，先用終端機把變因切開：若 curl 能拿到預期回應，代表核心與金鑰大致沒問題，剩下多半是面板 URL 或瀏覽器端設定；若 curl 也失敗，就回到綁定位址、埠、程序是否啟動、以及設定是否載入。

curl: probe controller with Bearer secret (example) 
# Replace host:port and YOUR_SECRET.
curl -sS -H "Authorization: Bearer YOUR_SECRET" \
  "http://127.0.0.1:9090/version"

你可以把 /version 換成其他唯讀端點做測試（端點路徑請以官方文件為準）。重點是建立一個可重複的最小測試：同樣的 host、同樣的埠、同樣的 secret，在終端機與面板兩邊應該得到一致結果。若終端機成功、面板失敗，優先檢查面板是否把 API Base 指到錯埠、是否多打了斜線、或是否仍在使用舊的快取連線。

安全模型：不必把控制口開成「全網可連」

許多人不敢開面板，其實是擔心「把管理介面暴露出去」。對多數個人使用者而言，最務實的起手式是：controller 綁本機＋強 secret＋只在同一台電腦操作。在這個模型下，區網或網際網路上的掃描流量預設碰不到你的 API，你也不依賴「整個區網都能改你策略」這種高風險拓樸。

若你因遠端管理而必須開放，請把它當成等同 SSH 的權限來設計：強密碼、最小暴露面、能關防火牆就關、能走 VPN／隧道就不要裸奔公開埠。更多「外部控制器暴露」的觀念題，亦可對照 常見問題 中相關段落，先把威脅模型講清楚再動手。

症狀對照與建議排查順序

  1. 連線被拒／timeout：優先確認程序有在跑、埠是否一致、以及是否誤把 127.0.0.1 當成別台機器上的位址。
  2. 401：優先確認 secret 是否啟用、面板 token 是否同步、以及請求是否真的帶上授權標頭。
  3. 404／路徑錯誤：常見於 API Base 多寫了後綴、或把靜態面板路徑與 API 前綴混在一起；先對照文件的最小 URL。
  4. 瀏覽器顯示混雜的 CORS／HTTPS 錯誤：先改用同一安全層級的開啟方式，或回到本機靜態頁對照。
  5. 升級後突然壞了：先核對設定檔是否被客戶端覆寫、預設埠是否改變，並參考 升級指南 的檢查點。
⚠ 合規提示：請在合法授權的網路環境下使用 Clash，並遵守在地法規與服務條款。本文僅說明技術設定，不鼓勵規避合規管控。

自檢清單

  1. external-controller 的 IP 與埠，是否與面板 API Base 完全一致。
  2. 若只綁 127.0.0.1，是否確實在同一台機器開面板，而非用手機連電腦的 127.0.0.1。
  3. secret 是否已載入；修改後是否已重載／重啟核心。
  4. 用 curl 最小請求驗證通過後，再回頭調整 Web UI。
  5. 是否誤用 mixed-port 或其他代理埠充當控制埠。
  6. 若必須區網或遠端管理，是否已同步檢視防火牆、來源 IP 限制與密碼強度。

結語

Web 面板 故障排查的本質，是把 Clash Meta 的控制面 REST API當成一個獨立服務：它有監聽位址（external-controller）、有金鑰（secret／token），而 Yacd、metacubexd 只是幫你把這些請求包得漂亮。當你能用 curl 穩定驗證 API，再把同樣的 host、port、secret 原封不動填回面板，大多數「能上網但面板壞了」的案例就會迅速收斂。

相較於把控制口開到整個區網甚至公網，本機綁定搭配高強度隨機 secret，通常是最划算的安全預設：你仍能在同一台電腦上完整管理策略與連線，但把最危險的「任何人都能改設定」從預設拓樸中移開。若你接下來要處理的是 DNS、TUN、或規則分流本體，站內也有對應專文可與本文互相補位。

→ 立即免費下載 Clash，開啟流暢上網新體驗，用一致的客戶端與可預期的控制面設定，讓資料面與管理面都穩定可維護。