Clash API自动切换节点:健康检查与故障转移脚本
Clash 通过 API 自动切换节点是怎么回事
Clash 自动换节点,不是客户端凭空「猜」哪条线最好,而是靠配置里的策略组、健康检查参数和控制接口一起完成的。在 Mihomo(Clash Meta)内核的客户端里,external-controller 是一个本机的 HTTP 控制接口,脚本、监控平台或 CI 任务可以通过它读运行状态、查代理组、换当前节点,需要时还能重载配置。Clash Verge Rev、Mihomo Party、一些路由器上的 OpenClash 都可能有类似功能,但菜单名、API 路径和鉴权方式要以你当前的内核版本为准。
一条典型的自动化链路分四块:订阅或静态 YAML 给出节点,策略组决定节点怎么编排,url-test 或外部脚本负责判断能不能用,external-controller 再把结果交给正在运行的 Clash。内置健康检查适合持续、低开销地探测;外部脚本适合把业务延迟、地区、出错率、时段这些条件加进来。两者不是二选一,正式环境里多半先靠内置策略组保底,再用 API 定时校正、处理故障。
自动切换只看得出测试请求成没成功、延迟有没有超线,保证不了每个网站、每个账号、每条长连接都稳。调试时先锁定一个节点做基准,再一步步打开延迟检测和故障转移,别让策略组来回跳,否则问题根本没法复现。
配置 external-controller 与访问权限
先在 Clash 配置的最外层确认控制器监听在哪。一般这样写,端口按本机占用情况改:
external-controller: 127.0.0.1:9090
secret: "change-this-to-a-long-random-token"
127.0.0.1 只让本机访问,桌面端用它最安全。要是写成 0.0.0.0:9090,局域网甚至公网都可能看得到这个口,谁能连上谁就能读你的配置、看节点名、改代理组。所以除非真要让另一台监控机来访问,否则别监听所有网卡;非要远程控制的,在防火墙里限定来源 IP,再用 VPN、SSH 隧道或反向代理把传输护住。
secret 是调用 API 用的认证令牌。别用 123456、域名或示例配置里的默认字符串,也别把它推到 Git 仓库、发到聊天里或写进公开日志。脚本请求时一般在 HTTP Header 里带上 Authorization: Bearer,比如:
curl -s \
-H "Authorization: Bearer ${CLASH_SECRET}" \
http://127.0.0.1:9090/proxies
拿到 JSON 后,再从里面找策略组的名字。注意 API 看到的是正在跑的那份配置,不是你编辑器里还没加载的 YAML。改了配置文件而客户端没自动重载,脚本读到的仍是旧的策略组。排查时把配置文件放在哪、用的哪个 Profile、内核是哪个进程、控制器开在哪个端口都对一遍,免得请求发到了另一个 Clash 实例上。
常用的 API 操作,以及怎么确认生效
不同 Mihomo 版本字段可能有增减,常用的无非是读代理列表、查某个代理组、切换代理、触发配置重载。切策略组时,别把节点名不编码就直接拼进 URL,名字里可能有空格、括号或特殊字符。一个简单的 Shell 例子:
#!/usr/bin/env bash
set -eu
: "${CLASH_SECRET:?CLASH_SECRET is required}"
controller="${CLASH_CONTROLLER:-http://127.0.0.1:9090}"
group="${1:-自动选择}"
node="${2:?node name is required}"
curl --fail-with-body -sS \
-X PUT \
-H "Authorization: Bearer ${CLASH_SECRET}" \
-H "Content-Type: application/json" \
--data "$(printf '{"name":"%s"}' "$node")" \
"$controller/proxies/$(python3 -c 'import urllib.parse,sys; print(urllib.parse.quote(sys.argv[1], safe=""))' "$group")"
切完别光看 HTTP 状态码。再请求一次那个代理组,看返回里的 now 字段是不是已经变成目标节点;然后发一个真正的 HTTPS 请求,确认流量确实从新出口走了。API 回 200 只说明控制器收下了请求,不说明节点能访问你要的服务。
用 YAML 搭延迟优选、故障转移和回退
要是只想「挑延迟低的节点,坏了自动换」,用 Clash 自带的策略组就够,没必要一上来就写复杂脚本。下面是个简化例子,节点名换成你订阅里真有的:
proxy-groups: - name: 自动选择 type: url-test proxies: - JP-01 - SG-02 - US-03 url: https://www.gstatic.com/generate_204 interval: 300 tolerance: 80 - name: 故障转移 type: fallback proxies: - JP-01 - SG-02 - US-03 url: https://www.gstatic.com/generate_204 interval: 180 rules: - MATCH,自动选择
url-test 按设定的测试地址和间隔去探测候选节点,偏向选延迟低的出口;fallback 看重的是能不能用,当前节点挂了才去试下一个。探测地址要挑响应稳、体积小、不会跳登录的。公司网络要是拦了某个测试域名,所有节点都会被当成坏的,所以要用你所在网络能稳稳访问的地址。API、视频、游戏这些不同用途,也可以拆成几个策略组,各配各的规则和节点范围。
interval 设得太短,连接数会变多、设备被频繁唤醒,还可能惹来服务端风控;设得太长,坏节点又会一直占着流量。办公电脑可以先从 180 到 300 秒试起,移动网络或省电设备可以再放宽些。tolerance 是为了不让几毫秒的差距就触发切换,它并不是越小越好,稳往往比一时的最低延迟要紧。要登录、传文件或保持长连接的业务,调试完后最好把策略组改回手动,或者只在连续几次失败时才用 API 切。
204 探测成功,只能说明 TCP、TLS 和一个简单的 HTTP 请求走得通。流媒体能不能看、AI 服务认不认这个地区、WebSocket、UDP、某个 API 的响应,它都验证不了。正式用的脚本起码要给每次请求设上限时间、要求失败累计到几次才动、动过之后歇一阵,别因为一次网络抖动就全局换线。
上手:用 Shell 和 CI/CD 同步配置
下面这套流程适合开发者拿去改。一,在 Clash 客户端里备一份能回滚的配置,确认策略组名字不会变,每个候选节点都手动试过。二,控制器地址和密钥放进环境变量或 CI Secret,不准直接写死在脚本里。三,脚本先读当前组的状态,做一遍业务探测,连续失败了才发起切换。四,把最后选了谁、为什么失败写进结构化日志,方便分辨是 DNS、TLS、节点还是规则的问题。
- 打开 Clash Verge Rev 或 Mihomo 客户端,确认配置已加载,到设置里看 external-controller 用的端口。
- 调 API 查
/proxies,记下目标策略组里的候选节点,核对名字和 YAML 里一字不差。 - 锁住一个节点连试三次,把 DNS 解析、建连耗时、TLS 握手、HTTP 状态都记下来,当作正常时的基准。
- 跑自动化脚本:先读当前节点,再带超时去访问业务 URL;连着两次失败就换备用节点。
- 换完重新验证一遍,把选了哪个节点、几点换的、因为什么错、请求花了多久,推到日志平台或 CI 的构建摘要里。
Linux 和 macOS 上可以用 cron 或 systemd timer 定时跑,Windows 用自带的计划任务。流水线更适合干三件事:校验配置文件、刷新订阅、上线前检查,而不是直接去操控开发者电脑上常驻的进程。稳妥的流水线可以先用 YAML 解析器查缩进和字段,再确认策略组引用的节点都存在,然后给配置打上版本号,经受保护的部署通道分发出去。订阅 URL、API 密钥、控制器的 secret,一样都不能出现在构建输出里。
#!/usr/bin/env bash
set -euo pipefail
controller="${CLASH_CONTROLLER:-http://127.0.0.1:9090}"
group="${CLASH_GROUP:-自动选择}"
probe="${PROBE_URL:-https://example.com/health}"
status="$(curl --connect-timeout 5 --max-time 12 \
-o /dev/null -s -w '%{http_code}' \
-x http://127.0.0.1:7890 "$probe" || true)"
if [ "$status" != "200" ] && [ "$status" != "204" ]; then
echo "proxy probe failed: http_status=$status" >&2
exit 1
fi
echo "proxy probe passed: http_status=$status"
做得更完善一点,可以加一个节点冷却名单:某节点失败后十分钟内不再选它;所有节点都不行时就停下自动操作并报警,别没完没了地循环切换。还可以按时段记住选择结果,少让同一个账号频繁换出口、被迫做安全验证。几个服务共用一个 Clash 实例的话,切换只限于专门的策略组,不能为了救一个 API 把全局代理组换掉。
权限、日志排查和正式环境要当心的地方
安全上头一条是控制器能少暴露就少暴露。只在本机用就绑回环地址;要远程监控,就上访问控制列表、加密隧道和权限最小的账号。secret 定期换,换完把所有脚本、服务和 CI Secret 一起更新。路由器上别做端口转发把控制器开到外网,那份带着全部节点细节的 /configs 返回内容也别交给第三方监控平台。
排查时把三份日志按时间对起来看:Clash 的连接日志、自动化脚本的日志、目标服务自己的日志。API 回 401,先看 Bearer 后面的密钥对不对、请求是不是发到了正确的控制器;回 404,多半是策略组名、URL 编码或 API 路径对不上;回 500,就看当前内核支不支持这个操作。切换显示成功、实际流量却没变,就去查 TUN 有没有开、系统代理指向哪个端口、浏览器是不是有缓存,以及是不是另有一个 VPN 抢了路由。
节点全红时,别急着把探测频率调高。先确认订阅没过期、系统时间准、DNS 能解析测试域名,再看 TLS 报错是不是本机证书拦截造成的。只有一个服务出问题,先看规则命中和那个服务的地区限制;所有服务一起挂,再查端口监听、TUN 路由、网卡变动和上游线路。自动化系统还要有熔断:短时间内连续失败到一定次数就暂停切换并报警,免得脚本出错把网络波动越搅越大。
常见问题排解
external-controller 开着却连不上,怎么办?
先在客户端设置里确认控制器到底用哪个端口,再用本机的 curl 访问根地址。连接被拒绝,可能是内核没起来、端口被占了或者配置没重载;回 401 的话,重点查 Authorization 请求头。Windows 上还得看防火墙规则,以及客户端是不是用别的用户身份在跑。
url-test 挑出来的节点,为什么业务上不好用?
它默认只看一个地址的响应时间,可业务还会受出口地区、IP 风控、UDP、WebSocket、带宽和丢包影响。url-test 拿来做初筛就好,最终用哪个还得结合业务探测和人工判断,别光盯着面板上的毫秒数。
自动切换为什么老是来回跳?
多半是探测间隔太短、容差太小、测试地址本身不稳,或者几个候选节点延迟咬得太紧。把 tolerance 调大、interval 拉长,再加上连续失败次数和冷却时间,往往比一个劲加节点管用。
正式环境里,能让 CI 直接去切办公网络的 Clash 吗?
不建议把控制器端口直接露出来。更稳的办法是让本地受控的代理程序执行切换,CI 只负责发布校验过的配置或下发带签名的任务;密钥统统放进 Secret 管理系统,同时留好回滚版本和人工接管的开关。
想换一款仍在维护的客户端,可以去下载页按平台挑选,安装包取自各客户端的官方 GitHub 发布页,页面上附了 SHA256。