为什么要用 Clash API 自动切换节点?

很多人第一次使用 Clash 的测速功能时,会直接在客户端里点击「延迟测试」,然后手动挑一个数字最小的节点。这种方式适合临时验证线路,却不适合长期运行的开发、运维或家庭网络环境:节点延迟会随时间变化,某个节点可能在白天表现很好,到了晚高峰却丢包严重;测速结果正常,也不代表真实的 HTTPS 请求、DNS 解析或长连接一定稳定。

Clash external-controller API提供了一条更适合自动化的路径。脚本可以读取当前配置中的节点和策略组,逐个发起延迟测试,按照延迟、失败次数、地区、协议或自定义权重筛选候选节点,再通过 API 把目标策略组切换到更合适的节点。这样,节点选择就不再依赖人工观察,而是变成可以重复执行、记录日志、设置阈值的流程。

本文以支持 external-controller 的 Clash 内核和 Mihomo 客户端为例,重点介绍 API 的工作方式、控制器配置、YAML 策略组设计、Python 脚本、定时任务与排障方法。不同客户端的界面名称可能略有差异,但只要底层内核提供相同或兼容的 REST API,Clash Verge、Clash Verge Rev、Clash for Windows 的部分版本以及 Mihomo 环境都可以参考。

⚠️
安全边界:external-controller 本质上是一个可以修改代理状态的管理接口。除非你明确理解鉴权、访问范围和防火墙规则,否则不要把它监听在公网地址,也不要把 secret 写入公开代码仓库或提交到日志中。

先理解 API:读取节点、测速与切换策略组

Clash 的自动选路通常涉及三个对象:代理节点、策略组和外部控制器。代理节点是配置文件中真正负责建立连接的条目,例如某个日本、香港或美国服务器;策略组则是把多个节点包装成一个可供规则引用的入口,例如「🚀 节点选择」或「自动选择」;external-controller 是本机提供的 HTTP API 服务,脚本通过它读取状态并执行操作。

常用接口可以按照下面的思路理解:

  • GET /version:查看内核版本,确认请求是否已经到达正确的 Clash 实例。
  • GET /proxies:获取全部代理与策略组,响应中通常包含每个对象的类型、当前选中项和候选列表。
  • GET /proxies/{name}:读取某个节点或策略组的详细信息。名称包含空格、表情符号或中文时,必须进行 URL 编码。
  • GET /proxies/{name}/delay:使用指定节点访问测试 URL,返回延迟结果;请求通常需要携带 url 与 timeout 参数。
  • PUT /proxies/{name}:修改可切换策略组的当前代理,JSON 请求体一般为 {"name":"节点名称"}。

自动切换并不等于「永远选择最小延迟」。延迟只描述某一次测试请求的往返时间,无法完整反映吞吐量、丢包、TLS 握手、晚高峰拥塞和目标网站的可用性。更稳妥的策略是先过滤失败节点,再设置延迟上限和切换阈值,例如只考虑低于 500 毫秒的节点,并且要求新节点比当前节点至少快 80 毫秒,避免脚本因为几毫秒的波动而频繁切换。

测试地址应该怎么选?

测试 URL 应尽量稳定、响应体小、支持 HTTPS,并且与你真正关心的业务路径有一定相关性。公共探测地址适合判断节点是否能建立基本连接,但不一定能代表代码仓库、AI API 或视频服务的实际体验。你可以准备两类地址:第一类是稳定的基础探测地址,用于快速筛掉完全不可用的节点;第二类是业务相关地址,用于在候选节点之间做二次验证。

如果测试地址经常返回重定向、需要登录、受到地区限制或对频繁请求敏感,脚本会把业务错误误判为节点故障。因此,生产环境不要盲目提高测速频率。对于几十个节点的订阅,五分钟或十分钟执行一次通常已经足够;如果只是个人电脑临时使用,手动运行脚本比后台持续轮询更节省资源。

配置 external-controller:先把接口安全地留在本机

在 YAML 配置中,常见的控制器配置如下。字段名称会随内核版本和客户端封装方式略有区别,修改前建议查看当前内核文档或客户端生成的配置文件:

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

127.0.0.1表示只允许本机访问,通常比监听 0.0.0.0安全得多。secret用于 API 鉴权,脚本请求时一般放在 Authorization 请求头中,格式类似 Bearer replace-with-a-long-random-secret。如果客户端界面提供「外部控制器」或「External Controller」输入框,优先在界面中设置,并确认保存后实际运行的配置已经包含这些字段。

修改完后,可以先用命令行验证接口是否可用:

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

成功时通常会返回包含版本号的 JSON。若返回 401 或 403,重点检查 secret 是否一致;若连接被拒绝,重点检查控制器是否开启、端口是否被其他程序占用,以及客户端是否在修改配置后重新加载了内核。不要一开始就使用复杂脚本,先确认最简单的版本接口能够正常访问。

ℹ️
建议:把 API 地址、端口和 secret 放到环境变量中,而不是直接写进脚本。这样可以在不同电脑、不同客户端之间复用代码,也能避免把管理凭证意外上传到 Git 仓库。

YAML 策略组设计:给自动切换预留清晰的入口

脚本要切换的是策略组,不是随意修改某个普通节点对象。因此,配置文件里应该有一个稳定、明确的策略组名称,并把规则统一指向它。下面是一个简化示例:

proxy-groups:
  - name: "自动选择"
    type: select
    proxies:
      - "延迟优选"
      - "手动选择"
      - DIRECT

  - name: "延迟优选"
    type: url-test
    url: "https://www.gstatic.com/generate_204"
    interval: 600
    tolerance: 80
    proxies:
      - "节点-日本-01"
      - "节点-日本-02"
      - "节点-香港-01"
      - "节点-美国-01"

rules:
  - MATCH,自动选择

select组适合提供人工总开关,url-test组则适合在候选节点中根据测试结果进行选择。两者可以分层使用:日常规则全部指向「自动选择」,用户需要临时固定线路时,手动把「自动选择」切到「手动选择」;脚本只负责更新「手动选择」或另一个专用自动组,避免影响所有流量。

需要注意,客户端有时会自动生成策略组名称,订阅更新后名称也可能改变。脚本依赖的是名称匹配,因此不要把一个容易变化的订阅组当作唯一目标。更稳妥的做法是在本地覆写配置中创建固定名称的策略组,并在订阅更新后检查候选节点是否仍然存在。节点名称同样可能因为服务商改名而失效,脚本应当记录找不到的节点,而不是直接退出后假装切换成功。

动手操作:用 Python 完成测速、筛选与切换

下面的脚本示例使用 Python 标准库和 requests。它的流程是:读取控制器中的策略组,取出候选代理;逐个请求延迟接口;过滤失败和超时节点;比较当前节点与最佳候选;只有在优势达到阈值时才发起切换。真实使用前,请把策略组名称、测试 URL 和环境变量替换为自己的值。

import os
import time
import requests

CONTROLLER = os.getenv("CLASH_CONTROLLER", "http://127.0.0.1:9090")
SECRET = os.environ["CLASH_SECRET"]
GROUP = os.getenv("CLASH_GROUP", "延迟优选")
TEST_URL = os.getenv("CLASH_TEST_URL", "https://www.gstatic.com/generate_204")
TIMEOUT = int(os.getenv("CLASH_TIMEOUT", "5000"))
MIN_IMPROVEMENT = int(os.getenv("CLASH_MIN_IMPROVEMENT", "80"))

session = requests.Session()
session.headers.update({"Authorization": f"Bearer {SECRET}"})

def encoded(value):
    from urllib.parse import quote
    return quote(value, safe="")

def get_group():
    response = session.get(
        f"{CONTROLLER}/proxies/{encoded(GROUP)}",
        timeout=10
    )
    response.raise_for_status()
    return response.json()

def measure(proxy_name):
    response = session.get(
        f"{CONTROLLER}/proxies/{encoded(proxy_name)}/delay",
        params={"url": TEST_URL, "timeout": TIMEOUT},
        timeout=TIMEOUT / 1000 + 3
    )
    if response.status_code != 200:
        return None
    data = response.json()
    return data.get("delay")

def switch_to(proxy_name):
    response = session.put(
        f"{CONTROLLER}/proxies/{encoded(GROUP)}",
        json={"name": proxy_name},
        timeout=10
    )
    response.raise_for_status()

group_data = get_group()
current = group_data.get("now")
candidates = group_data.get("all", [])

results = []
for proxy in candidates:
    try:
        delay = measure(proxy)
        if isinstance(delay, int):
            results.append((delay, proxy))
            print(f"{proxy}: {delay} ms")
    except requests.RequestException as error:
        print(f"{proxy}: failed ({error})")

if not results:
    raise SystemExit("No healthy proxy was found")

results.sort(key=lambda item: item[0])
best_delay, best_proxy = results[0]

if current and current != best_proxy:
    current_delay = next(
        (delay for delay, name in results if name == current),
        None
    )
    should_switch = (
        current_delay is None
        or current_delay - best_delay >= MIN_IMPROVEMENT
    )
    if should_switch:
        switch_to(best_proxy)
        print(f"Switched to {best_proxy}: {best_delay} ms")
    else:
        print("Current proxy is still within the tolerance window")
else:
    print(f"Keep current proxy: {current}")

这个示例有几个值得保留的工程细节。第一,使用 quote 编码策略组和节点名称,避免中文、空格或特殊符号破坏 URL。第二,单个节点失败不会阻断整个测试流程,脚本会继续检查其他节点。第三,切换前设置最小优势值,避免延迟只差十几毫秒时频繁改变出口。第四,脚本只根据 API 返回结果判断成功,并在终端输出每个节点的状态,方便后续审计和排障。

加入地区、名称与失败次数过滤

如果订阅中包含大量节点,逐个测速会比较慢,也可能触发上游服务的频率限制。可以在测速前先按名称过滤,例如只测试包含「日本」「香港」或「专线」的节点。也可以维护一个黑名单,跳过过去一段时间内连续失败的节点。需要注意名称过滤只是方便管理,不代表节点名称中的地区标签一定真实,最终仍应以连接日志和实际访问结果为准。

更成熟的做法是把结果写入本地 JSON 或 SQLite,保存节点、时间、延迟、错误类型和连续失败次数。某个节点连续三次超时后暂时冷却,十五分钟后再恢复测试;某个节点延迟突然升高但仍可用,则先保留观察,而不是立即判定为永久失效。这样可以把偶发网络抖动与真正的节点故障区分开。

定时任务:让自动化在合适的频率运行

在 Linux 或 macOS 上,可以使用 cron 定期执行脚本。假设脚本位于 /opt/clash/switch_node.py,虚拟环境位于 /opt/clash/.venv,可以设置为每十分钟执行一次:

*/10 * * * * CLASH_SECRET='your-secret' /opt/clash/.venv/bin/python /opt/clash/switch_node.py >> /var/log/clash-switch.log 2>&1

不过,把 secret 直接写进 crontab 并不是最理想的方式。更安全的方案是创建只有当前用户可读的环境文件,或使用系统的凭证存储,再让脚本读取环境变量。日志也不要无限增长,应该通过 logrotate 或脚本自身的轮转机制限制大小。Windows 用户可以使用任务计划程序,触发条件设置为用户登录后或固定时间执行,并勾选「使用最高权限」时谨慎确认是否真的需要。

定时任务的频率不能只看节点数量,还要考虑网络环境与业务类型。短连接网页浏览可以接受较频繁的检测,但 SSH、WebSocket、下载任务和在线会议不适合在连接期间自动换节点。最好把切换逻辑安排在低峰期,或者在脚本中加入维护窗口;一旦发现当前策略组正在承载重要长连接,应当延迟切换,而不是为了追求更小的延迟立即打断业务。

⚠️
不要把频繁切换当成稳定性:自动选择组每次换出口都会影响新建连接,部分长连接还会直接断开。稳定的 300 毫秒节点通常比在 180、210、190 毫秒之间反复跳转更适合实际使用。

常见故障:API 能访问,但节点没有按预期切换

返回 401、403 或接口路径不存在

401 通常表示 secret 缺失或不匹配;403 可能与控制器鉴权、客户端封装限制或访问来源有关。接口路径不存在时,先请求 /version 和 /proxies,确认你连接的是 Mihomo 或 Clash 内核,而不是客户端的其他管理端口。部分旧版本的接口字段与新版不同,不能仅凭网上的代码片段判断,应该以当前内核响应为准。

策略组名称找不到或无法 PUT

先打印 GET /proxies 返回的键名,确认名称是否包含表情符号、空格或大小写差异。可以切换的对象通常是 Selector、URLTest、Fallback 或类似策略组,而普通节点不是切换目标。若 API 返回请求格式错误,检查 JSON 是否使用了 name 字段,并确认目标节点确实属于该组的候选列表。

所有节点都超时或延迟数字异常

这不一定表示所有节点同时失效。测试 URL 可能不可达,系统时间可能错误,DNS 可能被当前规则送到了不合适的路径,也可能是脚本所在环境无法访问本机控制器。先在客户端手动点击相同节点的延迟测试,再用 curl 请求同一个 API,对比两边的结果。如果延迟测试成功但真实业务失败,还要检查目标服务的地区策略、TLS、UDP 支持和规则命中情况。

节点频繁来回切换

可以提高 MIN_IMPROVEMENT,增加两次脚本执行之间的冷却时间,或者采用连续两次测试的中位数而不是单次结果。对于高抖动网络,还可以要求新节点连续两轮排名靠前才允许切换。脚本的目标是减少故障,而不是让策略组实时追逐每一次延迟波动。

常见问题

external-controller 是否必须监听在 0.0.0.0?

不需要。脚本和 Clash 运行在同一台机器时,监听 127.0.0.1 就足够了,而且能显著降低局域网或公网误访问的风险。只有在确实需要从另一台受控设备管理 Clash 时,才考虑监听局域网地址,并同时使用强 secret、防火墙白名单和加密隧道。不要为了让手机或服务器「方便连接」而直接暴露到公网。

为什么测速最快的节点实际访问速度不一定最快?

延迟测试通常只代表一次小请求的往返时间,不能代表下载速度、持续连接稳定性、TLS 握手或目标站点的区域路由。可以为不同用途设置不同策略组,例如开发 API 使用低延迟组,视频或大文件使用带宽测试组,并结合真实业务请求做二次验证。

订阅更新后脚本为什么突然失效?

最常见原因是节点名称、策略组名称或候选列表发生变化。订阅服务商可能重命名节点、删除旧节点或重新生成策略组。建议脚本启动时检查目标组是否存在、候选数量是否合理,并在异常时只记录告警,不要自动把所有流量切换到未知的直连方案。

所有 Clash 客户端都支持相同的 API 吗?

不一定。不同内核、版本和客户端封装可能在字段、鉴权方式、延迟接口以及脚本能力上存在差异。自动化之前先用 /version、/proxies 和一个具体的 delay 请求做兼容性验证,并把 API 错误记录下来。不要假设某个客户端界面中出现了「控制器」选项,就代表它完整支持所有 Mihomo API。

与一些只提供手动下拉切换、缺少状态日志的传统代理客户端相比,ClashSky 在 external-controller、策略组管理和运行状态展示方面更适合做自动化实验:你可以先用图形界面确认节点和规则,再逐步接入脚本、定时任务与失败告警,而不必长期维护一套难以观察的黑盒配置。若你希望把本文的 API 自动切换方案落到实际设备上,可以前往下载 ClashSky,从可视化配置开始逐步搭建自己的稳定选路流程。