Clash Verge Rev 的外部控制器(External Controller)是一個供 Web 面板、管理工具或其他本機程式呼叫的 HTTP API。它與 mixed-port、port、socks-port 等代理連接埠用途不同:代理連接埠負責接收瀏覽器和應用程式的網路流量,外部控制器則負責讀取連線狀態、切換策略組、查看流量統計與管理執行中的核心。

在 Windows 上啟用這項功能時,通常需要同時確認三件事:Clash Verge Rev 實際使用的核心設定是否包含控制器位址、Web 面板填入的控制器 URL 是否正確,以及控制器密鑰是否與核心設定一致。只開啟面板而沒有啟動外部控制器,或把代理連接埠誤填成控制器連接埠,都會造成「面板載入失敗」或「驗證失敗」。

Windows 版 Clash Verge Rev 外部控制器設定教學

先了解外部控制器與代理連接埠的差異

Clash Verge Rev 啟動 Mihomo 核心後,通常會建立至少一個代理監聽連接埠,以及一個供管理介面使用的控制器連接埠。前者可以讓系統代理、瀏覽器或命令列工具轉送流量;後者則提供類似 REST API 的管理入口。兩者即使都使用本機位址,也不能互相替代。

項目 用途 常見示例 是否填入 Web 面板
HTTP 代理 接收 HTTP 或 HTTPS 代理請求 127.0.0.1:7890 否
SOCKS 代理 接收 SOCKS5 應用程式連線 127.0.0.1:7891 否
外部控制器 提供狀態查詢與控制 API 127.0.0.1:9090 是

例如,Windows 系統代理可能指向 127.0.0.1:7890,而 Web 面板應連線到 http://127.0.0.1:9090。如果把 7890 填入面板的控制器欄位,面板送出的 API 請求會被代理服務接收,通常會得到無法理解的回應;如果把 9090 填入 Windows 系統代理,瀏覽器也不會因此取得正常的代理服務。

在僅供本機使用的情況下,建議將控制器綁定在 127.0.0.1。這代表只有同一台 Windows 電腦上的程式可以連線,區域網路中的其他裝置無法直接存取控制器。除非確實需要讓另一台電腦管理 Clash,否則不應將控制器監聽位址改成 0.0.0.0。

在 Clash Verge Rev 中啟用外部控制器

不同版本的 Clash Verge Rev 介面文字可能略有差異,但設定核心的流程大致相同。先啟動 Clash Verge Rev,確認目前使用的是 Windows 版本,並讓目標設定檔處於啟用狀態。不要只修改未被載入的備份檔案,否則檔案內容看似正確,實際執行中的核心仍可能使用另一份設定。

  1. 開啟 Clash Verge Rev,進入設定檔或配置管理頁面,確認目前啟用的設定來源。
  2. 在應用程式設定、核心設定、覆寫設定或類似的 YAML 編輯入口中,尋找外部控制器相關欄位。
  3. 加入控制器位址與密鑰,保存後重新載入設定或重新啟動核心。
  4. 回到 Web 面板設定,填入與核心一致的控制器 URL 和密鑰。
  5. 查看連線清單或核心日誌,確認控制器啟動時沒有出現連接埠占用與設定解析錯誤。

常見的 Mihomo 設定結構如下。這段內容是說明用範例,不應覆蓋原有的節點、策略群組、DNS 與規則設定:

mixed-port: 7890
allow-lan: false
mode: rule

external-controller: 127.0.0.1:9090
secret: "replace-with-a-long-random-secret"

external-controller 定義控制器監聽的位址和連接埠;secret 則是 API 驗證密鑰。控制器 URL 通常寫成 http://127.0.0.1:9090,不需要在後面加上 /ui、/dashboard 或某個具體 API 路徑,除非面板本身明確要求這種格式。

如果 Clash Verge Rev 提供獨立的外部控制器欄位,優先使用圖形介面提供的欄位,而不是同時在多個地方重複設定。部分客戶端會將訂閱 YAML、全域覆寫與執行時參數合併;同一個鍵在不同層級出現時,最後生效的值可能不是你剛剛編輯的那一行。修改後應查看目前核心輸出的實際設定或啟動日誌。

設定 Web 面板與密鑰驗證

啟用控制器後,還需要讓 Web 面板知道應該連線到哪個 API。面板設定通常會要求輸入控制器位址、密鑰,有些面板還會要求選擇界面來源或輸入完整 URL。填寫時應以控制器本身的位址為準,不要把目前開啟面板的網頁網址誤當成 API 位址。

欄位 正確示例 常見錯誤
控制器 URL http://127.0.0.1:9090 填入 127.0.0.1:7890 或遺漏協定
密鑰 與 secret 完全一致 多一個空格、少一個字元或仍使用舊密鑰
連線範圍 本機面板連線本機控制器 使用錯誤電腦上的 127.0.0.1

127.0.0.1 永遠代表「目前執行請求的這台電腦」。因此,如果 Web 面板在同一台 Windows 電腦的瀏覽器中開啟,使用 127.0.0.1:9090 是合理的;如果面板在另一台電腦、手機或 Docker 容器中開啟,這個位址就會指向另一個裝置自身,而不是 Windows 上的 Clash Verge Rev。

密鑰是逐字比對,大小寫、標點與前後空格都會影響驗證結果。建議使用至少 24 個字元的隨機字串,避免使用 Windows 使用者名稱、生日、電話號碼或簡單的 123456。若曾把密鑰貼到公開截圖、聊天記錄或網頁原始碼中,應立即更換,並同步更新 Web 面板保存的舊密鑰。

控制器啟動後,部分面板會自動請求版本資訊或代理群組清單。如果 API 可連線但密鑰不正確,常見表現是 HTTP 401 或「未授權」;如果連接埠沒有服務,通常會顯示連線被拒絕;如果位址可達但瀏覽器受到跨來源限制,則可能出現 CORS 或網路請求被阻擋的訊息。這三種情況的排查方向不同,不應只反覆更換節點。

使用 Windows 工具驗證控制器是否正常

在 Web 面板出現錯誤時,可以先脫離面板,直接從 Windows PowerShell 測試控制器。這樣能將問題分成三段:Windows 是否能連到連接埠、核心是否接受 API 請求,以及密鑰是否通過驗證。

先使用 PowerShell 的連接測試確認連接埠是否有服務監聽:

Test-NetConnection 127.0.0.1 -Port 9090

如果輸出中的 TcpTestSucceeded 為 True,表示 TCP 層可以連到該連接埠;這不代表密鑰正確,也不代表 Web 面板格式一定正確。若結果為 False,優先檢查核心是否啟動、控制器連接埠是否寫錯,以及是否有其他程式占用該連接埠。

接著可以使用 PowerShell 的 Invoke-WebRequest 呼叫版本 API。以下的 REPLACE_SECRET 要替換成實際密鑰:

$headers = @{
  Authorization = "Bearer REPLACE_SECRET"
}

Invoke-WebRequest `
  -Uri "http://127.0.0.1:9090/version" `
  -Headers $headers

也可以在新版 Windows 中使用 curl.exe,避免 PowerShell 將 curl 別名解讀成其他命令:

curl.exe -i ^
  -H "Authorization: Bearer REPLACE_SECRET" ^
  http://127.0.0.1:9090/version

正常回應通常會包含核心版本資訊。若出現 401,表示服務存在但密鑰不符;若出現連線拒絕,表示該連接埠沒有可接受請求的服務;若命令長時間無回應,則應檢查控制器位址、Windows 防火牆規則、核心日誌與是否存在多個 Clash 執行個體。

確認 API 可以回應後,再檢查目前的監聽程序:

netstat -ano | findstr :9090

Get-NetTCPConnection -LocalPort 9090 -State Listen

netstat 最後一欄會顯示 PID,可以再用工作管理員的詳細資料頁面,或使用以下命令查詢對應程序:

tasklist /FI "PID eq 12345"

如果 9090 被其他程式使用,Clash Verge Rev 可能啟動失敗,也可能改用其他控制器連接埠。不要只在面板中嘗試新的數字,應先確認核心實際監聽的連接埠,再讓面板與核心使用相同值。

連不上控制器時的排查順序與安全設定

控制器問題最好按照由近到遠的順序排查。先確認 Clash Verge Rev 是否正在執行,再確認核心是否成功啟動,接著確認 TCP 連接埠,最後才檢查面板格式與密鑰。這樣可以避免在服務尚未監聽時,反覆修改瀏覽器或 Web 面板設定。

  1. 確認目前核心正在執行。查看 Clash Verge Rev 的狀態指示與核心日誌。如果 YAML 存在縮排錯誤、未知欄位或連接埠衝突,控制器可能根本沒有成功建立。
  2. 確認使用的是生效設定。訂閱檔、覆寫檔與本機設定可能同時存在。重新載入後,檢查最後生效的 external-controller 與 secret。
  3. 確認位址與連接埠。本機面板通常使用 http://127.0.0.1:9090。不要混用代理連接埠,也不要把 https:// 加在沒有 TLS 設定的控制器前面。
  4. 確認密鑰格式。刪除面板中保存的舊密鑰後重新貼上,檢查是否包含換行、前後空格或全形符號。
  5. 確認 Windows 防火牆範圍。本機回環連線通常不需要開放公用網路入站規則。若必須讓區域網路裝置存取,才需要評估防火牆規則與可信任網路範圍。
  6. 確認沒有同時執行多個核心。舊版客戶端、背景服務或其他 Mihomo 程序可能已占用控制器連接埠,導致你查看的不是 Clash Verge Rev 實例。

安全方面,最穩妥的本機設定是使用 127.0.0.1,搭配長而隨機的 secret,並保持 allow-lan: false,除非確實需要讓區域網路裝置使用代理。需要區域網路管理時,應先了解控制器 API 可執行的操作,再限制監聽位址、防火牆入站來源與可信任網段。不要把控制器直接暴露到公網,也不要只依賴「網址很難猜」作為保護。

external-controller: 127.0.0.1:9090
secret: "use-a-long-random-value"
allow-lan: false

控制器密鑰與訂閱網址都可能包含敏感資訊。分享錯誤畫面時,應遮蓋密鑰、訂閱參數、節點主機名稱和私人 IP。若只是測試本機連線,使用 127.0.0.1 比使用區域網路 IP 更安全,也能減少 Windows 防火牆與路由環境造成的變數。

完成設定後,建議依序驗證:先用 Test-NetConnection 確認連接埠,再用 /version API 驗證密鑰,最後才在 Web 面板中查看策略組與連線列表。當三個層次都正常時,控制器設定通常已經完成;若只有面板顯示異常,則應集中檢查面板 URL、跨來源限制與面板所要求的密鑰格式。

下載Clash