前言：为什么要用脚本自动切换节点？

在日常使用 Clash、Clash Verge Rev 或 Mihomo 时，节点列表通常会同时包含多个地区、多个协议和不同质量的线路。手动点击节点测试延迟，确实可以解决临时故障，但当你需要运行定时任务、部署服务、执行爬虫、访问远程 API，或者长期保持稳定出口时，单纯依赖人工操作就不够可靠了。

节点出现问题时，常见表现包括连接超时、TLS 握手失败、HTTP 状态码异常、出口 IP 不可用，以及延迟突然从几十毫秒升高到数秒。更麻烦的是，Clash 图形界面中的“延迟测试”只反映某一次请求结果，并不能完整判断节点是否适合当前业务。一个更稳妥的方案，是通过 Clash API 获取代理组和节点信息，再由脚本执行探测、评分、切换与恢复验证。

本文以 Mihomo 兼容 API 为基础，介绍一套适合 Windows、macOS、Linux 以及服务器环境的自动故障转移流程。脚本不会修改订阅源，也不会破坏原有规则，而是通过外部控制接口临时切换策略组中的当前节点。这样既能保留客户端的配置管理能力，也方便后续接入 cron、Task Scheduler 或 CI 任务。

本文目标

让脚本能够读取指定策略组，过滤不可用节点，综合延迟、HTTP 状态和连续失败次数进行评分，并在切换后再次验证出口是否恢复。

1开启 Clash API 并确认基础信息

Clash API 通常被称为 External Controller。它是一个本地 HTTP 控制接口，常见地址为 127.0.0.1:9090。不同客户端的菜单名称可能略有区别：Clash Verge Rev 一般可以在设置或内核配置中查看，Mihomo 命令行则直接在 YAML 配置中定义。进行自动切换前，必须确认 API 监听地址、端口、认证密钥和目标策略组名称。

配置 external-controller 与 secret

建议只监听本机回环地址，不要直接绑定到 0.0.0.0。如果 API 暴露到局域网甚至公网，任何获得端口访问权限的人都可能读取节点名称、切换代理，甚至修改运行状态。

# Mihomo / Clash 配置示例
external-controller: 127.0.0.1:9090
secret: "请替换为一段随机密钥"

# 如果使用 HTTPS API，可按实际客户端支持情况配置
# external-controller-tls: 127.0.0.1:9443
# external-controller-certificate: /path/to/cert.pem
# external-controller-certificate-key: /path/to/key.pem

保存配置并重启内核后，可以使用以下命令检查 API 是否正常响应。返回 JSON 版本信息，说明接口已经可用。

curl -s \
  -H "Authorization: Bearer 请替换为一段随机密钥" \
  http://127.0.0.1:9090/version

确认策略组名称，而不是只看显示名称

自动切换的目标通常是一个 select 类型策略组，例如 Proxy、🚀 节点选择 或 Auto。脚本调用 API 时必须使用配置文件中的真实名称，中文、空格和图标都要保持一致。可以先请求全部代理信息，再查找目标组：

curl -s \
  -H "Authorization: Bearer 请替换为一段随机密钥" \
  http://127.0.0.1:9090/proxies

安全建议

不要把 secret 直接提交到 Git 仓库，也不要在日志中输出完整请求头。生产环境可通过环境变量 CLASH_SECRET 注入密钥，并限制脚本文件权限。

2探测节点并建立可解释的评分机制

节点探测不能只依赖延迟数值。一个节点可能对测速地址响应很快，却无法访问实际业务；也可能延迟稍高，但连接稳定、出口地区符合要求。因此建议至少组合三类指标：Clash 内核返回的延迟、真实 HTTP 请求结果，以及连续失败次数。

延迟：使用 Clash 的代理延迟接口测试一个稳定的 HTTPS 地址，例如你自己的健康检查地址。不要频繁测试大型网页或视频资源，否则会浪费带宽。
HTTP 状态：检查请求是否能够完成，并根据状态码判断服务是否可用。常见的 200、204 可以视为成功，超时、连接拒绝和 TLS 错误应当判为失败。
出口验证：切换后访问一个可信的 IP 查询服务或自建接口，确认出口已经真正变化。仅仅收到 API 的切换成功响应，并不代表业务流量已经使用了新节点。
稳定性：不要因为一次高延迟就立刻切换。可连续探测两到三次，并记录最近结果，避免网络瞬时抖动造成频繁来回切换。

下面的 Python 示例展示了一个简化但可扩展的实现。它会读取策略组中的候选节点，调用 Clash API 查询延迟，再按照延迟阈值进行排序。实际部署时，可以继续加入地区过滤、节点名称过滤和业务 URL 检查。

import os
import time
import requests

API = os.getenv("CLASH_API", "http://127.0.0.1:9090")
SECRET = os.environ["CLASH_SECRET"]
GROUP = os.getenv("CLASH_GROUP", "Proxy")
TEST_URL = os.getenv("CLASH_TEST_URL", "https://www.gstatic.com/generate_204")

HEADERS = {"Authorization": f"Bearer {SECRET}"}

def get_group():
    response = requests.get(f"{API}/proxies/{GROUP}", headers=HEADERS, timeout=5)
    response.raise_for_status()
    return response.json()

def test_node(name):
    params = {"url": TEST_URL, "timeout": 5000}
    response = requests.get(
        f"{API}/proxies/{name}/delay",
        headers=HEADERS,
        params=params,
        timeout=8
    )
    if response.status_code != 200:
        return None
    value = response.json().get("delay")
    return value if isinstance(value, int) and value > 0 else None

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

results = []
for node in candidates:
    delay = test_node(node)
    if delay is not None:
        results.append((delay, node))
    time.sleep(0.2)

results.sort(key=lambda item: item[0])
print(results[:5])

测试地址最好与实际业务相近。例如主要访问 GitHub API，就可以使用一个轻量的 GitHub 地址；主要进行浏览器访问，则应选择稳定的 HTTPS 健康检查页面。对于需要固定国家或地区出口的场景，还应在切换后额外检查 IP 地理位置，避免脚本选择了延迟最低但地区不符合要求的节点。

3调用 API 切换节点并验证恢复

在 Mihomo API 中，切换策略组通常使用 PUT /proxies/{group}，请求体包含目标节点名称。策略组名称和节点名称需要进行 URL 编码，因此不建议手动拼接未经处理的中文字符串。切换动作完成后，应等待短暂时间，再发起实际请求验证。

def switch_node(group, node):
    response = requests.put(
        f"{API}/proxies/{group}",
        headers={**HEADERS, "Content-Type": "application/json"},
        json={"name": node},
        timeout=5
    )
    response.raise_for_status()

def verify():
    response = requests.get(TEST_URL, headers={"Cache-Control": "no-cache"}, timeout=10)
    return response.status_code in (200, 204)

for delay, node in results:
    try:
        switch_node(GROUP, node)
        time.sleep(2)
        if verify():
            print(f"已切换到 {node}，延迟约 {delay} ms")
            break
        print(f"{node} 切换后验证失败，继续尝试")
    except requests.RequestException as error:
        print(f"{node} 不可用：{error}")
else:
    raise SystemExit("没有找到通过验证的节点")

避免频繁切换的保护条件

自动化脚本最容易出现的问题不是“不会切换”，而是切换过于积极。节点在高峰期可能只短暂丢包，如果脚本每分钟都重新选择，就会造成连接反复中断，WebSocket、下载任务和登录会话也可能被破坏。因此建议加入以下保护：

设置冷却时间，例如切换后至少十五分钟内不再主动切换。
连续两次或三次业务探测失败后才判定当前节点故障。
设置最小收益阈值，新节点必须比当前节点快一定比例，或当前节点已经完全不可用，才执行切换。
记录上一次节点和切换原因，脚本重启后读取状态文件，避免重复选择同一故障节点。
保留一个人工可用的备用策略组，自动脚本只操作专用组，避免误改 DNS、直连或其他业务规则。

不要把“API 成功”当成“网络成功”

HTTP 204 只表示 Clash 接受了切换请求，不能证明目标站点可访问。切换后必须使用与业务一致的 URL 进行恢复验证，并设置合理的连接与读取超时。

4定时运行、日志记录与故障排查

完成脚本后，可以根据运行平台选择调度方式。Linux 和 macOS 用户可以使用 cron 或 systemd timer；Windows 用户可以使用任务计划程序。频率应根据业务特点决定：个人桌面环境每十到三十分钟检查一次通常足够，服务器上的关键任务则可以采用短周期探测，但必须配合冷却时间。

# Linux / macOS：每 15 分钟运行一次
*/15 * * * * /usr/bin/python3 /opt/clash/failover.py >> /var/log/clash-failover.log 2>&1

日志至少应包含执行时间、策略组、候选节点、测试延迟、失败原因、最终选择和验证结果。不要记录订阅链接、API secret 或完整的代理地址。对于长期运行的任务，还要配置日志轮转，避免日志文件持续增长占满磁盘。

常见问题与处理顺序

返回 401：检查是否遗漏 Bearer 前缀、密钥是否与当前运行配置一致，或者客户端是否重启后生成了新的配置。
返回 404：确认使用的是 Mihomo 支持的 API 路径，并检查策略组或节点名称是否经过 URL 编码。
延迟接口全部失败：测速 URL 可能被拦截、DNS 解析异常或节点不支持该请求。可更换轻量 HTTPS 地址，并检查 Clash 日志。
切换后仍然访问旧出口：确认流量确实经过目标策略组，检查规则顺序、TUN 模式、系统代理和应用自身代理设置。
节点来回跳转：提高失败确认次数，增加冷却时间，并设置最小延迟差或评分差。

如果希望进一步提升可靠性，可以将评分结果保存为 JSON 文件，结合 Prometheus、Webhook 或邮件通知输出告警。对于多台设备，还可以让每台设备只控制本机 API，避免多个脚本同时争抢同一个策略组。自动切换的核心不是“永远找到最快节点”，而是在故障发生时快速恢复，并且让每一次决策都可追踪、可回滚、可解释。

推荐的落地顺序

先用只读模式确认 API、策略组和测速逻辑，再开启单次手动切换；验证日志和恢复流程无误后，最后接入定时任务。不要一开始就让脚本以高频率直接控制生产环境。

通过 Clash API、稳定的探测地址和明确的切换策略，你可以把节点管理从手动点击升级为一套可维护的故障转移机制。无论使用 Clash Verge、Clash Verge Rev 还是 Mihomo，只要客户端提供兼容的 External Controller，就能按照相同思路扩展到多策略组、分地区节点和不同业务出口。

立即免费下载 Clash，开启流畅上网新体验 →

Clash API自动切换节点：脚本化进阶配置指南