Clash API 節點自動切換:健康檢查與腳本實作
先啟用並保護 external-controller API
Clash 相容核心的 external-controller 是供圖形介面或外部程式讀取狀態、檢查延遲及切換策略組的控制介面;它不是 HTTP 或 SOCKS 代理連接埠。自動切換腳本會透過這個介面查詢代理清單,再向指定的選擇型策略組送出切換請求。本文範例以 Mihomo 常見的 REST API 為例,使用 Python 標準函式庫,不需要額外安裝套件。
先確認目前實際執行的設定有控制器位址與密鑰。控制器僅供本機腳本使用時,建議綁定 127.0.0.1,不要為了方便直接監聽所有網路介面:
external-controller: 127.0.0.1:9090
secret: "請換成長且隨機的密鑰"
儲存設定後重新載入核心,並確認連接埠沒有被其他程式占用。若用戶端提供 API 或控制器設定頁面,請以用戶端顯示的生效值為準;訂閱更新或設定覆寫有可能取代手動修改的欄位。控制器網址使用 http://127.0.0.1:9090,不是代理服務常用的 7890 或其他 mixed-port。
先從本機確認 API 是否可連線。以下命令使用環境變數傳遞密鑰,避免把密鑰直接留在命令列歷史或腳本檔案中。回應應包含 proxies 物件;如果得到連線拒絕,先檢查控制器位址、連接埠及核心狀態;若回應為 401,則檢查密鑰是否與生效設定一致。
# macOS / Linux
export CLASH_API="http://127.0.0.1:9090"
export CLASH_SECRET="請換成你的控制器密鑰"
curl -sS -H "Authorization: Bearer $CLASH_SECRET" \
"$CLASH_API/proxies"
# PowerShell
$Env:CLASH_API = "http://127.0.0.1:9090"
$Env:CLASH_SECRET = "請換成你的控制器密鑰"
Invoke-RestMethod -Headers @{ Authorization = "Bearer $Env:CLASH_SECRET" } `
-Uri "$Env:CLASH_API/proxies"
確認策略組並設計節點健康檢查
自動切換的目標應是 select 類型的手動選擇策略組,例如名為「節點選擇」的組別。腳本可以選擇該組中的實際節點,但不應把同一個 API 呼叫套用到任意策略組:url-test、fallback 與 load-balance 本身各有自動選擇機制,手動改寫它們可能與核心的排程行為互相干擾。先查詢 /proxies,確認組別名稱、型別、成員清單與目前選取的節點。
Mihomo API 可用 GET /proxies/{名稱}/delay?url=測試網址&timeout=毫秒 測量代理延遲。測試網址應是穩定、可用 HTTPS 存取的端點;不同網路環境對特定站點的可達性不同,因此應換成實際需要的服務,且不要把單一站點的失敗直接等同節點全面故障。延遲測試測量的是指定端點在當下的回應,不代表所有網站、遊戲或長連線都正常。
篩選候選節點時,排除 DIRECT、REJECT 等內建出口,也排除其他策略組。實務上還要設定逾時、失敗重試與切換門檻,避免短暫丟包就立刻改線。若目前節點仍可用,只有新節點明顯較快時才切換;若目前節點測試失敗,則可選擇成功回應且延遲最低的候選項。
- 測試目標:使用穩定的 HTTPS 網址,避免以容易受限流或地區政策影響的單一服務作為唯一判斷依據。
- 逾時設定:單次檢查可從 5 秒開始;網路延遲較高時可調整,但不宜讓腳本無限等待。
- 切換門檻:設定延遲改善幅度,例如新節點至少快 20% 才取代仍健康的目前節點。
- 執行頻率:初次測試可手動執行;排程後不要每幾秒重測,以免產生大量連線與頻繁切換。
用 Python 測量延遲並切換策略組
以下腳本會讀取指定策略組的成員,逐一呼叫延遲 API,挑選可用節點,並在必要時以 PUT /proxies/{策略組名稱} 切換目前選擇。請先依實際設定修改 GROUP_NAME 與 TEST_URL。程式只處理包含成員清單的選擇型組別,並對 API 請求最多重試一次;如果所有候選節點都測試失敗,會保留原選擇,不會盲目切換。
import json
import os
import time
import urllib.error
import urllib.parse
import urllib.request
API = os.environ.get("CLASH_API", "http://127.0.0.1:9090").rstrip("/")
SECRET = os.environ["CLASH_SECRET"]
GROUP_NAME = "節點選擇"
TEST_URL = "https://www.gstatic.com/generate_204"
TIMEOUT_MS = 5000
IMPROVEMENT_RATIO = 0.80
SKIP_NAMES = {"DIRECT", "REJECT", "PASS", "COMPATIBLE"}
def request_api(path, method="GET", payload=None):
url = API + path
data = None if payload is None else json.dumps(payload).encode("utf-8")
headers = {"Authorization": "Bearer " + SECRET}
if data is not None:
headers["Content-Type"] = "application/json"
req = urllib.request.Request(url, data=data, headers=headers, method=method)
for attempt in range(2):
try:
with urllib.request.urlopen(req, timeout=8) as response:
body = response.read()
return json.loads(body) if body else {}
except (urllib.error.URLError, TimeoutError) as exc:
if attempt == 1:
raise RuntimeError(f"API 請求失敗:{exc}") from exc
time.sleep(1)
def encoded_name(name):
return urllib.parse.quote(name, safe="")
def check_delay(name):
query = urllib.parse.urlencode({
"url": TEST_URL,
"timeout": str(TIMEOUT_MS),
})
path = f"/proxies/{encoded_name(name)}/delay?{query}"
try:
result = request_api(path)
delay = int(result["delay"])
return delay if delay > 0 else None
except (RuntimeError, KeyError, TypeError, ValueError):
return None
def main():
data = request_api("/proxies")
proxies = data.get("proxies", {})
group = proxies.get(GROUP_NAME)
if not group:
raise RuntimeError(f"找不到策略組:{GROUP_NAME}")
if group.get("type") != "Selector":
raise RuntimeError(
f"{GROUP_NAME} 不是 Selector;目前型別為 {group.get('type')}"
)
current = group.get("now")
candidates = []
for name in group.get("all", []):
item = proxies.get(name, {})
if name in SKIP_NAMES or item.get("all"):
continue
candidates.append(name)
if not candidates:
raise RuntimeError("策略組中沒有可測試的節點")
results = []
for name in candidates:
delay = check_delay(name)
if delay is not None:
results.append((delay, name))
print(f"可用 {name}: {delay} ms")
else:
print(f"失敗 {name}")
if not results:
print("所有候選節點均測試失敗;保留目前選擇。")
return
results.sort()
best_delay, best_name = results[0]
current_delay = next(
(delay for delay, name in results if name == current), None
)
should_switch = current not in candidates or current_delay is None
if current_delay is not None and best_name != current:
should_switch = best_delay < current_delay * IMPROVEMENT_RATIO
if not should_switch or best_name == current:
print(f"維持目前節點:{current},最佳測得 {best_delay} ms")
return
request_api(
f"/proxies/{encoded_name(GROUP_NAME)}",
method="PUT",
payload={"name": best_name},
)
print(f"已切換:{current} -> {best_name}({best_delay} ms)")
if __name__ == "__main__":
main()
程式中的 IMPROVEMENT_RATIO = 0.80 表示:目前節點可用時,新節點必須低於目前延遲的 80% 才切換;例如目前為 100 ms,新節點須低於 80 ms。若目前節點測試失敗,則會選取成功回應者中延遲最低的節點。這個比例不是固定最佳值,可依節點數量與延遲波動調整;若只想在目前節點故障時切換,可移除「較快才換」的判斷,並另外加入連續失敗次數門檻。
將程式存成 switch_node.py,先在終端機設定 CLASH_API 和 CLASH_SECRET,再執行 python3 switch_node.py;Windows 可使用 py switch_node.py。第一次建議在終端機前景執行,確認策略組名稱與節點名稱完全一致,並觀察腳本輸出的毫秒數及最後選擇。API 回應中的節點名稱含空格或特殊字元時,程式會先進行 URL 編碼。
安排重試、檢視日誌與限制自動化風險
手動測試正常後,才考慮以作業系統排程定期執行。排程間隔應配合使用情境,例如每 3 至 5 分鐘檢查一次,而不是短時間內反覆掃描所有節點。若節點很多,逐一測試會增加總執行時間;可以縮小候選清單,或依序分批檢查。不要未經測試就同時開啟大量延遲請求,否則可能增加本機負載,也可能觸發測試站點的限制。
除了腳本的一次重試,還可加入「連續兩次失敗才判定故障」的保護:保存每個節點的失敗計數,成功時歸零,達到門檻後才切換。切換後再查詢 /proxies 確認 now 已更新;如果 PUT 回應成功但用戶端介面仍顯示舊節點,先確認腳本呼叫的 API 是否屬於目前正在執行的核心,而非另一個同時運作的 Clash 執行個體。
- 401 或 403:檢查
CLASH_SECRET是否與目前生效設定相符,以及請求是否使用Authorization: Bearer標頭。 - 404:檢查 API 路徑、策略組名稱與 URL 編碼;策略組名稱須逐字符合
/proxies回傳內容。 - 連線逾時或拒絕:確認核心已啟動、控制器監聽位址與連接埠正確,且沒有把代理連接埠誤當控制器連接埠。
- 某些節點沒有延遲值:確認核心可取得測試網址、該節點已加入策略組,並用較長的測試逾時重新驗證。
- 切換後流量仍不通:檢查規則是否確實指向該策略組,並在連線記錄中確認實際命中的規則與出口。
日誌可協助區分「API 呼叫失敗」、「節點測試失敗」與「切換成功但目標網站仍不可用」。排查時暫時保留腳本的節點與延遲輸出,並查看 Mihomo 的核心日誌或用戶端連線頁面;確認問題後,應避免長期輸出密鑰、完整訂閱內容或含敏感資訊的控制器請求。若腳本由排程器執行,使用權限受限的帳戶與僅本機可讀的環境設定檔,並限制日誌保留量。
最後,自動選路不等同於保證連線品質。延遲檢查只是一個健康訊號,無法涵蓋封包遺失、頻寬、特定服務可達性或長時間連線穩定度。對日常使用而言,保留手動選擇與可回退的備用節點,並讓切換條件可觀察、可調整,通常比毫秒數稍低但不穩定的頻繁跳線更可靠。