Clash 外部控制 API 完全指南：接口、面板与自动化脚本

Mihomo 内核自带一个 RESTful API。Clash Verge 的界面本身就是通过它和内核通信的——理解这套接口，你可以用脚本做任何界面上能做的事。

开启与安全

external-controller: 127.0.0.1:9090
secret: "一段足够长的随机字符串"

生成一个随机 secret：

openssl rand -hex 24

认证方式

所有请求带上 Bearer Token：

curl -H "Authorization: Bearer 你的secret" http://127.0.0.1:9090/version

WebSocket 接口（日志、流量）可以用查询参数：

ws://127.0.0.1:9090/traffic?token=你的secret

接口全表

方法	路径	作用
GET	`/version`	内核版本
GET	`/configs`	当前配置
PATCH	`/configs`	修改运行时配置（端口、模式等）
PUT	`/configs?force=true`	重载配置文件
GET	`/proxies`	所有节点与策略组
GET	`/proxies/:name`	单个节点/组的详情
PUT	`/proxies/:name`	切换策略组选中的节点
GET	`/proxies/:name/delay`	测试单个节点延迟
GET	`/group/:name/delay`	测试整个策略组
GET	`/connections`	当前所有连接
DELETE	`/connections`	断开所有连接
DELETE	`/connections/:id`	断开指定连接
GET	`/rules`	当前生效的规则列表
GET	`/providers/proxies`	所有 proxy-provider
PUT	`/providers/proxies/:name`	手动更新某个 provider
GET	`/providers/rules`	所有 rule-provider
PUT	`/providers/rules/:name`	手动更新规则集
GET	`/logs`	日志流（WebSocket）
GET	`/traffic`	实时流量（WebSocket）
GET	`/memory`	内存占用（WebSocket）

常用操作

查看所有策略组和当前选中的节点

curl -s -H "Authorization: Bearer $SECRET" \
  http://127.0.0.1:9090/proxies | jq '.proxies | to_entries[] | select(.value.type=="Selector") | {group: .key, now: .value.now}'

切换节点

curl -X PUT \
  -H "Authorization: Bearer $SECRET" \
  -H "Content-Type: application/json" \
  -d '{"name":"HK-01"}' \
  http://127.0.0.1:9090/proxies/PROXY

策略组名含中文或 emoji 时需要 URL 编码：

GROUP=$(printf '%s' "🚀 节点选择" | jq -sRr @uri)
curl -X PUT -H "Authorization: Bearer $SECRET" \
  -d '{"name":"HK-01"}' \
  "http://127.0.0.1:9090/proxies/$GROUP"

测试节点延迟

curl -s -H "Authorization: Bearer $SECRET" \
  "http://127.0.0.1:9090/proxies/HK-01/delay?timeout=5000&url=http%3A%2F%2Fwww.gstatic.com%2Fgenerate_204"
# 返回 {"delay":123}

切换代理模式

curl -X PATCH -H "Authorization: Bearer $SECRET" \
  -H "Content-Type: application/json" \
  -d '{"mode":"global"}' \
  http://127.0.0.1:9090/configs

mode 可选 rule / global / direct。同一个接口还能改 log-level、allow-lan 等。

重载配置

curl -X PUT -H "Authorization: Bearer $SECRET" \
  -H "Content-Type: application/json" \
  -d '{"path":"/etc/mihomo/config.yaml"}' \
  "http://127.0.0.1:9090/configs?force=true"

断开所有连接

curl -X DELETE -H "Authorization: Bearer $SECRET" \
  http://127.0.0.1:9090/connections

换节点后连接不会自动切换（已建立的 TCP 连接会继续用旧节点），执行这条能强制全部重连。

更新 provider

# 更新节点订阅
curl -X PUT -H "Authorization: Bearer $SECRET" \
  http://127.0.0.1:9090/providers/proxies/main

# 更新规则集
curl -X PUT -H "Authorization: Bearer $SECRET" \
  http://127.0.0.1:9090/providers/rules/cn-domain

实用脚本

一、自动选择延迟最低的节点

#!/bin/bash
# pick-fastest.sh —— 测速后切到最快的节点
set -euo pipefail
API="http://127.0.0.1:9090"
SECRET="你的secret"
GROUP="AUTO"
TEST_URL="http%3A%2F%2Fwww.gstatic.com%2Fgenerate_204"

# 触发整组测速
curl -s -H "Authorization: Bearer $SECRET" \
  "$API/group/$GROUP/delay?timeout=5000&url=$TEST_URL" > /dev/null

# 取出延迟最低的
BEST=$(curl -s -H "Authorization: Bearer $SECRET" "$API/proxies" \
  | jq -r --arg g "$GROUP" '
    .proxies[$g].all[] as $n
    | .proxies[$n]
    | select(.history | length > 0)
    | select(.history[-1].delay > 0)
    | "\(.history[-1].delay) \(.name)"
  ' | sort -n | head -1 | cut -d' ' -f2-)

echo "最快节点：$BEST"
curl -s -X PUT -H "Authorization: Bearer $SECRET" \
  -d "{\"name\":\"$BEST\"}" "$API/proxies/$GROUP" > /dev/null

二、监控节点健康，全挂时告警

#!/bin/bash
# health-watch.sh
API="http://127.0.0.1:9090"
SECRET="你的secret"

ALIVE=$(curl -s -H "Authorization: Bearer $SECRET" "$API/proxies" \
  | jq '[.proxies[] | select(.type != "Selector" and .type != "URLTest")
         | select(.history | length > 0)
         | select(.history[-1].delay > 0)] | length')

if [ "$ALIVE" -eq 0 ]; then
  echo "$(date '+%F %T') 所有节点不可用" >> /var/log/mihomo-alert.log
  # 这里可以接你的通知渠道
fi

三、统计流量最大的连接

curl -s -H "Authorization: Bearer $SECRET" http://127.0.0.1:9090/connections \
  | jq -r '.connections
      | sort_by(-.download)
      | .[:10][]
      | "\(.download/1048576 | floor)MB  \(.metadata.host // .metadata.destinationIP)  \(.metadata.processPath // "-")"'

排查「谁在偷跑流量」时很好用。

四、实时看日志

# 需要 websocat 或 wscat
websocat "ws://127.0.0.1:9090/logs?token=你的secret&level=info"

部署 Web 面板

面板是纯静态页面，通过 API 和内核通信。

方式一：内核托管（推荐）

external-ui: /etc/mihomo/ui
external-ui-name: metacubexd
external-ui-url: "https://面板发布地址/dist.zip"

把面板文件解压到 external-ui 指定的目录，然后浏览器访问：

http://内核地址:9090/ui

首次打开需要填 API 地址（http://内核地址:9090）和 secret。

方式二：用公开托管的面板

面板本身是纯前端，你也可以用别人托管好的页面，填上你的 API 地址和 secret 即可连接。

常见面板对比

面板只是 API 的前端，随时可以换，不影响内核

用 API 做的几个巧妙用法

定时切换节点

晚高峰自动切到专线，白天用普通节点：

# crontab
0 20 * * * /usr/local/bin/switch-node.sh "IPLC-HK"
0 1  * * * /usr/local/bin/switch-node.sh "AUTO"

快捷键切换（桌面端）

配合 AutoHotkey（Windows）或 Hammerspoon（macOS），一个快捷键切换全局/规则模式：

# 切到全局
curl -X PATCH -H "Authorization: Bearer $SECRET" \
  -d '{"mode":"global"}' http://127.0.0.1:9090/configs

接入监控系统

/traffic 是 WebSocket 接口，每秒推送上下行速率。可以采集后写入时序数据库，做成流量图表。

排查

快速验证：

curl -i -H "Authorization: Bearer $SECRET" http://127.0.0.1:9090/version

返回 200 和版本号 JSON 就是通的。

小结

API 能做界面上的一切，包括切节点、改模式、重载配置
secret 是必须的，尤其监听在 0.0.0.0 时
策略组名含中文/emoji 要 URL 编码
换节点后记得 DELETE /connections，否则已有连接还在用旧节点
面板只是前端，自建比用第三方托管的更安全

相关：Mihomo 家庭网关部署、流量与连接排查。