Clash 控制器 API 防護設定與代理節點自動切換實作

Clash 控制器 API 是什麼?先看清它能做什麼

在 Clash API 節點切換的使用情境中,「控制器 API」通常是指 Mihomo(常稱 Clash Meta)提供的 HTTP 管理介面。它能讓相容的桌面面板、維運腳本或本機工具讀取目前代理狀態、檢視策略組,也能替 select 群組指定節點。這代表你可以把切換節點整合進排程、監控或自己的操作流程,不必每次都手動打開客戶端逐層尋找。

但 API 不是只有「方便」這一面。只要有人能連到控制器並取得有效權限,就可能讀取設定狀態或更改代理群組選擇;若監聽介面暴露在區域網路甚至公網,風險會遠高於一般客戶端設定。尤其是把控制器位址、密鑰直接寫進可分享的腳本、公開儲存庫或工作日誌,可能讓原本只供本機維運的功能變成未授權的遠端操作入口。

因此,合理的順序應該是先縮小可連線範圍、設定足夠強度的密鑰,再測試 API 操作,最後才加入自動切換。以下範例以 Mihomo 常見設定為基礎;不同 Clash 分支、核心版本與 GUI 對欄位或操作頁面的呈現可能不同,請先確認目前使用的核心確實支援相關 API。

先保護控制器:限制監聽範圍並設定密鑰

控制器相關設定通常寫在設定檔的頂層,而不是放進 proxy-groups 或 rules 區塊。最保守的做法是只監聽本機迴圈位址,讓同一台電腦上的腳本可以連線,但區域網路中的其他裝置不能直接連進來。設定密鑰則可避免只因服務端口可達,就讓任何本機程序或同網段使用者都能呼叫管理介面。

# Bind the controller to localhost only.
external-controller: 127.0.0.1:9090
secret: "REPLACE_WITH_A_LONG_RANDOM_SECRET"

請將範例密鑰替換成自行產生的隨機字串,不要照抄示例,也不要使用帳號名稱、生日或容易猜中的短字詞。若 GUI 會自動產生或管理控制器密鑰,先確認它實際寫入核心的值;不要只看介面上某個開關已開啟,就假設 API 已完成驗證。修改 YAML 後,使用客戶端的設定檢查或核心日誌確認解析成功,再重新載入設定。

不要為了讓手機或另一台電腦方便操作,就直接把監聽位址改成 0.0.0.0 並暴露控制器端口。這會讓所有可到達該端口的裝置都有機會嘗試連線;密鑰是必要防線,卻不代表可以省略網路存取限制。

如果確實需要從其他裝置管理,應先確認網路邊界、作業系統防火牆與路由器規則,只允許指定管理端連線;更穩妥的方式是透過受控的 VPN 或其他經過驗證的管理通道,而不是把控制器直接發布到網際網路。若以反向代理提供入口,還要妥善處理 TLS、認證、來源限制與請求轉送,避免代理層意外移除認證標頭或讓未授權來源繞過限制。

external-ui 是控制器可搭配使用的網頁介面設定,不等同於存取控制,也不能取代 external-controller 的監聽範圍限制與 secret 驗證。請分別檢查管理介面資源與 API 的網路暴露情況。

設計可切換的策略組:先確認 API 要操作誰

API 不能憑空建立一個能切換節點的群組;它操作的是目前設定中已存在的代理或策略組。若要讓腳本挑選節點,通常會準備一個 select 群組,並將可用節點名稱列入其中。群組名稱、節點名稱都必須與核心實際載入的設定一致,大小寫、空格與標點不同,都可能造成查詢或切換失敗。

proxy-groups:
  - name: "AUTO-MANUAL"
    type: select
    proxies:
      - "NODE-A"
      - "NODE-B"
      - DIRECT

  - name: "AUTO-TEST"
    type: url-test
    url: https://www.gstatic.com/generate_204
    interval: 300
    tolerance: 50
    proxies:
      - "NODE-A"
      - "NODE-B"

select 適合由使用者或外部腳本明確指定目前使用的節點;url-test 則會依設定的測試目標與週期評估候選節點,適合希望核心自行選擇的情況。兩者解決的問題不同:前者提供可控的手動選擇入口,後者提供群組內的自動測試與選擇。若你只需要固定週期挑選可用線路,直接使用 url-test 往往比自己寫一套外部輪詢更簡單,也較少遇到狀態不同步。

在採用 API 腳本前,建議先從客戶端介面確認群組確實存在,且群組裡顯示的節點名稱與 YAML 相符。接著查看核心的代理列表或控制器文件,確認目前版本採用的 API 路徑、請求方法與資料格式。不要假設不同核心版本或 GUI 封裝的 API 行為完全相同;如果節點名稱含有斜線、百分比符號或其他特殊字元,呼叫時也要按 URL 規則正確編碼。

安全呼叫 API:先讀取,再切換並驗證結果

Mihomo 相容的控制器 API 通常使用 Bearer Token 傳送密鑰。操作前先以只讀方式查詢目前代理資料,確認端點可達、認證有效,並在回應中找到目標策略組。以下命令以本機控制器為例;將 YOUR_SECRET 換成實際密鑰,並避免把真實密鑰貼進公開文件、截圖或多人共用的終端紀錄。

curl -sS \
  -H "Authorization: Bearer YOUR_SECRET" \
  http://127.0.0.1:9090/proxies

確認群組名稱後,再使用目前核心支援的端點更新選擇。常見的 Mihomo API 操作方式是對策略組資源送出 PUT,並在 JSON 內容中指定要選取的代理名稱;此處的端點名稱與方法仍應以你安裝版本的 API 文件或實際回應為準。

curl -sS -X PUT \
  -H "Authorization: Bearer YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"name":"NODE-B"}' \
  http://127.0.0.1:9090/proxies/AUTO-MANUAL

切換請求沒有回傳明顯錯誤,不代表流量已經走上預期節點。務必再讀取一次群組狀態,核對目前選擇是否變成 NODE-B,並以客戶端連線紀錄或受控的測試請求確認實際出口。若操作會影響正在進行的下載、視訊會議或長連線,先在低影響時段驗證;節點切換可能中斷既有連線,這是連線重建造成的正常現象,不一定表示 API 失敗。

寫腳本時,請把「查詢、判斷、切換、複查」視為完整流程,而不是只送出一個請求。對候選節點做健康檢查時,使用固定且可重複的測試目標,設定合理逾時,並避免因單次短暫失敗就頻繁切換。若應用場景對穩定性比延遲更敏感,可以加入冷卻時間、連續失敗門檻與回復確認,避免網路抖動時在多個節點之間來回跳轉。

自動化腳本不必把密鑰硬寫在程式碼裡。可使用作業系統的安全憑證儲存或受限權限的環境變數,並避免在錯誤訊息中輸出完整請求標頭。定期輪替密鑰時,也要同步更新腳本並確認舊密鑰不再可用。

自動切換的判斷流程與常見故障排查

一個可維護的 Clash 節點自動切換流程,應先判斷目前群組是否已有可用選項,再評估是否真的需要切換。單看延遲數字不一定能代表所有應用的連線品質:測試目標可能回應很快,但實際服務仍可能遇到丟包、頻寬不足或長連線不穩。若自動切換的依據只有一次測速結果,可能反而讓使用者感受到更多中斷。

  • 設定合理的觸發條件:例如連續數次測試失敗才更換節點,或目前節點不可用時才切換;避免把細微延遲差距直接當成切換理由。
  • 保留穩定的回退選項:確認策略組中有可用的備援節點,並清楚決定失敗時應維持原選擇、切至備援,或通知管理者。
  • 記錄必要狀態:記下時間、群組、切換前後節點與錯誤類型,但不要記錄密鑰或完整的認證標頭。
  • 限制執行頻率:設定最短切換間隔與重試上限,避免多個排程或腳本同時操作同一策略組。

遇到 API 回傳 401 或 403 時,先核對密鑰是否正確、Bearer 標頭格式是否完整,以及 GUI 是否覆寫了設定檔中的密鑰。若連線直接逾時或拒絕,則檢查控制器是否啟動、端口是否正確,以及腳本是否在同一台主機或正確的網路命名空間中執行。不要為了解決本機連線失敗,就立刻把監聽位址改成所有介面;先用本機查詢確認控制器狀態,再逐層檢查防火牆與路由。

若回應指出找不到代理群組或代理名稱,請重新查詢核心載入的代理清單,確認策略組名稱、節點名稱與編碼方式,並檢查設定檔是否成功重新載入。若切換成功但流量表現沒有改變,則確認應用程式的規則是否真的指向該策略組:控制器成功更改一個未被規則使用的群組,並不會改變實際流量路徑。另需留意多個 GUI、排程與外部腳本同時管理同一群組時,後執行者可能立即覆蓋先前選擇。

最後,建立一份簡單的維運檢查表:確認監聽位址仍限於預期範圍、密鑰未被意外更動、群組成員仍存在、切換日誌沒有異常頻率,並在核心或客戶端升級後重新驗證 API。這些檢查不需要複雜的監控平台,但能及早發現設定被覆寫、節點改名或核心升級造成的介面差異。把自動切換視為有邊界、有記錄、可停用的維運功能,會比把它當成永遠可靠的「智慧按鈕」更安全。

相較之下,部分同類工具只提供簡單的手動切換,或將遠端管理與本機控制混在一起,使用者往往得在便利性與存取安全之間自行摸索。Clash/Mihomo 的控制器 API 能搭配明確的監聽範圍、密鑰驗證與策略組設計,讓節點管理流程更容易檢查、測試與回復;無論是本機維運還是受控的自動切換,都可以先從最小權限與可驗證步驟開始。如果你還沒有合適的客戶端,可前往本站客戶端下載頁,了解不同平台的選擇。

→ 立即免費下載 Clash,開啟流暢上網新體驗

前往本站下載頁取得客戶端