Clash external-controller API 切换节点脚本
external-controller 是干什么的:先搞清 API 能管到哪
在 Clash、Clash Verge Rev、Mihomo 这些客户端里,external-controller 可以看成本机程序能调用的一个管理口。图形界面不是唯一的操作方式,面板里能看到的分组、正在用的节点、连接列表和一部分运行状态,多半都能通过 REST API 读或改。只要内核启动时开了 external-controller,脚本不用打开客户端窗口,也能查策略组、换节点、读延迟结果。
这项功能最适合要自动换节点的场合。比如办公电脑工作日上午固定走一条低延迟线路,家里的服务器每隔几分钟看一次出口还通不通;又或者某个 API 连续超时后,由脚本替你把出口换成后备的那一个。和只靠客户端里的 url-test 比,用 API 自动化可以把业务状态、失败次数、时段、日志告警都算进去,逻辑也看得更清楚。
不过 external-controller 说到底是管理通道,不是平常的代理端口。mixed-port 负责承接浏览器和应用的流量,external-controller 负责接配置查询和控制指令。两个端口可以不一样,也最好不一样。一般这么配:
mixed-port: 7890
allow-lan: false
external-controller: 127.0.0.1:9090
secret: "replace-with-a-long-random-secret"
这里的 127.0.0.1:9090 意思是只有本机能访问控制接口,个人电脑上跑自动化脚本用它正合适。secret 是 API 的鉴权令牌,脚本调用时放进 Authorization: Bearer 请求头。别为了省事把密钥删掉,也别把控制端口直接开到公网;一旦没授权的人能访问,就可能改你的代理出口、看你的连接信息,甚至影响所有经过 Clash 的请求。
浏览器里要填 7890 这类 mixed-port,只有脚本的管理请求才发到 9090。两个端口搞混了,往往是浏览器那边报协议不对,脚本这边拿回一堆读不懂的内容。
第一步:用 REST API 拿到代理组和节点状态
自动切换之前,得先弄清配置里一共有几个分组。Mihomo 一般用 GET /proxies 来查,返回里有各个代理组、节点和当前选中的代理。不同客户端的内核版本可能不一样,具体字段以接口实际返回为准,别光看面板上的显示名去猜。
curl -s \
-H "Authorization: Bearer replace-with-a-long-random-secret" \
http://127.0.0.1:9090/proxies
返回的一般是一个 JSON 对象,最外层的 proxies 字段里列着代理名。策略组会带 all、now 等信息,单个节点可能还附带延迟记录、用量和过去的状态。脚本开头别把组名写死,先查一下目标组在不在。服务商一刷新订阅,组名说不定就从「Proxy」换成了「节点选择」,写死的定时任务就会天天报错。
查看某个策略组可以用下面这条请求:
curl -s \
-H "Authorization: Bearer replace-with-a-long-secret" \
"http://127.0.0.1:9090/proxies/节点选择"
命令行要是不会自动做 URL 编码,带空格、井号或中文的组名可能访问不到。工程上更稳的办法是在 Python 或 Node.js 里调用 URL 编码函数,别手动拼没处理过的名字。脚本至少要记下:目标代理组名、当前节点、候选节点清单、上次切换的时间,以及每个候选节点失败了几次。
节点健不健康,不只看延迟。有的节点延迟数字很好看,真发 HTTPS 请求时却老是被重置连接;有的能开普通网页,长连接或 API 响应却不稳。所以自动挑节点时,要把延迟高低、返回码、已经连败几回、上次切换后过了多久放在一起考虑,别每次都挑数字最小的那个。
调脚本时,先手动把这个组钉在某一个节点上,再去访问目标网站或 API,看 Clash 日志、命中的规则和返回结果。等 API 能控制、出口正确、业务请求也正常,再打开自动选择,免得好几个不确定的因素搅在一起。
第二步:用 PUT 请求切换代理组
通过 Clash API 切换代理组,核心就是往 /proxies/{group} 发一个 PUT 请求,请求体是 JSON,把 name 设成目标节点。下面这个例子把「节点选择」切到「日本 01」:
curl -X PUT \
-H "Authorization: Bearer replace-with-a-long-secret" \
-H "Content-Type: application/json" \
-d '{"name":"日本 01"}' \
"http://127.0.0.1:9090/proxies/节点选择"
收到成功的响应,也别马上认为流量好了。接口成功只说明控制通道接受了新选择,实际连接还可能被 DNS、TLS、目标服务风控或节点本身质量卡住。脚本切完要等一小会儿,再做一次轻量的健康检查,把结果和切换前的失败原因对应起来。不然节点还没建好连接,脚本就可能把它也误判成不能用。
落到实处,自动换节点大致分六步:
- 从配置里读出目标策略组,并确认这个组真的存在。
- 用
GET /proxies拿到候选节点,名字里写着已停用、已过期,或者标明专线专用的,先剔掉。 - 逐个对候选节点做延迟测试或真实的 HTTP 健康检查,记下响应时间和错误类型。
- 用
PUT /proxies/{group}选中候选节点,等连接状态稳下来。 - 让请求从代理端口出去,打一个稳定的探测地址,看域名解析、TLS 握手和返回的内容是否都正常。
- 把切换结果写下来,设好冷却时间,别让任务短时间里来回横跳。
自动切换最常见的毛病是来回抖。比如两个节点延迟只差一点,脚本每分钟测一次,网络稍微一波动,就可能在它俩之间反复切。可以加一个最小收益门槛:候选节点得明显快过现在这个,或者现在这个已经连挂两三回,才动手切。再设一个最短保持时间,比如切过去以后至少十五分钟内不因为一点延迟差异再换。
| 判断项 | 建议做法 | 避免的问题 |
|---|---|---|
| 延迟 | 用固定的测试地址,并设好超时 | 一次探活失败就误切换 |
| 失败次数 | 连续失败够次数才切 | 网络一闪断,节点跟着来回跳 |
| 冷却时间 | 切完保持一段时间不动 | 定时任务反复改写策略组 |
| 候选范围 | 把过期、专用和不兼容的节点排除掉 | 切到一条干不了正事的线路上 |
把脚本做成工程:YAML 拆分、鉴权和部署到服务器
规则、代理组和脚本越来越多以后,最不该做的就是全塞进一个几千行的 YAML。基础设置、代理来源、规则集、本机覆写可以各放一个文件,再用客户端支持的合并或覆写机制拼起来。拆开不是为了文件数量多,目的是订阅一刷新,不会把本机那套自动化设置冲掉,反过来也一样。
比如订阅只管节点和远程规则,本机的覆写文件里只放端口、控制接口、加强过的策略组和脚本要用的组名。刷新订阅前先备份当前配置,确认覆写语法和 Mihomo 版本还对得上。有些旧版 Clash 客户端认的字段,到新内核里可能改了名;启动失败时先看内核日志,别一遍遍点重新加载。
下面是一段精简过的 Python 脚本,只演示鉴权、读分组、发切换请求这几个基本动作;真要上线,还得把出错分类、日志按大小切分、探活逻辑和返回码补齐:
import os
import requests
CONTROLLER = os.getenv("CLASH_CONTROLLER", "http://127.0.0.1:9090")
SECRET = os.environ["CLASH_SECRET"]
GROUP = "节点选择"
TARGET = "日本 01"
headers = {
"Authorization": f"Bearer {SECRET}",
"Content-Type": "application/json",
}
response = requests.get(
f"{CONTROLLER}/proxies",
headers=headers,
timeout=5,
)
response.raise_for_status()
proxies = response.json().get("proxies", {})
if GROUP not in proxies:
raise RuntimeError(f"proxy group not found: {GROUP}")
switch = requests.put(
f"{CONTROLLER}/proxies/{GROUP}",
headers=headers,
json={"name": TARGET},
timeout=5,
)
switch.raise_for_status()
print(f"switched {GROUP} to {TARGET}")
密钥别写进公开仓库、定时任务的命令行或截图里。桌面上可以用系统环境变量,Linux 服务器上可以用只有管理员能读的环境文件或服务管理器的凭据功能。非要让局域网里另一台设备调 API 的,把监听地址限定在可信网卡上,防火墙只放行指定 IP;更安全的是把脚本就放在 Clash 所在的机器上,走回环地址访问,管理端口不用暴露给整个局域网。
部署到服务器时,可以用 systemd、Docker 或 cron 跑健康检查。不管哪种,都要考虑进程重启、网络还没就绪、订阅还没加载完、控制端口一时连不上这些情况。脚本启动后先反复尝试读 /version 或 /proxies,确认内核准备好了再开始切换。定时任务也别并发:上一轮检查没跑完,下一轮就不该同时去改同一个代理组。
排查用的日志至少留四样:请求时间和目标组、切换前后各是哪个节点、健康检查用的 URL 和状态码、API 返回的错误信息。订阅地址、访问令牌、完整请求头都别写进普通日志。碰到「脚本说成功了、网页还是打不开」,按顺序查:external-controller 连不连得上、策略组名对不对、代理端口正不正常、请求有没有命中预期规则、切过去的节点到底能不能访问目标。这样很快就能分清是控制通道坏了、代理通道坏了,还是目标站点自己有限制。
先手动调 API,再跑只读的健康检查;接着加上单次切换,最后才交给 cron 或 systemd 定时执行。每一步都留着可以回退的固定节点和原始 YAML,稳了再扩大候选范围。
有些代理工具只给一个封闭面板,节点坏了只能手动刷新、重新登录或者等客服,很难把健康检查接进自己的服务器和监控流程。Clash 系客户端开放了 API,配置细节都能自己掌握。想先用图形界面管好订阅和节点、再慢慢加脚本自动切换,可以到Clash站 下载页挑一个客户端,安装包取自官方 GitHub 发布页。