Clash RESTful API使用教程，程序化控制代理组与分流规则

本文详解Clash RESTful API的启用配置与接口调用方法，涵盖代理组切换、规则更新及流量监控等核心功能，帮助用户实现跨境网络环境的自动化管理。

启用API服务

Clash RESTful API默认关闭，需在配置文件中手动开启，编辑config.yaml，添加：

external-controller: 127.0.0.1:9090
secret: "your-password"

external-controller指定监听地址与端口，secret设置鉴权密钥，建议绑定127.0.0.1避免未授权访问，远程管理需改为0.0.0.0并配置防火墙。

核心接口调用流程

获取代理组状态

发送GET请求至/proxies可获取所有代理组详情，重点关注type字段：

• select：手动选择节点，适合固定线路需求
• url-test：自动测速选优，延迟敏感场景首选
• fallback：故障自动转移，学术资源访问稳定性保障

curl http://127.0.0.1:9090/proxies \
  -H "Authorization: Bearer your-password"

动态切换节点

PUT请求/proxies/{group-name}实现程序化换线：

curl -X PUT http://127.0.0.1:9090/proxies/自动选择 \
  -H "Content-Type: application/json" \
  -d '{"name": "香港节点01"}'

更新分流规则

POST /rules接口支持运行时追加规则，无需重启服务：

# 请求体示例
{
  "type": "DOMAIN-SUFFIX",
  "payload": "github.com",
  "proxy": "国际加速"
}

规则优先级自上而下,建议将DOMAIN精确匹配置于DOMAIN-SUFFIX之前，IP-CIDR用于段级控制，GEOIP处理国家级分流。

TUN模式与系统代理的API控制

通过PATCH /configs切换运行模式：

• TUN模式：接管全流量（含UDP/游戏流量），需管理员权限
• 系统代理：仅HTTP/HTTPS流量，兼容性好但无法处理ICMP

curl -X PATCH http://127.0.0.1:9090/configs \
  -d '{"tun": {"enable": true}}'

实战：自动化脚本示例

结合cron实现定时节点健康检查：

import requests
api = "http://127.0.0.1:9090"
headers = {"Authorization": "Bearer your-password"}
# 检测延迟，自动切换
def auto_switch():
    r = requests.get(f"{api}/proxies/自动选择/delay", headers=headers)
    if r.json()["delay"] > 500:
        requests.put(f"{api}/proxies/手动选择", 
                    json={"name": "备用线路"}, headers=headers)

常见问题排查

现象：API返回403 Forbidden 原因：鉴权失败或IP白名单限制 解决：检查secret配置，确认请求头格式为Bearer token，远程访问需设置external-controller: 0.0.0.0:9090

现象：切换节点后流量未走新线路 原因：连接池保持长连接 解决：调用/connections清空现有连接，或设置--force参数强制断开

现象：TUN模式开启后DNS解析异常 原因：DNS劫持与系统DNS冲突 解决：配置dns.enable: true并指定nameserver为可信DNS，避免本地DNS污染

对于需要稳定国际网络加速的用户,建议配合支持Clash RESTful API的订阅服务使用，通过程序化节点管理实现智能负载均衡，满足跨境办公与学术资源访问的自动化需求。