Clash Verge Rev 外部控制器如何設定？Windows 操作指南

先分清外部控制器與代理連接埠

Clash Verge Rev 的「外部控制器」不是用來承載一般網頁流量的代理伺服器，而是 mihomo 核心提供的管理 API。它讓客戶端、Web 管理介面或其他本機工具讀取核心狀態、查看目前連線、切換策略組，以及重新載入部分設定。啟用外部控制器，不會自動讓所有應用程式經過代理，也不會取代 mixed-port、http-port 或 socks-port。

在 Windows 上，常見的分工如下：127.0.0.1:7890 用於 HTTP、SOCKS5 或 mixed 代理流量；127.0.0.1:9090 則用於外部控制 API。實際數值可以自行修改，但兩者不能誤填。將瀏覽器代理設定成 9090，通常只會得到 API 回應或連線錯誤，並不能正常瀏覽一般網站。

在 Clash Verge Rev 開啟設定檔

先啟動 Clash Verge Rev，確認目前已選取一份可正常啟動的設定。不同版本的介面文字可能略有差異，通常可以從左側的「設定檔」、設定檔卡片上的更多選單，或「開啟資料夾」進入設定檔位置。若使用的是由訂閱產生的設定，建議先複製一份本機設定或建立覆寫檔案，再加入外部控制器欄位，避免下一次更新訂閱時被遠端內容覆蓋。

在編輯 YAML 前，先找出是否已有下列欄位。如果檔案已經存在 external-controller、secret 或 external-ui，應直接修改原值，不要在檔案底部重複加入相同的 YAML 鍵。YAML 對縮排與重複欄位十分敏感，同一層級出現兩個相同鍵時，可能造成解析錯誤，或讓前面的值被後面的值覆蓋。

1. 開啟 Clash Verge Rev，進入「設定檔」或目前使用中的 Profile。
2. 選擇編輯、檢視設定，或使用「開啟資料夾」找到實際使用的 YAML。
3. 先複製原檔並重新命名，例如保存為 profile-backup.yaml。
4. 在頂層設定區加入外部控制器、密鑰與 Web 介面欄位。
5. 儲存後回到 Clash Verge Rev，重新載入設定或重啟 mihomo 核心。

如果訂閱每次更新都會重新產生完整設定，直接修改產生檔可能只在當下有效。這時應使用 Clash Verge Rev 提供的覆寫、Mixin 或本機自訂設定功能，具體入口會依版本與設定檔類型不同。原則是讓自訂欄位在訂閱更新後仍能合併到最終設定，而不是修改下載快取。

設定 API 連接埠與密鑰

以下範例適合只在本機 Windows 使用的情況。external-controller 使用回環位址，表示只有本機程式可以直接連接；secret 是呼叫 API 時需要提供的認證字串。密鑰應至少使用 16 個字元，並避免使用帳號名稱、生日或容易被猜到的固定字串。

mixed-port: 7890
allow-lan: false
mode: rule
log-level: info

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

external-ui: ui

external-ui: ui 表示 Web 管理介面的檔案位於核心工作目錄下的 ui 資料夾。這個欄位只會指定前端檔案位置，不一定會替你下載前端。若目錄不存在，瀏覽器可能可以連到控制連接埠，但開啟 /ui 時仍會顯示找不到頁面。部分 Clash Verge Rev 版本會透過介面管理或下載外部控制器頁面；若版本沒有內建前端，需依客戶端提供的方式安裝相容 Web UI。

密鑰只負責 API 驗證，不是 Windows 登入密碼，也不是訂閱網址。測試時不要把完整密鑰貼到公開截圖、問題回報或聊天記錄中。若懷疑密鑰已外洩，應立即更換並重新載入核心。

重新載入核心並確認連接埠

儲存 YAML 後，回到 Clash Verge Rev 重新載入設定。常見操作名稱包括「重新載入設定」、「切換設定檔」或重新啟動核心。若只重新整理圖形介面而沒有重啟 mihomo，新的控制器欄位可能尚未生效。重新載入後，先觀察核心日誌是否出現 YAML 解析錯誤，再測試控制連接埠。

Windows 可以使用 PowerShell 檢查 9090 是否正在監聽：

Test-NetConnection 127.0.0.1 -Port 9090

當結果中的 TcpTestSucceeded 為 True，代表該 TCP 連接埠可以建立連線，但不代表密鑰正確或 Web UI 已安裝。若結果為 False，應依序檢查核心是否正在執行、設定是否載入成功、連接埠是否被其他程式占用，以及是否誤將控制器寫成了其他位址。

也可以使用 PowerShell 呼叫版本 API。以下命令中的密鑰必須替換成自己的值：

$headers = @{
  Authorization = "Bearer replace-with-a-long-random-secret"
}
Invoke-RestMethod `
  -Uri "http://127.0.0.1:9090/version" `
  -Headers $headers

成功時通常會得到包含版本資訊的 JSON 回應，例如核心版本、版本日期或訂製版本欄位。若回傳 401 Unauthorized，表示控制器可連線，但密鑰不正確；若回傳 404 Not Found，可能是路徑輸入錯誤或目前核心沒有提供該 API；若直接無法建立連線，則應先回頭檢查核心與監聽連接埠。

從瀏覽器確認 Web 管理介面

控制 API 正常並不等同於 Web 管理介面一定存在。先在瀏覽器開啟 http://127.0.0.1:9090/version，這個路徑主要用於確認 API 回應；它可能顯示 JSON，而不是圖形化頁面。若要開啟管理介面，通常使用 http://127.0.0.1:9090/ui，部分 Web UI 需要在網址後加上斜線，或由其設定頁指定 API 位址。

1. 確認 Clash Verge Rev 與 mihomo 核心正在執行。
2. 在瀏覽器開啟 http://127.0.0.1:9090/ui。
3. 若頁面要求輸入控制器位址，填入 http://127.0.0.1:9090。
4. 若頁面要求密鑰，填入 YAML 中 secret 的相同內容。
5. 進入狀態、代理或連線頁面，確認能讀取 mihomo 的資料。

Web UI 連線時常見的錯誤是把代理連接埠與控制連接埠混在一起。Web UI 的 API 位址應指向 9090，而不是 7890。如果頁面顯示「無法連線」，可以先直接測試 /version；如果版本 API 有回應，問題多半出在 Web UI 路徑、前端檔案或密鑰，而不是核心控制器本身。

Windows 常見錯誤與處理順序

設定檔無法載入

若重新載入後出現 YAML 錯誤，先檢查欄位是否位於頂層、冒號後是否有空格，以及是否使用 Tab 縮排。external-controller:127.0.0.1:9090 少了冒號後的空格，或把欄位錯誤放到 proxy-groups 之下，都可能導致解析失敗。建議使用支援 YAML 語法提示的編輯器，並逐次加入一個欄位。

9090 已被其他程式占用

可以使用 PowerShell 查看是哪個程序占用連接埠：

Get-NetTCPConnection -LocalPort 9090 -ErrorAction SilentlyContinue |
  Select-Object LocalAddress, LocalPort, State, OwningProcess

Get-Process -Id <PID>

如果確認是其他服務正在使用 9090，可以將控制器改成 127.0.0.1:9091 或其他未占用的連接埠，重新載入核心後，記得同步修改 Web UI 的 API 位址。不要為了避開衝突而關閉 Windows 防火牆或隨意開放所有網路介面。

API 回傳 401 或 Web UI 無法登入

401 Unauthorized 幾乎都表示 Authorization 標頭中的密鑰不一致。確認 YAML 沒有多餘空格或引號差異，並確認請求格式使用 Bearer 加上一個空格，再接密鑰。若密鑰包含特殊字元，優先透過 Web UI 的輸入欄位或 PowerShell 變數傳入，不要在命令列中反覆直接貼上。

/ui 顯示 404 或空白頁

這通常表示 external-ui 指向的資料夾不存在、資料夾內沒有可用的前端，或目前核心不支援該路徑。先確認 Clash Verge Rev 的 Web 管理介面設定，再檢查核心工作目錄下是否真的有 ui 資料夾與入口檔案。若 API 的 /version 能正常回應，便不必重複修改代理節點或 DNS，應集中處理 Web UI 檔案與路徑。

完成設定後，建議保留一份不含密鑰的操作記錄，例如記下使用的控制連接埠、Web UI 路徑與設定檔名稱；真正的密鑰則放在安全位置。日後若發現控制器突然無法連線，可以依序檢查核心狀態、YAML 載入結果、TCP 連接埠、/version 回應與 Web UI 位址，通常比直接重裝 Clash Verge Rev 更快找到原因。