API 进阶

Clash API 全接口梳理：自动化脚本的进阶用法

2024年11月20日 约16分钟 API 梳理

外部控制器 API 是自动化一切的基础：切节点、查连接、看流量、改配置都能用 HTTP 完成。 这篇按接口分类完整梳理一遍，附 curl 示例与两个能直接用的进阶脚本。

认证方式

# 请求头里带 Bearer token，token 即配置中的 secret
curl -H "Authorization: Bearer your-secret" http://127.0.0.1:9090/version

接口全景

接口 方法 用途
/version GET 版本与认证验证
/configs GET / PATCH 读配置 / 运行时改模式、端口
/proxies GET 代理组与节点列表
/proxies/{name} GET / PUT 单节点详情 / 切换选中
/proxies/{name}/delay GET 节点延迟测试
/connections GET / DELETE 活跃连接列表 / 断开全部
/rules GET 当前生效的规则列表
/dns/query GET 用内核 DNS 解析域名
/traffic / /logs GET 实时流量 / 日志流（SSE）

进阶脚本 1：运行时切换全局模式

# 临时切到全局模式（用于验证节点是否可用）
curl -X PATCH -H "Authorization: Bearer secret" \
  -d '{"mode":"global"}' http://127.0.0.1:9090/configs

进阶脚本 2：按域名查命中规则

# 用内核 DNS 解析，确认域名走了哪条规则
curl -H "Authorization: Bearer secret" \
  "http://127.0.0.1:9090/dns/query?name=example.com&type=A" | jq .

自动化组合拳

进阶用法是组合多个接口：定时轮询 /proxies/{组}/delay 选出最优节点，通过 PUT 切换； 同时监听 /connections 统计每个进程的流量，超过阈值自动断开；配合 /logs 流 把内核日志推送到告警系统。整套脚本可以挂在同一台机器上，不依赖客户端 GUI。

安全注意事项

API 默认监听回环地址，自动化脚本在同机跑没问题；如果跨设备调用，务必用 external-controller 绑定内网 IP + 强 secret，并避免把 secret 写进会同步到 Git 的脚本里（用环境变量代替）。

相关阅读