Clash Verge Rev 外部控制器怎么在 macOS 开启？

Clash Verge Rev 外部控制器是什么，macOS 用户为什么需要它

Clash Verge Rev 外部控制器（external-controller）是 Clash 或 Mihomo 内核提供的一组 HTTP API 入口。它不负责直接产生代理流量，而是让受授权的 Web 面板、桌面工具或命令行程序读取运行状态、切换代理节点、修改模式、查看连接以及关闭指定连接。换句话说，系统代理和 TUN 负责“让应用的流量进入 Clash”，外部控制器则负责“让另一个管理工具控制正在运行的 Clash”。

在 macOS 上开启它，常见用途包括：用浏览器打开 Yacd、MetaCubeXD 等 Web 面板；在调试规则时查看某个域名实际命中了哪条规则；远程观察家中 Mac 的内核状态；或者通过 API 脚本切换策略组。很多用户能正常访问代理，却找不到 Web 面板，原因往往不是面板地址错误，而是 Clash Verge Rev 仍未监听控制器端口，或者控制器只绑定了本机地址、面板却使用了错误的访问地址。

需要先区分三个概念。HTTP 代理端口或 mixed-port 是给浏览器、终端和其他应用使用的；TUN 是虚拟网卡入口，负责接管没有读取系统代理的程序；external-controller 是管理 API 端口，通常不能拿来当普通网页代理端口。把三者混用，可能出现浏览器无法联网、面板显示连接失败，甚至把管理接口错误暴露到局域网的情况。

开启前的准备：确认内核、配置与监听端口

Clash Verge Rev 的界面版本、内核版本和配置来源不同，菜单名称可能略有差异。你可能在「设置」「常规」「内核」「外部控制器」或「控制器」区域看到相关选项，也可能需要打开当前配置文件的 YAML 编辑器。本文使用的关键字段是 external-controller 与 secret，因此即使图形界面改版，也可以用字段搜索定位，而不必完全依赖截图中的菜单名称。

动手前先确认 Clash Verge Rev 已经成功启动内核，并且当前配置确实处于活动状态。打开主窗口的运行状态、日志或代理页面，确认不是只有程序外壳在运行而内核处于停止状态。若配置来自远程订阅，还要注意服务商更新配置时可能覆盖本地修改；如果你直接编辑生成的订阅文件，下一次更新后外部控制器字段可能消失。长期使用时，应把控制器设置放在客户端的全局配置、覆写配置或不会被订阅覆盖的本地扩展区域。

端口可以使用常见的 9090，也可以选择本机其他未被占用的高位端口，例如 9097。端口不是越特殊越安全，真正重要的是绑定地址、密钥和访问范围。若 macOS 上已有其他服务占用该端口，Clash 可能启动失败或日志中出现 bind error。建议选择一个固定端口，并在记事本中记录它，后续配置 Web 面板和排障时不容易混淆。

如果你同时运行多个 Clash 客户端，例如 Clash Verge Rev、ClashX Pro 和其他 Mihomo GUI，每个内核都需要使用不同的代理端口和控制器端口。否则即使配置看起来正确，也可能出现端口占用、面板连接到了另一套内核，或者切换节点后实际生效的并不是你正在查看的那一个客户端。

通过 Clash Verge Rev 设置页开启外部控制器

最简单的方法是使用 Clash Verge Rev 的图形设置。打开应用主窗口，进入与「设置」或「常规」相关的页面，寻找 External Controller、外部控制器、Controller Address 或类似名称的输入框。将监听地址填写为 127.0.0.1:9090，再在密钥或 Secret 输入框中填写一组新的随机字符串。保存后，通常需要重新加载配置、重启内核，部分版本还需要完全退出并重新打开 Clash Verge Rev。

地址中的冒号前是监听 IP，冒号后是端口。127.0.0.1:9090 表示只接受当前 Mac 自己发出的请求；如果填写 0.0.0.0:9090，则意味着监听本机所有网络接口，局域网内其他设备可能也能发现这个端口。对只想在本机打开 Web 面板的用户而言，前者更加合适。不要为了“让面板能连上”就直接改成 0.0.0.0，这会把问题从地址配置扩大为网络安全问题。

密钥建议使用至少二十位的随机字符串，包含大小写字母、数字和符号，并且不要与机场密码、Apple ID 密码或其他管理后台重复。部分版本允许密钥为空，但不建议这样做，因为控制器 API 能够切换节点、读取连接信息，某些接口还可以修改运行参数。即便监听地址是本机，浏览器扩展、恶意网页或本机其他进程也可能尝试访问开放接口，设置 Secret 仍然是必要的保护层。

保存后回到主界面，观察内核日志是否出现类似 controller started、external controller listening 或监听地址成功的提示。若没有看到明显日志，不代表一定失败，因为不同版本的日志级别和文字不同；可以使用下面的本机测试确认端口是否真正工作。

curl -i http://127.0.0.1:9090/version \
  -H "Authorization: Bearer 替换为你的密钥"

如果返回包含版本信息的 JSON，说明控制器已经可以响应请求。如果返回 401 Unauthorized，通常表示端口可达，但密钥为空、密钥不一致或请求头格式错误；如果出现 Connection refused，则更像是内核未运行、端口填错或控制器没有成功监听。测试完成后不要把真实密钥复制到公开工单、截图或 Git 仓库中。

在 YAML 配置中手动写入 external-controller 与 secret

当设置页面没有对应开关，或者图形界面的值保存后总是被覆盖，可以打开当前活动配置的 YAML 编辑器，在顶层字段区域加入控制器配置。字段必须放在顶层，不能缩进到 proxy-groups、rules 或某一个代理节点下面。一个最小示例如下：

mixed-port: 7890
mode: rule

external-controller: 127.0.0.1:9090
secret: "请替换为随机密钥"

这里的 mixed-port 只是示例，不能因为照抄控制器配置而覆盖你原有的代理端口。你可以保留现有的 port、socks-port 或 mixed-port，只新增 external-controller 和 secret。YAML 对缩进、冒号和引号比较敏感，建议使用两个空格缩进，避免把 Tab 键混入配置文件。密钥含有特殊字符时加双引号，可以降低解析歧义。

修改前先复制一份完整配置作为备份，文件名可以包含日期，例如 config-backup-2026-07-25.yaml。保存后让 Clash Verge Rev 重新载入配置，并查看是否出现 YAML parse error。如果客户端拒绝启动，不要继续添加其他字段，先恢复备份，再逐项检查冒号后是否有空格、引号是否成对、字段是否位于顶层。

订阅覆盖是手动配置最常见的陷阱。有些订阅更新功能会重新下载完整 YAML 并替换本地文件，导致你刚加入的控制器字段消失。验证方法很简单：成功开启后先记录当前设置，再手动执行一次订阅更新，重新检查控制器页面和 /version API。如果更新后端口失效，就需要改用 Verge Rev 的覆写功能，或者建立一个本地补丁配置，把控制器字段作为固定覆盖项合并到远程配置中。

连接 Web 面板：地址、密钥与权限验证

控制器启动后，还需要一个能调用该 API 的 Web 面板。Clash Verge Rev 某些版本内置面板入口，其他版本则需要在设置里指定本地面板目录，或通过客户端提供的面板管理页面安装。打开面板时，控制器地址通常填写为 http://127.0.0.1:9090，Secret 填写刚才设置的密钥。若面板运行在同一台 Mac 上，不要把地址写成机场节点地址、Mac 的公网地址或 Web 面板自身的静态资源地址。

面板登录成功后，可以先查看版本、运行模式和代理组，再进行节点切换。建议先执行低风险操作，例如读取当前模式或查看代理组状态，确认面板连接的是正确内核后，再尝试切换策略组。若你打开的是旧版 Yacd 或其他面板，字段名称可能与当前 Mihomo 内核存在差异，部分高级策略组、规则提供者或连接详情可能无法完整显示，这不一定代表 Clash Verge Rev 配置错误。

如果浏览器提示跨域、无法连接或 WebSocket 失败，先不要立刻改防火墙。第一步是在终端用 curl 请求 /version，确认控制器本身可用；第二步检查面板设置中的控制器地址是否少写端口；第三步确认 Secret 没有多余空格或换行。只有 API 已经能在终端正常返回，而面板仍然失败时，才需要进一步检查面板版本、浏览器缓存和 WebSocket 兼容性。

部分面板会把密钥保存在浏览器本地存储中。如果你在共享 Mac、公共测试账户或远程桌面环境中使用，退出面板后应清理浏览器站点数据，并在怀疑密钥泄露时立即回到 Clash Verge Rev 修改 Secret。改密钥后，旧面板会全部失去权限，这也是处理未知访问记录时最直接的应急措施。

需要局域网访问时，如何降低外部控制器风险

默认的 127.0.0.1 只允许 Mac 本机访问。如果你希望在同一 Wi-Fi 下用 iPhone、iPad 或另一台 Mac 查看控制状态，就必须让控制器监听局域网接口，例如填写 Mac 当前局域网地址加端口，或在确认风险后使用 0.0.0.0:9090。前者的暴露范围更容易理解，后者虽然配置简单，却可能同时监听多个网络接口，因此不建议在公共 Wi-Fi、酒店网络或公司访客网络中使用。

开放局域网访问前，先在 macOS「系统设置 → 网络」中确认当前 Wi-Fi 的网络类型和 IP 地址，再检查应用防火墙是否允许 Clash Verge Rev 接收传入连接。路由器侧不要设置端口转发，不要把 9090 映射到互联网，也不要把控制器端口加入任何公网反向代理。外部控制器的 API 权限通常比普通状态页更高，一旦密钥泄露，攻击者可能切换代理、读取连接目标，甚至调用内核提供的管理接口。

如果只是偶尔远程管理，更推荐使用安全的组网工具或 SSH 隧道，而不是长期暴露控制器端口。例如可以把本地控制器通过 SSH 隧道映射到远程设备的回环地址，再让面板连接远程端的 127.0.0.1。这样控制器仍然只绑定 Mac 本机，传输层由 SSH 负责加密和认证。具体命令应根据你的 SSH 账户、端口和网络拓扑调整，不要直接复制不理解的端口转发参数。

排障原则：能不开放局域网，就不要开放；能用本机面板，就不要把控制器绑定到所有接口；能定期轮换 Secret，就不要长期复用一条容易猜测的密码。管理便利性应建立在最小暴露面之上。

常见故障排查：端口、密钥与配置被覆盖

浏览器显示无法连接或 Connection refused

先确认 Clash Verge Rev 内核是否正在运行，再确认端口号是否与设置页或 YAML 中完全一致。终端可以执行 lsof -nP -iTCP:9090 -sTCP:LISTEN 查看 9090 是否有进程监听；如果没有结果，说明控制器没有在该端口启动。若有其他程序占用端口，应换用新的端口并重启内核。若端口监听存在但控制器仍无法使用，继续查看内核日志是否有地址格式错误或配置解析失败。

401 Unauthorized 或面板一直要求输入密钥

这通常不是代理节点问题，而是认证请求没有通过。确认面板使用的是 Bearer Secret 方式，并重新手动输入密钥，避免从带有换行符的密码管理器中复制。YAML 中如果密钥包含 #、冒号或引号等字符，建议用双引号包住并检查转义。为了快速定位，也可以暂时生成一条只含字母和数字的随机密钥，验证成功后再换成更复杂的版本。

重启或更新订阅后控制器设置消失

如果控制器配置只写在订阅生成文件里，更新订阅时被覆盖是正常现象。应检查 Clash Verge Rev 是否提供「覆写」「本地配置」「扩展配置」或「Merge」入口，把控制器字段放到固定的本地层。修改后连续测试一次普通重启和一次订阅更新，确认字段都能保留。不要通过修改缓存目录中的临时文件来解决，因为客户端升级或清理缓存后仍可能丢失。

FAQ：macOS 外部控制器设置的常见问题

外部控制器端口可以和 mixed-port 相同吗？

不可以。两者是不同的监听服务，通常不能绑定同一个 IP 和端口。mixed-port 用于接收应用代理流量，external-controller 用于接收管理 API 请求。建议分别使用例如 7890 和 9090，并在面板设置中填写控制器端口，而不是填写代理端口。

Secret 可以不设置吗？

技术上部分内核允许空 Secret，但不推荐。控制器接口涉及状态读取和运行控制，空认证会增加本机脚本、浏览器扩展或局域网设备误调用的风险。即使只绑定 127.0.0.1，也应设置随机密钥，并避免把密钥写进公开截图、配置仓库或聊天记录。

打开 Web 面板后看不到节点，是控制器坏了吗？

不一定。先用 /version API 确认控制器可用，再检查面板是否连接到了正确端口和正确内核。面板版本过旧、当前配置没有活动节点、配置更新后策略组结构变化，都会造成界面空白或信息不完整。还要确认 Clash Verge Rev 当前启用的是你刚才修改的那份 Profile。

局域网访问一定要使用 0.0.0.0 吗？

不一定。优先考虑绑定 Mac 的局域网 IP，并在不需要远程管理时恢复为 127.0.0.1。如果确实使用 0.0.0.0，必须配合强密钥、macOS 防火墙和路由器不做端口转发，且不要在公共网络中开启。远程访问需求稳定时，SSH 隧道或安全组网通常比直接暴露控制器更稳妥。

与一些只提供简化菜单的代理客户端相比，ClashX Pro 等轻量工具上手路径更短，但在外部控制器密钥管理、配置覆写、Web 面板兼容性和内核日志方面往往不够完整；部分第三方面板也可能因为 API 版本滞后而无法显示最新策略组。Clash V.CORE 则更适合需要在 macOS 上长期管理多份配置的用户：它保留清晰的控制器入口、支持安全密钥与本机绑定，便于结合 Web 面板、连接日志和规则调试逐项验证。完成本文设置后，如果你希望使用更完整的 Clash 内核能力，可以前往下载 Clash V.CORE，再按自己的配置和网络环境迁移使用。