Clash API 自動換線實戰：節點健康檢查與腳本管理

為什麼要用 Clash API 自動換線

節點的「可用」與「好用」其實是兩個不同概念。某個代理可能仍然能完成 TCP 連線，但延遲已經高到不適合即時通訊；另一個節點雖然測速結果漂亮，卻在連續請求時頻繁重置連線。若每天只靠 Clash Verge Rev、Clash for Windows 或 Mihomo Party 的介面手動點選節點，你通常只能在問題發生後被動處理，無法把「檢查、判斷、切換、記錄」串成一個穩定流程。

Clash API提供了一個可由腳本呼叫的控制入口，能讀取目前代理群組、查詢節點延遲、切換策略組成員，部分 Mihomo 核心還能取得連線與健康檢查相關資訊。這代表你可以把換線邏輯從「看到卡頓就手動點一下」改成「每隔一段時間檢查候選節點，只有符合條件才切換」。對於長時間運作的下載工具、遠端終端、影音播放或需要持續連線的工作流，這種差異非常實際。

不過，自動換線不等於每次都追求最低延遲。若腳本只看一次測速結果，可能把正在短暫抖動的節點誤判成最佳選擇，接著在幾分鐘內反覆切換，造成連線重建、登入狀態遺失，甚至讓服務端把請求視為異常。較可靠的設計應同時考慮延遲、成功率、連續失敗次數、冷卻時間與目前使用中的節點，讓「穩定」優先於一個孤立的毫秒數。

啟用 API 前的安全與配置準備

在開始寫 Python 之前，先確認目前客戶端使用的是哪一個核心，以及 API 的監聽位址與控制密鑰。不同版本的 Clash、Clash Verge Rev 與 Mihomo 在介面名稱上可能略有差異，但核心概念一致：API 通常監聽在本機位址，例如 127.0.0.1:9090，而控制密鑰會透過 secret 或類似欄位保護管理操作。請優先把 API 綁定在 localhost，不要為了方便直接監聽所有網路介面；否則同一區域網路內的其他裝置可能嘗試讀取節點資訊或改動代理群組。

建議先建立一個專用策略組，例如 AUTO-SWITCH，並確認其中的節點名稱與設定檔內的 proxies 完全一致。節點名稱可能包含空格、括號、旗幟 emoji 或供應商標記，腳本不要自行猜測名稱，也不要只依靠「第一個節點」「第二個節點」這種位置概念。比較穩定的做法是從 API 讀取策略組成員，依照明確的排除規則過濾後再產生候選清單。這樣即使訂閱更新後節點順序改變，腳本仍能正常運作。

# 只作為格式示意，請依你的核心與客戶端設定調整
mixed-port: 7890
external-controller: 127.0.0.1:9090
secret: change-this-to-a-long-random-value

proxy-groups:
  - name: AUTO-SWITCH
    type: select
    proxies:
      - node-a
      - node-b
      - DIRECT

secret不要直接寫死在公開的 Git 儲存庫、同步筆記或螢幕截圖中。若腳本會放在多人共用的主機，應使用環境變數、作業系統的秘密儲存區，或至少使用權限受限的設定檔。API 回應中可能包含代理名稱、位址、延遲與目前策略狀態，這些資訊未必等同密碼，但仍然不適合無限制寫入公開日誌。完成設定後，先用瀏覽器或 curl 測試讀取介面，確認只有本機可以存取，再進一步測試切換操作。

curl -H "Authorization: Bearer change-this-to-a-long-random-value" \
  http://127.0.0.1:9090/proxies

用 Python 實作延遲、成功率與冷卻機制

健康檢查腳本可以拆成四個步驟。第一步是取得策略組與候選節點；第二步是對候選節點執行延遲測試；第三步是按照門檻與排序結果選出目標；第四步是確認新節點與目前節點不同，且沒有處於冷卻期間，才呼叫 API 切換。這個拆分很重要，因為它讓你可以單獨測試每一層：API 讀取失敗時不用懷疑排序邏輯，延遲全部超標時也不會誤以為切換 API 壞掉。

Mihomo 常見的代理延遲測試介面會以策略組名稱或代理名稱作為路徑參數，測試 URL 則由腳本指定。不同核心版本與客戶端包裝可能存在端點差異，因此不要盲目複製一段網路上宣稱「所有 Clash 都通用」的程式碼。先從開發者工具、核心文件或現有客戶端請求確認實際端點，再把它固定在自己的腳本中。測試網址應選擇回應內容簡單、穩定且符合你實際用途的 HTTPS 端點；不要把大型網頁、串流檔案或需要登入的頁面當成健康檢查目標。

延遲排序也不應只使用「最小值」。更實用的方式是對每個節點測試兩到三次，忽略一次明顯超時的極端值，然後使用中位數或平均值。若某節點有一次成功、兩次失敗，即使那一次只用了二十毫秒，也不應該排在穩定完成三次測試的節點前面。你可以設定三個門檻：單次請求逾時秒數、允許的最大延遲，以及最低成功次數。只要候選清單中沒有節點符合條件，腳本就應保持目前選擇，不要為了「完成自動化」而強行切到品質未知的節點。

import os
import statistics
import time
import requests

API = "http://127.0.0.1:9090"
TOKEN = os.environ["CLASH_API_TOKEN"]
GROUP = "AUTO-SWITCH"
TEST_URL = "https://www.gstatic.com/generate_204"

HEADERS = {"Authorization": f"Bearer {TOKEN}"}

def get_proxies():
    response = requests.get(f"{API}/proxies", headers=HEADERS, timeout=5)
    response.raise_for_status()
    return response.json()["proxies"]

def test_proxy(name):
    values = []
    for _ in range(3):
        try:
            response = requests.get(
                f"{API}/proxies/{name}",
                params={"url": TEST_URL, "timeout": 5000},
                headers=HEADERS,
                timeout=7,
            )
            response.raise_for_status()
            delay = response.json().get("delay")
            if isinstance(delay, int):
                values.append(delay)
        except requests.RequestException:
            pass
    return statistics.median(values) if values else None

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

上面的程式只是結構示意，真正使用時還要補上節點排除、目前節點讀取、錯誤記錄與切換冷卻。特別要注意節點名稱必須經過 URL 編碼，因為名稱中的空格、斜線或特殊符號可能造成請求路徑解析錯誤。若你不想自行處理 URL 編碼，可以交給 requests 的參數機制，或先確認核心提供的端點是否能接受安全編碼後的名稱。

避免頻繁切換與錯誤判斷

最常見的自動換線問題叫作「抖動」：腳本在 A 與 B 之間不斷來回，因為兩者的延遲差距只有幾毫秒。解決方法是加入切換裕度，例如只有當新節點比目前節點快至少三十毫秒，或目前節點連續失敗兩輪時才切換。除此之外，每次切換後設定五至十五分鐘的冷卻時間，期間只在連續健康檢查失敗時提前解除。這樣可以避免一次短暫網路擁塞就重建所有正在進行的連線。

還可以為節點建立簡單的信譽分數。成功完成測試加分，逾時扣分，連續失敗則大幅扣分；分數低於門檻的節點暫時移出候選清單，隔一段時間再重新測試。這比永久封鎖更適合機場訂閱環境，因為節點可能只是暫時維護，而不是永久失效。腳本也應保留最近幾次結果，讓你能回答「為什麼今天切到這個節點」而不是只能猜測。

排程執行、日誌管理與故障排查

腳本穩定後，再使用作業系統排程工具定期執行。Linux 或 macOS 可以使用 cron、systemd timer 或 launchd；Windows 則可使用工作排程器。建議先用每十五分鐘一次的低頻率測試，確認 API、權限、日誌與切換行為都正常，再依實際需求調整。影音播放或互動工作不一定需要每分鐘測試；頻率過高只會增加健康檢查流量，也可能讓服務端或代理提供者把這些請求視為異常探測。

排程環境與互動式終端的環境變數通常不同，這是「手動執行成功、排程卻失敗」的主要原因之一。請在排程設定中明確指定工作目錄、Python 執行檔的完整路徑，以及 CLASH_API_TOKEN 的來源。不要依賴目前使用者的 shell 設定或圖形介面啟動順序。若客戶端尚未啟動，腳本應記錄「API 無法連線」後正常結束，下一輪再試，而不是持續重試幾百次把 CPU 和日誌塞滿。

日誌至少應包括執行時間、策略組名稱、候選節點數量、每個節點的成功次數與延遲、目前節點、選定節點、切換原因，以及 API 錯誤類型。不要在日誌中寫入完整 Token，也不要把所有回應內容原封不動保存；只保留排查所需的狀態欄位即可。當你發現「測速很快但實際很慢」時，先比較測試 URL 與實際服務是否屬於同一地區或同一類型流量，再檢查規則命中與 DNS 行為。健康檢查只能代表某條測試請求的結果，不能保證所有網域都會經過相同路由。

• API 回傳四〇一或四〇三：先檢查 Token、標頭格式與目前核心是否啟用驗證。
• API 回傳四〇四：確認端點屬於你的核心版本，不要直接套用其他客戶端的路徑。
• 切換回傳成功但流量未變：檢查實際流量是否使用同一個策略組，以及規則是否指向其他組。
• 延遲全部為空：確認測試 URL 可用、DNS 能解析，並檢查節點名稱是否經過正確編碼。
• 節點不停來回切換：提高切換裕度、增加冷卻時間，並改用中位數而非單次最低值。

最後，請為設定檔與腳本保留版本管理。每次修改候選節點、測試網址、延遲門檻或策略組名稱，都記錄原因與日期；訂閱更新後也要重新確認組名沒有被覆蓋。若自動換線在某次更新後突然失效，先回看最近一次變更，再用手動 API 請求驗證，不要立刻刪掉整個腳本重寫。對於重要工作流，可以讓腳本先輸出「建議切換」而不立即執行，觀察一兩天的結果後再開啟自動切換，這是降低誤切風險的實用過渡方案。

相較於只靠 Clash for Windows 舊式介面手動選節點，或只使用沒有自訂門檻的簡單自動選擇功能，API 腳本能保留測試紀錄、加入成功率與冷卻邏輯，也更容易配合 Linux、macOS 和 Windows 的排程工具；但自行拼接請求的腳本若缺少權限保護、錯誤處理與回滾機制，同樣可能比手動操作更難維護。Clash V.CORE 將核心控制、策略組管理與跨平台使用體驗集中在較一致的工作流程中，適合把本文的健康檢查思路落實到日常環境；如果你希望少處理客戶端差異與設定細節，可以先前往下載頁，選擇符合平台的版本開始建立自己的自動換線方案。