Clash API 節點自動切換：external-controller 進階設定
利用 Clash external-controller API 管理代理節點，將延遲測試、故障轉移與策略組控制串成可自動執行的流程，適合需要穩定連線與可觀測性的技術使用者。
external-controller 是什麼？
Clash 的 external-controller 是提供給管理工具與自動化腳本使用的本機 API 入口。開啟後，您可以透過 HTTP 請求讀取目前設定、查看代理節點、取得策略組狀態、執行延遲測試，甚至直接切換某個策略組所使用的節點。對一般使用者來說，圖形化用戶端中的「代理」頁面已經足以完成手動選擇；但當您需要長時間維持穩定連線，或希望在節點異常時自動處理，external-controller 就能把原本需要人工點選的工作串成一套可重複執行的流程。
這個 API 常見於 Clash Verge Rev、Mihomo、Clash Meta 核心以及其他相容 Clash API 的用戶端。不同版本支援的端點可能略有差異，因此實際操作前應先確認核心版本與 API 文件。本文以常見的 REST API 介面為例，說明如何設定控制入口、查詢節點、測試延遲，以及根據測試結果切換策略組。API 的用途是管理您自己執行的 Clash 核心，並不會替您產生節點或提供代理服務。
需要特別區分的是，external-controller 主要負責「控制與觀測」，並不是一般應用程式使用的代理埠。瀏覽器或其他軟體要經過 Clash，仍然要連線到 mixed-port、http-port、socks-port 或 TUN 介面。API 只是在旁邊讀取狀態與下達指令，例如查看目前出口、替策略組選擇節點，或要求核心對一批節點發出延遲測試。
開始前的設定與安全原則
在修改設定檔之前，先確認目前使用的是哪一個核心。Clash Verge Rev 與 Mihomo 通常支援較完整的控制 API，而部分舊版用戶端可能只提供有限端點。若用戶端介面已經有「External Controller」「外部控制器」或「API 監聽」欄位，可以直接在圖形介面中查看；若是手動管理 YAML，則需要在設定檔加入對應項目。
建議的本機控制設定
external-controller: 127.0.0.1:9090
secret: "請替換成一組足夠複雜的密碼"- 127.0.0.1：只允許本機存取，適合個人電腦與單機腳本。
- 9090：API 監聽埠，可依其他服務的使用情況調整。
- secret：API 驗證密鑰，建議使用隨機且不重複的長字串。
不建議一開始就把監聽位址改成 0.0.0.0:9090。這會讓區域網路中的其他裝置也有機會連到控制介面；如果沒有同時設定密鑰、防火牆規則與可信網段限制，攻擊者可能讀取節點資訊、改變代理出口，甚至利用 API 影響您的網路流量。即使您只是想讓手機或另一台電腦管理 Clash，也應優先使用區域網路指定 IP、VPN 或 SSH 隧道，而不是直接把控制埠暴露到公網。
安全提醒
secret 不等同於代理訂閱密碼，也不應直接放在公開程式碼、截圖或 Git 儲存庫中。若曾經將密鑰貼到聊天群組或公開平台，請立即更換，並重新啟動 Clash 核心讓新設定生效。
修改完成後，請重新載入設定檔，並在日誌或用戶端狀態頁確認 API 已開始監聽。若使用的是容器、虛擬機或路由器，還要另外確認連接埠映射與防火牆規則；本機設定正確，不代表外部腳本一定能抵達該服務。最穩妥的做法是先在執行 Clash 的同一台機器上測試，確認 API 回應正常後再處理跨裝置管理。
查詢節點與策略組狀態
API 自動切換的第一步不是立即更換節點，而是先取得 Clash 目前認得的代理名稱與策略組結構。訂閱中的節點名稱可能包含空格、 emoji、括號或不同語言文字，因此不要在腳本裡假設名稱一定固定。較可靠的方式是先讀取完整清單，再依名稱前綴、關鍵字或策略組成員判斷。
查詢代理清單
curl -H "Authorization: Bearer YOUR_SECRET" \
http://127.0.0.1:9090/proxies
回應通常會包含一個 proxies 物件。每個代理可能是單一節點，也可能是 Selector、URLTest、Fallback 或 LoadBalance 等策略組。策略組的 all 欄位代表可選成員，now 則表示目前使用中的成員。您可以先找出名稱為「Proxy」「節點選擇」「自動選擇」或訂閱自訂名稱的策略組，再確認它是不是規則中真正使用的出口。
先確認「實際出口」
很多自動切換失效的原因，不是 API 請求錯誤，而是腳本切換了不會被規則使用的策略組。例如規則指向「🚀 節點選擇」，腳本卻改變「♻️ 自動選擇」。執行切換前，請從 Connections、Logs 或設定檔的 rules 區塊確認規則實際指向哪一個名稱。
如果只想取得某一個策略組的資訊，也可以讀取特定代理的資料。名稱需要進行 URL 編碼，不能直接把含有空格的原始字串拼接到網址中。使用程式庫時應交給 HTTP 客戶端負責編碼；手動測試則可以先使用瀏覽器開發工具或命令列工具處理特殊字元。這個細節很容易被忽略，尤其是策略組名稱包含斜線、井號或非 ASCII 字元時，伺服器可能回傳 404 或錯誤的代理名稱。
用延遲測試判斷節點是否可用
「延遲最低」不一定等於「使用體驗最好」。延遲測試反映的是 Clash 到指定測試網址的連線時間，不能完整代表影片播放、檔案下載或長時間 HTTPS 連線的穩定性。不過，將延遲測試與錯誤次數、最近使用時間及最低可接受門檻結合，仍然可以建立一個實用的自動選擇機制。
測試單一節點
curl -G \
-H "Authorization: Bearer YOUR_SECRET" \
--data-urlencode "timeout=5000" \
--data-urlencode "url=https://www.gstatic.com/generate_204" \
"http://127.0.0.1:9090/proxies/NODE_NAME/delay"
測試網址應選擇穩定、回應內容簡單且不需要登入的端點。若目標是評估一般網頁連線，可以準備兩到三個不同網域，避免某個測試站點暫時故障造成誤判。timeout 應設定合理範圍，例如 3000 至 8000 毫秒；太短會把只是稍慢的節點全部判定為失敗，太長則會讓切換流程卡住。若回應成功，API 通常會返回一個代表延遲毫秒數的數值；逾時、DNS 失敗或 TLS 錯誤則表示本次測試不可用。
實務上可以先篩選策略組中的節點，再以延遲排序。例如排除名稱含有「故障」「維護」或已連續失敗的節點，接著測試剩餘成員。若節點數量很多，不建議在短時間內對所有節點反覆測試，因為這會增加核心與遠端服務的負擔，也可能觸發供應商的連線限制。可以採用輪詢方式，每次只測試尚未確認的節點，並為結果設定五至十五分鐘的快取時間。
| 判斷項目 | 建議做法 | 常見誤區 |
|---|---|---|
| 延遲數值 | 設定最大可接受門檻，再從合格節點中選擇 | 只追求最低數值，忽略波動與穩定性 |
| 測試網址 | 準備多個可信端點，必要時分開測試 | 只依賴一個可能暫時故障的網站 |
| 失敗處理 | 記錄連續失敗次數，避免立即反覆切換 | 每次逾時都立刻改節點，造成頻繁抖動 |
| 測試頻率 | 使用快取與退避時間，分批執行測速 | 每秒對全部節點發送請求 |
透過 API 切換策略組
查詢與測速完成後，才能將結果套用到真正的策略組。切換策略組通常使用 PUT 請求，請求本文包含名為 name 的節點名稱。這個操作只會改變目前執行中的選擇，未必會永久修改原始 YAML 設定檔；重新啟動核心或重新載入設定後，是否保留選擇取決於用戶端與設定檔的持久化行為。
切換策略組中的節點
curl -X PUT \
-H "Authorization: Bearer YOUR_SECRET" \
-H "Content-Type: application/json" \
-d '{"name":"Hong Kong 01"}' \
"http://127.0.0.1:9090/proxies/Proxy"
腳本不應只送出切換請求就結束，而應在收到成功狀態後再次查詢策略組，確認 now 已經變成目標節點。若切換失敗，常見原因包括節點名稱不在該策略組的 all 清單中、策略組本身是不可手動指定的類型、請求方法不符合核心版本，或 API 密鑰不正確。切換完成後，也建議觀察短時間內的 Connections 與 Logs，確認新出口確實承擔了流量。
一個較穩定的自動切換流程可以分成幾個階段：先讀取策略組成員，排除不應使用的節點；接著執行延遲測試，保留低於門檻且測試成功的節點；然後依延遲、歷史失敗次數與最近切換時間計算分數；最後只有在新節點明顯優於目前節點，或目前節點連續失敗時才切換。這樣可以避免兩個延遲相近的節點互相來回跳轉，降低連線中斷與登入工作階段失效的機率。
不要忽略切換冷卻時間
自動切換應設定冷卻時間，例如五分鐘內不重複更換同一策略組。節點短暫抖動時，如果腳本同時受到多個測試結果觸發，可能在幾秒內連續切換，反而比維持原節點更不穩定。對需要登入、串流或長連線的應用程式，穩定性通常比少數幾十毫秒的延遲差距更重要。
建立可觀測且不易失控的自動化流程
真正可用的節點自動切換，不只是把幾個 API 請求放進排程器，而是要同時處理驗證、錯誤、日誌與回復。建議腳本至少保存目前策略組、原本節點、測試時間、測試網址、延遲結果與錯誤原因。當使用者發現「今天網路變慢」時，這些資料能幫助判斷是節點本身不穩、測試站點異常，還是規則與 DNS 發生變化。
API 請求應設定連線逾時與整體執行逾時，並對暫時性錯誤採用有限次數的重試。重試時使用逐步增加的等待時間，不要在伺服器尚未恢復時持續轟炸。若所有節點都測試失敗，最佳行為通常是保留目前選擇並產生警告，而不是隨機切換到未知節點。若目前節點也已確定無法使用，才依照備援順序選擇下一個候選，並在恢復後重新驗證。
另外要把「測速成功」與「實際服務正常」分開看待。API 延遲測試可能只驗證 TCP 或 HTTPS 連線，而您的目標服務還可能受到規則、SNI、DNS、地區限制或服務端速率控制影響。因此可以在切換後進行一次輕量的業務驗證，例如檢查指定網址的 HTTP 狀態碼，或確認 Clash Connections 中出現預期的代理連線。驗證請求不要攜帶私人資料，也不要把完整網址中的權杖或帳號資訊寫入日誌。
如果您使用 systemd、工作排程器、Docker 或自製服務執行腳本，請將 API 密鑰放在環境變數或權限受限的設定檔中，並確保只有執行帳號可以讀取。更新 Clash 核心後，應重新測試 /proxies、/delay 與策略組切換端點，因為不同核心的端點支援、錯誤格式與策略組行為可能有所差異。當 API 回應 401、404 或 500 時，先記錄狀態碼與非敏感錯誤內容，再對照目前核心文件，不要直接放寬權限或關閉驗證。
推薦的檢查順序
- 確認
external-controller只監聽預期的位址。 - 使用密鑰成功讀取
/proxies。 - 找出規則真正使用的策略組與目前節點。
- 以少量候選節點測試
/delay，確認測試網址可達。 - 先在非關鍵時段測試切換，並驗證
now狀態。 - 最後才加入定時排程、失敗退避與通知機制。
相較於部分只提供固定手動選擇、缺乏 API 或監控能力的代理工具，Clash 的 external-controller 能把節點狀態、延遲測試、策略組切換與日誌觀測整合在同一套核心中；不過，API 功能越完整，越需要使用者妥善管理密鑰、權限與自動化邏輯。如果您希望在不手動編輯大量設定的情況下管理節點，同時保留跨平台用戶端、策略分流與可觀測性，Clash 會是更容易延伸的選擇。完成安全設定後，不妨免費下載 Clash，立即體驗，再依自己的裝置與核心版本逐步建立自動切換流程。