為什麼要用 Clash API 自動挑選節點
手動在 Clash 介面裡切換節點,適合偶爾旅行或臨時測試;但當你每天都要連線到 AI 服務、程式碼平台、套件倉庫或遠端主機時,只看一次延遲數字往往不夠。節點可能在幾分鐘後丟包、TLS 握手逾時,或出口 IP 被目標服務暫時限制。更麻煩的是,單純使用介面上的「自動選擇」並不一定符合你的實際需求:最低延遲的節點未必最穩定,測速網址可達也不代表 API、WebSocket 或長連線能正常工作。
Clash 的外部控制器(External Controller)提供了一組 HTTP API,讓腳本可以讀取目前的代理群組、取得節點清單、測試延遲,並透過 API 將指定節點切換到策略組。配合 Mihomo 支援的 url-test、fallback 與健康檢查機制,你可以建立一套「先篩選可用節點,再依延遲選擇,最後保留人工覆寫」的流程。這比單純按照節點名稱排序更可靠,也比較容易在不同電腦、不同訂閱與不同使用情境中重複執行。
本文以 Clash Verge Rev 或其他使用 Mihomo 核心的客戶端為例,示範如何安全開啟控制器、理解常用 API、撰寫可重複執行的腳本,以及如何避免自動切換反而造成 AI 對話中斷、SSH 連線斷線或登入工作階段失效。文中的測試網址、策略組名稱與節點名稱都只是範例,請依你的配置實際替換。
secret,不要把控制器埠直接暴露到公網,也不要將含有密鑰的腳本提交到公開儲存庫。
啟用外部控制器與認識核心 API
在 Mihomo 配置中,外部控制器通常使用 external-controller 指定監聽位址與埠號,並使用 secret 保護 API。若只打算讓本機腳本使用,推薦綁定 127.0.0.1,不要直接寫成所有介面都能監聽的 0.0.0.0。基本配置可以是:
external-controller: 127.0.0.1:9090
secret: "請替換成隨機且足夠長的密鑰"
修改後請重新載入配置或重啟核心,然後用瀏覽器或 curl 測試控制器是否可用。帶有驗證的請求需要在 HTTP 標頭中加入 Authorization: Bearer:
curl -H "Authorization: Bearer YOUR_SECRET" \
http://127.0.0.1:9090/version
若回傳核心版本資訊,代表控制器已正常工作。常用端點可以分成幾類。GET /proxies 用來取得所有代理與策略組;GET /proxies/{name} 可查詢某個策略組目前選中的節點;GET /proxies/{name}/delay 用來測試指定代理的延遲;對策略組發送 PUT /proxies/{name},則可以切換目前選中的代理。
策略組名稱若含有空格、斜線或特殊字元,必須先進行 URL 編碼,不能直接把原始名稱拼在網址後面。實務上建議先呼叫 /proxies,從 JSON 回應中確認實際名稱,再由程式使用 URL 編碼處理。這一步很重要,因為訂閱更新後策略組可能從「Proxy」變成「🚀 節點選擇」,腳本若寫死錯誤名稱,就會在執行時得到 404。
GET /version、GET /proxies 和一次單節點延遲測試確認控制器可用。若 API 本身回應逾時,先排查控制器位址、核心狀態、防火牆與密鑰,不要急著修改節點規則。
自動挑選的判斷邏輯:可用性比最低延遲重要
一套穩定的自動選線流程,不應只做「找最小數字」這一件事。比較實用的順序是:先排除明顯不可用的節點,再測試剩餘節點的延遲,最後依照使用情境選擇固定節點或交給策略組。若一個節點回報 80 毫秒,但連續測試三次有兩次逾時,它就不應該勝過穩定回報 120 毫秒的節點。
- 第一層是名稱過濾:排除過期、剩餘流量不足、明確標示維護中的節點,也可以依地區或協定建立白名單。不要只用關鍵字「高速」判斷,節點名稱是訂閱服務商提供的文字,不一定代表真實品質。
- 第二層是延遲測試:選擇一個穩定、回應內容簡單的 HTTPS 測試網址。測試網址應與你的實際流量類型接近;如果主要使用程式碼平台,不要只用一般入口頁作為唯一依據。
- 第三層是逾時與重試:對每個候選節點設定合理的 timeout,例如 3000 至 5000 毫秒。一次失敗不必立刻永久淘汰,可以進行兩次測試並記錄成功率。
- 第四層是用途分組:AI API、程式碼平台、影音與一般瀏覽不一定要共用同一個策略組。長連線應優先選擇低抖動、低丟包的節點,而不是只追求瞬間最低延遲。
- 第五層是冷卻時間:不要每隔幾十秒就重新切換。頻繁切換會讓瀏覽器登入、WebSocket、下載工作階段與 SSH 連線一起中斷,甚至比節點本身不穩更難排查。
在配置層面,可以先讓 Mihomo 自己處理一般健康檢查,再由腳本負責較複雜的條件。例如,url-test 適合週期性找低延遲節點,fallback 適合按照可用性維持主備順序;腳本則適合加入「連續失敗才切換」「避開特定地區」「只在工作時間切換」等業務邏輯。多層機制不要互相搶控制權:如果策略組正在自動測試,外部腳本又每分鐘強制寫入節點,最後看到的結果可能只是兩套決策不停互相覆蓋。
此外,延遲 API 測出的通常是一次 HTTP 請求的耗時,不等同於完整頁面載入時間,也不等同於長連線品質。若你要服務 AI 對話或遠端開發,建議把「連續成功率」「TLS 握手時間」「長時間連線是否中斷」加入人工驗收。對節點做選擇時,穩定性、出口位置與服務相容性通常比少幾十毫秒更值得優先考慮。
動手實作:用 Python 透過 API 自動切換節點
以下範例使用 Python 標準函式庫,避免額外安裝套件。它會先讀取策略組,篩選名稱符合條件的節點,逐一呼叫延遲 API,忽略逾時節點,最後將成功率較高且延遲最低的節點切換進目標策略組。你可以先在測試用策略組執行,確認行為正確後再套用到日常使用的策略組。
import json
import os
import time
import urllib.error
import urllib.parse
import urllib.request
CONTROLLER = os.getenv("CLASH_CONTROLLER", "http://127.0.0.1:9090")
SECRET = os.environ["CLASH_SECRET"]
GROUP = os.getenv("CLASH_GROUP", "Proxy")
TEST_URL = os.getenv("CLASH_TEST_URL", "https://www.gstatic.com/generate_204")
TIMEOUT_MS = 4500
headers = {
"Authorization": f"Bearer {SECRET}",
"Content-Type": "application/json",
}
def request(path, method="GET", body=None):
data = None
if body is not None:
data = json.dumps(body).encode("utf-8")
req = urllib.request.Request(
CONTROLLER + path,
data=data,
headers=headers,
method=method,
)
with urllib.request.urlopen(req, timeout=8) as response:
return json.loads(response.read().decode("utf-8"))
def measure(proxy_name):
group = urllib.parse.quote(proxy_name, safe="")
query = urllib.parse.urlencode({
"url": TEST_URL,
"timeout": TIMEOUT_MS,
"extra": "false",
})
try:
result = request(f"/proxies/{group}/delay?{query}")
return int(result["delay"])
except (KeyError, ValueError, urllib.error.URLError, TimeoutError):
return None
data = request("/proxies")
group_info = data["proxies"][GROUP]
candidates = [
name for name in group_info.get("all", [])
if name not in {"DIRECT", "REJECT"}
and "故障" not in name
and "維護" not in name
]
results = []
for name in candidates:
delay = measure(name)
if delay is not None:
results.append((delay, name))
time.sleep(0.2)
if not results:
raise SystemExit("沒有可用節點,保留目前選線")
results.sort(key=lambda item: item[0])
best_delay, best_name = results[0]
group_path = urllib.parse.quote(GROUP, safe="")
request(f"/proxies/{group_path}", method="PUT", body={"name": best_name})
print(f"已切換至 {best_name},測得延遲 {best_delay} ms")
執行前不要把密鑰直接寫入程式檔案。可以在終端機暫時設定環境變數,或使用作業系統的密鑰管理工具:
export CLASH_SECRET='your-secret'
export CLASH_GROUP='Proxy'
python3 auto_switch.py
這個範例刻意保持簡單,方便你看懂每個 API 呼叫的作用。正式使用時可以再加入兩項保護。第一,切換前先呼叫 GET /proxies/{group},若目前節點仍在冷卻時間內,就先不切換。第二,要求新節點連續兩次測試都成功,並與目前節點比較,例如只有當新節點快 20% 或目前節點連續失敗,才進行切換。這能避免測速誤差造成頻繁跳線。
如果你希望同時驗證可用性與實際服務,還可以把測試分成兩層:先用一般 HTTPS URL 篩掉完全不可用的節點,再針對 AI 或程式碼平台所需的網域進行一次小型請求。請注意不要在腳本中放入服務金鑰、私有程式碼或敏感資料;健康檢查應盡量使用公開、不會產生費用的端點。
排錯、日誌與長期維護
腳本回報成功,不代表應用程式一定使用了剛切換的節點。首先要在 Clash Verge Rev 的連線紀錄裡確認實際命中的策略組與代理名稱,接著再用瀏覽器、終端機或目標應用程式做一次真實測試。若瀏覽器已切換但 CLI 沒有變化,可能是 CLI 沒有讀取系統代理;此時需要確認 HTTP_PROXY、HTTPS_PROXY 或 SOCKS5 設定,必要時才考慮 TUN 模式。
常見的 404 通常表示策略組名稱或節點名稱不正確,特別是訂閱更新後名稱發生變化;401 多半是密鑰遺漏或錯誤;400 則可能是請求格式不符合核心版本要求。若延遲測試全部逾時,先檢查測試網址是否能從目前網路環境存取,再確認節點本身,而不是立刻判定整份訂閱失效。
- 把每次執行時間、候選節點數量、成功數量、選中節點與測得延遲寫入日誌。
- 保留目前節點與上一次節點,避免腳本在兩個節點之間來回震盪。
- 訂閱更新後重新讀取策略組,不要假設節點清單永遠固定。
- 使用最小權限思維,讓腳本只在本機執行,並限制檔案權限,避免密鑰被其他帳號讀取。
- 排程執行時加入鎖定機制,避免兩個相同腳本同時修改同一策略組。
對需要穩定工作的使用者來說,最好的自動化通常不是「每次都換到看起來最快的節點」,而是「只有在足夠證據顯示目前節點不適合時才切換」。例如辦公時間固定使用已驗證的節點,夜間再執行完整測試;或為 AI、Git、遠端主機建立不同策略組,讓每種流量按照自己的穩定性需求選線。這樣既能降低維護成本,也能避免自動化干擾正在進行的工作。
常見問題
只使用 url-test,還需要自己寫 API 腳本嗎?
不一定。若你的需求只是按照固定測試網址週期性選擇低延遲節點,url-test 已經足夠,而且由核心管理通常更穩定。腳本的價值在於補充核心策略組難以表達的條件,例如名稱過濾、連續失敗判斷、不同工作時段使用不同節點,或在切換前留下可追蹤的日誌。兩者可以並存,但要明確決定誰負責最後的切換,避免互相覆蓋。
延遲最低的節點就是最適合的節點嗎?
不是。延遲只反映特定時間、特定測試網址的一次結果,不能代表丟包率、下載速度、出口相容性或長連線穩定度。對 AI API、Git 推送與 SSH 等用途,建議同時觀察連續成功率、尖峰時段表現與實際應用日誌。若最低延遲節點經常逾時,應選擇延遲稍高但穩定的節點。
可以把 external-controller 設定成 0.0.0.0 方便手機控制嗎?
除非你非常清楚防火牆、路由器與認證設定,否則不建議。控制器可以讀取節點資訊,也能直接修改目前選線,暴露後可能成為高風險管理入口。較安全的做法是維持本機監聽,或透過受驗證的 SSH 隧道、VPN 與嚴格的內網防火牆存取;無論如何都應設定強密鑰,並避免在日誌或截圖中洩漏。
腳本切換成功,但某個程式仍然沒有走代理,原因是什麼?
API 切換的是 Clash 策略組,不會自動讓所有程式使用代理。瀏覽器可能讀取系統 Proxy,但部分 CLI、IDE 子行程或服務程序只會讀取自己的環境變數,甚至完全忽略 HTTP 代理。請先在連線紀錄確認該程式是否有請求進入 Clash;若沒有,再檢查應用程式代理設定、環境變數與是否需要 TUN 模式。不要只看策略組名稱就判定所有流量已經生效。
相比之下,部分同類代理工具在外部控制器、節點延遲測試與策略組切換之間缺少一致的 API,使用者往往只能手動點選,或另外拼接多套腳本,遇到訂閱更新與節點改名時很難排查。ClashSky 以較清楚的圖形介面呈現核心狀態、策略組與連線紀錄,搭配 Mihomo 控制器即可把本文的自動測試流程逐步接上,不必先維護一整套複雜面板。如果你想在保留人工覆寫的前提下嘗試自動挑選節點,歡迎前往下載 ClashSky,先從本機控制器與單一策略組開始驗證。