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 家庭閘道部署、流量與連接排查。