手动打开 Clash 客户端、进入代理组再逐个测试节点,适合偶尔切换,却不适合需要长时间运行的电脑、开发环境或服务器。Mihomo 提供的 external-controller 控制接口可以让脚本读取代理组成员、测试节点延迟,并通过接口切换策略组。自动化的关键不是“发现一个延迟最低的节点就立刻切过去”,而是先确认接口只对可信访问者开放,再加入超时、失败处理和切换门槛,避免短暂抖动造成频繁切换。
本文以本机运行的 Mihomo API 为例。Clash Verge、Clash Verge Rev 等客户端通常会管理内核配置,界面菜单和覆写方式因版本不同而异;无论使用哪种客户端,都应先确认当前运行内核支持相关 API,且脚本连接的是正在工作的那个内核,而不是另一个旧实例。
Clash API节点自动切换:脚本配置与工程实践
准备 external-controller 控制接口
external-controller 是供客户端或外部程序读取运行状态、管理代理组的 HTTP 控制接口。它与 mixed-port、socks-port 等代理监听端口用途不同:代理端口转发应用流量,控制端口接收管理请求。脚本不能把代理端口当成 API 地址使用。
在配置中确认控制接口监听地址,并设置访问密钥。仅在本机运行脚本时,通常绑定到回环地址,例如:
external-controller: 127.0.0.1:9090
secret: "替换为足够长且随机的密钥"
修改配置后,按客户端支持的方式重新载入配置或重启内核,再从运行日志确认配置已生效。不要只看 YAML 文件:订阅更新、客户端覆写或配置合并可能改变最终运行值。脚本中的 API 地址、端口和密钥必须对应当前内核实际使用的设置。
调用 API 时,认证信息放在 HTTP 请求头 Authorization: Bearer 密钥 中。Mihomo 的常用接口包括:
GET /proxies:读取代理、策略组及其状态。GET /proxies/{名称}:读取指定代理或策略组信息。GET /proxies/{名称}/delay?url=...&timeout=...:测试代理到指定测试地址的延迟。PUT /proxies/{策略组名称}:将策略组切换到请求体指定的代理。
API 路径中的名称可能包含空格、斜线或非 ASCII 字符,拼接 URL 时必须进行路径编码。测试接口返回的是一次探测结果,不等于持续带宽、真实业务成功率或所有目标站点的访问质量。某些接口字段与行为会随内核版本变化,遇到 404 或响应结构不同,应先检查实际内核和版本,而不是假定所有 Clash 兼容实现完全相同。
读取策略组并测试候选节点
自动切换前,先确定要管理的策略组名称,例如配置中的 手动选择、Proxy 或 自动选择。名称必须与当前运行配置完全一致。调用 GET /proxies 后,可以在返回 JSON 的 proxies 对象中找到该策略组;组对象通常包含当前选择的 now 以及可选成员 all。all 中可能既有普通节点,也有 DIRECT、其他代理组或特殊策略,因此不能无条件把每一项都当成可用节点。
对候选项逐一请求延迟接口时,应给测试地址和超时设置明确值。常见测试地址是返回空响应的 HTTPS 检测页面;选择时要考虑网络环境是否能稳定访问该域名。超时过短会把偶发拥塞误判成节点故障,过长则会让每轮检测拖得很久。比如将单次超时设为 5000 毫秒,并在脚本侧再设 HTTP 请求超时,可以避免请求无限等待。
下面的 Python 示例使用标准库,不需要额外安装依赖。它读取策略组成员、逐个测试延迟,选择低于设定上限的候选项,并在当前节点已经可用时避免因几毫秒差异立即切换。运行前通过环境变量提供密钥,并根据实际配置调整地址、组名和测试参数。
import json
import os
import time
from urllib.error import HTTPError, URLError
from urllib.parse import quote, urlencode
from urllib.request import Request, urlopen
API = "http://127.0.0.1:9090"
GROUP = "手动选择"
TEST_URL = "https://www.gstatic.com/generate_204"
PROBE_TIMEOUT_MS = 5000
HTTP_TIMEOUT = 8
MAX_DELAY_MS = 3000
IMPROVEMENT_MS = 80
SECRET = os.environ["CLASH_SECRET"]
def call_api(method, path, data=None):
body = None if data is None else json.dumps(data).encode("utf-8")
request = Request(
API + path,
data=body,
method=method,
headers={
"Authorization": "Bearer " + SECRET,
"Content-Type": "application/json",
},
)
with urlopen(request, timeout=HTTP_TIMEOUT) as response:
content = response.read()
return json.loads(content.decode("utf-8")) if content else {}
def encoded_path(name):
return quote(name, safe="")
group_path = "/proxies/" + encoded_path(GROUP)
group_info = call_api("GET", group_path)
members = group_info.get("all", [])
current = group_info.get("now", "")
candidates = [
name for name in members
if name not in ("DIRECT", "REJECT") and name != GROUP
]
results = []
for name in candidates:
query = urlencode({
"url": TEST_URL,
"timeout": str(PROBE_TIMEOUT_MS),
})
path = "/proxies/" + encoded_path(name) + "/delay?" + query
try:
result = call_api("GET", path)
delay = int(result["delay"])
if 0 < delay <= MAX_DELAY_MS:
results.append((delay, name))
except (HTTPError, URLError, TimeoutError, KeyError, ValueError) as error:
print("节点测试失败:", name, error)
if not results:
raise SystemExit("没有通过延迟测试的候选节点,保持当前选择。")
best_delay, best_name = min(results)
current_result = next(
(delay for delay, name in results if name == current),
None,
)
if current_result is not None and best_delay + IMPROVEMENT_MS >= current_result:
print("当前节点仍可用,暂不切换:", current, current_result, "ms")
else:
call_api("PUT", group_path, {"name": best_name})
print("已切换到:", best_name, best_delay, "ms")
time.sleep(1)
print("切换请求已发送;请检查连接记录确认实际路由。")
设置环境变量后再运行脚本,避免将密钥作为命令行参数留在历史记录中。Linux 或 macOS 的当前 Shell 可使用 export CLASH_SECRET='实际密钥';PowerShell 可使用 $Env:CLASH_SECRET = '实际密钥'。如果脚本报告连接被拒绝,先检查 API 地址、端口和内核状态;如果返回 401 或 403,重点核对密钥及请求头;如果接口返回组名不存在,则从 GET /proxies 的结果中复制实际名称。
设置切换门槛,避免频繁抖动
单次延迟测试只代表某个时间点、某个目标地址的往返时间。网络拥塞、DNS、测试站点状态和节点负载都会影响结果。若脚本每隔几十秒就选择数字最小的节点,可能在两个相近节点之间来回切换,导致长连接中断、下载重连或登录会话失效。示例中的 IMPROVEMENT_MS 是切换迟滞:新节点至少比当前节点快一个设定幅度,才允许切换。
实际运行时还可以增加以下约束,让选择逻辑更适合工作流:
- 连续失败才判定不可用:对当前节点连续测试两到三次;一次超时先记录,不立即切换。
- 多次采样取中位数:对候选节点重复探测,使用中位数降低单次异常值的影响。
- 设置最短驻留时间:切换后至少等待数分钟再进行下一次自动切换,避免短周期反复变更。
- 限制候选范围:只从指定策略组成员中挑选,不要把节点提供器、嵌套策略组和直连出口混为一谈。
- 保留兜底行为:没有合格候选时保持当前选择,并报告错误;不要在数据不完整时随意切换到
DIRECT。 - 验证业务目标:延迟检测通过后,可用低频、只读的业务探测确认目标服务可访问,但不要把高频请求压到生产接口上。
还要明确谁拥有策略组的最终控制权。用户在界面中手动切换时,脚本可能在下一轮把选择改回去;多个脚本若同时管理同一组,也会出现互相覆盖。建议为自动化单独指定一个策略组,或约定只由一个调度任务负责切换,并在客户端界面中明确当前自动策略的行为。
安排任务、记录日志并处理失败
脚本验证通过后,再设置周期运行。桌面设备可以用系统计划任务或定时器;服务器可通过 cron、systemd timer 等方式调用。周期应根据用途设置,而不是越短越好:一般自动选择可从几分钟一次开始观察。若每轮要测试十个节点且单次超时为五秒,理论上可能耗费数十秒,因此调度间隔要长于一轮检测耗时,并避免上一次任务尚未结束时又启动下一份实例。
日志至少应记录时间、策略组、候选节点、延迟、失败原因和最终动作,但不要记录控制密钥、完整认证头或包含账户标识的订阅 URL。建议将“没有切换”与“脚本失败”区分开:当前节点仍符合门槛属于正常结果;API 无法连接、所有节点超时或返回内容无法解析才需要告警。发生错误时保留当前策略组选择,避免失败恢复逻辑反而造成流量绕行。
常见问题可以按现象逐层定位:
- 连接超时或拒绝连接:确认内核已启动、控制接口端口正确,并检查脚本是否运行在能访问该地址的网络命名空间中。
- 认证失败:确认使用的是控制接口密钥,而不是订阅密码、代理节点密码或其他客户端的密钥。
- 测试返回超时:先在相同设备上检查测试 URL 是否可达,再调整超时时间;也要确认候选节点本身在策略组中可用。
- 切换请求成功但流量没变化:检查业务连接实际使用的策略组、规则命中结果和连接是否为切换前建立的长连接。
- 节点名称含特殊字符时请求失败:检查路径段是否经过 URL 编码,并确认 JSON 请求体中的名称与组成员名称完全一致。
- 重新载入配置后脚本失效:检查策略组名称、控制端口和密钥是否被订阅更新或客户端覆写改动。
如果运行的是多个 Clash 兼容内核实例,应为每个实例配置独立的控制端口,并让脚本明确指向目标实例。切换策略组前先读取当前状态,执行后再重新读取一次,是比单纯打印“请求成功”更可靠的确认方式。对于需要长期运行的服务器,还应测试内核重启、网络断开、密钥变更和策略组成员更新时的恢复行为,再将任务交给无人值守调度。
上线前的工程检查清单
自动切换脚本不仅要能请求 API,还要能在网络条件变化时保持可预测。上线前可以先在非关键时段运行只读模式:读取策略组并测试延迟,但暂不发送 PUT 请求。观察一段时间后,确认候选节点、超时比例和切换阈值合理,再启用真正的自动切换。这样可以先发现组名错误、测试地址不可达和接口权限不足等问题。
- 配置正确:使用本机回环地址、独立控制端口和强密钥,确认运行中的内核已加载设置。
- 接口可用:读取
/proxies,核对策略组名称、当前成员和候选列表,不要只凭配置文件推断运行状态。 - 请求有界:为 API 请求、节点探测和整轮调度分别设置超时;错误时有限重试,不无限循环。
- 策略稳定:配置最低延迟上限、切换迟滞、连续失败阈值和最短驻留时间,降低抖动影响。
- 结果可追踪:记录切换前后的选择与原因,并在执行后再次查询策略组状态;日志中移除密钥等敏感信息。
- 故障可恢复:无可用节点时保持当前选择并通知维护者,不能确认状态时停止操作,而不是猜测并强行切换。
使用 external-controller 自动切换的价值,是把重复的状态检查和节点选择交给可审计的脚本,而不是把所有网络故障都交给“最低延迟”一个指标。将接口限制在可信范围、用多次测量确认节点质量、为切换设置明确门槛,并保留完整但脱敏的运行记录,才能让方案在日常桌面和服务器任务中稳定工作。