外部控制器是什麼？先理解 API 與面板的關係

在 Clash Verge Rev 裡，外部控制器（External Controller）不是另一個代理模式，也不會自動提供節點或訂閱來源；它本質上是 Mihomo 核心提供的一組本機 HTTP API。當 API 正常啟動後，瀏覽器面板、桌面管理工具或自製腳本，就能透過這個介面讀取目前設定、查看代理群組、切換節點、檢查連線，以及觀察規則命中狀態。

許多 Windows 使用者搜尋「Clash Verge Rev 外部控制器怎麼開」時，實際遇到的不是單一開關，而是三個設定互相配合：外部控制器監聽位址與連接埠、API 密鑰（secret），以及瀏覽器管理面板所使用的連線位置。只開啟其中一項，仍可能看到「無法連線」「401 Unauthorized」或面板載入後一片空白。

此外，Windows 上同時可能存在 Clash Verge Rev、舊版 Clash for Windows、Mihomo Party 或其他本機代理服務。不同程式若搶用同一個 API 埠，會造成啟動失敗或面板連到錯誤核心。因此本文會從確認版本、設定 API、連接面板，到最後的安全檢查與排障，依照實際操作順序說明。

合規提醒：Clash Verge Rev 與 Mihomo 是本機代理與規則管理工具，不提供遠端節點。請只在合法授權、符合所在地法規及相關服務條款的情況下使用，並不要把訂閱連結或 API 密鑰公開貼出。

開始前：確認核心、權限與可用連接埠

首先開啟 Clash Verge Rev，確認目前使用的是可正常啟動的 Mihomo 核心。不同版本的介面名稱可能略有差異，有些版本把相關項目放在「設定」「常規」「核心」或「外部控制器」區域，也有版本會將 API 設定整合到目前 profile 的進階設定中。不要只依照某張舊版截圖找按鈕，應以畫面上實際顯示的欄位為準。

接著檢查 Windows 是否已有其他程式使用預定連接埠。外部控制器常見使用 127.0.0.1:9090、127.0.0.1:9097 或其他自訂埠，但沒有必要盲目照抄數字。你可以在 PowerShell 執行下列指令，查看指定埠是否已被佔用：

PowerShellGet-NetTCPConnection -LocalPort 9090 -ErrorAction SilentlyContinue

若沒有回傳內容，通常代表該埠目前未被 TCP 服務監聽；若看到其他程序，請改用另一個未佔用的埠，或先關閉衝突程式。也可以使用：

PowerShellnetstat -ano | findstr :9090

如果輸出結果顯示某個 PID 正在使用該埠，再用工作管理員對照 PID。不要在不清楚用途的情況下強制結束系統服務，尤其是公司電腦或有安全管理軟體的環境。最穩妥的做法是選擇一個未被使用的高位埠，並記錄下來，後續設定瀏覽器面板時才不會混淆。

步驟一：在 Clash Verge Rev 設定外部控制器

完成前置檢查後，進入 Clash Verge Rev 的設定頁面，尋找「外部控制器」「External Controller」「API」或相近名稱的欄位。部分版本會把它放在「核心設定」之下，部分版本則需要先選取正在使用的設定檔，再編輯該 profile 的 YAML 內容。你要找的核心設定通常包含監聽位址、連接埠與密鑰三個部分。

  1. 設定監聽位址：一般只在本機瀏覽器管理時使用 127.0.0.1 或 127.0.0.1:9090。這代表 API 只接受本機連線，不會直接暴露給區域網路中的其他裝置。
  2. 設定 API 連接埠：選擇未被其他程式佔用的埠，例如 9090；若欄位要求完整格式，請填入 127.0.0.1:9090，不要額外加上 http://。
  3. 設定密鑰：在 secret 欄位填入一組足夠長、難以猜測的字串。密鑰不是訂閱密碼，也不是 Windows 登入密碼，請單獨保存。
  4. 套用並重啟核心：按下儲存、套用或重新載入設定。若畫面提示必須重啟核心，請完整退出 Clash Verge Rev 後再次開啟，確保新 API 設定真的被 Mihomo 載入。

若你需要直接檢查 YAML，常見結構如下；實際欄位名稱與版本支援情況仍應以目前 Mihomo 文件及 Clash Verge Rev 介面為準：

YAMLexternal-controller: 127.0.0.1:9090
secret: "請替換成你自己的隨機密鑰"

不要直接使用空密鑰：只要 API 監聽在 0.0.0.0 或被防火牆放行，沒有密鑰就可能讓同一網路中的其他裝置操作你的代理核心。除非你非常清楚風險，否則不建議把外部控制器暴露到區域網路。

步驟二：使用瀏覽器面板連接 API

外部控制器本身只提供 API，不一定包含完整的圖形化管理頁面。你需要使用與 Mihomo API 相容的 Web Dashboard，並在面板設定中填入 API 位址與密鑰。常見欄位可能叫作「Backend」「API Base URL」「External Controller」或「秘密」。這些名稱雖然不同，但要填入的資訊大致相同。

  1. 開啟相容的 Web Dashboard，先找到面板的設定或後端連線選項。
  2. 在 API 位址欄輸入 http://127.0.0.1:9090；若你的實際埠不是 9090，請換成前面設定的數字。
  3. 在 Secret、Token 或密鑰欄貼上 Clash Verge Rev 中設定的同一組字串，注意前後不要多出空格或換行。
  4. 儲存設定後重新整理頁面。若連線成功，通常可以看到目前模式、代理群組、流量統計與連線列表。

瀏覽器面板連不上時，先不要急著重灌程式。第一個測試是確認 API 埠是否真的有回應。你可以在 PowerShell 執行：

PowerShellcurl.exe http://127.0.0.1:9090/version

若 API 正常，通常會返回核心版本資訊；如果回覆 401 或類似未授權訊息，代表服務有啟動，但需要正確的密鑰。若顯示連線被拒絕，則較可能是核心未啟動、連接埠填錯、設定尚未套用，或該服務實際監聽在其他位址。

也可以用帶有 Authorization 標頭的方式測試：

PowerShell$headers = @{ Authorization = "Bearer 你的API密鑰" }
Invoke-RestMethod -Uri "http://127.0.0.1:9090/version" -Headers $headers

若這個指令能返回版本資料，但瀏覽器面板仍無法載入，問題通常在面板 URL、面板相容性、瀏覽器快取或 CORS 設定，而不在 Clash 核心本身。此時可先用無痕視窗測試，並確認面板要求的 API 路徑是否包含結尾斜線。

步驟三：驗證功能並做好 Windows 安全設定

API 成功連線後，建議不要只看面板是否顯示綠色狀態，而要實際完成幾項驗證。首先在面板查看目前代理模式與策略組，確認顯示內容與 Clash Verge Rev 內部一致；其次切換一個測試用代理群組，觀察桌面客戶端是否同步變更；最後開啟連線列表，確認新的測試請求能被 Mihomo 記錄。完成驗證後，請切回日常使用的策略，避免把測試節點長時間留下。

測試項目 正常結果 異常時優先檢查
版本 API 返回 Mihomo 版本資料 監聽位址、連接埠與核心狀態
密鑰驗證 正確密鑰可讀取資料 Bearer 格式、空格與密鑰是否一致
代理群組 面板顯示目前策略與節點 面板 API 路徑及 profile 是否載入
連線列表 測試請求出現在 Connections 請求是否真的經過 Clash 代理

安全方面，建議將監聽位址維持在 127.0.0.1。只有在你確實需要用手機或區域網路其他裝置管理時，才考慮改成區域網路位址；即使如此，也必須設定強密鑰、限制 Windows 防火牆入站規則，並避免直接使用 0.0.0.0 對所有介面開放。若外部控制器只為瀏覽器管理服務，讓它留在本機通常已經足夠。

API 密鑰也不應寫入公開截圖、教學文章、Git 儲存庫或聊天群組。若你懷疑密鑰已經外洩，請立即在 Clash Verge Rev 產生新密鑰，重新啟動核心，並在所有面板與腳本中同步更新。密鑰外洩的影響不只是讀取流量資訊，還可能讓他人替換代理群組、修改設定或中斷你的連線。

常見失敗情況：從錯誤訊息定位問題

「外部控制器已開啟但面板不能用」通常可以依錯誤類型快速分流。若是 ERR_CONNECTION_REFUSED，代表目標位址沒有服務監聽，應檢查核心是否已啟動、連接埠是否輸入正確，以及 Clash Verge Rev 是否在套用設定後重新載入。若是 401 Unauthorized，則 API 已經收到請求，問題集中在密鑰缺失、密鑰錯誤或 Authorization 標頭格式不正確。

  • 面板顯示 CORS 錯誤：確認面板使用的是與 Mihomo 相容的後端連線方式；不要自行把瀏覽器安全限制全部關閉。若面板是從其他網域載入，可能需要在核心設定中允許對應的外部 UI 位址，但應只加入可信來源。
  • 設定儲存後又恢復原狀：可能是你修改的是臨時 profile、遠端訂閱產生檔，或程式啟動時會重新覆蓋設定。先確認目前啟用的 profile，再查看是否有覆寫欄位與訂閱更新腳本。
  • API 可以連線但看不到代理群組：檢查面板是否指向另一個核心埠，或 profile 是否尚未成功載入。重啟後先在 Verge Rev 內部確認代理頁面正常，再測試外部面板。
  • Windows 防火牆跳出提示：若 API 只監聽 127.0.0.1，通常不需要對公用網路開放入站連線。請閱讀規則內容，不要為了消除提示而直接允許所有網路。

若近期更新了 Clash Verge Rev 或 Mihomo 核心，還要留意欄位名稱與 API 行為變更。最有效的排查方式是先回到最小設定：只保留本機監聽、單一埠、明確密鑰，關閉不必要的遠端面板與自訂腳本，確認 /version 能通後，再逐項恢復進階功能。這比一次修改多個 YAML 欄位，更容易找到真正造成失敗的變更。

相較於一些只提供固定 Web UI、API 文件不完整，或必須額外安裝多個管理元件的同類工具，Clash Verge Rev 的外部控制器更適合用來建立一套可觀察、可驗證的 Windows 本機管理流程；當然，它仍需要使用者理解連接埠、密鑰與防火牆的基本關係。Clash 官網 將這些步驟、錯誤訊息與安全取捨集中整理，讓你不必在零散截圖之間反覆猜測設定位置；如果你正想在 Windows 上穩定管理 Clash API，不妨前往下載 Clash 官網，再依本文完成外部控制器設定與測試。