為什麼要用 Clash API 做自動選線

當訂閱裡只有三、五個節點時,手動點擊策略組並不困難;但節點數量一多,或你需要長時間維持穩定連線,單靠介面上的一次性測速就不夠了。某個節點可能在白天延遲很低,到了晚間卻開始丟包;也可能是 TCP 測試成功,但實際存取 API、影音服務或長連線應用時頻繁逾時。這些情況若沒有持續監測,通常要等到使用者感覺「網路壞掉」後,才手動切換節點。

Clash 核心提供的控制介面,能讓腳本讀取目前的代理與策略組狀態,再透過 /proxies、/proxies/{name} 等 API 查詢節點資訊或切換代理。配合 Mihomo/Clash Meta 的 url-test、fallback 策略組,你可以建立一個更完整的故障轉移流程:定期檢查候選節點,排除無法連線或延遲異常的節點,必要時把策略組切換到健康節點,並留下可供事後排查的紀錄。

這類自動化並不是「延遲最低就永遠最好」。實際選線還要考慮封包丟失、連續失敗次數、切換冷卻時間,以及目前應用是否正在維持長連線。本文以熟悉 YAML、能操作命令列的進階使用者為對象,示範一套偏保守的設計:先以 Clash 內建策略組為主要決策者,腳本只負責監測、告警與在明確故障時切換,避免因短暫抖動造成頻繁跳線。

⚠️
安全與合規提醒:控制介面等同於本機代理的管理入口,任何取得密鑰的程式都可能讀取節點資訊並切換流量。請只在自己管理的裝置與網路環境中使用,遵守所在地法令、服務條款與公司網路政策,不要把控制介面暴露到公網。

先建立 API 基線:端點、認證與策略組

開始寫監測腳本前,先確認 Clash 控制介面是否真的可用。不同客戶端的設定名稱可能略有差異,但 Mihomo 常見的控制器設定會包含 external-controller 與 secret。例如控制器綁定在本機的 127.0.0.1:9090,腳本就應該透過本機回環介面連線,而不是使用區域網路 IP。若沒有設定密鑰,部分客戶端仍可運作,但不建議在腳本化環境中省略認證。

external-controller: 127.0.0.1:9090
secret: "請改成隨機且不重複的密鑰"

完成設定後,可以先用 curl 檢查 API 是否回應。以下請把 YOUR_SECRET 換成實際密鑰;若密鑰為空,則依你的核心設定移除 Authorization 標頭。回應能否正常解析,比單純看到 HTTP 200 更重要,因為某些反向代理或客戶端錯誤頁也可能回傳成功狀態碼。

curl -s \
  -H "Authorization: Bearer YOUR_SECRET" \
  http://127.0.0.1:9090/proxies

/proxies 通常會回傳所有代理與策略組。你要先找出目標策略組的實際名稱,例如 自動選線、Proxy 或訂閱提供者自訂的名稱。名稱可能包含空格、斜線或非 ASCII 字元,因此在 URL 中使用時必須進行 URL 編碼,不要直接假設所有策略組都叫作 Proxy。

對於「自動選線」用途,建議在 YAML 中準備清楚的候選集合,而不是讓腳本掃描全部節點。候選節點可以排除過期、重複、地區不符或不適合長連線的項目;策略組則負責正常狀態下的測速。常見設計如下:

proxy-groups:
  - name: 自動選線
    type: url-test
    proxies:
      - 節點-A
      - 節點-B
      - 節點-C
    url: "https://www.gstatic.com/generate_204"
    interval: 300
    tolerance: 80

  - name: 故障備援
    type: fallback
    proxies:
      - 節點-A
      - 節點-B
      - 節點-C
    url: "https://www.gstatic.com/generate_204"
    interval: 120

url-test 適合在多個可用節點之間比較測試延遲,fallback 則更重視依序使用第一個健康節點。若你的目標是平常維持固定出口、故障時才切換,fallback 往往比持續追逐最低延遲更穩定;若是短連線、對延遲敏感的請求,才考慮使用 url-test。測試 URL 也不要只挑一個與實際服務完全無關的站點,最好選擇穩定、回應快速且符合你使用情境的 HTTPS 位址。

監測腳本:從查詢狀態到自動切換

一個可靠的節點故障轉移腳本,至少要分成四個步驟:讀取策略組狀態、取得候選節點清單、執行實際健康檢查,以及依條件決定是否切換。不要把「單次測試失敗」直接等同於「節點死亡」,否則 Wi-Fi 短暫干擾、遠端測試站點擁塞或 DNS 抖動,都可能造成不必要的切換。

  1. 讀取目前狀態:先確認策略組是否存在、目前選中的代理名稱是什麼,以及核心回傳的延遲與歷史錯誤資訊。
  2. 建立候選集合:只檢查配置中明確列出的節點,排除 DIRECT、REJECT、其他策略組與暫時停用的項目。
  3. 重複健康檢查:在短時間內進行兩至三次測試,記錄成功率、平均延遲與最大延遲,而不是只看一次結果。
  4. 執行切換:只有在連續失敗達到門檻,或目前節點明顯高於備援節點時,才呼叫策略組切換 API。
  5. 寫入紀錄:記下時間、舊節點、新節點、失敗原因與測試數據,方便分辨是節點問題、區域網路問題還是控制器故障。

切換策略組時,通常會對目標群組發送帶有代理名稱的請求。以 Python 為例,腳本可以使用標準函式庫建立一個簡單的 API 客戶端;實務上則建議使用有逾時控制的 HTTP 函式庫,並對回應狀態碼與 JSON 結構做檢查。

import os
import time
import requests

API = "http://127.0.0.1:9090"
SECRET = os.environ["CLASH_SECRET"]
GROUP = "自動選線"

headers = {"Authorization": f"Bearer {SECRET}"}

def get_group():
    response = requests.get(
        f"{API}/proxies/{GROUP}",
        headers=headers,
        timeout=5
    )
    response.raise_for_status()
    return response.json()

def switch_proxy(proxy_name):
    response = requests.put(
        f"{API}/proxies/{GROUP}",
        headers=headers,
        json={"name": proxy_name},
        timeout=5
    )
    response.raise_for_status()

上面的程式只展示 API 互動骨架,並不代表應該每幾秒無條件切換。真正使用時,請另外保存每個節點的連續失敗次數與最後切換時間。例如目前節點連續三次檢查失敗,且距離上次切換已超過五分鐘,才進入備援選擇;切換完成後再等待一段觀察期,避免腳本在兩個節點之間來回震盪。

備援選擇可以採用分級門檻。第一級是可連線性,只要節點無法完成 TLS 握手或健康檢查,就不應被選中;第二級是延遲,例如平均延遲低於 500 毫秒;第三級是穩定度,要求最近五次測試至少成功四次。若多個節點都達標,再以延遲、地區或人工優先順序排序。這種做法比單純選最小數字更能避免把偶然的低延遲誤判成最佳線路。

ℹ️
實作建議:把節點切換與「是否需要代理」分開管理。腳本只切換策略組內的代理,不要在故障時直接修改整份 YAML、重啟核心或覆蓋訂閱,否則容易遺失手動設定,也會讓問題更難回溯。

服務化部署、排程與故障排查

在桌面環境中,你可以用排程器每五至十五分鐘執行一次腳本;Linux 主機則可使用 systemd timer 或 cron。頻率不要盲目設得太高。若核心本身已經以 60 秒或 300 秒頻率進行 url-test,外部腳本只需負責比較連續失敗、檢查特定應用路徑與發送告警即可。過度頻繁的 API 請求會增加控制器負擔,也可能讓節點測試流量與實際業務流量互相干擾。

服務化部署時,請把密鑰放在環境變數、作業系統密鑰環或權限受限的設定檔中,不要直接寫進公開 Git 儲存庫。執行帳號只需要讀取腳本與紀錄檔的權限,不應該使用不必要的系統管理員權限。若腳本需要透過網路傳送告警,告警內容也不要包含訂閱 URL、完整節點名稱、控制器密鑰或可能識別使用者的流量資訊。

建議至少保留以下幾類紀錄:控制器是否可連線、策略組當前選擇、健康檢查的 URL、每次請求的狀態碼、連續失敗計數、切換前後的節點,以及腳本自身的例外訊息。紀錄檔要設定輪替與保留期限,避免長時間執行後佔滿磁碟。若環境中有 Prometheus、Webhook 或其他監控系統,也可以只輸出彙總指標,例如健康節點數、最近一次切換時間與五分鐘內失敗率。

遇到「腳本顯示節點健康,但實際應用仍然斷線」時,請按層次排查。首先確認腳本使用的測試 URL 是否真的經過 Clash;其次比對連線紀錄中的規則命中與策略組名稱;再次確認應用程式是否讀取系統代理或混合埠。某些命令列工具、背景服務與瀏覽器子程序不會自動使用系統代理,此時即使 Clash API 已成功切換,也不代表該程式的流量會跟著改道。需要涵蓋這類流量時,才評估 TUN 模式,並留意 DNS、路由與權限設定。

另一個常見問題是切換 API 回傳成功,但使用者感覺沒有變化。這可能是因為切換的是上層策略組,而實際應用命中了另一個策略組;也可能是既有 TCP 連線仍在使用舊出口,新建立的連線才會採用新節點。因此測試時要關閉或重新建立相關連線,不要只看策略組顯示名稱。對於 WebSocket、資料庫連線或長時間下載,應特別設定切換冷卻期,並讓應用自行處理重連。

最後,請為腳本加入失敗保護:API 無法連線時不要清空策略組,不要把所有節點標記為不可用,也不要在例外狀況下自動切換到未知代理。當控制器沒有回應時,最安全的動作通常是保留目前配置、記錄錯誤並發出告警。只有在能確認候選節點與控制器狀態都正常時,才執行自動變更。

相較於部分只提供手動節點列表的工具,或需要自行拼接 API、排程與日誌的通用腳本方案,ClashSky 在節點策略組、健康檢查與圖形化狀態查看上更容易形成完整流程,遇到切換異常時也能從介面與紀錄快速確認問題。若你不想從零維護複雜的控制腳本,可以先使用 ClashSky 熟悉策略組與 API,再逐步加入自己的監測規則;歡迎前往下載並實際體驗。