Clash external-controller API 节点自动切换进阶配置指南
在日常使用中,我们经常会遇到只有 PC 端开启了代理,但手机、电视盒或其他移动设备也需要科学上网的情况。通过 Clash Verge Rev 的「允许局域网连接(Allow LAN)」功能,你可以轻松地将电脑的代理网络共享给同一 Wi-Fi 下的所有设备。本文将手把手带你完成从软件开关到 Windows 防火墙策略的完整配置流程。
external-controller 是什么:把 Clash 变成可编排的代理服务
Clash 的图形界面适合人工查看节点、切换策略组和观察连接日志,但当你希望定时测速、自动剔除失效节点,或者把代理状态接入监控系统时,仅依靠手动操作就不够了。external-controller 是 Clash、Clash Verge、Clash Verge Rev、Mihomo 等内核提供的外部控制接口。开启后,其他程序可以通过 HTTP API 读取运行状态、查询代理组、切换当前节点、刷新配置,并执行部分运行时控制操作。
可以把它理解为「Clash 控制面板的程序化入口」。浏览器中的客户端界面本身也需要与内核通信,只是它把 API 请求、按钮和状态展示封装起来了。自动切换脚本则可以绕过图形界面,按照延迟、成功率、失败次数或业务优先级执行相同的管理动作。这样一来,节点管理就从一次性的人工选择,变成了可以重复运行、记录日志、自动回滚的运维流程。
需要注意的是,external-controller 只负责控制 Clash,不会凭空产生代理节点,也不会改善质量很差的线路。它通常与配置文件中的 proxy-groups、proxy-providers 和健康检查参数配合使用。API 负责「发出动作」,策略组负责「承载动作结果」,节点测速则负责「提供决策依据」。三者职责清晰,自动化配置才容易维护。
使用前先确认内核差异
不同 Clash 分支支持的接口路径和字段可能略有不同,尤其是原版 Clash、Clash Premium、Clash Meta 与 Mihomo 之间。本文示例以常见的 Clash API 兼容接口为基础,实际部署时应先通过 /version 和 /proxies 验证当前客户端是否支持对应功能。
第一步:开启 external-controller 并限制访问范围
在 YAML 配置中,通常使用下面几个字段开启外部控制服务。external-controller 是监听地址与端口,secret 是 API 认证密钥。为了让本机脚本访问,可以监听在 127.0.0.1;只有确实需要让局域网监控机或另一台管理主机访问时,才考虑监听局域网地址。
external-controller: 127.0.0.1:9090
secret: "replace-with-a-long-random-secret"
如果客户端已经自动生成了控制端口,不要在多个配置层重复定义同一字段。Clash Verge 或 Mihomo 客户端可能通过设置页面、启动参数或配置覆盖功能写入 external-controller,最终生效值应以运行时接口为准。修改 YAML 后,重新加载配置并查看日志,确认类似「RESTful API listening」的启动信息已经出现。
- 打开当前实际使用的配置文件或配置覆写页面,确认 external-controller 没有被其他配置覆盖。
- 将监听地址优先设置为
127.0.0.1,端口可以使用未被其他程序占用的本地端口。 - 生成长度足够、不可预测的 secret,不要使用用户名、端口号或简单的
123456。 - 重载配置后请求版本接口,确认 API 能够响应,再开始编写自动切换逻辑。
不要把控制端口直接暴露到公网
external-controller 不是普通的只读状态页面,它通常具备切换节点、刷新配置等控制能力。若把监听地址设置为 0.0.0.0,又没有防火墙、强密钥或额外反向代理保护,端口扫描者可能接管你的代理策略。即使设置了 secret,也不建议把它直接映射到公网;远程管理应通过 VPN、SSH 隧道或严格限制来源地址实现。
用命令行验证时,常见请求格式如下。Authorization 请求头的值必须带上 Bearer 前缀,secret 中若含有特殊字符,也应避免在 shell 中直接拼接而造成转义错误。
curl -H "Authorization: Bearer replace-with-a-long-random-secret" \
http://127.0.0.1:9090/version
curl -H "Authorization: Bearer replace-with-a-long-random-secret" \
http://127.0.0.1:9090/proxies
第二步:掌握节点自动切换所需的 API
自动切换不需要调用所有接口,先掌握版本检查、代理列表、延迟测试和策略组切换即可。接口返回通常是 JSON,脚本应读取字段而不是依赖图形界面上的文字。策略组名称可能包含中文、空格或特殊符号,因此请求 URL 时必须进行 URL 编码,不能假定所有组名都叫「节点选择」。
| 用途 | 常见接口 | 说明 |
|---|---|---|
| 检查内核 | GET /version |
确认控制端口可用,并记录 Clash 或 Mihomo 版本 |
| 读取代理 | GET /proxies |
获取节点、策略组及当前选中代理 |
| 测速节点 | GET /proxies/{name}/delay |
对指定节点请求延迟测试,通常需要传 url 与 timeout 参数 |
| 切换策略 | PUT /proxies/{group} |
把策略组的当前代理切换为指定节点 |
延迟测试并不等同于真实业务质量。一个节点能够快速完成 HTTP HEAD 请求,只能说明它在当前时刻能访问测速地址;视频、网页、游戏和长连接对带宽、丢包、TLS 握手及 UDP 的要求不同。因此,自动化脚本应把延迟当成筛选条件,而不是唯一的评分指标。更稳妥的做法是结合多次采样、连续失败次数和实际业务探测。
策略组切换请求的主体一般是一个 JSON 对象,例如将名为「自动选择」的策略组切换到「东京-01」。组名和节点名必须使用运行时返回的真实名称。如果节点已经从订阅中删除,API 可能返回错误,脚本不能把这类错误静默忽略,否则界面看似仍有选择,实际流量却可能落到失效节点。
curl -X PUT \
-H "Authorization: Bearer replace-with-a-long-random-secret" \
-H "Content-Type: application/json" \
-d '{"name":"东京-01"}' \
"http://127.0.0.1:9090/proxies/自动选择"
建议先做只读验证
- 先请求
/version,确认端口和认证没有问题。 - 再请求
/proxies,保存策略组名称与节点名称。 - 只对一个明确的节点执行 delay 测试,不要一开始并发请求全部节点。
- 最后切换测试策略组,并在客户端连接面板中确认实际出口已经变化。
第三步:用 YAML 策略组建立基础自动选择
如果你的需求只是「从可用节点中选择延迟较低者」,优先使用 Clash 原生的自动策略组,而不是立刻编写常驻脚本。常见类型包括 url-test、fallback 和 load-balance。它们都可以利用 url、interval 和 tolerance 等参数进行健康检查,但决策方式并不相同。
| 策略组类型 | 适合场景 | 主要特点 | 注意事项 |
|---|---|---|---|
url-test |
优先使用延迟较低的节点 | 周期测速并选择响应较快的成员 | 测速快不代表带宽和稳定性最好 |
fallback |
强调主备和故障转移 | 当前节点不可用时按顺序尝试后备节点 | 节点顺序需要体现业务优先级 |
load-balance |
多节点分担连接 | 按请求在多个代理之间分配流量 | 不适合需要固定出口 IP 的业务 |
proxy-groups:
- name: Auto-Proxy
type: url-test
proxies:
- Tokyo-01
- Singapore-02
- Frankfurt-01
url: "https://www.gstatic.com/generate_204"
interval: 300
tolerance: 80
- name: Failover-Proxy
type: fallback
proxies:
- Tokyo-01
- Singapore-02
- Frankfurt-01
url: "https://www.gstatic.com/generate_204"
interval: 120
interval 控制检测周期,设置过短会增加节点请求、设备 CPU 和网络消耗,也可能触发服务商的频率限制。设置过长则会让故障节点持续工作较久。桌面日常使用可以从 300 秒开始,办公室网关或重要服务可根据节点数量调整到 120 至 300 秒之间。tolerance 用于避免节点延迟只有几毫秒差异时频繁跳转,数值越合理,连接越不容易抖动。
测试 URL 应选择稳定、响应内容简单且在你的网络环境中可访问的地址。不要只因为某个测速域名在一条线路上表现良好,就认定所有业务都正常。若访问目标需要代理,测速请求也必须按照 Clash 当前的出站逻辑执行;否则测试的可能只是本地网络,而不是节点到目标站点的完整链路。
第四步:通过脚本实现可控的测速、切换与故障转移
原生策略组适合通用场景,但技术用户通常还会有更细的要求,例如连续失败三次才切换、切换后至少保持十分钟、排除某些地区节点、保留上一次成功节点,或把结果写入 Prometheus、邮件和企业微信。此时可以使用 Python、Node.js 或 Shell 调用 external-controller API。
脚本的核心流程应当是「读取配置、筛选候选、逐个探测、计算结果、执行切换、验证结果、记录状态」。不要每次运行都无条件切换到测速第一名,否则网络延迟的正常波动会造成频繁迁移,表现为网页连接重置、下载中断和登录会话失效。
- 读取当前策略组。 从
/proxies获取当前选择、候选节点和可用状态,过滤掉名为 DIRECT、REJECT 以及嵌套策略组的项目。 - 设置候选范围。 可以按节点名称、地区标签、协议类型或订阅来源筛选,避免把不适合当前业务的节点纳入自动选择。
- 执行多次测试。 对每个节点进行两到三次探测,使用中位数而不是单次最小值,减少偶然抖动对结果的影响。
- 应用切换阈值。 只有新节点比当前节点快出一定幅度,或当前节点连续失败达到阈值时,才调用 PUT 接口切换。
- 切换后再次验证。 等待几秒后读取策略组状态,并重新测试目标 URL;若切换失败,应恢复上一个已知可用节点。
- 保存运行状态。 记录时间、节点、延迟、失败原因和切换结果,便于判断是节点问题、API 问题还是脚本自身异常。
import requests
import statistics
import time
API = "http://127.0.0.1:9090"
HEADERS = {"Authorization": "Bearer replace-with-a-long-random-secret"}
GROUP = "Auto-Proxy"
TEST_URL = "https://www.gstatic.com/generate_204"
def get_proxies():
response = requests.get(API + "/proxies", headers=HEADERS, timeout=5)
response.raise_for_status()
return response.json()["proxies"]
def test_node(name):
params = {"url": TEST_URL, "timeout": 5000}
response = requests.get(
API + "/proxies/" + requests.utils.quote(name, safe=""),
headers=HEADERS, params=params, timeout=8
)
if response.status_code != 200:
return None
return response.json().get("delay")
# Production code should add retry, threshold, logging and rollback.
生产环境中还应加入超时、指数退避、并发上限和锁机制。超时不能无限等待,否则前一个探测卡住会阻塞整个循环;并发也不能一次打满所有节点,否则容易造成大量连接和误判。若脚本通过定时任务运行,要避免上一次任务尚未结束时下一次任务再次启动,可以使用文件锁、进程锁或单实例服务。
切换不是越频繁越好
节点自动切换会中断部分已有连接,尤其是下载、WebSocket、视频播放和需要固定出口的登录会话。建议采用「故障优先、性能其次」的策略:先保证当前节点仍然可用,只有当新节点明显更优或当前节点确实失败时才切换,并设置冷却时间与最短驻留时间。
第五步:安全加固、监控与常见故障排查
API 自动化上线后,安全边界与可观测性和功能本身同样重要。首先,secret 应通过环境变量或受限权限的配置文件注入,不要直接提交到 Git 仓库,也不要把带有认证头的完整 curl 命令写进公开日志。其次,控制端口最好只监听本机;若必须跨主机访问,应在防火墙中只允许固定管理地址,并通过 WireGuard、SSH 隧道或可信内网传输。
对于需要反向代理的场景,应关闭不必要的公开路径,限制请求方法,并在代理层设置认证和速率限制。不要为了方便而允许任意来源的跨域请求。浏览器端跨域访问尤其需要谨慎,因为一个被入侵的网页可能尝试向本机控制端口发起请求。即使 API 具备 secret,也不应把密钥嵌入公开前端页面。
监控方面,至少记录 API 可达率、测速成功率、当前节点、连续失败次数、最近切换时间和切换原因。将「API 请求失败」与「节点测速失败」分开统计非常重要:前者可能是客户端退出、端口冲突或密钥错误,后者才更接近线路质量问题。若所有节点在同一时刻失败,还要检查本地 DNS、上游网络、系统时间和订阅是否过期,而不是立即判定所有节点同时失效。
| 现象 | 优先检查 | 处理建议 |
|---|---|---|
| 连接被拒绝 | 客户端是否运行、端口是否正确 | 检查监听日志与端口占用,确认配置已加载 |
| 返回 401 | secret 与 Bearer 格式 | 重新读取实际配置,避免复制了多余空格或引号 |
| 返回 404 | 接口路径和内核分支 | 先请求 /version,核对当前客户端 API 兼容性 |
| 测速全部超时 | 测试 URL、DNS、节点和本机网络 | 换一个可验证地址,并与客户端手动测试结果对照 |
| 节点来回跳转 | interval、tolerance 和切换阈值 | 增加采样次数、冷却时间和最短驻留时间 |
最后,建议为脚本保留一个明确的人工接管入口。例如当自动化连续失败时,切换到预先确认的备用组,而不是继续循环尝试;在客户端界面中保留手动选择能力,并把脚本选择的节点写入日志。自动化的目标是降低重复劳动、缩短故障恢复时间,而不是让使用者失去控制。
一些只提供简单手动切换的代理客户端,在节点数量增加后往往需要反复打开界面、逐个测速,规则覆写、日志查看和故障恢复也容易分散在不同页面;有的工具虽然能测速,却缺少稳定的 API 或策略组联动能力。Clash 通过 external-controller、结构化 YAML、原生健康检查和清晰的策略组模型,把人工操作与脚本编排放在同一套体系中,既可以保持图形界面的直观体验,也能满足自动化运维、故障转移和安全审计需求。如果你希望进一步实践这套方案,可以前往下载适合自己平台的 Clash 客户端,从本地 API 验证开始逐步构建可靠的节点自动切换流程。