Clash 外部控制器 API 節點故障轉移與自動切換實戰
進入 2026 年,Perplexity AI 憑藉其強大的實時搜索與生成能力,已成為許多用戶不可或缺的生產力工具。然而,隨著其風控系統的升級,越來越多的用戶在使用 Clash 代理時遇到了「Access Denied」或無限加載的問題。本文將深度解析其背後的技術原因,並提供一套從基礎規則到進階 TUN 模式的完整配置方案,確保您的 AI 搜索體驗穩定無障礙。
外部控制器 API 是什麼?
Clash 的外部控制器(external-controller)是一組供管理工具與自動化腳本使用的 HTTP API。它不負責取代代理核心,而是讓您在不直接修改 YAML 的情況下,讀取目前設定、查看連線、取得策略組狀態、切換代理節點,以及重新載入設定檔。Clash Verge Rev、Mihomo 等客戶端通常會在背景啟動這個介面,Web 面板也多半是透過同一組 API 與核心溝通。
對一般使用者來說,點選介面上的節點名稱就能完成切換;但在伺服器、家庭網路、CI 測試環境或長時間運作的下載主機上,單靠人工操作並不可靠。節點可能在半夜逾時、TCP 連線仍存在但實際網站已無法開啟,甚至只是 DNS 正常而 HTTPS 握手失敗。此時可以讓腳本定期呼叫外部控制器,依據實際測試結果切換策略組,達到故障轉移與自動恢復的效果。
需要先釐清的是:API 能控制的是目前正在執行的 Clash 核心。它不會替您產生節點,也不會修復失效的訂閱。若所有節點都已過期、訂閱格式無法解析,或上游服務本身中斷,API 只能回報失敗。因此正確的設計應分成三層:第一層是 YAML 中的代理與策略組;第二層是外部控制器提供的即時管理介面;第三層才是監測、告警與切換腳本。
先準備可被 API 控制的 YAML 設定
自動切換是否穩定,首先取決於策略組設計。不要讓腳本直接記住某個節點的完整名稱,也不要把每一個節點寫死在多個規則中。比較容易維護的方式是建立一個固定名稱的主策略組,例如 PROXY,再讓它包含手動選擇、URL 測試與備援節點。訂閱更新後,即使節點名稱改變,只要策略組名稱仍然存在,腳本就不需要重新編寫。
建議的設定重點
- 固定策略組名稱:例如
PROXY或🚀 節點選擇,但自動化環境最好使用不含表情符號的英文名稱。 - 保留多個候選節點:至少準備兩個不同地區或不同線路的節點,避免單一供應商故障時沒有替代路徑。
- 設定測試網址:使用穩定、回應內容簡單的 HTTPS 網址,不要只測試首頁很大的網站。
- 控制測試間隔:桌面使用者可使用三至五分鐘;伺服器則應依流量與服務重要性調整,避免過於頻繁測速。
- 把直連與拒絕分開:
DIRECT是直連,不應被誤當成代理備援;REJECT更不能放進自動代理候選清單。
Mihomo 常見的自動選擇策略包括 url-test、fallback 與 load-balance。url-test 會按照測試結果選擇延遲較低的節點;fallback 則著重於可用性,通常按照清單順序尋找能通過測試的節點;load-balance 適合需要分散連線的場景。若您的目標是「主要節點失效時切到備用節點」,fallback 通常比單純比較延遲更符合預期。
proxy-groups:
- name: PROXY
type: fallback
proxies:
- Tokyo-01
- Singapore-01
- Frankfurt-01
url: https://www.gstatic.com/generate_204
interval: 300
tolerance: 50
rules:
- DOMAIN-SUFFIX,example.com,PROXY
- MATCH,DIRECT
上面的範例只是結構示意,節點名稱必須與您自己的 proxies 清單完全一致。若使用訂閱覆蓋或 YAML 模組化,建議將策略組放在固定的本地覆寫檔中,再由客戶端的 Merge、Mixin 或覆蓋功能套用。這樣更新訂閱時不必手動修改遠端產生的原始檔,也比較容易在出錯時回復上一個版本。
不要把 API 密鑰直接寫進公開設定檔
secret 等同管理權杖。若設定檔會同步到 Git 儲存庫、雲端硬碟或團隊聊天工具,請使用不含密鑰的範本,並透過環境變數或本機秘密管理機制注入。日誌也不要直接輸出完整的 Authorization 標頭。
認識外部控制器的核心 API
在 YAML 中,外部控制器常見寫法是 external-controller: 127.0.0.1:9090。這代表 API 只監聽本機,其他裝置無法直接連入,是桌面環境較安全的預設方式。若要讓區網內的監控主機存取,才需要改成 0.0.0.0:9090 或指定內網 IP,但同時必須設定密鑰與防火牆規則。
API 路徑可能因核心版本或客戶端封裝方式略有差異,實際使用前請先查看您所用核心的 API 文件。以下幾個端點是排查與自動切換最常用的類型:/version 用來確認核心是否可達;/proxies 用來讀取代理與策略組;/proxies/{name} 可取得指定策略組的狀態;對策略組發送 PUT 請求則可切換目前選取的代理;/connections 適合觀察現有連線;部分 Mihomo 版本還提供健康檢查、規則與流量統計等延伸資料。
| 用途 | 方法 | 端點或操作 | 實務提醒 |
|---|---|---|---|
| 確認核心狀態 | GET | /version |
先確認服務可達,再進行後續請求 |
| 讀取策略組 | GET | /proxies |
策略組名稱可能含空格或特殊字元 |
| 切換節點 | PUT | /proxies/{group} |
請求內容通常是 JSON 的 name 欄位 |
| 查看連線 | GET | /connections |
只代表目前連線,不等於節點長期健康 |
| 重新載入設定 | PUT | /configs |
重載前先備份,避免錯誤 YAML 中斷服務 |
使用 API 時,策略組名稱需要進行 URL 編碼。比如 🚀 節點選擇 不能直接拼接在網址中,否則空格、表情符號或非 ASCII 字元可能造成 404。較穩妥的做法是讓腳本先讀取 /proxies,按照 JSON 中的實際鍵名尋找策略組,再由 HTTP 客戶端自動完成編碼。
curl -s \
-H "Authorization: Bearer YOUR_SECRET" \
http://127.0.0.1:9090/version
curl -s \
-H "Authorization: Bearer YOUR_SECRET" \
http://127.0.0.1:9090/proxies
curl -X PUT \
-H "Authorization: Bearer YOUR_SECRET" \
-H "Content-Type: application/json" \
--data '{"name":"Singapore-01"}' \
http://127.0.0.1:9090/proxies/PROXY
若您的控制器沒有設定 secret,第一個標頭通常可以省略;但在任何可被其他裝置存取的監聽位址上,都不應依賴「只有內網所以安全」的假設。辦公室、旅館、虛擬私有網路甚至受感染的區網裝置,都可能掃描常見的 9090 連接埠。
用腳本實作健康檢查與故障轉移
一個可靠的自動切換腳本,不應看到一次逾時就立即改節點。短暫的 DNS 延遲、目標網站限流或本機 CPU 忙碌,都可能製造假故障。比較實用的判斷方式是連續測試兩至三次,只有在達到失敗門檻後才切換;切換後再等待一段冷卻時間,避免兩個節點之間來回震盪。
推薦的處理流程
- 向
/version發送請求,確認 Clash 核心仍在執行。 - 向
/proxies取得策略組、候選節點與目前選取的節點。 - 透過代理實際請求測試網址,確認 HTTP 狀態碼、連線時間與 TLS 是否正常。
- 連續失敗達到門檻後,從候選清單中排除目前節點,選擇下一個節點。
- 對策略組發送切換請求,記錄切換前後名稱與原因。
- 等待冷卻時間後重新驗證,若仍失敗才繼續切換,並發送告警。
測試內容最好同時涵蓋「控制器可達」與「代理出口可用」兩件事。若 /version 可正常回應,但外部 HTTPS 請求失敗,問題多半在節點、規則、DNS 或上游線路;若連 /version 都無法回應,則應先檢查 Clash 是否崩潰、連接埠是否被其他程式佔用,以及用戶端是否在更新設定後重啟失敗。
#!/usr/bin/env bash
set -u
API="http://127.0.0.1:9090"
SECRET="${CLASH_SECRET:?CLASH_SECRET is required}"
GROUP="PROXY"
TEST_URL="https://www.gstatic.com/generate_204"
api_get() {
curl -fsS --max-time 8 \
-H "Authorization: Bearer ${SECRET}" "$1"
}
if ! api_get "${API}/version" >/dev/null; then
echo "controller is unreachable" >&2
exit 1
fi
current="$(api_get "${API}/proxies" | jq -r --arg g "$GROUP" '.[$g].now')"
if curl -fsS --max-time 12 -o /dev/null "$TEST_URL"; then
echo "proxy is healthy: ${current}"
exit 0
fi
echo "health check failed for ${current}" >&2
# Select the next candidate according to your own allowlist.
# Require consecutive failures before changing the group.
這段腳本刻意沒有直接替您決定節點,因為不同訂閱的節點命名、測試方式與風險不一樣。實際部署時,建議建立明確的 allowlist,只允許名稱符合預期的節點進入切換範圍;不要把所有從訂閱回傳的字串直接當成命令參數。若使用 Python、Node.js 或 Go 實作,也應設定連線逾時、讀取逾時、最大重試次數與錯誤記錄,避免腳本本身成為無限重試的流量來源。
另一個常被忽略的問題是「測試成功,但應用仍無法使用」。這可能是測試請求走了系統代理,而實際應用走的是 TUN;也可能是測試網址能連線,目標服務卻被規則分到 DIRECT。因此正式環境應使用與實際服務相同的網路路徑與代表性域名,並在 Clash 的 Logs、Connections 中確認該請求最後命中的規則與策略組。
安全部署、日誌除錯與常見故障
外部控制器本質上是一個高權限管理入口。任何能取得密鑰的使用者,通常都可能讀取節點資訊、切換出口,甚至重新載入設定。最安全的起點是只監聽 127.0.0.1,讓監測腳本與 Clash 位於同一台主機。如果必須跨主機管理,請限制防火牆來源 IP,透過 SSH 隧道或反向代理提供加密通道,並避免直接把 9090 暴露到公網。
不要為了方便把控制器開放到公網
external-controller: 0.0.0.0:9090 只代表監聽所有介面,不代表自動具備 HTTPS、身份驗證或存取控制。跨網段部署時至少要同時設定強密鑰、主機防火牆、來源白名單與加密傳輸;不使用時應恢復為本機監聽。
除了控制器本身,還要妥善處理日誌。建議記錄時間、測試網址、目前節點、失敗類型、切換結果與 API 狀態碼,但不要記錄訂閱 URL、完整密鑰或含有個人資料的連線標頭。遇到節點切換頻繁時,可依照下列順序排查:先看控制器是否回應,再看策略組是否真的變更,接著檢查規則命中,最後才分析 DNS、TLS 與上游節點。若只看客戶端首頁的「已連線」狀態,很容易把本機核心正常誤判成外部網站正常。
常見的 401 通常表示密鑰遺失或 Authorization 格式錯誤;404 可能是策略組名稱沒有編碼,或該版本沒有提供您使用的端點;400 常見於 JSON 格式錯誤、節點名稱不存在,或把普通代理名稱誤當成可切換的策略組。若 API 回應正常但切換後流量沒有改變,請確認規則實際引用的是該策略組,而不是另一個同名相近的群組。
設定重載也要特別保守。自動更新訂閱前先將舊檔備份,下載完成後進行 YAML 語法與核心相容性檢查,再呼叫重載 API。若重載失敗,腳本應立即保留舊設定並發送告警,而不是不斷重試同一份錯誤檔案。對桌面用戶端而言,Clash Verge、Clash Verge Rev 與不同版本的 Mihomo 可能對欄位、端點及 WebSocket 支援略有差異,請以實際核心的回應為準,不要單純照搬其他客戶端的教學。
部署前的驗收清單
- 手動切換策略組後,Logs 與外部測試都能顯示新節點。
- 拔除主要節點或模擬逾時後,腳本不會立即頻繁來回切換。
- 控制器只接受預期來源,密鑰不出現在版本控制與公開日誌中。
- 重啟 Clash 後,策略組名稱、API 監聽位址與自動化服務仍然一致。
- 訂閱更新失敗時保留上一份可用設定,並能由人工快速接管。
有些同類代理客戶端只提供基本的節點按鈕,遇到故障時往往需要手動重測、重新選擇,或依賴額外外掛才能取得穩定的策略組控制;部分工具的 API 文件與核心版本也不一致,導致腳本在更新後容易失效。Clash 搭配 Mihomo 時,則能以清楚的 YAML 策略組、外部控制器 API、日誌與連線檢視建立完整的故障轉移流程,並可從本機限制管理入口,兼顧自動化與安全性。如果您希望在熟悉的圖形介面中管理設定,再逐步加入 API 監測與節點自動切換,不妨先從適合您平台的版本開始體驗:下載 Clash,立即體驗。
準備好恢復您的 AI 工作流了嗎?
獲取 2026 最新版 Clash,內建優化分流規則,一鍵解決 Perplexity 與 ChatGPT 存取難題。
免費下載 Clash(Windows / macOS)