Skip to Content
功能介绍HTTP API

HTTP API

Stash 运行时提供一组 HTTP 控制接口，可用于查询运行状态、切换策略组、刷新远程资源，以及进行 DNS、代理和路由诊断。接口与 Clash 的控制 API 保持兼容，现有的 Clash 控制面板可以直接连接 Stash；在此基础上，Stash 还提供了一组以 /stash 和 /diagnosis 开头的扩展接口。

开启与认证

  • iOS / tvOS：在「设置」-「外部访问」中开启外部控制，并设置 API 密钥。页面会显示可供外部控制器连接的地址。
  • macOS：在设置中配置控制端口，默认为 9090。

所有请求通过 Authorization 请求头携带密钥：

Authorization: Bearer <API 密钥>

WebSocket 连接无法自定义请求头时，可以改用查询参数 token 传递密钥，例如 /traffic?token=<API 密钥>。

⚠️

执行脚本和读写脚本存储的接口只接受来自本机回环地址、且已设置密钥的请求。

基础信息

方法路径说明
GET/返回 App 版本、系统版本、设备 ID、架构与平台
GET/version返回版本号
GET/configs返回当前 mode、log-level 与混合代理端口
PATCH/configs切换运行模式，请求体为 {"mode": "rule"}，可选 rule、global、direct
GET/logs实时日志流，支持 level 参数
GET/traffic当前上下行速率与累计流量
GET/stash/speed当前速率与累计流量

连接

方法路径说明
GET/connections活动连接列表，包含来源、目标、命中的规则与代理链
GET/connections/{id}单条连接的详情与日志
DELETE/connections/{id}断开指定连接
GET/httpHTTP 引擎抓取的最近请求列表
GET/http/{id}单条 HTTP 请求的完整请求与响应内容

规则

方法路径说明
GET/rules当前生效的规则列表
GET/rules/count规则总数，规则集合按其包含的条目数计算
GET/rules/match不发起真实连接，返回指定目标会命中的规则与出站

/rules/match 的查询参数：

  • target：必填，域名、域名:端口 或 IP 地址。
  • network：tcp 或 udp，默认为 tcp。
  • port：目标端口，默认为 443；target 中已带端口时以其为准。
  • process、user-agent：模拟进程路径与 User-Agent，供 PROCESS-NAME、PROCESS-PATH、USER-AGENT 规则匹配。
  • src-ip、src-port：模拟来源地址与端口，供 SRC-IP、SRC-PORT 规则匹配。
  • resolve：是否允许为匹配进行 DNS 解析，默认为 true。

响应包含命中的规则（类型、内容与序号）、最终出站、代理链、解析结果以及评估过的规则数量。

代理与策略组

方法路径说明
GET/proxies全部代理与策略组及其延迟、当前选择
PUT/proxies/{name}切换策略组的选择，请求体为 {"name": "<代理名>"}
GET/proxies/{name}/delay对指定代理执行一次延迟测试并返回结果
GET/proxies/{name}/info代理的详细信息
GET/stash/proxies代理名称列表
GET/stash/proxy/count代理数量
GET/stash/proxy/display/v2App 策略组页面使用的汇总数据
PUT/stash/proxy/delay/{name}触发指定代理的延迟测试

Tailscale 节点另有一组接口：GET /proxies/{name}/tailscale 返回节点状态，GET /proxies/{name}/tailscale/stream 持续推送状态变化，POST /proxies/{name}/tailscale/login 与 /logout 发起登录和登出，PUT 与 DELETE /proxies/{name}/tailscale/exit-node 设置或清除出口节点。

远程资源

方法路径说明
GET/providers/proxies远程代理集列表及其节点
PUT/providers/proxies/{name}立即更新指定远程代理集
GET/providers/proxies/{name}/healthcheck对该代理集的节点执行延迟测试
GET/providers/rules规则集合列表
PUT/providers/rules/{name}立即更新指定规则集合
GET/providers/scripts脚本列表
PUT/providers/scripts/{name}立即更新指定脚本
GET/providers/geodbGeoIP / ASN 数据库信息
PUT/providers/geodb/{name}立即更新指定数据库
PUT/stash/provider立即更新全部远程资源

DNS

方法路径说明
GET/dns/recordDNS 缓存内容，包含问题、记录类型、答案、应答服务器与耗时
GET/dns/countDNS 缓存条目数
GET/dns/resolve/{host}通过当前 DNS 配置解析域名并返回记录
POST/dns/flush清空 DNS 缓存

诊断

方法路径说明
GET/diagnosis/dns逐个测试已配置的 DNS 服务器，返回名称、耗时与错误
GET/diagnosis/dns/latencyDNS 解析延迟
GET/diagnosis/proxies逐个测试代理的 HTTP 与 UDP 连通性
GET/diagnosis/traceroute对目标执行路由追踪
GET/diagnosis/usedMemory核心当前内存占用
GET/diagnosis/availableMemory可用内存

/diagnosis/traceroute 的查询参数：target（必填），proxy（指定出站代理，省略时按规则选择），direct（设为 true 时追踪直连路径），maxHops 与 probes（最大跳数与每跳探测次数）。响应先给出路由决策（命中的规则、出站与代理链），再逐跳返回探测结果，每个地址附带国家、ASN 与机构信息。经代理转发的目标只能追踪到代理服务器为止。

脚本

方法路径说明
POST/script/evaluate以模拟环境执行一段脚本，返回输出、日志、发出的通知与耗时
GET / POST/script/runtime/store/{key}读取或写入脚本持久化存储

/script/evaluate 的请求体字段：script（必填，脚本内容），engine（webkit 或 jsc），timeout（秒），argument，name。

实时推送

列表类接口（如 /traffic、/connections、/http、/dns/record、/proxies、/diagnosis/dns/latency）支持升级为 WebSocket 连接。升级后 Stash 先推送一次完整数据，之后按 interval 查询参数指定的间隔（单位为毫秒）在数据变化时推送。/diagnosis/dns 和 /diagnosis/proxies 只以 WebSocket 方式提供，测试结果逐条推送。

面板

GET /dashboard 返回内置的 Web 控制面板，可直接在浏览器中打开。

Last updated on
MTProto 代理服务器服务提供商订阅