前言：為什麼需要外部控制器

在日常使用 Clash 或 Mihomo 時，節點能否穩定連線，往往比單次測速結果更重要。某個節點可能在上午延遲只有 80 毫秒，到了晚間卻出現封包遺失、連線逾時或頻繁重置。如果每次都要手動打開 Clash Verge、Clash Verge Rev 或其他客戶端，再逐一點選節點，不僅耗時，也很難在服務中斷的幾秒內完成切換。

外部控制器 API 提供了一個可程式化的管理入口。只要客戶端核心開啟 External Controller，你就能透過 HTTP API 讀取代理群組、查詢目前節點、測試延遲，甚至主動切換代理。配合排程任務或常駐腳本，便能建立一套「檢查狀態、判斷品質、必要時換線」的自動化流程。

本文以常見的 Mihomo API 為例，說明如何安全取得 API 入口、尋找策略群組、測試節點，以及在連線異常時執行有條件的自動切換。示例使用 Python 標準函式庫，無須額外安裝套件；若你偏好命令列，也會提供 curl 請求方式。

先了解風險

External Controller 等同於本機管理介面。請優先綁定到 127.0.0.1，並設定密碼；不要在沒有防火牆和驗證的情況下直接暴露到公網。

1API 入口與核心概念

不同客戶端的介面名稱可能略有差異，但底層通常由 Mihomo 或相容核心提供 API。設定檔中的 external-controller 用來指定監聽位址與連接埠，secret 則是驗證密鑰。典型設定如下：

external-controller: 127.0.0.1:9090
secret: "請替換成一組長密碼"

修改後需要重新載入設定或重啟核心。若 API 監聽在 127.0.0.1，只有同一台電腦上的程式可以連線；若寫成 0.0.0.0:9090，區域網路上的其他設備也可能存取，除非你清楚知道防火牆和驗證如何配置，否則不建議這樣做。

驗證標頭與基本請求

啟用密碼後，請求通常需要加入 Authorization 標頭。格式是 Bearer 加上一個空格，再接上設定檔中的密鑰。先用 API 讀取整體狀態，可以確認連接埠、密鑰及核心是否正常：

curl -H "Authorization: Bearer 請替換成一組長密碼" \
  http://127.0.0.1:9090/version

如果回應包含核心版本資訊，代表 API 已經可用。若收到 401，通常是密鑰錯誤或 Bearer 格式少了空格；若收到連線拒絕，則應檢查核心是否啟動、埠號是否正確，以及客戶端是否覆蓋了你修改的設定。

不要把密鑰寫入公開程式碼

避免將含有真實密鑰的腳本上傳到 GitHub 或貼到公開論壇。建議使用環境變數、作業系統密碼儲存區，或至少將密鑰放在不納入版本控制的設定檔中。

2動手操作：讀取群組並測試節點

實作時不要先假設策略群組一定叫作 PROXY。訂閱或設定檔可能使用「自動選擇」、「節點選擇」、「Proxy」等名稱，因此第一步應該讀取所有代理資料，再根據群組名稱或類型找到目標。

列出代理群組

Clash 相容 API 的代理資料通常位於 /proxies。使用以下命令，可以將完整 JSON 儲存下來，再搜尋 type、all 或 now 欄位：

curl -s \
  -H "Authorization: Bearer 請替換成一組長密碼" \
  http://127.0.0.1:9090/proxies

一個策略群組常見的資料包含目前選中的 now、可選節點清單 all，以及群組類型 Selector、URLTest 或 Fallback。自動切換腳本最好只操作 Selector 群組，避免直接干預由核心自行測速或故障轉移的群組。

測試節點延遲

測速請求通常使用 /proxies/{name}/delay，並透過查詢參數指定測試網址與逾時時間。節點名稱可能包含空格、斜線或特殊符號，因此必須先進行 URL 編碼。測試網址應選擇穩定、回應快速的 HTTPS 端點，不要使用過大的網頁或需要登入的服務。

curl -G \
  -H "Authorization: Bearer 請替換成一組長密碼" \
  --data-urlencode "timeout=5000" \
  --data-urlencode "url=https://www.gstatic.com/generate_204" \
  "http://127.0.0.1:9090/proxies/日本節點/delay"

回應中的 delay 通常以毫秒表示。若節點不可用，API 可能回傳錯誤或無法取得延遲。判斷時不要只看最低數值：一個 60 毫秒但封包遺失嚴重的節點，實際體驗可能不如 120 毫秒且長時間穩定的節點。

Python 自動測速與選擇節點

以下腳本會讀取指定群組，測試可選節點，忽略 DIRECT、REJECT 等保留名稱，最後選擇延遲最低且低於門檻的節點：

import json
import urllib.parse
import urllib.request

API = "http://127.0.0.1:9090"
TOKEN = "請替換成一組長密碼"
GROUP = "PROXY"
TEST_URL = "https://www.gstatic.com/generate_204"
LIMIT = 800

def request(path, method="GET", data=None):
    body = None if data is None else json.dumps(data).encode()
    req = urllib.request.Request(API + path, data=body, method=method)
    req.add_header("Authorization", "Bearer " + TOKEN)
    req.add_header("Content-Type", "application/json")
    with urllib.request.urlopen(req, timeout=8) as response:
        return json.loads(response.read().decode())

proxies = request("/proxies")
group = proxies["proxies"][GROUP]
candidates = [
    name for name in group.get("all", [])
    if name not in ("DIRECT", "REJECT")
]

results = []
for name in candidates:
    path = "/proxies/" + urllib.parse.quote(name, safe="")
    query = "?timeout=5000&url=" + urllib.parse.quote(TEST_URL, safe="")
    try:
        result = request(path + "/delay" + query)
        delay = int(result.get("delay", 99999))
        if delay < LIMIT:
            results.append((delay, name))
    except Exception:
        continue

if results:
    results.sort()
    selected = results[0][1]
    request("/proxies/" + urllib.parse.quote(GROUP, safe=""),
            "PUT", {"name": selected})
    print("已切換至:", selected, "延遲:", results[0][0], "ms")
else:
    print("沒有找到符合條件的節點")

3建立可靠的自動切換策略

直接以一次測速結果決定切換，容易造成「乒乓效應」：節點 A 略快就切到 A，下一次節點 B 略快又切回 B，長連線因此反覆中斷。較穩妥的做法是加入多項條件，讓腳本只在確實異常時執行切換。

連續失敗： 至少連續兩至三次測試失敗，再判定目前節點不可用。
延遲門檻： 例如連續三次高於 800 毫秒，才進入候選節點篩選。
冷卻時間： 每次切換後等待五至十五分鐘，避免短時間內再次換線。
保留目前節點： 新節點只需比目前節點快一個合理幅度，例如快 20% 或至少快 100 毫秒，避免無意義切換。
限制範圍： 只在同一地區、同一協議或同一訂閱群組內選擇，避免 IP 地理位置突然變動。

透過 PUT 切換群組

確認目標節點後，對策略群組發送 PUT 請求即可切換。群組名稱和節點名稱都必須進行編碼，否則包含特殊字元時可能得到 404：

curl -X PUT \
  -H "Authorization: Bearer 請替換成一組長密碼" \
  -H "Content-Type: application/json" \
  -d '{"name":"新加坡 01"}' \
  "http://127.0.0.1:9090/proxies/PROXY"

建議在切換前後記錄時間、原節點、新節點、測試延遲與錯誤原因。日後遇到「切換後仍然卡頓」時，可以從日誌判斷問題究竟來自節點、DNS、規則，還是應用程式本身，而不是盲目增加切換頻率。

推薦的判斷順序

先確認 API 可用，再查詢群組目前節點；接著測試目前節點，只有在連續失敗或超過門檻時，才測試候選節點並執行切換。

4安全性、排錯與維護建議

外部控制器可以管理核心，但它不會替你修正所有網路問題。若腳本測得延遲正常，實際瀏覽仍然失敗，應進一步檢查 DNS、TUN 模式、分流規則與系統防火牆。部分應用程式會維持既有 TCP 或 WebSocket 連線，切換節點後不一定立即重建連線，這是正常現象。

常見錯誤與處理方式

401 Unauthorized： 檢查 secret 是否正確，確認標頭使用 Authorization: Bearer，不要把密鑰直接放在 URL。
404 Not Found： 群組或節點名稱可能未編碼，或該名稱已因訂閱更新而改變；請重新讀取 /proxies。
408、504 或逾時： 測試網址可能不可達，先用瀏覽器或 curl 確認測試端點，再調整 timeout。
切換成功但流量未變： 檢查實際使用的規則是否指向該群組，也要確認客戶端是否啟用 TUN 或系統代理。
節點清單為空： 可能選到了內層群組、設定檔尚未完成更新，或腳本使用了錯誤的群組名稱。

排程方面，Windows 可以使用工作排程器定時執行 Python 腳本；macOS 和 Linux 則可使用 cron 或 systemd timer。頻率不宜過高，通常每五至十五分鐘檢查一次已足夠。若需要即時監控，可採用較短的檢查間隔，但必須搭配冷卻時間與失敗計數器。

避免過度自動化

頻繁更換出口 IP 可能讓帳戶服務觸發重新驗證，也會中斷下載、視訊會議及長連線工作。對需要固定地區的服務，應建立獨立策略群組，不要與一般自動選擇群組共用。

常見問題

Clash Verge 和 Mihomo 都能使用這套 API 嗎？

能否使用取決於客戶端採用的核心及是否開啟 External Controller，而不是單純取決於圖形介面名稱。Clash Verge Rev、Mihomo 等常見組合通常支援這些端點，但不同版本的欄位和行為可能有細微差異。開始自動化前，建議先測試 /version、/proxies 與單一節點的 /delay。

測速網址應該選哪一個？

選擇回應內容很小、HTTPS 穩定且不需要登入的端點，例如常用的 204 測試網址。若某個網址在你的網路環境中經常被阻擋，就不適合拿來作為唯一判斷依據。更嚴謹的方案可以準備兩至三個測試網址，以多數結果作為判斷。

自動切換會不會中斷正在進行的下載？

有可能。切換代理通常會使新建立的連線使用新節點，但已存在的 TCP 或 TLS 連線可能中斷，也可能繼續使用原路徑。下載、同步和視訊會議等工作不適合設定過於積極的切換條件，應先提高失敗次數門檻，並延長冷卻時間。

可以把 API 開放給區域網路的其他設備嗎？

技術上可以，但必須同時設定強密鑰、防火牆白名單和可信任的區域網路。一般使用者只需在本機腳本呼叫 API，綁定 127.0.0.1 已經足夠。若無法確認網路邊界，請不要將控制器監聽在 0.0.0.0。

透過 API 管理節點的重點，不是讓腳本不停換線，而是建立可觀測、可回溯的流程：先取得真實狀態，再以穩定的測試方式評估品質，最後在明確條件滿足時才切換。只要把驗證、編碼、錯誤處理、冷卻時間和日誌記錄做好，Clash 就能從單純的代理客戶端，進一步成為可監控、可維護的節點管理工具。

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

Clash API 自動切換節點：外部控制器進階設定實戰