Clash API节点自动切换:external-controller 定时

为什么用 external-controller 来自动切换节点

在 Clash 或 Mihomo 里手动点节点,偶尔换换线路没问题;可要是你得长时间挂着下载任务、定时调海外 API、维护家里的服务器,或者想让几台设备用同一套运维逻辑,只在界面上点就跟不上了。external-controller 在本机开放了一套 HTTP 接口,脚本可以读当前配置、看代理组、测节点延迟,再把指定节点写进策略组。这样一来,选节点就从“凭感觉点”变成了脚本照着通断情况和你定的条件自己挑。

这里讲的是基于 Clash Meta 或 Mihomo 内核的自动化做法,常见的客户端有 Clash Verge、Clash Verge Rev、兼容 Clash for Windows 的环境、ClashX,以及 Clash for Android。(Clash for Windows 已经停止维护,新装建议换 Clash Verge Rev 这类仍在更新的客户端。)各客户端的菜单叫法可能不太一样,但只要内核开放了 external-controller,请求方式基本相同。要特别注意,API 只能操作眼下正在运行的那个 Clash 实例;它不会替你变出好节点,也修不了订阅本身失效的问题。自动化真正省掉的,是检查、挑选、切换、记录这几样重复的活。

💡
先想清楚要自动化什么

如果只想在几个节点里挑延迟最低的,用内置的 url-test 或 fallback 策略组就够了;要是还想排除丢包多的节点、限定地区、让业务尽量粘在一个出口上,或者切换后发个通知,再用 external-controller 配合 Shell、Python 或定时任务。

第一步:打开控制器,并把 API 保护好

控制器的监听位置写在配置里的 external-controller 字段,填的是地址加端口。多数人写 127.0.0.1:9090,意思是只有这台机器自己能连;改成 0.0.0.0:9090 后,同一局域网里的设备乃至外面的机器都可能摸到这个接口。做自动切换用不着把它开到公网,正式跑的机器上请绑在回环地址,再配一个足够随机的 secret。

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

Clash Verge Rev 这类图形客户端会把这两项放在「设置」「内核配置」或「外部控制器」之类的页面里。改完以后要确认内核真的加载了新配置,别只是改了一份没被启用的 YAML。验证方法很简单:浏览器里打开 http://127.0.0.1:9090/version,或者在终端里发下面这条请求:

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

拿到一段带版本号的 JSON,就说明地址和端口都通了;返回 401 Unauthorized 多半是 secret 填错,或者请求头写法不对;直接被拒绝连接,就去看内核有没有在跑、端口是否让别的程序占了、客户端是不是用的另一个控制器端口。secret 不要出现在公开仓库、截图和聊天里,也别图省事把认证关掉。

⚠️
控制器能改东西,别把它当只读接口

external-controller 除了查询,还能换代理、改一部分运行中的状态。把 0.0.0.0:9090 开到公网上,别人只要拿到 secret,就能从远处改掉你的出口。需要远程管理时,把它藏在 VPN、SSH 隧道或者收紧过的防火墙后面,控制器端口也别直接做转发。

第二步:搞清楚查节点和换节点分别调哪个接口

写脚本前,可以把接口按用途分成三组:状态接口看版本和运行情况,发现接口列出代理组和节点,控制接口负责真正的切换。别一开始就写循环去改配置文件,运行中的 Clash 大多能直接用 API 改掉某个策略组的当前选择,重启之后再按配置文件回到原样。

  • GET /version:看控制器能不能连上,顺便拿到内核版本。
  • GET /configs:查看运行中的配置,包括当前模式、监听设置、配置文件所在位置等。
  • GET /proxies:列出全部代理、代理组,以及每组此刻选的是哪个。
  • GET /proxies/{name}:看单个代理或代理组的细节。名字里有空格、中文或特殊符号的,要先做 URL 编码。
  • GET /proxies/{name}/delay:让指定代理跑一次延迟检测,参数里一般要带上 url 和 timeout。
  • PUT /proxies/{group}:给某个策略组指定当前节点,请求体多为 {"name":"节点名称"} 这种格式。

比如配置里有个叫 Auto 的手选组,先把它包含哪些成员查出来:

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

返回内容里 all 一般是能选的节点清单,now 是正在用的那个。节点名可能带空格、括号、国旗符号或斜杠,脚本别默认它只有字母和数字。拿到候选名单后,挨个调用延迟接口:

curl -s \
  -H "Authorization: Bearer replace-with-a-long-random-secret" \
  "http://127.0.0.1:9090/proxies/节点名称/delay?url=https%3A%2F%2Fwww.gstatic.com%2Fgenerate_204&timeout=5000"

检测用的地址要挑回应稳定、内容轻、又符合你出口需要的 URL。generate_204 用来判断通不通很合适,可延迟低不等于你要访问的 API 也能正常用;要是任务主要是拉代码、调 AI 接口或看视频,最好再加一个贴近真实用途的检查地址。接口返回延迟值后,可以给自己定一个可接受的上限;超时或报错的节点直接算作不可用,别把错误返回当成延迟最低。

选好节点,执行切换:

curl -s -X PUT \
  -H "Authorization: Bearer replace-with-a-long-random-secret" \
  -H "Content-Type: application/json" \
  -d '{"name":"日本东京 01"}' \
  "http://127.0.0.1:9090/proxies/Auto"

切完别急着当作万事大吉。再读一遍策略组,看 now 是否真换成了目标节点;脚本若负责要紧的任务,最好再真实发一次 HTTPS 请求,把 DNS、TLS、HTTP 状态码和耗时都看一眼。API 回成功,只表示控制器收下了指令,远端网站、订阅线路和业务登录是否正常是另一回事。

第三步:用 Shell 或 Python 把调度跑起来

环境简单的话 Shell 就够了:拿到组成员,逐个测延迟,排好序取第一个达标的,再调 PUT 接口切过去。写的时候要把「自动选择」「故障转移」「DIRECT」「REJECT」这类成员剔掉,免得把策略组当节点送去测延迟。备用线路、已过期的节点、地区不对的名字也要排除,不然挑出来延迟最低的那个未必适合你手头的活。

#!/usr/bin/env bash
set -euo pipefail

API="http://127.0.0.1:9090"
SECRET="${CLASH_SECRET:?CLASH_SECRET is required}"
GROUP="Auto"
TEST_URL="https://www.gstatic.com/generate_204"
TIMEOUT=5000

get_json() {
  curl -fsS -H "Authorization: Bearer ${SECRET}" "$1"
}

switch_node() {
  local node="$1"
  curl -fsS -X PUT \
    -H "Authorization: Bearer ${SECRET}" \
    -H "Content-Type: application/json" \
    -d "{\"name\":\"${node}\"}" \
    "${API}/proxies/${GROUP}"
}

get_json "${API}/version" >/dev/null
echo "Controller is reachable"
echo "Discover candidates from ${GROUP}"
# Production code should parse JSON with jq and URL-encode node names.
# Keep the selected node and measured delay in a log file.

上面这段骨架特意没把 secret 写死在文件里。Linux 上可以用环境变量、权限收紧的配置文件或者 systemd credentials 传进去;Windows 上可以放在当前用户的环境变量里,或者交给系统的凭据管理器。Shell 里解析 JSON 请用 jq,别靠截字符串去猜节点名,名字里一旦有引号、换行或 Unicode 符号,脚本就容易出岔子。

筛选条件一多,用 Python 写会好维护得多。给每个候选节点记下名字、延迟、失败原因、地区标签、上次成功的时间,再按几层规则排序:先扔掉检测失败的,再剔除延迟超过上限的,然后优先你要的地区,最后按延迟和上次切换时间排。这样脚本不会每次都盯着同一条线,也就不容易把单个节点压垮或者触发服务端的风控。

import os
import requests

API = "http://127.0.0.1:9090"
GROUP = "Auto"
TOKEN = os.environ["CLASH_SECRET"]
HEADERS = {"Authorization": f"Bearer {TOKEN}"}

group = requests.get(
    f"{API}/proxies/{GROUP}",
    headers=HEADERS,
    timeout=5
).json()

candidates = [
    name for name in group.get("all", [])
    if name not in {"DIRECT", "REJECT"}
]

for node in candidates:
    result = requests.get(
        f"{API}/proxies/{node}/delay",
        params={"url": "https://www.gstatic.com/generate_204",
                "timeout": 5000},
        headers=HEADERS,
        timeout=8
    )
    if result.ok:
        print(node, result.json().get("delay"))

# Select a validated node, then send a PUT request to the group.

定时检测别排得太密。每分钟扫几十个节点会建立大量连接,机场或目标网站也可能把这些探测当成异常流量。平时每隔 5 到 15 分钟查一次就行,只有当前节点连着失败两次、延迟一直超标,或者真实请求失败时才换。换完再加一段冷静期,比如 10 分钟内不再动它,避免几个定时任务撞在一起让线路来回乱跳。

ℹ️
用内置策略组还是自己写脚本

只想按延迟自动挑,url-test 就够了,配置少,内核自己会维护;想按顺序在备用节点之间兜底,用 fallback 更顺手。要做地区过滤、统计丢包、探测业务、发通知或者几台机器协同,才有必要上外部脚本。逻辑写得越复杂,越要把切换条件写明白,并且留好操作日志。

放到正式环境:权限、日志和出错后的恢复

在服务器或家里的网关上跑自动切换,最容易漏掉的是权限。脚本别一直用 root 或管理员身份运行,除非它确实要装服务;存 secret 的文件只让运行它的那个用户能读,日志目录也别让随便谁都能翻。控制器和脚本在同一台机器上时,绑 127.0.0.1 基本就够;非要跨机器调用,就走内网防火墙、带认证的反向代理或 SSH 隧道,别把控制器端口直接映射出去。

日志起码要写下这几样:一轮检测的起止时间、候选节点有几个、每个节点的延迟或失败原因、最后切到了哪里。完整的订阅地址、Authorization 请求头和 secret 都别往日志里写。节点名可以记,但名字里如果带账号、邮箱或服务商的私有标记,要先打码。日志还得设好轮转和保留天数,不然常年跑的探测程序可能把磁盘写满,反过来拖垮 Clash 和系统服务。

现象 优先检查 常见原因
连控制器时被拒绝 看监听地址、端口和内核是否在运行 控制器没开,或者端口撞了
返回 401 Authorization 请求头 secret 写错、前后多了空格,或者读到的是旧密钥
所有节点检测都超时 测试 URL、DNS、当前出站 检测地址本身连不上,或者检测请求没走你以为的那个代理
切过去没多久又自己切回来 看策略组类型和有没有并发任务 url-test、客户端界面、外部脚本三方同时在改
脚本说成功了,业务还是不通 看真实请求和命中的规则 延迟看着正常,可目标域名、TLS 或出口地区对不上

出问题时的处理思路是「能不换就不换」:当前节点还能把核心任务做完,就别因为一次延迟偏高立刻换掉;连续失败才把它放进候选池。切换失败时把旧节点记下来,必要时退回上一个确认可用的节点。SSH、数据库连接、上传这类长连接,一切换就会断掉现有会话,所以别把所有流量都交给一个经常变动的策略组。更稳的办法是把浏览、下载、开发接口和即时通讯分成几个策略组,只给真正需要自动恢复的那一组挂脚本。

升级 Clash 客户端或 Mihomo 内核之前,先把配置和脚本备份,顺手记下现在 API 的表现。内核版本不同,代理组字段、延迟检测参数、WebSocket 控制接口和报错格式都可能有出入。升级完按顺序验一遍:/version、读取策略组、测一个节点、手动切一次,都没问题再把定时任务打开。用 Docker 或 systemd 跑的,还要看容器网络、服务启动先后、环境变量在重启后还在不在。

常见问题排解

external-controller 能不能监听公网地址?

能做到,但不建议。控制器既能换代理又能读运行状态,开到公网上比一个只读监控接口危险得多。真要远程维护,先用 WireGuard、Tailscale 或 SSH 隧道进到可信网络,再让脚本去连回环或内网里的控制器;同时配上强 secret、防火墙白名单和访问记录,别只靠一个 Bearer Token 撑着。

延迟最低的节点就最稳吗?

未必。延迟检测反映的只是某个地址在某一刻的回应快慢,看不出丢包、带宽、TLS 握手、出口地区和长连接能撑多久。实际挑节点时,要把多次检测、失败次数、业务请求结果和冷静期一起考虑。对 AI 接口、流媒体或企业 SaaS 来说,能不能稳稳连上目标服务,比延迟上差那么一点要紧得多。

PUT 返回成功了,客户端界面怎么没变?

先把对应策略组的 now 重新读一次,核对请求里的组名和节点名是不是一字不差。如果 API 说成功、过一会儿又变回去,可能有另一个 url-test、fallback 或别的自动化脚本在管这个组,也可能你改的那个组压根没被规则用到。排查时先停掉全部定时任务,只手动发一次 PUT,再看连接日志和组的状态。

secret 在脚本里怎么存才稳妥?

别让 secret 进 Git 仓库、命令行历史或公开日志。Linux 上可以用权限设成 600 的环境文件、systemd credentials 或专门的密钥管理服务,Python 和 Shell 都能从环境变量里取。定期换密钥后,记得同步改服务配置、重启脚本,最后拿 /version 做一次带认证的请求,确认旧密钥已经不能用了。

和只能手动测延迟、节点刷新慢、或者老要改配置文件的客户端比,external-controller 加脚本更适合长期维护,代价是权限、日志和误切换都得自己操心。想先用图形界面把节点和策略组理顺,再慢慢接上 Shell 或 Python 调度,可以前往下载一个支持外部控制器的客户端,安装包取自官方 GitHub 发布页,按自己的需要一步步开启自动切换。