文档 控制器 API

控制器 API 文档

Clash / Mihomo 内核暴露了一套本地 RESTful 接口（外部控制器），面板、脚本都是靠它拿数据和下指令。约 30 个接口，按功能分组列出请求方式和返回字段。

请求示例

面板/脚本发给内核的每一条请求都要带上认证头，格式统一如下：

curl Shell
curl -H 'Authorization: Bearer ${secret}' http://${controller-api}/configs?force=true \
  -d '{"path": "", "payload": ""}' -X PUT
  • ${secret} 是配置文件里设置的 secret 密钥
  • ${controller-api} 是配置文件里设置的 external-controller 监听地址
  • ?force=true 是查询参数，部分接口需要携带
  • '{"path": "", "payload": ""}' 是要更新的资源数据

如果请求里要传文件路径，而路径又不在 mihomo 工作目录下，需要手动设置 SAFE_PATHS 环境变量把它加入安全路径，语法与操作系统的 PATH 变量一致（Windows 用分号分隔，其他系统用冒号分隔）。

日志

GETWS/logs

获取实时日志。

  • 可选参数 ?level=log_level，log_level 可选 info/warning/error/debug
  • 可选参数 ?format=structured，携带后输出结构化日志（含 time/level/message/fields）
  • 标准模式每行推送一个 JSON：type 日志级别、payload 日志内容
  • 结构化模式：time（HH:MM:SS）、level、message、fields（附加字段数组）

流量信息

GETWS/traffic

获取实时流量，up/down 单位是字节/秒，upTotal/downTotal 单位是字节，每秒推送一次。

  • up 当前上传速率　down 当前下载速率
  • upTotal 累计上传字节数　downTotal 累计下载字节数

内存信息

GETWS/memory

获取实时内存占用（字节），每秒推送一次。

  • inuse 当前内存使用量　oslimit 系统内存限制（固定为 0）

版本信息

GET/version

获取内核版本信息。

  • meta 是否为 Meta 版本　version 版本号字符串

缓存

POST/cache/fakeip/flush

清除 fakeip 缓存，返回 HTTP 204。

POST/cache/dns/flush

清除 DNS 缓存，返回 HTTP 204。

运行配置

GET/configs

获取当前运行配置，返回一个 JSON 对象，包含 port、socks-port、mixed-port、mode、log-level、allow-lan、ipv6、tun 等字段。

PUT/configs

重新加载基本配置，携带参数 ?force=true，返回 HTTP 204。

PATCH/configs

局部更新基本配置，例如 '{"mixed-port": 7890}'，返回 HTTP 204。

POST/configs/geo

更新 GEO 数据库，携带 '{"path": "", "payload": ""}'，返回 HTTP 204。

POST/restart

重启内核，携带 '{"path": "", "payload": ""}'，返回 HTTP 204。

更新

POST/upgrade

更新内核，可选 ?channel=xxx 指定更新通道、?force=true 强制更新，返回 {"status": "ok"}。

POST/upgrade/ui

更新面板（须先在配置里设置 external-ui），返回 {"status": "ok"}。

POST/upgrade/geo

更新 GEO 数据库，返回 HTTP 204。

策略组

GET/group

获取全部策略组信息，返回 proxies 数组，每项格式同 /proxies/{name}。

GET/group/{group_name}

获取指定策略组信息，格式同 /proxies/{name}。

GET/group/{group_name}/delay

对策略组内全部节点测速，返回新的延迟数据，并清除该自动策略组当前的 fixed 固定选择。

  • 携带参数 ?url=xxx&timeout=5000
  • 可选 ?expected=xxx，期望的 HTTP 响应状态码，支持范围写法如 200/204、200-299
  • 返回以节点名为键、延迟毫秒数为值的对象，如 {"节点A": 120, "节点B": 350}

代理

GET/proxies

获取全部代理/策略组信息，返回以名称为键的 proxies 对象，每条公共字段包括：

  • name/type（如 Shadowsocks、VMess、DIRECT、Selector、URLTest 等）
  • udp/uot/xudp/tfo/mptcp/smux 能力标志
  • alive 当前是否存活，history 延迟历史（time+delay），extra 按测速 URL 分组的额外历史
  • interface/routing-mark/provider-name/dialer-proxy
  • 策略组额外含：now 当前选中（LoadBalance 无此字段）、all 成员列表、testUrl、hidden、icon、emptyFallback、expectedStatus（Selector 无）、fixed（仅 URLTest/Fallback）
GET/proxies/{name}

获取指定代理/策略组信息，字段同上（普通代理只有公共字段）。

PUT/proxies/{name}

切换该策略组当前选中的节点，携带 '{"name":"日本"}'，返回 HTTP 204。

DELETE/proxies/{name}

清除该代理/策略组的 fixed 固定选择（Selector 类型除外），返回 HTTP 204。

GET/proxies/{name}/delay

对指定代理测速，携带 ?url=xxx&timeout=5000（可选 ?expected=xxx），返回 {"delay": 120}。

代理集合

GET/providers/proxies

获取全部代理集合信息，返回以集合名称为键的 providers 对象，每个集合含元信息及代理列表。

GET/providers/proxies/{name}

获取指定代理集合信息，含配置信息及 proxies 代理列表。

PUT/providers/proxies/{name}

更新该代理集合，返回 HTTP 204。

GET/providers/proxies/{name}/healthcheck

触发该代理集合的健康检查，返回 HTTP 204。

GET/providers/proxies/{name}/{proxy_name}

获取集合内指定代理的信息，字段同 /proxies/{name}。

GET/providers/proxies/{name}/{proxy_name}/healthcheck

对集合内指定代理测速，携带 ?url=xxx&timeout=5000，返回 {"delay": 120}。

规则

GET/rules

获取全部规则，返回 rules 数组，每项包含：

  • index 索引（从 0 开始）　type 规则类型　payload 匹配内容　proxy 目标代理/策略组
  • size 规则条目数（仅 GEOIP/GEOSITE 有效，其余为 -1）
  • 可选 extra：disabled/hitCount/hitAt/missCount/missAt
PATCH/rules/disable

按索引临时禁用/启用规则（重启后失效），携带 '{"0": false,"1": true}'，返回 HTTP 204。

规则集合

GET/providers/rules

获取全部规则集合信息，返回以名称为键的 providers 对象。

PUT/providers/rules/{name}

更新指定规则集合，返回 HTTP 204。

连接

GETWS/connections

获取活跃连接信息，可选参数 ?interval=milliseconds（刷新间隔，默认 1000ms）。

  • downloadTotal/uploadTotal 累计流量　memory 当前内存占用
  • connections 活跃连接数组：id、metadata（源/目标地址、协议、进程名等）、upload/download、start、chains/providerChains 代理链路、rule/rulePayload 命中的规则
DELETE/connections

关闭全部连接，返回 HTTP 204。

DELETE/connections/{id}

关闭指定连接，返回 HTTP 204。

域名查询

GET/dns/query

获取指定名称和类型的 DNS 查询结果，携带 ?name=example.com&type=A。

  • Status DNS 响应码　Question 查询问题数组
  • TC/RD/RA/AD/CD 各类 DNS 标志位
  • 可选 Answer/Authority/Additional：均为记录数组，每项含 name/type/TTL/data

存储

GET/storage/{key}

获取指定 key 的存储值，不存在时返回 null。

PUT/storage/{key}

写入指定 key 的值（须为合法 JSON，最大 1MB），携带 '{"foo": "bar"}'，返回 HTTP 204。

DELETE/storage/{key}

删除指定 key 的存储值，返回 HTTP 204。

DEBUG

/debug 系列接口需要内核启动时的日志级别设为 debug。

PUT/debug/gc

触发一次主动 GC，返回 HTTP 204。

GET/debug/pprof

浏览器打开 http://${controller-api}/debug/pprof 查看原始 DEBUG 信息：

  • allocs：每个函数调用的内存分配情况（栈上/堆上大小与次数），用来排查内存泄漏、频繁申请等问题
  • heap：堆上内存使用详情，包含分配块的大小、数量、地址并按大小排序，用来定位内存占用过高的位置

安装 Graphviz 后可以看图形化报告：

Shell pprof
go tool pprof -http=:8080 http://127.0.0.1:xxxx/debug/pprof/heap
go tool pprof -http=:8080 http://127.0.0.1:xxxx/debug/pprof/allocs

浏览器访问 http://${controller-api}/debug/pprof/heap?raw=true 即可下载报告文件，遇到问题时可以把它上传到 issue 里方便排查。