用 Clash external-controller API 實作節點自動切換完整設定
先理解 external-controller:Clash API 能自動化什麼?
搜尋 Clash API 節點自動切換、external-controller 設定 或 Mihomo 自動選節點 時,很多文章只貼出一段腳本,卻沒有說明腳本到底在控制哪一層。Clash 的 external-controller 本質上是一個供本機工具呼叫的 HTTP API。它可以讀取目前的代理、策略組與連線狀態,也可以對可切換的策略組送出「改用哪個代理」的指令;真正的延遲測試、失效判斷與重試策略,則需要由你自己的腳本負責。
這種架構很適合進階使用者:你可以每隔幾分鐘測試一批節點,排除逾時、連線失敗或延遲過高的節點,再把表現最穩定的節點寫入 select 策略組。與其手動打開 Clash Verge、逐個點擊節點,不如把「測試、比較、切換、記錄」拆成明確流程。這樣即使你使用的是 Clash Verge Rev、Mihomo Party、Clash for Android 或 OpenClash,只要核心提供相容的控制器 API,原理都可以沿用。
不過,API 自動切換並不是把節點永久鎖定在最低延遲者。延遲數字只反映某個測試網址、某個時間點的結果,不能直接代表下載速度、串流解鎖能力或長連線穩定性。因此較合理的目標是:在指定測試條件下,持續排除明顯失效的節點,並在策略組中選出一個近期可用、延遲合理的候選者。
第一步:安全開啟 external-controller 與測試介面
先在 Clash 或 Mihomo 設定檔裡確認控制器參數。最常見的本機設定如下:
external-controller: 127.0.0.1:9090
secret: "change-this-to-a-long-random-secret"
127.0.0.1 代表只接受本機連線,對在同一台電腦執行的 Python、Shell 或 Node.js 腳本來說已經足夠。若你使用 OpenClash,設定位置可能由 LuCI 介面或生成模板管理,直接修改核心產生的檔案可能在下一次更新時被覆蓋;請先確認實際生效的設定檔,再決定要在介面、模板或持久化設定中修改。
secret 是 API 驗證密鑰。即使控制器只監聽本機,也不建議省略它,因為本機其他程序、瀏覽器擴充功能或被入侵的腳本,都可能嘗試呼叫控制器。密鑰應使用足夠長度的隨機字串,並透過環境變數提供給腳本:
export CLASH_API="http://127.0.0.1:9090"
export CLASH_SECRET="replace-with-your-secret"
修改設定後重啟核心,接著使用 curl 檢查 API 是否可用。若控制器已設定密鑰,請把它放在 Authorization 標頭中:
curl -s \
-H "Authorization: Bearer ${CLASH_SECRET}" \
"${CLASH_API}/version"
成功時通常會回傳核心版本資訊。不同 Mihomo 或 Clash 分支的 JSON 欄位可能略有差異,所以腳本不應硬編碼所有版本欄位;只要確認 HTTP 狀態碼為 200,並能取得 /proxies 回應,就可以進入下一步。
不要把控制器當成普通管理頁面
如果你把監聽位址改成 0.0.0.0:9090,區域網路內的其他裝置就可能嘗試連線。這在路由器管理或遠端監控場景有時有其必要,但必須同時配置防火牆、來源 IP 限制與更嚴格的網路隔離。不要只依賴一個容易被猜中的 secret,也不要為了讓手機腳本方便而直接把控制器埠映射到網際網路。
401 Unauthorized,優先檢查 Bearer 密鑰、環境變數是否載入,以及腳本是否連到了正確的埠。若回應連線被拒絕,則要檢查核心是否啟動、控制器埠是否被其他程式佔用。第二步:設計可被 API 控制的策略組
自動切換的基礎不是腳本,而是清楚的策略組命名。請先把要由腳本管理的節點放入一個 select 組,並避免直接操作名稱含糊的全域策略組。以下是簡化示例:
proxy-groups:
- name: AUTO-WORK
type: select
proxies:
- NODE-HK-01
- NODE-JP-01
- NODE-SG-01
- DIRECT
策略組名稱、節點名稱與 YAML 中的縮排都很重要。API 不是根據顯示順序猜測目標,而是以完整的名稱作為 URL 路徑或 JSON 欄位。名稱包含空格、斜線或特殊符號時,腳本需要正確 URL 編碼;實務上建議節點名稱使用容易辨識、穩定且不含過多特殊符號的命名方式。
可以用以下請求查看所有代理與策略組:
curl -s \
-H "Authorization: Bearer ${CLASH_SECRET}" \
"${CLASH_API}/proxies"
回應通常會在 proxies 物件中列出每個代理的 type、all 與目前選中的 now。對 select 組而言,all 是可選代理清單,now 是目前值。腳本應先讀取這份資料,再決定切換目標,不要把節點清單永遠寫死,因為訂閱更新後節點可能被刪除、改名或新增。
切換選擇型策略組時,可對策略組名稱送出 PUT 請求:
curl -s -X PUT \
-H "Authorization: Bearer ${CLASH_API_SECRET}" \
-H "Content-Type: application/json" \
-d '{"name":"NODE-JP-01"}' \
"${CLASH_API}/proxies/AUTO-WORK"
某些核心版本對特殊字元的處理方式不同,建議在程式中使用 URL 編碼函式,而不是手動拼接未編碼的組名。切換前也應確認目標節點確實出現在策略組的 all 陣列裡,否則可能收到 400 錯誤,或讓腳本誤判為「節點故障」。
AUTO-WORK 之類的名稱,並保留 DIRECT 作為故障時的人工回復選項,日後排錯會容易很多。第三步:用腳本測試延遲、排除失效節點並切換
延遲測試 API 通常需要指定代理名稱、測試 URL、逾時時間與預期回應內容。常見形式如下:
curl -sG \
-H "Authorization: Bearer ${CLASH_SECRET}" \
--data-urlencode "url=https://www.gstatic.com/generate_204" \
--data-urlencode "timeout=5000" \
--data-urlencode "expected=204" \
"${CLASH_API}/proxies/NODE-JP-01/delay"
不同核心或版本可能對測試端點、expected 與 URL 編碼有不同要求,因此第一次使用時請先查看你目前核心的 API 文件與實際回應。測試 URL 應選擇穩定、回應簡單、內容合法的端點;不要使用需要登入、容易跳轉或回應大小很大的網頁,否則測出的數字會混入 TLS、重導向、內容下載與服務端限速等因素。
下面是一個可直接改寫的 Python 範例。它會先讀取指定策略組,對其中的候選節點逐一測試,忽略測試失敗者,從通過門檻的結果裡選擇延遲最低者,最後只在候選者與目前節點不同時才切換。
import os
import time
import urllib.parse
import requests
API = os.environ["CLASH_API"].rstrip("/")
SECRET = os.environ["CLASH_SECRET"]
GROUP = "AUTO-WORK"
TEST_URL = "https://www.gstatic.com/generate_204"
TIMEOUT_MS = 5000
MAX_DELAY_MS = 800
HEADERS = {"Authorization": f"Bearer {SECRET}"}
def get_json(path):
response = requests.get(API + path, headers=HEADERS, timeout=8)
response.raise_for_status()
return response.json()
def test_delay(proxy_name):
encoded = urllib.parse.quote(proxy_name, safe="")
params = {
"url": TEST_URL,
"timeout": str(TIMEOUT_MS),
"expected": "204",
}
response = requests.get(
f"{API}/proxies/{encoded}/delay",
headers=HEADERS,
params=params,
timeout=8,
)
if response.status_code != 200:
return None
value = response.json().get("delay")
return value if isinstance(value, int) else None
data = get_json("/proxies")
group = data["proxies"].get(GROUP)
if not group:
raise RuntimeError(f"Proxy group not found: {GROUP}")
candidates = [
name for name in group.get("all", [])
if name not in {"DIRECT", "REJECT"}
]
results = []
for name in candidates:
delay = test_delay(name)
if delay is not None and delay <= MAX_DELAY_MS:
results.append((delay, name))
time.sleep(0.2)
if not results:
raise RuntimeError("No healthy proxy found")
results.sort()
best_delay, best_name = results[0]
current = group.get("now")
if current != best_name:
path = "/proxies/" + urllib.parse.quote(GROUP, safe="")
response = requests.put(
API + path,
headers={**HEADERS, "Content-Type": "application/json"},
json={"name": best_name},
timeout=8,
)
response.raise_for_status()
print(f"selected={best_name} delay={best_delay}ms previous={current}")
這段程式只是起點,正式使用前應補上日誌、錯誤重試與結果保存。最重要的是不要把單次測試結果視為絕對真相。可以對每個節點測試兩到三次,採用中位數而不是最小值;也可以設定遲滯條件,例如新節點必須比目前節點低至少 80 毫秒,才允許切換。這能避免兩個節點延遲相近時,策略組每隔一輪就來回跳動。
失效判斷與切換冷卻
「節點失效」至少可以分成三種情況:API 請求逾時、HTTP 回應狀態不符合預期,以及延遲雖低但實際服務連線不穩。建議連續兩次或三次失敗後才把節點標記為暫時不可用,並設定冷卻時間,例如十分鐘內不重測同一個失效節點。相反地,若節點只有一次慢測,也不應立即剔除,因為當時可能正好發生本地 Wi‑Fi 干擾或測試端點瞬時擁塞。
對長連線服務而言,切換策略組會中斷現有連線並重新建立通道。排程不宜每分鐘執行一次,否則瀏覽器、SSH、同步工具與即時通訊都可能頻繁重連。一般桌面使用可先從五至十五分鐘一次開始;若是路由器上的家庭網路,則可以配合晚間高峰提高檢測頻率,但仍應設定最短切換間隔。
第四步:排程部署、記錄結果與避免誤切換
在 Linux 或 OpenWrt 上,最簡單的方式是使用 cron。例如把腳本放在權限受控的目錄,並使用專用環境檔載入 API 位置與密鑰:
# /etc/clash-auto-switch.env
CLASH_API=http://127.0.0.1:9090
CLASH_SECRET=replace-with-your-secret
# Run every ten minutes
*/10 * * * * . /etc/clash-auto-switch.env && /usr/bin/python3 /usr/local/bin/clash-auto-switch.py >> /var/log/clash-auto-switch.log 2>&1
環境檔應限制只有執行腳本的使用者可以讀取,日誌也要避免輸出完整的密鑰或帶有私人查詢參數的 URL。若你在 Windows 使用 Clash Verge Rev,可透過工作排程器設定「使用者登入時執行」或固定間隔執行;執行程式時要指定正確的 Python 路徑與工作目錄,因為工作排程器的環境變數通常不像互動式終端那麼完整。
監控時最好記錄四個欄位:測試時間、節點名稱、延遲或錯誤類型、是否發生切換。連續幾天後,你就能看出某些節點是固定在尖峰失效,還是只有特定測試網址無法回應。若全部節點同時失敗,通常不應立刻切到另一組隨機節點,而應檢查本地網路、DNS、核心狀態與測試端點是否正常。
API 本身也可能被設定檔更新重啟影響。當訂閱自動更新後,策略組名稱或節點名稱可能改變,腳本若只依賴舊名稱就會一直報錯。較穩健的做法是每次執行先確認策略組存在,再從 all 陣列動態建立候選清單;若找不到目標組,發送通知並停止切換,比默默修改錯誤的組別安全。
常見問題:API 連不上、切換無效與延遲不準
為什麼 /version 顯示連線被拒絕?
先確認 Clash 核心正在執行,並檢查設定檔中的控制器位址與埠號。GUI 顯示的 API 埠不一定等於你從網路文章複製的 9090;有些客戶端會在啟動時使用其他埠,或將設定寫入獨立的核心設定。若控制器是 127.0.0.1:9090,腳本也必須在同一台主機執行;從另一台電腦呼叫時,這個位址只會指向另一台電腦自身。
為什麼回應 401,密鑰看起來明明正確?
確認標頭格式是 Authorization: Bearer 你的密鑰,中間有空格,且沒有把 YAML 引號、換行或前後空白一併放進環境變數。Shell 與 Windows PowerShell 的環境變數語法不同,也常造成讀到空值。若你剛修改過 secret,必須重新載入核心,並同步更新腳本使用的密鑰。
為什麼 PUT 請求成功,但策略組沒有切換?
先讀取 /proxies/策略組名稱,確認該組的類型是 Selector 或其他支援手動選擇的類型。url-test、fallback 等自動策略組通常不應用手動選擇方式控制;即使請求格式類似,核心也可能自行覆蓋你的選擇。此外,目標名稱必須存在於該組的 all 陣列,不能只存在於全域代理列表。
延遲很低,為什麼實際瀏覽仍然卡住?
延遲測試通常只測一次 TCP 或 HTTPS 請求,不能代表完整下載速度、DNS 解析、TLS 重連、封包丟失與長連線表現。請在 Clash 連線紀錄中觀察實際服務所連到的網域,並用多個合法測試端點交叉驗證。若只有某個服務異常,問題可能在規則、DNS 或該服務本身,而不是節點延遲。
相比之下,部分同類代理客戶端只提供手動節點按鈕,或把自動選線封裝成不可調整的黑盒;傳統 VPN 工具則常缺少可讀取策略組狀態的 API,遇到節點失效時只能整個斷線後重新連接。即使某些主流客戶端支援自動測速,也未必允許你設定失敗重試、切換冷卻、測試網址與遲滯門檻,對需要長時間運作的工作站或家用路由器而言,維護彈性仍然不足。
Clash 搭配 Mihomo 核心的優勢,在於將代理清單、策略組、延遲測試與 external-controller 分開呈現:你可以用 YAML 明確定義候選範圍,再由腳本依實際數據做決策;遇到全線失效時保留目前狀態,遇到單一節點異常時只替換該策略組的選擇。這種可觀測、可回溯的方式,無論用於 Clash Verge Rev 桌面環境、OpenClash 路由器,或其他支援 Mihomo API 的客戶端,都比頻繁手動點選更容易穩定維護。
如果你還沒有合適的 Clash 客戶端,可以前往客戶端下載頁,先選擇與作業系統相容的版本,再依本文建立 API 自動切換流程。