Clash external-controller API自动切换节点进阶配置指南

external-controller 是什么：把 Clash 节点管理变成可调用的 API

在 Clash、Clash Verge Rev 与 Mihomo 的配置体系里，external-controller不是代理流量经过的端口，而是一个供管理工具、脚本和自动化任务调用的控制接口。它通常监听在本机地址与端口上，例如 127.0.0.1:9090，客户端界面正是通过这类接口读取当前配置、查询代理组、发起延迟测试以及切换节点。理解这一点很重要：浏览器访问的业务流量走的是 mixed-port 或透明代理入口，而自动切换脚本访问的是 external-controller，两者端口、用途和安全边界完全不同。

通过 API 自动切换节点，核心流程可以拆成四步：先从控制器读取目标代理组，再取得组内节点列表；随后逐个或批量进行延迟探测，根据结果筛选可用节点；最后向代理组的选择接口发送切换请求。脚本不需要打开 Clash Verge 的窗口，也不依赖鼠标点击，因此特别适合远程服务器、无桌面 Linux、开发机、家庭网关和定时维护任务。当当前节点超时、延迟突然升高或出口不可用时，程序可以按照预设规则重试，而不是等用户发现网页打不开后手动处理。

不同客户端的界面名称可能不同，但只要底层使用兼容的 Clash 或 Mihomo API，接口思路基本一致。Clash for Windows、Clash Verge、Clash Verge Rev、Clash for Android 的版本支持范围并不完全相同，尤其是代理测速接口、控制器监听地址和鉴权字段可能存在差异。因此实际部署时不要只看客户端菜单是否有「外部控制」选项，还要在日志或配置文件中确认控制器确实已经启动，并记录准确的端口、密钥和当前代理组名称。

启用 external-controller：监听地址、端口与鉴权

配置 external-controller 时，最稳妥的做法是优先绑定回环地址，只让本机脚本访问。例如在 YAML 中使用 127.0.0.1:9090，可以避免同一局域网内的其他设备直接连接管理接口。如果你确实需要从另一台运维机管理服务器上的 Mihomo，才考虑监听局域网地址或所有网卡；此时必须同时配置强随机密钥、防火墙限制和访问来源白名单。把控制器直接暴露到公网而不设置鉴权，等于把切换节点、读取代理信息和修改运行状态的权限交给任何能够扫描到端口的人。

常见配置结构如下，端口可以按你的环境调整，密钥也应替换成长度足够的随机字符串：

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

修改后需要让核心重新加载配置，部分图形客户端还需要重启内核才能真正开始监听。可以在本机使用 curl 请求控制器的基础接口进行验证。如果返回版本信息或状态 JSON，说明端口已经工作；如果出现连接被拒绝，应先检查核心是否运行、端口是否被其他程序占用，以及当前客户端加载的是否正是你修改的那份配置。若返回未授权，则说明控制器可达，但请求缺少正确的鉴权头。

curl -H "Authorization: Bearer replace-with-a-long-random-secret" \
  http://127.0.0.1:9090/version

服务器环境中还要特别注意端口转发。不要为了方便把 9090 映射到 Docker 宿主机的公网网卡，也不要在 SSH 隧道、反向代理或面板中长期保留无密码转发。若必须远程操作，可以使用仅绑定本机的控制器加 SSH 隧道，让管理请求先经过加密登录通道，再从远端以本地地址访问，这比直接开放管理端口更容易审计和撤销。

读取代理组：确认组类型与真实节点名称

自动切换的第一步不是立即测节点，而是确认目标策略组。Clash API 通常可以通过代理组接口读取所有组及其当前状态，响应中会包含组名、组类型、当前选中节点以及可选的代理列表。脚本应根据组名寻找目标，而不是假定数组中的第一个元素就是代理组。机场订阅更新后，组的排序可能变化，节点名称也可能增加地区标识；依赖固定下标的脚本很容易把「DIRECT」、另一个策略组或故障节点当成切换目标。

实际使用时建议专门建立一个用途明确的策略组，例如 AUTO_SELECT 或 SERVER_PROXY，并确认它的 type 是 select、url-test 或其他当前内核支持的类型。若组本身是 url-test，内核已经具备周期性测速和自动选择能力，外部脚本不一定要重复测量；脚本更适合处理跨组决策、业务时段切换、失败后的通知以及复杂的优先级逻辑。若目标组是 select，脚本则可以根据外部测速结果主动写入当前节点。

节点名称必须使用 API 返回的原始字符串，包括空格、括号、地区符号和 emoji。不要根据显示文本自行截断，也不要把订阅里的代理键名与策略组中的展示名称混为一谈。较可靠的做法是先过滤掉 DIRECT、REJECT 和其他策略组，只保留真正可以作为出站代理的成员，然后再对名称做去重。对于同一地区存在多个倍率或协议版本的情况，可以把名称、延迟、失败次数和最近成功时间保存到本地状态文件，避免每次任务都从零开始。

延迟探测与自动选节点：不要只看一次测速结果

延迟探测接口通常需要目标代理组、测试 URL 和超时时间。测试 URL 应选择稳定、响应体较小且与你的业务场景相关的地址。测试搜索引擎首页只能说明某个 HTTPS 请求能完成，不能完全代表 API、代码仓库或长连接服务的质量；如果服务器主要访问软件仓库，就应选择稳定的仓库探针；如果主要调用接口，则应选择能够快速返回状态码的业务域名。探针不必追求内容正确，重点是 TLS 握手、连接建立和首字节响应是否在可接受时间内完成。

选节点时建议同时考虑超时、延迟、连续失败次数和冷却时间。例如把超过 2500 毫秒的结果视为不可用，第一次失败后立即重试一次，连续两次失败才加入冷却列表；低于 800 毫秒的节点优先，但不要为了 20 毫秒的差异频繁切换。频繁切换会中断已有 TCP 连接，也可能让 API、下载任务或 SSH 会话突然断开。服务器场景通常更看重稳定性，因此可以给「最近成功」和「连续可用」更高权重。

一个实用的评分模型是：先排除超时和明确失败的节点，再以延迟作为主要排序依据，同时给连续成功节点增加稳定性分数。如果当前节点仍在可接受范围内，就保持不变；只有当候选节点明显更快，或当前节点连续失败达到阈值时才切换。这样可以避免定时任务每五分钟重新选择一次节点，造成日志噪声和连接抖动。对于不同业务，还可以维护两套策略组：下载任务使用偏向吞吐的选择逻辑，交互式 API 使用偏向低延迟的逻辑。

目标：SERVER_PROXY
超时：2500 ms
失败重试：1 次
连续失败切换阈值：2 次
最小改善幅度：15%
冷却时间：10 分钟

切换请求、异常重试与定时任务

找到候选节点后，脚本需要向代理组的选择接口发送请求，通常以组名和节点名组成 JSON 数据。发送前应再次确认节点仍存在于当前组中，因为订阅可能恰好在测速期间完成更新。请求成功返回并不代表流量已经完全恢复，脚本还应等待短暂时间，再通过控制器读取代理组状态并执行一次实际连通性验证。只有「切换接口成功、当前节点状态已更新、探针请求成功」三个条件都满足，才可以把本次操作记录为成功。

异常处理至少要覆盖四种情况：控制器无法连接、鉴权失败、节点名称不存在，以及测速接口超时。控制器无法连接通常意味着核心退出、端口变化或防火墙拦截，此时继续重试并不能解决问题；鉴权失败应立即停止，避免把错误密钥持续写入日志；节点不存在多半来自订阅更新，应重新读取代理组；测速超时则可以切换到下一个候选节点。每次重试之间使用递增等待，例如 2 秒、5 秒、10 秒，并设置总时限，避免 systemd、cron 或 CI 任务无限挂起。

定时执行可以使用 Linux 的 cron、systemd timer、Windows 任务计划程序或容器编排平台。建议把任务拆成「健康检查」和「切换执行」两个阶段：健康检查只读取状态并记录结果，达到失败阈值后才允许修改代理组。脚本的标准输出应包含时间、目标组、旧节点、新节点、探针地址、延迟和失败原因，但绝对不要打印完整 secret。运行账号也应使用最低权限，配置文件和状态文件设置为仅该账号可读，避免密钥通过共享目录或公开日志泄露。

如果自动切换用于生产服务器，不要让它成为唯一的故障恢复机制。可以保留一个明确可用的手动备用节点，并在切换成功或全部候选失败时发送通知。部署前先在测试组中运行，确认不会误改主代理组；升级客户端或替换订阅后，也要重新核对 API 路径、组名和字段结构。Clash 与 Mihomo 的接口实现可能随版本变化，脚本应记录核心版本，并对未知响应做安全失败处理，而不是默认把空字符串当成合法节点。

与只依赖客户端图形界面的手动切换相比，传统桌面工具往往需要保持窗口运行，远程服务器上也缺少可复用的探测和重试机制；一些简单的定时脚本则只按节点顺序轮换，无法识别延迟、鉴权失败和订阅变更。Clash V.CORE 在这类 external-controller 自动化场景中更适合做统一入口：你可以结合策略组、实时日志、延迟测试和可审计的配置文件，把节点选择从一次性点击变成可回滚、可监控的运行流程。如果希望直接获得兼容日常桌面与服务器管理的客户端，可前往下载并按本文的控制器安全原则完成配置。