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 的核心日誌或用戶端連線頁面;確認問題後,應避免長期輸出密鑰、完整訂閱內容或含敏感資訊的控制器請求。若腳本由排程器執行,使用權限受限的帳戶與僅本機可讀的環境設定檔,並限制日誌保留量。

最後,自動選路不等同於保證連線品質。延遲檢查只是一個健康訊號,無法涵蓋封包遺失、頻寬、特定服務可達性或長時間連線穩定度。對日常使用而言,保留手動選擇與可回退的備用節點,並讓切換條件可觀察、可調整,通常比毫秒數稍低但不穩定的頻繁跳線更可靠。

下載Clash