Clash Verge Rev 外部控制器在 macOS 如何設定？

外部控制器是什麼：先分清 API 與代理連接埠

在 Clash Verge Rev 裡，「外部控制器」不是用來承載一般網頁流量的代理連接埠，而是提供給 Web 面板、桌面管理工具或腳本呼叫的控制 API。許多 macOS 使用者第一次設定時，會把 mixed-port、socks-port 或 redir-port 當成外部控制器連接埠，結果瀏覽器可以透過代理上網，Web 面板卻一直顯示無法連線。兩者的用途完全不同：代理連接埠負責轉送應用程式流量，外部控制器則負責讀取核心狀態、切換策略組、查看連線、重新載入設定檔，以及讓管理介面取得目前節點資料。

你在 macOS 上使用的 Clash Verge Rev，通常會由內建的 mihomo 核心提供控制 API。介面文字可能因版本、語言或核心版本而略有不同，有時稱為 External Controller、外部控制器、API 位址或 Controller。真正需要對上的資訊只有三項：核心正在監聽的位址、控制器連接埠，以及 API 密鑰。Web 面板若還要求輸入完整 URL，通常格式會接近 http://127.0.0.1:9090；若密鑰已設定，還必須在面板中填入相同的 Secret。

這項功能特別適合需要細緻管理的人。例如你想在不打開主視窗的情況下查看目前連線，或想從瀏覽器面板切換 PROXY、GLOBAL、DIRECT 等策略，也可以透過控制器檢查某個網域實際命中了哪一條規則。不過，控制 API 等同於一個具有管理權限的本機入口，不能把它當成普通的狀態查詢服務來處理。位址與密鑰若暴露給其他裝置，對方可能讀取設定、切換節點，甚至影響整個代理核心的運作。

開始前的 macOS 與 Clash Verge Rev 檢查

在修改外部控制器之前，先確認 Clash Verge Rev 確實正在使用你以為的那份設定檔。若你有多個訂閱、覆寫檔或本地設定，畫面上的某個欄位不一定代表目前記憶體裡正在執行的核心配置。建議先打開 Clash Verge Rev 的主視窗，確認目前啟用的 Profile、核心狀態，以及目前使用的核心類型。若介面顯示核心尚未啟動，先處理 Profile 解析錯誤或核心啟動問題，否則即使填入正確的 API 位址，也不會有程序在該連接埠上等待請求。

macOS 的權限與網路環境也可能影響測試結果。若你同時開著其他 Clash 客戶端、VPN、網路加速器或開發用代理工具，應先暫時關閉不必要的程式。雖然外部控制器常見於 127.0.0.1，不會直接與遠端伺服器競爭，但多個核心可能使用相同的控制連接埠，後啟動的核心就可能因為 address already in use 而無法綁定。此時主介面可能仍然存在，但實際提供 API 的可能是另一個背景程序。

另外，請確認 macOS 的系統時間正常，並檢查 Clash Verge Rev 是否被放在「應用程式」資料夾中。從下載項目直接執行 App 不一定會造成控制器失效，但會讓權限、更新與設定檔位置更難追蹤。若你使用的是公司或學校管理的 Mac，MDM、端點防護或本機防火牆政策也可能限制應用程式建立本機監聽。這種情況不應直接關閉安全功能，而是先確認該政策是否允許本機回環連線。

在 Clash Verge Rev 設定外部控制器與 Secret

開啟 Clash Verge Rev 後，先進入設定或核心設定相關頁面，尋找名稱接近「外部控制器」「External Controller」「API」的欄位。不同版本可能把它放在一般設定、核心設定、覆寫設定或 YAML 編輯器中，因此不必只依照某一張舊版截圖尋找。你要找的是一組可以表示「位址加連接埠」的值，而不是代理模式選擇器。最適合本機管理的起點通常是：

external-controller: 127.0.0.1:9090
secret: "請換成長度足夠的隨機密鑰"

9090 只是常見示例，不代表每台 Mac 都必須使用這個數字。若該連接埠已被其他程序使用，可以改成其他未占用的本機連接埠，例如 9091 或 19090。重要的是，設定檔、Web 面板與實際監聽狀態必須三方一致。如果你在設定檔寫的是 127.0.0.1:9091，卻在面板填入 9090，面板自然會得到連線拒絕或等待逾時。

Secret 不建議使用姓名、生日、App 名稱或簡單的 123456。它雖然主要用於本機控制，但瀏覽器外掛、惡意網頁、錯誤的區域網路綁定位址，都可能讓過短密鑰變得容易被猜測。可以使用密碼管理工具產生一段隨機字串，並避免把密鑰貼進公開截圖、Git 儲存庫、聊天群組或文章留言。若你只在同一台 Mac 上使用 Web 面板，密鑰依然應該保留，因為「本機」不等同於「絕對沒有其他程序可以存取」。

修改後請儲存設定，並依 Clash Verge Rev 的提示重新載入設定檔或重啟 mihomo 核心。不要只關閉設定視窗就直接測試，因為有些欄位必須經過 Profile 重載才會寫入核心。重載後回到主畫面，確認核心狀態仍然是運行中，並留意日誌中是否出現控制器綁定失敗、YAML 解析失敗或密鑰格式錯誤。若核心因為一個縮排錯誤而沒有啟動，先恢復備份，再逐項加回外部控制器設定。

在 macOS 驗證控制連接埠是否真的可用

最可靠的排查方式不是先反覆刷新 Web 面板，而是先確認本機是否真的有程序監聽該連接埠。開啟「終端機」，執行下列指令，把連接埠替換成你的實際數值：

lsof -nP -iTCP:9090 -sTCP:LISTEN
curl -i http://127.0.0.1:9090/version

如果 lsof 沒有任何輸出，表示目前沒有程序在 9090 上監聽，問題應回到核心是否啟動、設定是否被載入，或連接埠是否寫錯。若輸出顯示其他程序占用該連接埠，請不要直接終止不明程序；先查看程序名稱與 PID，再決定是關閉另一個 Clash 客戶端，還是將 Verge Rev 改用新的連接埠。若 curl 回傳版本資訊，代表 TCP 層與基本 HTTP 路徑大致正常；若回傳 401 Unauthorized，反而可能是好消息，因為這通常表示控制器已連通，只是請求缺少正確的 Secret。

使用密鑰時，可以用 HTTP 標頭測試授權是否正確：

curl -i \
  -H "Authorization: Bearer 你的Secret" \
  http://127.0.0.1:9090/version

若回應為 200 OK 並包含核心版本資訊，表示控制器位址、連接埠與密鑰已對上。若回應是 401，請確認 Secret 沒有多餘空格、引號或換行；若回應是 404，可能是路徑或核心 API 版本差異；若是 Connection refused，則優先檢查監聽狀態，而不是先更換節點。這個分層方法能把「核心沒開」「連接埠錯誤」「驗證失敗」與「Web 面板設定錯誤」分開處理。

把 Web 面板連到 Clash Verge Rev

Web 面板通常會要求輸入 External Controller URL 與 Secret。URL 應與核心的監聽值一致，例如核心設定為 127.0.0.1:9090，面板可能要填 http://127.0.0.1:9090。有些面板會自動補上 http://，有些則不會；若畫面明確要求完整 URL，就不要只輸入數字連接埠。Secret 欄位則填入設定中的原始密鑰，不要把 Bearer 一起輸入，除非該面板的說明特別要求你自行填寫標頭格式。

連線成功後，先做低風險檢查：查看核心版本、列出代理節點、讀取策略組狀態，再嘗試切換一個非關鍵策略組。不要一連上就批量刪除節點、修改整份設定或重載訂閱。部分 Web 面板會把控制 API 的能力包裝得很方便，但它們對不同 mihomo 版本的支援不一定完全一致。若面板能顯示狀態，卻在切換策略時報錯，可能是 API 權限、欄位格式或核心版本相容性問題，不一定代表外部控制器斷線。

若你希望從 iPhone、iPad 或另一台 Mac 管理這個控制器，必須重新評估綁定位址。把 127.0.0.1 改成區域網路位址或 0.0.0.0，代表控制器不再只接受本機請求。除了設定強密鑰，還要確認 macOS 防火牆、家用路由器、Wi-Fi 隔離與目前網路是否可信。更安全的做法是透過受控的 VPN 或 SSH 通道轉發本機連接埠，而不是把管理 API 直接暴露在公共網路上。

無法連線時的系統化排查順序

第一層先確認「設定是否真的生效」。重新載入後查看核心日誌，搜尋 external-controller、listen、bind 或 secret 等關鍵字。如果設定檔由訂閱更新自動覆蓋，本地手動新增的控制器欄位可能在下一次更新後消失。此時應使用 Clash Verge Rev 的覆寫功能或本地補丁，避免每次更新訂閱都把設定洗回原狀。不要把一份完整訂閱直接複製到另一個檔案後長期手動修改，否則日後很難判斷到底是哪一層配置在生效。

第二層確認位址格式。127.0.0.1:9090、localhost:9090與 0.0.0.0:9090 的用途不同；Web 面板若在同一台 Mac 執行，優先使用回環位址。若使用 IPv6，還可能需要符合面板要求的括號格式，例如 http://[::1]:9090，不能把 IPv6 位址直接當成普通 IPv4 字串。若你不確定，先回到 IPv4 回環位址完成本機驗證，再處理跨裝置需求。

第三層檢查瀏覽器本身。某些面板以 HTTPS 開啟，卻嘗試呼叫 HTTP 的本機控制器，瀏覽器可能因混合內容政策拒絕請求；也有面板使用 CORS 或 WebSocket，導致基本 curl 測試成功，但瀏覽器仍報跨來源錯誤。此時請查看 Safari、Chrome 或面板開發者工具的 Network 與 Console 訊息，分辨是 CORS、WebSocket、TLS 還是單純 401。不要因為看到紅色錯誤就立刻認定 mihomo 核心故障。

第四層才處理 macOS 安全與程序衝突。檢查是否有第二個核心、舊版 ClashX、VPN 代理服務或測試腳本佔用同一連接埠；必要時重新啟動 Clash Verge Rev，但不要在尚未備份設定的情況下刪除整個資料目錄。若問題只在睡眠喚醒後出現，可以觀察核心是否被系統終止、連接埠是否重新綁定，以及面板是否仍保留舊的 WebSocket 連線。重新整理面板有時能恢復顯示，但若 lsof 顯示監聽已消失，仍需從核心日誌找原因。

排查原則：先證明「有程序監聽」，再證明「HTTP 可以回應」，接著驗證「Secret 正確」，最後才處理 Web 面板的相容性與瀏覽器政策。按這個順序排查，比單純反覆更換連接埠或節點更有效。

密鑰安全、備份與日後維護

外部控制器設定完成後，建議把目前有效的 YAML 或覆寫內容備份一份，並記錄控制器連接埠與面板 URL，但不要在同一份文字檔中明文保存 Secret。若你要把設定同步到另一台 Mac，應透過密碼管理器或安全通道傳送密鑰，而不是直接把整份設定貼到雲端筆記。完成測試後，可以查看 macOS 的瀏覽器網站資料與已儲存表單，確保不會因共用電腦而留下控制器密鑰。

每次更新 Clash Verge Rev 或 mihomo 核心後，都應重新測試一次 /version、策略組讀取與基本切換。核心 API 的端點、欄位或驗證行為可能隨版本改變，舊 Web 面板也可能依賴已被調整的回應格式。若你發現只剩部分功能可用，不要立即把所有設定改回預設；先記錄核心版本、面板版本、HTTP 狀態碼與日誌，再對照發行說明。這份紀錄對於判斷是版本相容性還是設定覆蓋非常有幫助。

常見問題

外部控制器一定要使用 9090 嗎？

不一定。9090 只是常見示例，任何未被其他程序占用、且符合本機安全政策的連接埠都可以使用。設定完成後，必須讓核心、Web 面板與測試指令使用同一個連接埠；若改用 9091，面板 URL 也要同步改為 http://127.0.0.1:9091。

Web 面板顯示 401，代表控制器壞了嗎？

通常不是。401 多半表示控制器已經收到請求，但 Secret 不存在、不正確或格式不符合面板要求。先用 curl 搭配 Authorization: Bearer 標頭測試，再檢查面板是否要求只輸入密鑰文字。

可以讓同一個 Wi-Fi 的手機連線嗎？

技術上可以，但需要把監聽位址、macOS 防火牆、路由器隔離與 Secret 一起考慮。外部控制器具有管理能力，不建議為了方便而直接暴露到公共網路。若只是偶爾遠端操作，透過 VPN 或 SSH 通道轉發通常比開放 0.0.0.0 更容易控制。

為什麼更新訂閱後外部控制器設定消失？

這通常是因為訂閱更新覆蓋了手動修改的主設定檔。請將外部控制器欄位放到 Clash Verge Rev 支援的覆寫層、本地補丁或獨立配置中，並在更新後檢查實際載入結果。不要只在訂閱原文上直接修改，因為下一次更新仍會把本地變更取代。

相較於只提供基本代理開關的舊式 macOS 客戶端，ClashX 類工具在外部控制器的位置、密鑰管理與 Web 面板相容性上往往缺少清楚的檢查流程；部分簡化型 VPN App 甚至無法查看策略組、連線日誌或核心 API 狀態。Clash V.CORE 則能以 mihomo 核心為基礎，讓你在 Clash Verge Rev 這類介面中集中管理外部控制器、策略切換與連線診斷，並透過本機綁定與 Secret 降低暴露面；如果你希望在 macOS 上更穩定地完成設定並保留完整控制能力，可以前往下載頁取得 Clash V.CORE，再依本文的驗證順序建立自己的管理環境。