API Reference

🔌 API 参考

本页记录当前正式 Release 面向用户的 HTTP 路由和 /sub 参数。参数名称、布尔值和机器可读字段保持原样。

路由

方法	路径	作用
GET	/version	版本、构建和源代码身份页面
GET	/healthz	进程存活检查，返回 ok
GET	/inspect	/sub 可视化诊断台
GET	/dashboard	可选运行仪表盘；仅在统计启用时注册
GET	/dashboard/data	可选统计 JSON；仅在统计启用时注册
GET	/sub	生成目标配置或 explain 诊断
HEAD	/sub	执行转换检查，不返回正文
GET	/getruleset	为生成配置转换远程规则集

配置文件还可以通过 [aliases] / [[aliases]] 注册重定向别名，例如 /clash 到 /sub?target=clash。

必需参数

参数	类型/格式	必填	说明
target	字符串	是	目标格式；也可以使用 auto，但建议显式填写
url	URL 编码字符串；多个输入以 `	` 分隔	通常是

当前正式 Release 的显式目标：

clash, clashr, surge, quan, quanx, loon, surfboard, stash,
mellow, singbox, ss, ssd, ssr, sssub, v2ray, v2rayn,
v2rayng, shadowrocket, trojan, vless, hysteria2, mixed

输入、配置和输出参数

参数	类型/示例	缺省行为	说明
config	URL/路径	使用部署默认外部配置	外部配置；请求值需要 URL 编码
group	字符串	空	订阅组名
filename	字符串	由目标或后端决定	响应下载文件名
ver	整数	Surge 兼容默认值	Surge 主版本
interval	整数	托管配置默认	托管配置更新间隔，不等同于 Provider 前缀 interval:
strict	布尔	配置默认	托管配置严格更新
dev_id	字符串	配置默认	Quantumult X 兼容设备参数；属于敏感信息
upload	布尔	false	转换后尝试上传；受安全档位限制
upload_path	字符串	空	上传目标路径；属于敏感信息
append_info	布尔	配置默认	附加订阅流量信息

节点筛选和名称

参数	类型	说明
include	正则表达式	仅保留匹配节点，或转换为目标能表示的远程筛选
exclude	正则表达式	排除匹配节点，或转换为目标能表示的远程筛选
rename	重命名规则	按规则修改节点名称
emoji	布尔	覆盖 Emoji 总开关
add_emoji	布尔	添加 Emoji
remove_emoji	布尔	移除已有 Emoji
append_type	布尔	在节点名称后追加类型
sort	布尔	启用排序
sort_script	布尔	使用部署者配置的排序脚本
fdn	布尔	过滤已弃用节点

节点选项

参数	类型	说明
udp	布尔	覆盖目标能够表示的 UDP 选项
tfo	布尔	覆盖 TCP Fast Open
scv	布尔	覆盖 skip-cert-verify；开启会降低安全性
tls13	布尔	覆盖目标能够表示的 TLS 1.3 选项
new_name	布尔	Clash 新字段名兼容参数；Mihomo 路径会强制使用新字段

生成方式

参数	类型	说明
list	布尔	生成节点列表；Clash 远程订阅会转为后端解析
script	布尔	生成 Clash Script 模式；与部分规则扩展不兼容
expand	布尔	展开规则集；本项目 Clash 默认不展开
classic	布尔	生成 classical Rule Provider
insert	布尔	是否加入部署者配置的插入节点
prepend	布尔	插入节点放在原始节点之前

Provider 扩展

参数	类型	适用范围	说明
provider_proxy_direct	布尔	Clash/ClashR Provider	当前请求默认是否写入 proxy: DIRECT
provider_headers	逗号分隔请求头名称	Clash/Stash Provider	从当前 HTTP 请求选择允许的头写入 Provider

url 中还可以使用：

tag:<标签>,
provider:<名称>,
interval:<秒>,
proxy_direct:<true|false|1|0>,

适用范围和优先级见特色参数与扩展语法。

诊断

参数	类型	说明
explain	布尔	返回脱敏 JSON 诊断，不返回目标配置；抑制上传

诊断报告会列出参数状态。未知参数值不会原样回显。

布尔值

不同兼容参数沿用项目既有布尔解析。面向用户的示例统一使用：

true
false

Provider 前缀 proxy_direct: 还明确接受 1 和 0。不要依赖未记录的拼写。

常见响应头

响应头	说明
X-Request-ID	服务端生成的请求关联 ID
Subscription-UserInfo	上游订阅流量信息，存在且允许附加时返回
Content-Disposition	下载文件名
Cache-Control / Pragma	缓存边界；诊断和错误通常禁止公共缓存
Vary	响应依赖的请求头，例如目标自动识别或 Provider User-Agent

/getruleset

主要参数：

参数	格式	说明
type	整数	规则转换类型，由生成器按目标格式选择
url	URL-safe Base64	原始规则 URL
group	URL-safe Base64	某些目标需要的策略组

普通用户通常不需要手写此接口。生成配置会自动构造正确 URL。

错误处理

错误响应正文通常同时包含英文和中文。先读取具体原因，再根据请求诊断和故障排查处理。不要只根据“400”或“500”推测原因。