Clash external-controller API节点自动切换进阶配置指南
为什么要用 external-controller API 做节点自动切换
很多用户第一次配置 Clash 节点自动切换时,会直接在策略组里选择 url-test、fallback 或 load-balance。这类内置策略已经能够覆盖日常使用,但当你的需求变成按业务类型选择节点、记录检测结果、避开特定地区、在异常后自动恢复、或者把切换动作接入定时任务时,仅靠 YAML 往往不够灵活。此时,Clash 的 external-controller API 就提供了一个可编程的控制面。
external-controller 可以理解为 Clash 内核开放出来的本地 HTTP 管理接口。客户端界面展示的代理列表、策略组、当前节点和连接信息,很多都可以通过这个接口读取或修改。脚本不必直接编辑正在使用的配置文件,而是先查询当前状态,再调用策略组切换接口,从而减少 YAML 被覆盖、格式错误或热更新失败带来的风险。对于运行 Mihomo 内核的 Clash Verge、Clash Verge Rev、部分 Clash for Windows 分支以及服务器上的 Mihomo 实例,这种方式尤其适合自动化运维。
需要区分的是,节点自动切换并不等于单纯追求最低延迟。延迟测试只能说明某个 URL 的响应速度,不能完全代表视频播放、长连接、文件下载或 API 请求的稳定性。一个节点可能测速只有 80 毫秒,却频繁重置 TCP 连接;另一个节点延迟略高,但连续运行数小时没有丢包。因此,比较可靠的方案通常包括四层:先确认 API 可访问,再读取策略组和节点状态,随后执行针对目标 URL 的健康检查,最后依据连续失败次数、冷却时间和优先级决定是否切换。
先理解 external-controller 的地址、认证与常用接口
在配置文件中,常见写法如下。端口可以按你的环境修改,但建议使用未被其他服务占用的本地端口。
external-controller: 127.0.0.1:9090
secret: "replace-with-a-long-random-secret"
当 external-controller 只监听 127.0.0.1 时,只有本机程序能够访问它,安全性通常优于监听 0.0.0.0。如果必须让局域网内另一台设备管理,则应明确填写受控网卡地址,同时设置足够长的 secret,并在防火墙中限制来源 IP。API 请求一般通过 Authorization 请求头传递令牌:
curl -H "Authorization: Bearer replace-with-a-long-secret" \
http://127.0.0.1:9090/proxies
自动切换前最值得掌握的接口有以下几类:
GET /version:读取内核版本,判断当前实例是否支持你准备使用的字段。GET /proxies:查看全部代理、策略组及当前选中的节点。GET /proxies/{name}:读取某个策略组的详细信息,包括可选节点与当前值。PUT /proxies/{name}:向指定策略组提交新的节点名称,完成运行时切换。GET /proxies/{name}/delay?url=...&timeout=...:让内核通过目标代理检测指定 URL 的延迟。GET /connections:排查当前连接是否命中了预期策略组,辅助定位规则和切换逻辑问题。
策略组名称可能包含空格、斜杠、括号或非 ASCII 字符,因此不能把名称直接拼接到 URL 中。脚本应使用 URL 编码,例如 JavaScript 中使用 encodeURIComponent(groupName),Python 中使用 urllib.parse.quote。同样,节点名称也不要通过模糊匹配随意截断,否则当订阅中同时存在多个相似节点时,脚本可能切错目标。
secret 写进公开 Git 仓库、截图、前端网页或聊天记录。若 API 曾经暴露过,应立即更换密钥并重启内核;仅仅修改脚本而不修改服务端配置,不能消除风险。设计可靠的节点健康检查逻辑
一个可维护的自动切换脚本,最好不要只调用一次延迟接口就立即换节点。单次检测容易受到 DNS、目标站点瞬时拥塞、代理刚建立连接或本地网络抖动影响。更稳妥的判断方式是给每个候选节点建立一个简单的状态模型:成功次数、连续失败次数、最近一次成功时间、最近一次切换时间以及冷却截止时间。
检测 URL 也应当与你的真实业务相近。检查普通网页时,可以选择一个响应稳定、体积较小的 HTTPS 地址;检查开发环境时,可以选择代码托管平台的 API 或原始文件地址;检查视频场景时,单纯请求首页并不能代表后续 CDN 下载质量。目标 URL 不宜过多,否则周期性检测会给节点和目标站点增加不必要的请求。通常准备两个到三个具有不同网络特征的地址,再使用“多数通过”原则,比依赖一个站点更抗误判。
| 判断项 | 建议做法 | 避免的问题 |
|---|---|---|
| 超时时间 | 根据业务设为 3000 至 8000 毫秒,并保持各节点一致 | 某节点超时更长,导致比较结果失真 |
| 失败阈值 | 连续失败 2 至 3 次后再触发切换 | 一次瞬时丢包造成频繁跳转 |
| 恢复阈值 | 新节点连续成功后才标记为健康 | 刚切换就遇到抖动,形成来回震荡 |
| 冷却时间 | 切换后至少等待 60 至 180 秒再重新决策 | 多个脚本同时运行,策略组不断改写 |
| 候选过滤 | 排除过期、重复、明确标记为备用的节点 | 把故障节点或低质量节点选回去 |
在候选排序方面,可以先建立明确的优先级,而不是完全交给字符串排序。例如把日常主力节点放入 PRIMARY 组,把备用节点放入 BACKUP 组;脚本首先检测主力组,全部失败时才进入备用组。若订阅节点名称带有地区、线路或倍率信息,可以通过完整名称列表维护候选,而不是凭“香港”“日本”等关键词判断质量。关键词只适合作为初筛,不能替代真实健康检查。
还要注意策略组的类型。对于已经由 url-test 自动维护的组,外部脚本再次频繁写入当前节点,可能与内核自己的测速调度互相干扰。更合理的做法是选择一个专门供脚本控制的 select 组,或者让脚本只在主策略组连续失败时介入。这样可以把“内核自动测速”和“业务级故障转移”分成两个层次,日志也更容易阅读。
动手实现:用 Python 调用 API 完成节点切换
下面的示例使用 Python 标准库,不依赖第三方包,适合放在个人电脑、NAS 或 Linux 定时任务中运行。它的流程是:读取策略组当前状态,逐个检测候选节点,通过 API 切换策略组,并使用连续失败与冷却时间避免震荡。示例中的密钥、组名和测试地址必须替换为你自己的值。
import json
import time
import urllib.parse
import urllib.request
API = "http://127.0.0.1:9090"
SECRET = "replace-with-your-secret"
GROUP = "AUTO_SELECT"
CANDIDATES = ["Node-A", "Node-B", "Node-C"]
TEST_URL = "https://www.gstatic.com/generate_204"
def request(path, method="GET", payload=None):
data = None
headers = {"Authorization": "Bearer " + SECRET}
if payload is not None:
data = json.dumps(payload).encode("utf-8")
headers["Content-Type"] = "application/json"
req = urllib.request.Request(API + path, data=data,
headers=headers, method=method)
with urllib.request.urlopen(req, timeout=10) as response:
return response.read().decode("utf-8")
def get_delay(node):
group = urllib.parse.quote(node, safe="")
url = urllib.parse.quote(TEST_URL, safe="")
result = request("/proxies/" + group + "/delay?url=" + url + "&timeout=5000")
return json.loads(result).get("delay")
def switch_node(node):
group = urllib.parse.quote(GROUP, safe="")
request("/proxies/" + group, method="PUT", payload={"name": node})
for node in CANDIDATES:
try:
delay = get_delay(node)
if isinstance(delay, int) and delay > 0:
switch_node(node)
print("selected:", node, "delay:", delay)
break
except Exception as error:
print("failed:", node, error)
else:
print("no healthy node found")
这个最小版本适合验证 API 连通性,但不建议未经修改就长期运行。生产或长期使用时,至少应增加以下能力:把检测结果写入日志;限制每轮最多切换一次;比较多个地址而不是一个地址;对 HTTP 状态码和响应内容做基本校验;在 API 返回 401、404 或 500 时输出明确原因;并通过文件锁避免两个定时任务同时执行。
如果你更习惯 Shell,也可以使用 curl 组合 jq 完成同样工作。但 Shell 在处理包含空格、引号或 Unicode 的节点名称时更容易出现转义问题。Python、Node.js 或 Go 更适合构建带状态、重试和日志的自动化工具。无论采用哪种语言,都应把 API 地址、密钥、策略组名称和检测 URL 放在环境变量或权限受控的配置文件中,而不是硬编码到共享脚本。
- 在 Clash 或 Mihomo 配置中确认
external-controller已启用,并设置新的随机secret;重启内核后用curl /version验证接口是否响应。 - 调用
/proxies,找到真正需要控制的策略组,记录其完整名称以及可用节点名称,不要凭界面上的缩写猜测。 - 先手动调用延迟接口,对两个候选节点分别测试,确认 URL 编码、认证头和节点名称都正确。
- 运行切换脚本,观察客户端界面和连接日志,确认 PUT 请求改变的是目标策略组,而不是同名的嵌套组或订阅生成组。
- 将脚本放入定时任务前,加入锁文件、冷却时间和日志轮转;连续观察一天以上,再根据误切换情况调整阈值。
安全、定时运行与故障排查
API 安全边界
external-controller 拥有修改策略组的能力,不能按普通状态接口对待。最安全的默认值是监听本机回环地址,并通过系统权限限制脚本文件。若必须远程控制,不建议直接把 9090 端口映射到公网,而应使用 VPN、SSH 隧道或带访问控制的反向代理,并限制管理来源。即使设置了 secret,也不应把接口当成具备完整身份管理、审计和细粒度权限的企业管理系统。
调试结束后,检查 shell 历史、CI 日志和异常报告中是否留下 Bearer Token。脚本输出只记录节点名称、延迟、错误类型和时间,不要把完整请求头写入日志。多人共用一台服务器时,应给定时任务单独的系统用户,并把配置文件权限收紧到只有该用户可读。
定时任务与状态管理
Linux 可以使用 systemd timer 或 cron,Windows 可以使用任务计划程序,macOS 则可以使用 launchd。无论使用哪一种,运行环境都应显式设置工作目录、Python 路径、环境变量和日志位置。常见错误是手动运行脚本正常,但定时任务失败,原因往往不是 Clash,而是任务没有继承用户的环境变量,或者执行时机早于客户端内核启动。
定时周期不宜过短。每分钟轮询一次会产生大量检测请求,还可能与内核自身测速撞车;对于普通办公场景,三到十分钟一次通常更合理。脚本应保存上一次选择的节点和最近切换时间,启动时先读取状态,而不是每次都从候选列表第一项开始。若系统重启后状态文件损坏,应回退到策略组现有节点,并在日志中标记“状态重置”,不要静默切换。
常见故障定位方法
- 返回 401:优先检查
Authorization: Bearer格式、密钥是否包含多余空格,以及修改配置后是否真的重启了内核。 - 返回 404:检查策略组或节点名称是否经过 URL 编码,并确认你调用的是当前内核支持的接口路径。
- 延迟接口全部失败:先在客户端手动选择节点,再观察连接日志;也要确认测试 URL 在当前网络环境下没有被拦截或临时下线。
- PUT 成功但界面没有变化:确认写入的是
select类型策略组。由url-test或订阅脚本自动接管的组,可能会在下一轮测速后覆盖人工选择。 - 节点来回跳转:提高连续失败阈值,加入冷却时间,降低检测频率,并检查是否同时运行了多个脚本或多个客户端实例。
- 切换后部分应用仍然失败:通过
/connections查看实际命中的策略组,确认问题是节点质量、规则顺序、DNS 解析还是应用没有经过系统代理。
常见问题与方案总结
external-controller 可以监听局域网地址吗?
可以,但不建议为了方便直接监听所有网卡。只有在确实需要另一台设备管理时,才考虑绑定受控的局域网地址,并同时设置强密钥、防火墙白名单和加密隧道。完成远程维护后,恢复到 127.0.0.1 是更稳妥的做法。局域网并不等于可信网络,访客 Wi-Fi、虚拟机网络和恶意软件都可能访问开放端口。
API 检测延迟能代表节点一定可用吗?
不能。延迟接口主要反映某个目标 URL 的一次请求结果,无法覆盖所有协议、域名、长连接和大文件下载场景。它适合做快速筛选,而不是最终质量证明。实际方案应结合多个目标地址、连续成功率、连接日志和业务体验;如果你的主要需求是视频、游戏或开发 API,还应选择与这些场景更接近的检测目标。
已经有 url-test 策略组,还需要写 API 脚本吗?
不一定。只想自动选择低延迟节点时,内置 url-test 通常已经够用。只有当你需要自定义失败阈值、按业务拆分策略、记录历史数据、执行黑名单过滤、接入告警或跨设备控制时,external-controller API 才更有价值。建议先使用 YAML 验证策略组结构,再用 API 增加自动化能力。
Clash Verge 和 Mihomo 的 API 配置完全一样吗?
基本控制思路相同,但具体支持的字段、策略组行为和客户端界面可能不同。Clash Verge 或 Clash Verge Rev 只是图形界面,真正提供 API 的通常是其运行中的 Clash 或 Mihomo 内核。排查时应先调用 /version 确认内核,再以该版本的接口行为为准,不要把不同客户端的菜单名称直接等同于 API 资源名称。
相比之下,部分同类客户端或传统 VPN 工具通常只提供一个全局开关,节点切换依赖手动操作,既不能读取策略组状态,也难以根据连续失败、业务域名和冷却时间建立可审计的自动决策;一些看似支持“智能线路”的方案还会把测速、规则和切换逻辑封装起来,出现问题时用户很难判断究竟是节点故障还是策略误判。Clash 在这方面的优势,是通过 YAML 提供清晰的策略组基础,再借助 external-controller API 暴露版本、节点、延迟、连接和运行时切换能力,让进阶用户可以按自己的网络环境编写检查、日志和回滚逻辑。无论你是在 Clash Verge Rev 桌面端维护办公线路,还是在服务器上运行 Mihomo 并用定时任务管理备用节点,都能逐步建立可验证、可调整的自动切换流程。如果还没有合适的客户端,可以前往客户端下载页,根据系统选择对应版本。