Clash API 節點自動切換：健康檢測與腳本化設定指南

Clash API 節點自動切換到底在處理什麼

當你使用 Clash、Clash Verge Rev 或 Mihomo 時，節點自動切換並不是單純按照節點名稱輪流跳轉，而是一套「取得狀態、發送檢測、整理結果、更新策略」的流程。腳本會先透過 Clash API 讀取目前核心的代理、代理群組與運作狀態，再依照你的條件對指定節點發出健康檢測請求，最後把延遲、HTTP 回應、連線失敗次數等結果整理成可供判斷的資料。只有當節點符合條件，腳本才會呼叫切換 API，把代理群組改到更合適的節點。

這種方式特別適合需要長時間執行的電腦、家用伺服器、NAS、開發機或遠端工作環境。手動切換的問題在於，你通常只會在「已經很慢」或「完全連不上」之後才發現節點失效；健康檢測則可以提早發現延遲升高、TLS 握手失敗、回應碼異常或節點雖然顯示可用但實際無法通過目標服務的情況。對需要維持 API、同步工具或串流連線的工作流來說，這種提前判斷比單純看訂閱頁上的綠色狀態更可靠。

不過，自動切換也不代表節點越多越好。若候選節點太多、檢測頻率太高，可能增加代理服務端的請求量，甚至讓本機日誌充滿無意義的切換紀錄。較穩妥的做法是先選出用途相近的節點建立策略群組，再讓腳本針對這個群組做檢測；例如將同一地區、同一協定或相近頻寬的節點放在一起，而不是讓腳本在所有訂閱節點中盲目選擇。

本文使用的 API 概念以 Mihomo／Clash.Meta 常見介面為主。不同客戶端的選單名稱、API 埠號和部分回應欄位可能略有差異，因此實際部署前，請先確認你使用的核心是否開啟外部控制器，以及目前設定檔中的 external-controller、API 密鑰與代理群組名稱。若你使用的是圖形化客戶端，先在介面中確認核心正在執行，再進行腳本測試，會比直接猜測連接埠有效。

先理解 API 端點、群組結構與安全風險

Clash API 通常透過 HTTP 方式提供狀態讀取與控制功能。常見用途包括讀取版本資訊、列出代理節點、查詢代理群組、檢視目前選中的節點，以及修改某個選擇器群組的當前代理。不同核心版本的路徑可能有所不同，但概念大致可以分成幾類：

• 核心狀態：用來確認 API 是否可達、核心是否仍在運作，以及讀取版本或運行資訊。
• 代理清單：取得節點、DIRECT、REJECT、URLTest、Fallback、Load-Balance 等代理項目，供腳本建立候選集合。
• 代理群組：查詢某個策略組內有哪些成員，避免腳本直接把所有訂閱節點當成同一類資源。
• 目前選擇：讀取指定群組目前使用的節點，讓腳本在切換前後都能留下可追蹤的狀態。
• 切換操作：向指定群組提交新的代理名稱。這個動作應該只針對選擇器群組執行，不要把節點名稱誤當成群組名稱。

最需要注意的是外部控制器的暴露範圍。若 API 只綁定在 127.0.0.1，通常只能由本機腳本呼叫；若設定成 0.0.0.0，區域網路中其他裝置可能也能嘗試存取。即使你使用的是家中內網，也不應把控制器當成普通的公開服務。請設定足夠複雜的密鑰，並避免把控制器埠直接映射到公網；如果確實需要從另一台管理機操作，應透過防火牆、VPN 或受限制的管理網段來保護。

另一個常見問題是把 API 密鑰直接寫進公開的 Shell 腳本、Git 儲存庫或截圖。腳本可使用環境變數保存密鑰，例如把控制器位址與密鑰放在本機的權限受限設定檔，再由程式讀取。若是 systemd、Docker 或排程器執行，請確認環境變數真的傳遞到該程序；你在互動式終端中能成功呼叫 API，不代表背景服務也一定讀得到相同設定。

健康檢測怎麼設計才不會頻繁誤切換

健康檢測的第一個選擇是測試端點。你可以測試一個回應內容小、可穩定存取的 HTTPS 端點，也可以測試工作流真正需要的服務。兩者各有用途：通用端點適合確認節點基本可用，實際服務端點則能反映某個 API 或網站的真實可達性。若你只測試通用端點，可能出現「檢測成功但目標服務失敗」；若只測試單一服務，又可能把服務本身的短暫故障誤認為所有節點失效。

建議把檢測結果拆成至少三個欄位：是否連線成功、耗時多少、回應是否符合預期。延遲可以設定一個合理上限，例如超過日常平均值的兩倍才標記為需要觀察，而不是看到任何高於一百毫秒的數字就切換。對跨地區節點而言，絕對延遲差異可能很大；更實用的方式是建立相對排名，並為不同用途設定不同門檻。互動式網頁重視首包延遲，檔案下載重視持續速度，API 串流則更在意長連線中斷與重試。

第二個重點是失敗容忍度。假設排程每三十秒檢測一次，只要一次超時就切換，網路稍微抖動便會造成節點來回跳轉。較穩定的策略是採用連續失敗，例如連續兩至三次失敗才把節點標記為不健康；切換到新節點後，再觀察一段冷卻時間，避免下一輪檢測立刻切回原節點。對恢復中的節點，也可以使用較長的重新加入時間，讓它先通過多次測試再回到候選集合。

第三個重點是不要把不同類型的節點混在同一個評分模型中。某些節點延遲低但頻寬有限，某些節點延遲稍高卻非常適合長時間串流；如果只按照單一毫秒數排序，腳本可能選出最不適合實際工作的節點。可以把評分寫成多條件規則：連線失敗直接淘汰，超過延遲上限則降權，最近曾成功完成實際請求則加分，頻繁切換過的節點則暫時冷卻。這比「永遠選最小延遲」更能降低不穩定。

動手部署：用腳本呼叫 Clash API 完成節點切換

開始前，先確認你的設定檔中已經存在一個可切換的代理群組，例如名稱為 Proxy，並且該群組包含數個可用節點。請不要直接修改訂閱原始檔；訂閱更新可能會覆蓋手工修改的內容，較好的做法是使用客戶端支援的覆寫、Merge 或外部控制器功能，讓策略組結構在更新後仍然存在。

1. 在 Clash Verge Rev 或其他 Mihomo 客戶端中確認核心已啟動，查看設定檔使用的外部控制器位址與 API 密鑰。
2. 在瀏覽器或終端機中先呼叫狀態端點，確認位址、埠號和密鑰無誤。若 API 回傳未授權，先處理密鑰，不要直接重啟整個客戶端。
3. 讀取代理群組清單，確認腳本使用的是精確群組名稱。名稱包含空格、括號或非 ASCII 字元時，請使用正確的 URL 編碼或由程式庫處理。
4. 為候選節點設定檢測端點、逾時時間、連續失敗次數與冷卻時間，先用三至五個節點進行小範圍測試。
5. 將檢測結果寫入日誌，包括時間、候選節點、延遲、失敗原因、原節點和新節點，方便日後判斷是節點問題還是腳本邏輯問題。
6. 手動執行腳本數次，確認只有在新節點明顯較好或原節點確實失效時才切換，最後再交給排程器長期執行。

以下是概念性的 API 呼叫流程，實際端點名稱請以你所使用的 Clash 核心文件為準。這段示例的重點不在於複製後立即執行，而在於理解每一步應該驗證什麼：先讀取群組，再檢測候選節點，最後提交選擇結果。

GET  http://127.0.0.1:9090/proxies
GET  http://127.0.0.1:9090/proxies/Proxy
PUT  http://127.0.0.1:9090/proxies/Proxy
{
  "name": "Node-A"
}

如果你以 Shell、Python 或 Node.js 撰寫腳本，請為每次請求設定連線逾時和整體逾時。沒有逾時的 HTTP 呼叫可能讓排程程序永久卡住，下一輪排程又啟動另一個程序，最後形成多個腳本同時切換節點。腳本也應該處理 API 回傳的非二百狀態碼、JSON 格式錯誤、節點不存在和控制器暫時無法連線等例外，而不是把錯誤當成空節點繼續執行。

執行頻率可以從每五至十分鐘開始，觀察一至兩天後再調整。若你的需求是即時維持 API 連線，仍不建議把週期縮短到每幾秒；更好的方式是讓實際請求失敗時觸發一次快速檢查，再由背景排程進行低頻率健康確認。Linux 可使用 systemd timer 或 cron，Windows 可使用工作排程器，macOS 則可使用 launchd。無論使用哪一種，請避免讓腳本與客戶端同時改寫同一個策略組。

評分、切換與回復策略：避免節點來回震盪

一個可維護的切換器通常會保留上一輪結果，而不是每次都從零開始。你可以為每個節點記錄最近成功時間、最近失敗時間、連續失敗次數、平均延遲和切換次數。當目前節點仍然健康時，即使另一節點只快了幾毫秒，也不必立刻切換；只有當新節點的評分高出最低改善幅度，或目前節點連續失敗，才執行切換。這個「滯後」設計能避免兩個節點在數值接近時反覆互換。

切換後應設置冷卻時間。例如從 Node-A 切換至 Node-B 後，在接下來幾分鐘內不要重新選擇 Node-A，除非 Node-B 也連續失敗。冷卻不只是防止震盪，也能避免某個短暫恢復的節點因一次成功檢測就立即搶回流量。若工作流使用長連線，切換還可能讓原有連線中斷，因此最好只在確認新節點足以改善問題時執行，而不是把切換當成一般的負載平衡。

失敗處理可以分成三層。第一層是單一節點失敗：降低該節點分數並繼續使用目前健康節點。第二層是整個群組候選節點都失敗：保留目前狀態、記錄警告，並延長下一次重試間隔。第三層是 Clash API 本身無法連線：不要把所有節點標記為失效，因為問題可能在核心停止、控制器埠號改變或密鑰不正確。只有先區分「控制面失效」和「代理面失效」，日誌才有診斷價值。

若腳本服務的是重要工作流，還可以加入人工鎖定功能。例如在需要固定出口地區、登入特定服務或進行交易測試時，暫停自動切換；任務完成後再解除鎖定。也可以在切換前檢查目前是否存在大量活動連線，避免在下載、視訊會議或資料同步中途突然更換出口。自動化的價值不是完全取代判斷，而是把重複性的檢測工作交給程式，讓人只在真正需要介入時收到通知。

常見問題與排錯方法

為什麼瀏覽器能上網，但腳本一直顯示 API 無法連線？

瀏覽器能上網只代表代理流量正常，不代表外部控制器 API 的位址和埠號正確。請先確認腳本呼叫的是本機控制器，而不是代理的 mixed-port；兩者用途不同。接著檢查客戶端是否重啟後更換了 API 埠號、是否設定了密鑰，以及腳本執行環境是否使用了錯誤的 HTTP_PROXY。呼叫本機地址時，通常應把 127.0.0.1 和 localhost 放在 NO_PROXY 中，避免管理請求被再次送入代理。

為什麼節點自動切換得太頻繁？

最常見原因是檢測週期太短、只有一次失敗就切換，或評分差距沒有設定最低改善幅度。請提高連續失敗門檻，加入冷卻時間，並把檢測結果與實際切換分開記錄。若兩個節點延遲非常接近，就保留目前節點；只有在原節點確實失效，或新節點長時間明顯較穩定時才切換。

健康檢測成功，但實際 API 請求仍然失敗，該怎麼辦？

這通常表示檢測端點和實際服務的網路條件不同。請使用與實際工作流相近的測試端點，並檢查 DNS、TLS、SNI、HTTP 方法、授權狀態和串流連線是否被分別處理。通用網址只能驗證基本可達性，不能證明特定供應商 API 的帳號權限、地區限制或長連線品質都正常。

訂閱更新後，腳本找不到原本的代理群組，怎麼處理？

訂閱更新可能重新產生代理群組，導致名稱改變或手工修改被覆蓋。建議使用穩定的策略組名稱、覆寫規則或 Merge 設定，並在腳本啟動時先檢查群組是否存在。若名稱確實會隨訂閱變化，可以用明確的標籤、前綴或群組映射，但不要只靠節點顯示名稱中的國家字樣判斷，因為服務商可能隨時改名。

相較於只依賴手動點選、固定單一節點，或使用缺少健康檢測與冷卻機制的簡單切換工具，Clash API 能把節點狀態、延遲、失敗原因與策略群組集中管理；即使某些同類工具介面較簡單，遇到訂閱更新、長連線中斷或多裝置共用時，往往仍要重新手動確認設定。透過本文的檢測門檻、失敗容忍、日誌與冷卻策略，你可以在保留人工控制權的同時降低維護成本；如果你希望把這套流程落實到實際客戶端，先選擇適合自己平台的 Clash 版本會是自然的下一步。

立即免費下載 Clash，開啟流暢上網新體驗 →