为什么要用 Clash API 自动切换节点?
在节点数量较少、网络环境稳定时,手动点击策略组似乎已经够用;但当你同时维护多条线路,或者需要让家庭服务器、开发机和远程任务持续运行时,手动切换很快就会变成一个不可靠的环节。节点可能在白天延迟正常,晚高峰突然丢包;订阅里的节点名称没有变化,实际出口却已经不可用;客户端界面显示代理已连接,但访问目标站点时仍然不断超时。
Clash API 自动切换节点的核心思路,是把「观察节点状态、发起测试、选择可用节点、记录结果」变成一个可重复执行的流程。脚本通过 Clash 或 Mihomo 提供的 external-controller 接口读取代理组和节点信息,再调用延迟测试接口,按照延迟、HTTP 状态码和超时情况筛选候选节点,最后通过 API 修改策略组当前选择。这样做并不是单纯追求最低延迟,而是把「可用性」放在第一位,避免脚本频繁切换到一个测速很快、实际访问却不稳定的节点。
本文以 Clash Verge Rev、Mihomo 等支持 REST API 的客户端为例,使用 Python 演示一套基础实现。不同客户端的界面名称可能略有区别,但接口思路基本一致:确认控制器监听地址,配置访问密钥,读取 /proxies,测试目标代理,再向策略组的 /proxies/{name} 发送选择请求。开始前,请确保你拥有合法使用的节点订阅,并且自动化任务不会违反网络、设备或服务提供方的使用规则。
准备 external-controller 与 API 请求
Clash API 的入口通常由 external-controller 指定,例如 127.0.0.1:9090。如果配置了 secret,每个请求都需要在 Authorization 请求头中携带 Bearer 密钥。Clash Verge Rev 的具体设置位置可能因版本和内核而不同,可以在设置、配置文件或运行日志中确认控制器地址。不要只凭端口号猜测接口是否可用,应该先用浏览器开发者工具、curl 或 Python 请求验证。
curl -H "Authorization: Bearer YOUR_SECRET" \
http://127.0.0.1:9090/proxies
请求成功后,返回结果通常是一个较大的 JSON 对象,其中 proxies 保存代理节点和策略组。策略组对象一般包含 type、now、all 等字段。now 表示当前选中的代理,all 列出该组可选择的成员。需要注意的是,节点名称可能包含空格、表情符号、括号或地区标识,脚本必须使用 API 返回的完整字符串,不能自行截断或拼接名称。
下面是一个更稳妥的读取方式。它不会把所有代理都当成可切换节点,而是先检查目标策略组是否存在,再过滤掉 DIRECT、REJECT、其他策略组以及明显不是实际出口的项目:
import os
import requests
CONTROLLER = os.getenv("CLASH_CONTROLLER", "http://127.0.0.1:9090")
SECRET = os.getenv("CLASH_SECRET", "")
GROUP = os.getenv("CLASH_GROUP", "Proxy")
headers = {}
if SECRET:
headers["Authorization"] = f"Bearer {SECRET}"
response = requests.get(
f"{CONTROLLER}/proxies/{GROUP}",
headers=headers,
timeout=5,
)
response.raise_for_status()
group_info = response.json()
candidates = [
name for name in group_info.get("all", [])
if name not in {"DIRECT", "REJECT"} and name != GROUP
]
print("当前节点:", group_info.get("now"))
print("候选数量:", len(candidates))
如果返回 401,优先检查密钥前缀、环境变量和控制器配置;如果返回 404,通常是策略组名称不正确,或者 URL 中的中文、空格没有经过编码。使用 Python 的 requests 方法拼接路径时,建议通过参数或 URL 编码处理名称,不要把用户输入直接拼进未编码的地址。若请求连接超时,则要检查 Clash 是否正在运行、端口是否被其他程序占用,以及脚本是否运行在容器或虚拟机中。
健康检查:延迟不是唯一判断标准
常用的测速接口是 GET /proxies/{proxy},并附带 url 与 timeout 参数。控制器会让指定节点访问测试地址,并返回延迟结果。部分版本返回 JSON 中的 delay 字段,单位通常为毫秒;失败时可能返回错误状态码或无法解析的响应。因此脚本不能只写「读取 delay 后排序」,还要处理超时、负数、空值和异常响应。
from urllib.parse import quote
TEST_URL = "http://www.gstatic.com/generate_204"
TIMEOUT_MS = 5000
def test_proxy(proxy_name):
encoded_name = quote(proxy_name, safe="")
url = (
f"{CONTROLLER}/proxies/{encoded_name}"
f"?url={quote(TEST_URL, safe='')}&timeout={TIMEOUT_MS}"
)
try:
result = requests.get(url, headers=headers, timeout=8)
result.raise_for_status()
delay = result.json().get("delay")
if isinstance(delay, int) and delay > 0:
return delay
except (requests.RequestException, ValueError):
return None
return None
测试地址应尽量选择响应稳定、体积很小、不会产生复杂页面渲染的目标。它只适合衡量某条代理路径能否在指定时间内建立连接,不能代表所有网站、视频服务或 API 的真实体验。你可以根据使用场景准备多个测试目标:一个用于基础连通性,一个用于常用业务域名,另一个用于长连接或 HTTPS 握手观察。不同测试地址之间出现明显差异时,不要立即认定脚本错误,可能是目标服务的 CDN、地区策略或协议支持不同。
节点选择建议采用可用性优先、延迟次之、稳定性加权的评分方式。比如,连续三次测试都成功且延迟低于 250 毫秒,可以判为健康;只成功一次的节点,即使延迟显示为 80 毫秒,也不应该立刻取代当前节点。脚本还应设置切换阈值,例如新节点至少比当前节点快 50 毫秒,或者当前节点连续失败两轮,才执行切换。这个阈值就是迟滞机制,可以避免网络轻微抖动造成来回跳转。
- 基础可用:在规定超时时间内获得合法延迟值,否则记为失败。
- 连续成功:至少进行两到三次测试,减少偶然成功对结果的影响。
- 失败保护:当前节点仍然可用时,不因一次异常就切换。
- 冷却时间:切换后等待一段时间再重新评估,避免策略组频繁变化。
- 业务验证:关键任务可在切换后请求实际 API,但要控制频率,避免造成额外流量和访问压力。
编写自动选择与切换脚本
确定候选节点和测试方法后,可以把逻辑组合成一个完整函数。下面的示例会测试所有候选节点,选择延迟最低且测试成功的节点;只有当当前节点不可用,或新节点至少快过阈值时,才调用切换接口。实际使用时建议进一步加入节点白名单,避免把备用、落地或特殊用途节点纳入普通自动选择。
import time
SWITCH_MARGIN = 50
MIN_DELAY = 2500
def switch_proxy(group, proxy_name):
endpoint = f"{CONTROLLER}/proxies/{quote(group, safe='')}"
result = requests.put(
endpoint,
headers={**headers, "Content-Type": "application/json"},
json={"name": proxy_name},
timeout=5,
)
result.raise_for_status()
def choose_node():
group_response = requests.get(
f"{CONTROLLER}/proxies/{quote(GROUP, safe='')}",
headers=headers,
timeout=5,
)
group_response.raise_for_status()
group = group_response.json()
current = group.get("now")
nodes = [
item for item in group.get("all", [])
if item not in {"DIRECT", "REJECT", GROUP}
]
results = {}
for node in nodes:
delay = test_proxy(node)
if delay is not None and delay <= MIN_DELAY:
results[node] = delay
if not results:
raise RuntimeError("没有通过健康检查的节点")
best = min(results, key=results.get)
current_delay = results.get(current)
should_switch = (
current not in results
or current_delay is None
or results[best] + SWITCH_MARGIN < current_delay
)
if should_switch and best != current:
switch_proxy(GROUP, best)
print(f"已切换:{current} -> {best}, {results[best]} ms")
else:
print(f"保持当前节点:{current}, 测试结果:{results}")
if __name__ == "__main__":
choose_node()
这个示例适合帮助理解接口流程,生产环境还需要补充日志、重试和状态保存。建议为每次运行记录时间、策略组、当前节点、候选节点数量、各节点延迟、切换原因和请求异常。日志中不要记录完整订阅 URL、API 密钥或带有身份信息的请求头。若节点名称本身包含账号标识,也可以在写入日志前做脱敏处理。
脚本最好使用固定的 Python 虚拟环境安装依赖,并通过环境变量传入控制器地址与密钥:
python3 -m venv .venv
. .venv/bin/activate
pip install requests
export CLASH_CONTROLLER="http://127.0.0.1:9090"
export CLASH_SECRET="replace-with-your-secret"
export CLASH_GROUP="Proxy"
python auto_switch.py
定时任务、权限保护与生产部署
自动切换并不意味着测试越频繁越好。测试间隔过短会增加节点连接数、消耗本地资源,也可能让节点服务商误判为异常探测。普通桌面用户可以从每五到十五分钟运行一次开始;对长时间运行的服务器,则应结合业务特点设置间隔。若只是检测当前节点,可以缩小测试范围;只有当前节点失败时,才遍历全部候选节点,这样比每次都完整测速更节省资源。
Linux 上可以使用 systemd timer 或 cron。cron 配置看起来简单,但要特别注意环境变量不会自动继承交互式终端中的设置,因此推荐把变量写入权限为 600 的独立环境文件,并在脚本中显式加载。systemd 则可以用专用用户运行服务,限制文件访问范围,并设置失败重启和日志轮转。Windows 用户可以通过任务计划程序运行 Python,勾选「无论用户是否登录都运行」前应谨慎评估密钥文件的访问权限;macOS 则可使用 launchd,避免依赖图形客户端是否处于前台。
- 监听地址:使用
127.0.0.1或::1,不要直接绑定公网网卡。 - 密钥管理:通过环境变量、受限权限文件或系统密钥存储管理,不要硬编码在脚本里。
- 最小权限:脚本只需要访问控制器和写入自身日志,不应使用过大的系统权限。
- 并发控制:使用锁文件或进程锁,避免上一次测速尚未结束时又启动新的实例。
- 切换通知:可以发送本地日志、桌面通知或内部监控告警,但不要把密钥放进通知正文。
- 升级回归:Clash 客户端或 Mihomo 内核升级后,重新测试 API 字段、策略组名称和切换权限。
常见故障可以按下面顺序定位。若所有请求都是 401,检查 secret 和 Bearer 格式;若只有中文节点名返回 404,检查 URL 编码;若延迟接口全部超时,先确认测试 URL 在当前环境可访问,再检查候选节点是否真实存在;若切换接口返回成功但界面没有变化,确认你操作的是外层策略组,而不是组内某个节点。最后,还要观察是否存在多个客户端实例争用同一个端口,或订阅更新后策略组被重新命名。
相比一些只提供手动测速或简单自动选择的同类客户端方案,单独维护脚本往往需要自己处理 API 认证、节点名称编码、失败重试、日志轮转和版本兼容,配置成本较高;而只依赖系统代理的通用工具,也可能无法覆盖未读取系统代理的终端、容器或后台服务。ClashSky 在图形界面、Mihomo 内核状态展示、策略组管理与连接日志之间提供了更完整的闭环,既方便新手先确认节点和规则,也便于熟悉 REST API 的用户接入定时脚本。若你希望在动手自动化前先获得稳定、直观的 Clash 使用体验,可以前往下载 ClashSky,再根据本文方法逐步接入健康检查与节点切换。