一、外部控制器是什麼、與 mixed-port 不同在哪？
external-controller 是 Clash 核心對外開放的 REST 風格 API 與（依版本而定的）圖層外掛位址，預設寫在設定檔最外層，常見寫成 127.0.0.1:9090 或帶一個 secret 字串。圖形客戶端內建的面板、或你另外開的 Web 面板（例如 yacd、metacubexd 等靜態頁面），在瀏覽器裡要指向同樣的 API 位址，否則畫面怎麼重新整理都不會有資料。相對的，mixed-port 或 port 是代理協定（HTTP／SOCKS）給系統、瀏覽器或訂閱裝置走流量用，兩者用途完全不同：代理能連外網，不代表 API 埠一定打得開。許多人「代理都正常、面板卻全白」，第一步應先確認實際載入的設定檔裡，external-controller 那一行與圖形介面顯示的埠是否一致，而不是去調整訂閱或規則。
若你使用 Clash Verge 類圖形殼，核心可能會在背景把設定合併或覆寫，建議在「關於／設定目錄」裡找實際生效的設定檔，再對照下兩節的位址邏輯。更多與 macOS 系統代理、TUN 權限相關的層面，可延伸閱讀 Clash Verge 與系統代理 的排錯專文，但本篇聚焦在 API 監聽 與 密鑰 本身。
二、逾時、連線被拒、401 各代表什麼？
先把現象分類，可大幅縮小範圍。瀏覽器若長時間沒有回應，最後變成逾時，多數是 TCP 根本沒有連到聽在該 IP／埠的行程，例如位址寫錯、程序沒有啟動、或防火牆在半路丟棄。若幾乎立刻出現「無法連線」或 ERR_CONNECTION_REFUSED，則是有送到該主機、但沒有服務在聽那個埠，常見於埠被改掉、寫了已佔用埠、或你打到錯的 IP（例如從手機打桌機的區網位址，但 API 其實只聽迴圈）。401 Unauthorized 則是有連上 API，但帶的密鑰不對或沒有帶；有些面板在填錯 secret 時仍會載入靜態殼、只是任何請求都失敗。不要把 401 誤以為是「沒有開代理」──它反而代表你該從 secret 與面板的 Authorization 欄位查起。
| 你看到的 | 較常見的原因 |
|---|---|
| 轉圈後逾時 | 目標 IP 不可達、被防火牆攔、或從外網打內網卻沒有對應轉送；也請核對 bind-address 是否只允許本機。 |
| Connection refused | 埠號寫錯、核心沒有載入帶有 external-controller 的設定、或與其他程式佔用埠衝突。 |
| 401 | secret 與面板內的 API 金鑰不一致；多餘空白、全形符號、或一邊有填一邊沒有填。 |
三、bind-address：本機、全部介面與從他機連入
在較新分支中，bind-address（有時與 external-controller 的位址一併理解）控制核心要把 API 聽在哪些介面上。若沒有特別寫，常見行為是只聽 127.0.0.1，也就是只允許本機迴圈。此時，你在同一台電腦的瀏覽器裡用 http://127.0.0.1:PORT 存取是對的；但若你想用手機連同一區網的桌機、或在 Docker／虛擬機裡從主機打進容器，就必須把監聽改為 0.0.0.0 或實際的 區網 IP，並且用桌機的區網位址＋正確埠號去開面板，光改瀏覽器書籤是不夠的。另一方面，把 API 聽在全部介面有安全風險，務必靠 secret 強密碼、可信區網、或額外防火牆規則限制來源，不要長期在公網上裸曬。
若你曾依 Windows 混合埠、區網與防火牆 一文調整過 區網存取，可類比理解：讓系統能從內往外的傳出規則是代理要用的；傳入 則是別台裝置連回你這台主機的 API 埠。在 Windows 上，若內建防火牆曾詢問而遭到封鎖，也會在「本機能開、他機卻打不開」的現象上表現出來。需要更廣的介面層面說明，可再對照 Clash TUN 與 Windows 防火牆 的整體流程，避免把 TUN 與 API 埠混淆。
127.0.0.1 搭配固定 secret 是較單純的組合。
四、secret 與 Web 面板的密鑰欄位
當 secret 出現在設定檔內，API 多數實作會要求請求夾帶 Authorization: Bearer <密鑰>。圖形客戶端內建面板有時會自動幫你帶入；若你使用獨立開啟的靜態面板，就要在面板的「API 位址」旁手動填同一條密碼。常見錯誤是：在 YAML 用引號包住了英數字、面板卻多複製一個引號、或兩邊一個有空白一個沒有。也請記得，若你重新產生過密鑰、或從下載的範本貼上時覆蓋了舊的 secret，瀏覽器若還留著上次的 localStorage，就會在看似「有網路」的狀態下一直 401。遇到這種情況，可優先關掉面板分頁、清掉該站點的儲存資料、再重新貼上完整 API URL（含 secret 參數，或依各面板文檔填寫欄位）。
少數佈署會把 external-controller 放在 Unix socket 或關掉 HTTP，此時瀏覽器方案就不適用，需要改用能指定 socket 的客戶端。一般桌面使用者則以 http:// ＋ 正確 主機、埠、密鑰 即可。
五、YAML 範例與圖形介面對應
以下為教學用示意，埠號、密碼與實際檔名請依你環境改寫。注意 YAML 的縮排與鍵名大小寫需與你使用的核心分支一致，若讀不進設定，可先看客戶端日誌有無 parse error。
# 僅本機可連 API（瀏覽器在本機用 127.0.0.1:9090）
external-controller: 127.0.0.1:9090
secret: "你的強密碼"
# 若需同一區網內他機以 http://<你的區網IP>:9090 連線，常見寫法例如：
# external-controller: 0.0.0.0:9090
# 並在防火牆允許 9090/tcp 的傳入（僅限信賴的區網）圖形介面中若有「**外部控制**」「**Controller**」「**Web UI** 埠」之類的欄位，本質上就是在改上述鍵。改完後務必**重啟核心**或讓客戶端**重新載入設定**，只按「儲存」卻沒有送進實際執行中的程序，一樣會出現連線被拒。也請確認**沒有兩份設定**互相蓋寫：例如使用者目錄下的手動檔與應用程式內的編輯器內容不同，最後被載入的是較舊那一份，便會導致「介面寫 9090、實際在聽 9091」的錯亂。若你正在整理完整路由與檔案結構，可搭配 站內說明文件 的架構章節一併閱讀，較容易維持單一真實來源。
六、防火牆、TUN 與本機迴圈
若只有在本機 127.0.0.1 存取、仍逾時，先排除埠號衝突與多核心實例（兩次啟動、或服務沒有殺乾淨）。在 macOS 與 Windows 上，用系統內建工具或 netstat／ss 觀察該埠是否由預期程序佔用。當 TUN 模式一併啟用時，少數情況會讓你誤以為「全機流量都經代理」，卻在路由層讓迴圈位址的連線被錯誤導向；若你懷疑此類邊界情況，可暫時關閉 TUN 或僅用系統代理模式，再試一次本機 API，並與 TUN 排障專文 交叉比對。若從另一作業系統的虛擬機連宿主上的 API，127.0.0.1 指的是虛擬機自己，要改用宿主在虛擬橋接下的 IP，這是初學者極常踩的坑。
七、排錯清單（可列印、依序打勾）
- 確認 Clash 核心正在執行，且載入的設定裡有
external-controller，埠號與你瀏覽器網址列完全一致。 - 分清楚：打的是
127.0.0.1還是區網 IP；從他機連入時，bind-address是否允許，而不只是改書籤。 - 若設了
secret，面板內的密鑰與設定檔逐字元比對（注意空白、引號與全形字元）。 - 在作業系統防火牆與可能的三方防毒中，放寫入站規則給你選定的 API 埠（僅在需要他機存取時）。
- 避免埠被其他服務佔用；變更埠後一併更新書籤、快捷方式與面板已儲存的位址。
八、小結
Clash 外部控制器 是進階管理與Web 面板 的基礎；把它想成與 代理埠 分開的管理後門，就不會在「能翻牆、卻看不了儀表板」的時候改錯方向。從 bind-address 與 external-controller 確認聽在哪裡、從 secret 確認誰有權限、再從本機、區網、防火牆一層層加寬，多數逾時、連線被拒、401 都能有條理地收斂。相較於只會「重灌客戶端」或反覆匯入訂閱，能讀懂 YAML 裡的這幾行，可長期省下一堆無謂嘗錯。若你尚未使用支援清楚顯示生效設定與重載流程的圖形殼，也可先從本站配好的用戶端取得安裝包，再回頭把 API 相關選項釘在你信任的值。