Clash 控制器 API 自動切換節點設定與維運實戰
先確認控制器 API 與可切換的策略群組
Clash 控制器 API 可讓外部程式讀取目前的代理與策略群組狀態,也能切換部分群組的選擇結果。自動化切換前,先分清楚「代理節點」和「策略群組」:節點是實際的代理出口;策略群組則負責組織節點、決定選擇方式,並可能被規則引用。日常維運通常應操作規則所引用的選擇型群組,而不是直接修改訂閱中的節點資料。
控制器位址由 external-controller 設定,例如 127.0.0.1:9090。這是 API 監聽連接埠,不是瀏覽器或終端機使用的 HTTP、SOCKS 代理連接埠。控制器常用的查詢入口包括 GET /version、GET /proxies 與 GET /proxies/{name};選擇型策略群組則可透過 PUT /proxies/{name} 更新目前選取的代理。
以下設定僅用於說明控制器應限制在本機,並使用非空的密鑰。實際檔案也可能由圖形化用戶端管理;修改前先確認目前執行中的設定來源,避免訂閱更新或用戶端覆寫把調整覆蓋。
external-controller: 127.0.0.1:9090
secret: "replace-with-a-long-random-secret"
若要讓同一區域網路的其他裝置呼叫 API,不應只把監聽位址改成 0.0.0.0 就視為設定完成。應先評估防火牆、可信任網段、控制器密鑰保存與存取記錄;控制器具有讀取狀態及操作策略的能力,暴露後可能讓未授權者改變流量路由。除非確有遠端管理需求,建議使用回環位址,讓自動化程式與核心在同一台裝置上執行。
查詢群組、檢查候選節點並執行切換
切換前先透過 API 讀取群組,而不是硬編碼節點清單。不同訂閱可能使用不同的節點名稱,更新訂閱後節點也可能增加、移除或改名。對選擇型群組而言,回應通常會提供群組類型、目前選取項目,以及可選代理名稱;自動化程式應先確認目標群組存在、類型符合預期,且候選節點仍在該群組的可選清單中。
以下以 Unix shell 的 curl 示範讀取狀態。把 PROXY 換成實際策略群組名稱,密鑰則從環境變數或受控的密鑰管理工具讀取,不要直接寫入將提交到版本控制的腳本。
export CLASH_SECRET='replace-with-a-long-random-secret'
BASE='http://127.0.0.1:9090'
curl --fail --silent --show-error \
-H "Authorization: Bearer ${CLASH_SECRET}" \
"${BASE}/proxies"
curl --fail --silent --show-error \
-H "Authorization: Bearer ${CLASH_SECRET}" \
"${BASE}/proxies/PROXY"
確認目標代理名稱確實出現在群組回應後,才送出切換請求。群組名稱與節點名稱若包含空格、斜線或非 ASCII 字元,放在 URL 路徑時應進行 URL 編碼;不要自行猜測編碼後的字串,也不要把未驗證的使用者輸入直接串接進 URL。
curl --fail --silent --show-error \
-X PUT \
-H "Authorization: Bearer ${CLASH_SECRET}" \
-H "Content-Type: application/json" \
--data '{"name":"node-a"}' \
"${BASE}/proxies/PROXY"
這個操作適用於可手動選擇出口的策略群組,例如 select。不同群組類型的控制方式並不完全相同:url-test 或 fallback 群組會依其測速、健康檢查與備援邏輯管理選擇結果,不應把它們當成一般手動選擇群組來操作。自動化程式應讀取 API 回傳的 type,遇到不支援的類型就停止並記錄原因。
如需先比較節點延遲,可使用核心支援的代理延遲測試介面。下列命令測試一個具體代理名稱;目標測試網址應選擇穩定、可由該網路環境存取的地址,並為請求設定合理逾時。延遲結果只能反映這次測試的連通性與回應時間,不等同於長期穩定性或所有服務的實際速度。
curl --fail --silent --show-error \
-H "Authorization: Bearer ${CLASH_SECRET}" \
"${BASE}/proxies/node-a/delay?url=https%3A%2F%2Fwww.gstatic.com%2Fgenerate_204&timeout=5000"
不同核心版本或相容實作可能在 API 細節上有所差異。若收到 404,先確認端點、群組名稱與目前核心支援的控制器介面;若收到 401 或 403,檢查密鑰設定及認證標頭;若連線被拒絕,則確認核心是否已啟動,以及控制器是否真的監聽於指定位址與連接埠。
建立可驗證、可重試的自動切換流程
自動切換不應等同於「測到一次延遲較高就立即換節點」。測速會受到網路尖峰、遠端服務限流、DNS 解析與測試目標狀態影響;若每次短暫波動都觸發切換,可能造成頻繁震盪,反而影響正在進行的連線。較穩健的流程是先讀取狀態、檢查候選、判定觸發條件、執行變更,再讀回狀態確認結果。
- 檢查控制器可用。先呼叫狀態或版本端點,設定短逾時;控制器無回應時不要繼續發出切換請求。
- 讀取群組目前狀態。記錄群組類型、目前節點及候選清單。若目標群組不存在或類型不符,應停止處理並發出告警。
- 驗證候選出口。確認候選名稱仍存在於該群組,並使用一致的測試網址與逾時測量。對單次失敗可短暫等待後再測,不要將一次逾時直接解讀為節點永久不可用。
- 套用切換條件。例如連續三次測試失敗,或延遲連續數個採樣週期超過內部門檻,才考慮切換。門檻需依工作負載調整,不宜把單一延遲數字當成所有網路的通用標準。
- 送出切換並讀回確認。請求成功後重新查詢群組狀態,確認
now或相應的目前選擇欄位已變成目標名稱。HTTP 成功只代表 API 接受請求,不應取代狀態驗證。 - 限制重試與切換頻率。採用有限次重試、逐步延長等待時間及切換冷卻期。超過上限後保留目前狀態,記錄錯誤並告警,避免在 API 或網路故障時不斷改寫策略。
呼叫程式應將「查詢失敗」、「測速失敗」、「切換請求失敗」與「切換後驗證失敗」分開記錄。這些狀況代表的故障層級不同:查詢失敗可能是控制器連線或認證問題;測速失敗可能是候選代理或測試目標不可達;切換後狀態未變則可能是群組類型不支援、請求內容不符或設定被其他程序同步修改。
例如,維運腳本可以使用固定的請求逾時,最多重試兩次,並在每次重試前重新查詢群組狀態。若重新查詢發現另一個程序已經切換到健康節點,腳本就應停止,不要再使用過期狀態覆寫新選擇。這種先讀後寫的保護能降低排程任務、桌面用戶端與人工操作同時執行時的競爭風險。
切換前保存原本選擇,可用於記錄變更與設計回復流程;但不建議無條件在錯誤時自動切回舊節點,因為舊節點可能正是故障來源。回復策略應重新檢查舊節點健康狀態,並明確設定觸發條件。每筆維運記錄至少包含時間、群組、原節點、目標節點、切換原因、測試結果、API 回應狀態及最終驗證狀態,同時避免記錄密鑰與完整認證標頭。
保護控制介面並避免維運事故
控制器 API 能變更代理策略,應按管理介面而不是一般查詢服務的標準保護。最小化暴露範圍是第一步:僅本機自動化使用時,將控制器綁定到 127.0.0.1,並讓防火牆拒絕外部連線。不要將控制器連接埠直接映射到公網,也不要因為設定了密鑰就忽略監聽位址和網路邊界。
- 使用高熵密鑰:避免使用短字串、常見密碼或與訂閱帳密相同的值。密鑰應存放於作業系統的安全憑證儲存、受限權限的環境設定或專用密鑰管理服務。
- 避免命令列與日誌洩漏:密鑰可能出現在 Shell 歷史、程序參數、除錯輸出或 CI 記錄中。自動化環境應限制日誌內容,並採取合適方式傳遞認證資訊。
- 限制操作對象:程式只允許操作預先設定的群組與候選清單,不接受任意群組名稱或節點名稱。對從 API 讀取的資料也要驗證欄位及類型。
- 設定逾時和上限:每次 HTTP 請求都設定連線及讀取逾時,重試次數與執行時間都要有上限,避免網路中斷時程序永久停留。
- 控制並行操作:同一群組的排程任務應避免同時執行;可使用作業鎖或佇列,並在寫入前重新查詢狀態,降低互相覆蓋的風險。
- 保留稽核與告警:記錄策略變更的必要資訊,為連續失敗、未知群組、候選清單變更及驗證不一致設定告警,方便定位問題並由人工接手。
還要留意控制器與代理服務並非同一個安全邊界。開啟 allow-lan 是讓其他裝置使用代理監聽連接埠的設定,不能代替控制器的安全設計;反過來,限制控制器只監聽本機,也不會自動限制所有代理連接埠的區域網路存取。應分別檢查控制器位址、代理監聽位址、區域網路開關與防火牆規則。
更新核心或圖形化用戶端後,應以低風險方式重新驗證自動化:先查詢版本與群組資料,再在非關鍵時段切換到已知可用的候選,最後讀回狀態並確認一般流量正常。不同核心版本可能調整 API 回應欄位、錯誤處理或群組行為;將 API 呼叫測試納入升級檢查,能避免程式在核心更新後仍表面執行、實際卻沒有完成切換。
常見問題
呼叫 API 成功,為什麼目前節點沒有改變?
先重新查詢策略群組,確認群組類型、目前選擇與回應內容。請求成功不代表所有群組都支援手動指定節點;自動測速或備援類型可能會依自身邏輯更新。也要確認使用的節點名稱在該群組候選清單內,並檢查是否有其他用戶端或排程任務隨後改回原選擇。
控制器 API 的 9090 連接埠可以當成系統代理使用嗎?
不可以。控制器連接埠提供狀態查詢與管理 API,與供應用程式轉送流量的 HTTP、SOCKS 或混合代理連接埠用途不同。終端機代理環境變數應指向實際代理監聽連接埠,不應填入控制器位址。
可以讓外部伺服器直接連線到控制器嗎?
除非有明確的遠端維運需求,否則不建議直接暴露控制器。優先讓自動化程式在核心所在裝置上執行;若必須遠端管理,應使用受控的安全通道、網路存取限制、強密鑰及防火牆規則,並在完成後確認沒有留下公開監聽或轉發設定。
如何避免切換腳本造成節點來回震盪?
不要依單次測速結果切換。使用連續多次失敗或多個採樣週期的門檻,加入切換冷卻時間,並限制重試次數。每次切換後都重新讀取狀態;若沒有通過驗證,就停止自動操作並告警,交由維運人員檢查。