手动打开 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 的常用接口包括:

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 是切换迟滞:新节点至少比当前节点快一个设定幅度,才允许切换。

实际运行时还可以增加以下约束,让选择逻辑更适合工作流:

还要明确谁拥有策略组的最终控制权。用户在界面中手动切换时,脚本可能在下一轮把选择改回去;多个脚本若同时管理同一组,也会出现互相覆盖。建议为自动化单独指定一个策略组,或约定只由一个调度任务负责切换,并在客户端界面中明确当前自动策略的行为。

安排任务、记录日志并处理失败

脚本验证通过后,再设置周期运行。桌面设备可以用系统计划任务或定时器;服务器可通过 cron、systemd timer 等方式调用。周期应根据用途设置,而不是越短越好:一般自动选择可从几分钟一次开始观察。若每轮要测试十个节点且单次超时为五秒,理论上可能耗费数十秒,因此调度间隔要长于一轮检测耗时,并避免上一次任务尚未结束时又启动下一份实例。

日志至少应记录时间、策略组、候选节点、延迟、失败原因和最终动作,但不要记录控制密钥、完整认证头或包含账户标识的订阅 URL。建议将“没有切换”与“脚本失败”区分开:当前节点仍符合门槛属于正常结果;API 无法连接、所有节点超时或返回内容无法解析才需要告警。发生错误时保留当前策略组选择,避免失败恢复逻辑反而造成流量绕行。

常见问题可以按现象逐层定位:

如果运行的是多个 Clash 兼容内核实例,应为每个实例配置独立的控制端口,并让脚本明确指向目标实例。切换策略组前先读取当前状态,执行后再重新读取一次,是比单纯打印“请求成功”更可靠的确认方式。对于需要长期运行的服务器,还应测试内核重启、网络断开、密钥变更和策略组成员更新时的恢复行为,再将任务交给无人值守调度。

上线前的工程检查清单

自动切换脚本不仅要能请求 API,还要能在网络条件变化时保持可预测。上线前可以先在非关键时段运行只读模式:读取策略组并测试延迟,但暂不发送 PUT 请求。观察一段时间后,确认候选节点、超时比例和切换阈值合理,再启用真正的自动切换。这样可以先发现组名错误、测试地址不可达和接口权限不足等问题。

使用 external-controller 自动切换的价值,是把重复的状态检查和节点选择交给可审计的脚本,而不是把所有网络故障都交给“最低延迟”一个指标。将接口限制在可信范围、用多次测量确认节点质量、为切换设置明确门槛,并保留完整但脱敏的运行记录,才能让方案在日常桌面和服务器任务中稳定工作。

下载Clash