配置 2026-08-31 · 約 12 分鐘閱讀

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 忙碌,都可能製造假故障。比較實用的判斷方式是連續測試兩至三次,只有在達到失敗門檻後才切換;切換後再等待一段冷卻時間,避免兩個節點之間來回震盪。

推薦的處理流程

  1. 向 /version 發送請求,確認 Clash 核心仍在執行。
  2. 向 /proxies 取得策略組、候選節點與目前選取的節點。
  3. 透過代理實際請求測試網址,確認 HTTP 狀態碼、連線時間與 TLS 是否正常。
  4. 連續失敗達到門檻後,從候選清單中排除目前節點,選擇下一個節點。
  5. 對策略組發送切換請求,記錄切換前後名稱與原因。
  6. 等待冷卻時間後重新驗證,若仍失敗才繼續切換,並發送告警。

測試內容最好同時涵蓋「控制器可達」與「代理出口可用」兩件事。若 /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)