节点切换通常通过客户端的代理组页面手动完成,但当某个节点延迟升高、连接中断,或需要在固定时间切换出口时,反复打开界面操作并不方便。Mihomo 兼容的 Clash 内核提供 external-controller 控制接口,可供本机脚本或管理面板读取代理组、查看节点状态并提交切换请求。把这些操作串成流程后,就能按健康检查结果自动选择候选节点,并在切换失败时进行重试和回退。
需要先明确控制接口的能力边界:API 可以读取运行状态,也可以请求可切换策略组更换当前代理;但它不会自动替你设计故障判定、候选节点排序和重试策略。不同客户端打包的内核版本、配置覆写方式和 API 兼容程度也可能不同。下文以 Mihomo 兼容的控制接口为例,具体字段应以正在运行的内核版本和客户端日志为准。
Clash external-controller API节点自动切换进阶配置指南
认识 external-controller 与认证方式
external-controller 指定 Clash 内核的控制 API 监听地址,它与 mixed-port、port 和 socks-port 等代理监听端口用途不同。代理端口用于接收应用流量;控制端口用于查询和修改内核运行状态。向控制端口发送代理请求,不会让流量自动经过节点;把浏览器或系统代理指向控制端口,也不会产生正常代理连接。
在自行维护的配置中,控制接口通常可以像下面这样绑定到本机回环地址,并配置密钥:
external-controller: 127.0.0.1:9090
secret: "replace-with-a-long-random-secret"
图形客户端可能会在启动时生成或覆写这两项,因此配置文件中的值不一定就是当前生效值。应在客户端的内核设置、运行配置或启动日志中确认 API 地址和端口。若本机端口 9090 已被其他程序占用,内核可能无法启动控制接口;可更换端口,但脚本和面板也要同步调整。
启用 secret 后,API 请求通常通过 HTTP Bearer 认证传递密钥。以查询策略组为例:
curl -sS \
-H "Authorization: Bearer replace-with-a-long-random-secret" \
http://127.0.0.1:9090/proxies
如果未配置密钥,本机请求可能不需要认证,但这不应成为将接口暴露到局域网或公网的理由。控制 API 能够改变代理策略、查看连接信息并读取运行状态;任何能够访问接口的主体都可能获得超出普通代理使用所需的控制权限。
限制监听范围与访问权限
个人电脑上的自动化脚本通常只需访问 127.0.0.1。不要为了让另一台设备调用方便,就把控制接口改为 0.0.0.0 并直接开放防火墙端口。若确实需要远程管理,应使用受控的内网通道或 VPN,限制来源地址,设置足够长且随机的密钥,并避免在浏览器地址栏、公开脚本仓库、日志或截图中留下认证信息。
还应区分控制接口与允许局域网共享的代理端口。即使需要让手机使用本机代理,也不代表手机需要访问控制 API。将代理服务和管理接口分开限制,可以减少误操作和密钥泄漏造成的影响。
查询代理组并确定可切换对象
自动切换之前,先通过 GET /proxies 读取当前内核看到的代理对象。响应中通常包含代理节点、策略组以及它们的类型、当前选择和可选成员。不要只凭客户端界面上的显示名称猜测 API 路径:策略组名称可能包含空格、中文或特殊字符,而且订阅更新后节点名称也可能改变。
查询单个策略组可使用 GET /proxies/{name}。路径中的组名需要进行 URL 编码;如果策略组名为“自动选择”,不能把其中的中文和空格未经处理地拼进 URL。API 返回的对象也可能是测速组、负载均衡组或其他类型,并非每种组都能像 select 组那样通过请求指定成员。自动切换脚本应先检查组类型和可选代理,再决定是否提交修改。
curl -sS \
-H "Authorization: Bearer replace-with-a-long-random-secret" \
"http://127.0.0.1:9090/proxies/%E8%8A%82%E7%82%B9%E9%80%89%E6%8B%A9"
响应里常见的 now 字段表示当前选中的成员,all 列表表示组中可用的选项。脚本应将当前成员排除在候选列表之外,避免无意义地重复切换;同时也要排除 DIRECT、REJECT 等特殊选项,除非业务规则明确允许把它们作为回退目标。
- 先确认目标组:用准确的组名读取数据,不要假定所有配置都使用
节点选择或PROXY作为组名。 - 再确认组类型:只有支持选择成员的组,才适合由脚本调用切换接口。
- 最后检查候选项:验证候选节点仍在组内,且不是需要排除的特殊策略。
- 保留当前状态:记录切换前的
now值,以便请求失败时报告或回退。
切换请求、健康检查与失败重试
对可切换策略组提交修改时,常见接口形式为 PUT /proxies/{group},请求体通过 name 指定目标成员。组名在 URL 路径中需要编码;JSON 请求体中的节点名则应由 JSON 编码器生成,避免引号、反斜杠或中文字符造成格式错误。
curl -sS -X PUT \
-H "Authorization: Bearer replace-with-a-long-random-secret" \
-H "Content-Type: application/json" \
-d '{"name":"节点 A"}' \
"http://127.0.0.1:9090/proxies/%E8%8A%82%E7%82%B9%E9%80%89%E6%8B%A9"
请求返回成功并不等于目标站点已可用。建议把“切换请求”和“切换后验证”分成两个步骤:先再次读取目标组,确认 now 已变为预期节点;再通过该节点的延迟测试接口检查实际连通性。兼容的 Mihomo API 通常提供 GET /proxies/{name}/delay,并可使用 url 和 timeout 参数指定测试地址与超时时间。测试网址应稳定、响应时间合理,并与日常要保障的访问目标相关。
curl -sS \
-H "Authorization: Bearer replace-with-a-long-random-secret" \
"http://127.0.0.1:9090/proxies/%E8%8A%82%E7%82%B9%20A/delay?url=https%3A%2F%2Fwww.gstatic.com%2Fgenerate_204&timeout=5000"
延迟结果只说明该测试请求在指定时间内得到响应,不能证明所有网站、应用协议或地区线路都正常。若请求超时、返回错误状态或结果中没有可用延迟值,应将本轮判定为失败,而不是把空值当成零延迟。自动切换还要设定冷却时间,避免多个检查任务在网络抖动时同时切换,造成节点来回跳变。
动手:用 Python 执行一次受控切换
下面的示例使用 requests 库,读取策略组、检查候选项、尝试切换并核对当前选择。它不负责永久后台轮询,也不包含针对所有节点的测速排序;先手动运行一次并确认组名、节点名和 API 认证正确,再扩展成定时任务。将密钥放入环境变量,而不是直接写进文件。
import os
import time
import requests
from urllib.parse import quote
BASE = "http://127.0.0.1:9090"
GROUP = "节点选择"
TARGET = "节点 A"
SECRET = os.environ["CLASH_SECRET"]
session = requests.Session()
session.headers.update({
"Authorization": f"Bearer {SECRET}",
"Content-Type": "application/json",
})
def group_url(name):
return f"{BASE}/proxies/{quote(name, safe='')}"
def get_group():
response = session.get(group_url(GROUP), timeout=5)
response.raise_for_status()
return response.json()
group = get_group()
if group.get("type") != "Selector":
raise RuntimeError(f"目标组不可按 select 方式切换:{group.get('type')}")
if TARGET not in group.get("all", []):
raise RuntimeError(f"目标节点不在当前组中:{TARGET}")
previous = group.get("now")
if previous == TARGET:
print(f"当前已使用目标节点:{TARGET}")
else:
response = session.put(
group_url(GROUP),
json={"name": TARGET},
timeout=5,
)
response.raise_for_status()
for attempt in range(1, 4):
time.sleep(1)
current = get_group().get("now")
if current == TARGET:
print(f"切换成功:{previous} -> {TARGET}")
break
if attempt == 3:
raise RuntimeError(f"切换后状态未确认,当前选择:{current}")
else:
示例中的 Selector 是需要按实际 API 响应核对的类型值;如果当前内核返回值不同,或策略组不是可选择类型,应停止执行并检查接口响应,不要删掉类型检查后强行调用。代码末尾的 else: 作为逻辑说明标记,实际运行时应删除它以及前一行对应的结束结构,并按下面的完整重试结构替换循环部分:
switched = False
for attempt in range(1, 4):
time.sleep(1)
current = get_group().get("now")
if current == TARGET:
switched = True
print(f"切换成功:{previous} -> {TARGET}")
break
if not switched:
raise RuntimeError(f"切换后状态未确认,原选择:{previous}")
为了避免示例被当成完整生产程序,实际部署时还应增加健康检查、日志记录和异常处理。检查目标节点的延迟接口时,先对目标名称进行 URL 编码,再判断响应码与 JSON 内容;如果健康检查失败,可尝试下一个候选节点,但每次切换后都要重新读取策略组状态。连续失败达到上限后应停止尝试并告警,而不是无限循环。若希望回到原节点,也要先确认原节点仍在当前组内,并对回退后的状态再次验证。
建立可预测的重试策略
简单地“失败就立即再试”容易放大短暂故障。更稳妥的策略是每个候选节点最多尝试一次,单次 API 请求设置明确超时,切换后等待一到数秒再核对状态,并为健康检查设置合理上限。候选节点全部失败时,保留当前有效状态或回到已验证的备用节点,同时记录原因和时间。
- 区分错误类型:连接被拒绝可能是控制服务未运行;HTTP 401 或 403 通常提示认证或访问策略问题;HTTP 404 可能是路径或名称错误。
- 限制切换频率:设置冷却窗口,例如一次自动切换后至少等待 30 秒再启动下一轮,防止反复震荡。
- 重复确认结果:更新请求后重新查询组状态,不能只依赖 PUT 的响应状态码。
- 留下可审计日志:记录组名、原节点、目标节点、检查结果和失败原因;日志中不得写出控制密钥。
部署自动化时的运行与安全建议
自动切换脚本可以由 Windows 任务计划程序、macOS 的启动项或 Linux 的 systemd timer 定期触发,也可以由监控程序在连接失败时调用。选择调度方式时,应确保同一时刻只有一个任务修改同一策略组。可以使用锁文件、进程锁或调度器的并发限制避免重复执行;脚本启动时还应检查本机控制接口是否可连接,避免把“内核尚未启动”误判成“节点故障”。
策略组之间可能存在嵌套关系。例如规则引用一个总入口组,而总入口组再选择地区组。自动化时应明确实际要修改的是哪一层:切换底层地区组可能影响多个上层入口;只切换某个专用组则可能完全不影响当前流量。先在客户端观察目标连接命中的策略组,再用 API 读取相同组的当前状态,能避免“脚本显示切换成功,但实际访问没有变化”的情况。
不要把健康检查等同于用户体验检查。延迟较低的节点仍可能无法访问特定服务,单一测试地址也可能被缓存、限速或单独路由。可靠的检测可以结合多个不同目标,但要控制请求频率,并避免把第三方服务当作高频探测端点。若检查的是业务服务,应关注真实请求的成功率、超时和错误码,而不只比较一个毫秒数。
客户端升级或订阅更新后,建议重新检查控制器端口、密钥、组名、组类型和候选节点。自动化运行环境也需要单独确认:终端手动运行正常,不代表计划任务继承了相同的环境变量、工作目录和用户权限。把程序路径、配置路径和日志路径明确写入任务设置,并在升级后执行一次人工验证,可以减少后台任务静默失败的风险。
常见问题
调用 API 返回 401 或 403 怎么办?
先检查请求是否带有 Authorization: Bearer 请求头,以及密钥是否与当前运行内核的 secret 一致。图形客户端可能使用自己的运行配置,手工编辑的 YAML 未必已被加载。403 也可能与客户端、访问控制或接口版本有关,应同时查看内核日志,并确认请求确实发往正确的本机端口。
策略组或节点提示不存在怎么办?
通过 GET /proxies 重新读取当前对象名称,再检查大小写、空格和中文字符,并对 URL 路径中的名称进行编码。订阅更新可能删除或重命名节点;旧脚本应先验证目标仍在当前组的 all 列表中,不能假设配置内容一直不变。
API 显示请求成功,但实际流量没有切换是什么原因?
常见原因包括操作了没有被当前规则引用的策略组、目标组不是可手动选择类型,或连接复用了已有会话。切换后应重新读取 now,再查看连接记录中的命中规则和策略组;必要时使用新建连接测试,而不是只观察一个已建立的长连接。
延迟最低的节点一定是最佳节点吗?
不一定。延迟接口只反映特定测试地址和时间窗口内的响应情况,不能全面代表吞吐量、稳定性或目标服务可用性。自动选择时应结合成功率、连续失败次数、冷却时间和业务目标设定阈值,并保留人工选择或停止自动切换的方式。