HTTP 控制 API 和 Web 控制台
[General]
external-http-controller = 127.0.0.1:9090
external-http-secret = your-secret-token
external-http-ui = true
external-http-cors = false
Chute 提供内嵌的 HTTP 控制 API 和 Web 控制台,类似于 Clash 和 Surge 面板。API 通过 REST 端点暴露引擎状态、流量、连接、DNS、策略控制和配置管理。
Surge 的 http-api = <密钥>@<主机>:<端口> 会被读作 external-http-controller 加 external-http-secret。各部分也可以分开写:http-api-secret、http-api-ui、http-api-cors 分别读作 external-http-secret、external-http-ui、external-http-cors,http-api-web-dashboard 同样读作 external-http-ui;配置保存时使用 external-http-* 键。http-api-tls 不受支持(控制器只使用明文 HTTP),只会给出提示。
external-http-controller(默认:禁用)
external-http-controller = 127.0.0.1:9090
控制台服务期间常驻的请求上限为 macOS 4 MB,iOS、tvOS 与 Android 1 MB。
HTTP 控制服务器的地址和端口。使用 127.0.0.1 表示仅本地访问。绑定到任何非回环地址(例如 192.168.1.5:9090)都必须显式设置 external-http-secret——否则服务器会拒绝启动,并在日志里说明缺什么。
通配地址(0.0.0.0、::、*)在这项检查里算作非回环:它监听所有网卡,与「仅本地」正好相反。可接受的写法有 0.0.0.0:9090、*:9090(两者等价),IPv6 则写 [::]:9090——裸写 :::9090 会自动补上方括号;解析不了的地址会被报告为配置错误,而不是悄悄让控制器不启动。整个 127.0.0.0/8 都算回环,而不只是 127.0.0.1。
external-http-secret(默认:自动生成的令牌)
external-http-secret = your-secret-token
用于 API 鉴权的 Bearer 令牌。请求必须包含请求头 Authorization: Bearer <secret>——令牌只接受这个请求头,不支持通过查询参数携带,比较采用常量时间算法。鉴权失败返回 401,响应体为 {"ok": false, "error": {"code": "unauthorized", "message": "missing or invalid token"}}。所有数据路由都受鉴权保护:/api/* 路径、Clash 兼容别名,以及只有 Chute Android 还提供的旧式路由(/status、/policies、/dns、/records 等)——这些旧式路由同样只接受这个请求头里的令牌。Chute Android 自己的远程面板现在只用 /api/* 路径。Web 控制台的页面和静态资源(/、/assets/…,Chute Android 上还有 /ui)不需要令牌(external-http-ui = false 时它们根本不存在——页面返回 404)。
未写这一项时,Chute 会生成一个令牌,而不是不加鉴权地提供服务。生成的令牌以仅属主可读的权限写入 Chute 共享目录下的 control-token 文件——不在配置旁边:iOS 与 tvOS 上是 App Group 容器,Android 上是应用的私有数据目录——重启后继续沿用,各端应用会展示给你——见打开 Web 控制台。控制 API 可以交出连接数据库,而其中的记录带有本次运行见过的每一条 URL、请求头和进程名,所以「默认开放」不是一个合理的默认值。
如果确实要不加鉴权地提供服务,请在配置里明说:
external-http-secret = none
该写法仅在回环绑定时被接受。在非回环地址上,none 和「不写」都不够:控制服务器会拒绝启动,并说明它需要什么。
升级提示:如果你此前依赖「不写
external-http-secret即不鉴权」,本机脚本会开始收到401。要么从应用里读出生成的令牌,要么写上external-http-secret = none,明确保留旧行为。
external-http-ui(默认:true)
external-http-ui = true
启用后,Chute 在控制器地址提供内嵌的 Web 控制台。Web 控制台提供概览、连接管理、DNS 检查、流量监控、策略控制和配置编辑。设置为 false 则仅启用 API 而禁用 UI。
打开 Web 控制台
控制台就在控制服务器的地址上,各端应用都能把地址和令牌交给你——包括自动生成的那一个,否则你没有别的办法读到它:
- Chute Mac:菜单栏 → 打开 Web 控制台,以及复制 Web 控制台令牌。连接详情窗口里还有请求与历史,同样会打开控制台——打开的是首页,不是那条连接。
- Chute iOS:控制面板 → Web 控制台那一行 → 打开、复制地址或复制访问令牌。
- Chute tvOS:控制面板另有一行Web 控制台地址,显示主机与端口。选中它时,若监听器能被其他设备访问,就显示二维码——登录令牌只藏在二维码里,不显示在屏幕上;若控制器绑定在回环地址,则显示一段说明,因为回环上的控制台没法从手机打开。
- Chute Android:控制面板 → Web 控制台地址 → 打开或复制地址,另有一行生成的访问令牌,点按即复制。令牌是你自己配置的 secret 时,这两行都不会出现——这种 secret 永远不会被显示。
这些入口给出的地址把令牌带在查询参数里。页面加载时会消费掉它并从地址栏移除,所以打开链接就是一次完整登录,没人需要手抄 32 个十六进制字符。
external-http-cors(默认:false)
external-http-cors = true
在 API 响应中启用 CORS(跨域资源共享)头。当 Web 控制台或第三方工具需要从不同源访问 API 时非常有用。
API 端点:
| 方法 | 端点 | 描述 |
|---|---|---|
GET |
/api/status |
运行时状态、端口、运行时长 |
GET |
/api/traffic |
全局和按策略的流量计数器 |
GET |
/api/connections |
当前活跃连接 |
DELETE |
/api/connections/:id |
关闭一个连接 |
GET |
/api/connections/history |
历史连接记录 |
GET |
/api/connections/processes |
按进程统计的连接信息 |
GET |
/api/connections/:id/request |
某个连接捕获的请求数据 |
GET |
/api/connections/:id/response |
某个连接捕获的响应数据 |
GET |
/api/dns |
DNS 缓存记录 |
DELETE |
/api/dns/cache |
清空 DNS 缓存 |
DELETE |
/api/dns/records/:domain |
删除单条 DNS 记录 |
GET |
/api/config |
当前配置 |
PUT |
/api/config |
重新加载配置 |
POST |
/api/config/validate |
解析一份配置并报告其错误,但不加载它 |
GET |
/api/policies |
策略组及当前选择;每一项都带 hidden,标了 hidden=true 的组为 true |
PUT |
/api/policies/:group |
更改策略组选择 |
PUT |
/api/mode |
设置出站模式 |
GET |
/api/features |
功能开关状态 |
PUT |
/api/features/mitm |
切换 MitM |
PUT |
/api/features/record-traffic |
切换流量录制 |
GET |
/api/rules |
匹配器实际遍历的规则表、每条规则的来源,以及哪些改写规则命中过 |
POST |
/api/rules/match |
一个请求将会被选到哪里,不用真的发出去 |
GET |
/api/rules/user |
运行时添加的规则,排在模块和配置之前匹配 |
PUT |
/api/rules/user |
替换运行时规则 |
POST |
/api/rules/user |
在现有运行时规则之后追加规则 |
DELETE |
/api/rules/user |
删除全部运行时规则 |
GET |
/api/logs |
最近的日志条目 |
GET |
/api/loglevel |
当前日志级别,以及正在写入的分区 |
PUT |
/api/loglevel |
不重启就改日志级别或分区 |
GET |
/api/health |
引擎健康:拒绝计数、代际、内存占用、上次退出 |
GET |
/api/events |
本次运行的关键事件 |
GET |
/api/tailscale |
Tailscale 引擎实时状态 |
GET |
/api/scripts |
可按需运行的 generic 脚本 |
POST |
/api/scripts/run |
按名称运行一个 generic 脚本 |
POST |
/api/diagnostics/ping |
ICMP 或 TCP 可达性探测 |
POST |
/api/diagnostics/dns-query |
用运行中的解析器解析域名 |
POST |
/api/diagnostics/egress-probe |
检测地址:Apple 引擎上是本机地址;Android 上是设备在其物理网络上的公网地址,而不是代理的出口 |
POST |
/api/diagnostics/internet-test |
直连互联网测试:不经代理请求 internet-test-url |
POST |
/api/diagnostics/url-test/:policy |
运行某条策略的延迟测试 |
POST |
/api/diagnostics/bundle |
生成脱敏的诊断包 |
GET |
/api/connections/export |
以 HAR 1.2 导出连接 |
GET |
/api/rewrites |
所有改写/模拟响应族,以及 MitM 主机列表 |
GET |
/api/rewrites/:family |
某一族的规则 |
POST |
/api/rewrites/:family |
新增一条规则 |
DELETE |
/api/rewrites/:family/:id |
删除一条规则 |
DELETE |
/api/rewrites/:family |
清空某一族 |
GET |
/api/mitm/hosts |
当前被解密的主机 |
POST |
/api/mitm/hosts |
新增一个主机 |
DELETE |
/api/mitm/hosts/:host |
删除一个主机 |
DELETE |
/api/mitm/hosts |
清空列表 |
GET |
/api/rules/providers |
规则提供者与规则集,含每一个的状态——包括某个为何没能加载 |
端点说明:
GET /api/features按设置报告每个开关——record_traffic、mitm、mitm_h2、mitm_auto_quic_block、rewrite——以及licensed。effective说明实际运行的是什么,只针对五项:record_traffic、mitm、rewrite、scripts和lan_proxy。在免费版中这五项都是 false,所以开关可以显示为打开,而它的effective项为 false。inactive是一个对象,列出运行中的配置要求了、但在这个版本中不会运行的东西:计数scripts、scriptRules、dnsScripts、rewrites和mapLocals,以及标志mitm、bodyCapture、lanProxy和exitNode(Tailscale 广播,只有 Chute Mac 会做)。有许可证时,或者引擎停止时,所有计数都是 0,所有标志都是 false。GET /api/connections接受limit(正整数,默认与上限均为 1000)和cursor(只返回id大于游标的连接)。响应data包含connections、total、page_size、has_more、server_time,还有更多分页时附带next_cursor。since(秒,即之前某次应答的server_time)只返回在那一刻之后发生变化的连接,并附加active_ids,即当前所有打开着的连接的 id:之前某次应答里有、而这里没有的连接已经关闭。since晚于server_time时按0处理,于是返回全部连接。GET /api/connections/history接受limit(默认 100,上限 1000)和cursor/before(同义参数;同时传两个会被拒绝)。GET /api/connections/:id/request与.../response返回{"connection_id": <id>, "data": "<base64>"}。捕获内容超过 2 MiB 时返回413。没有 Chute Pro 时两者都返回403,附带request data is not available或response data is not available,之前有许可证时录下的正文也是如此。GET /api/config原样返回运行中的配置,包括凭证——http-auth、external-http-secret、ca-p12、ca-passphrase、WireGuard 密钥以及每个代理的密码——因此能访问控制 API,就能拿到所有这些凭证。只有诊断包会把凭证替换为<redacted>,而那份副本无法再载入:发给PUT /api/config的配置只要任何地方仍含<redacted>,就会以400被拒绝,返回的说明会指出第一处这样的行。请改为提交原始配置。GET与PUT /api/config也可以通过/api/configs访问,以及 Clash 的别名/configs。PUT /api/config接受 JSON{"configuration": "<full text>"}或直接以请求体承载裸配置文本(上限 1 MB)。成功后引擎会重新加载——若尚未运行则直接启动。PUT /api/policies/:group按policy、name、selected、select的顺序取请求体中第一个存在的键作为选择值;取值可以是策略名,也可以是数字下标的字符串。特殊组名GLOBAL用于设置全局选中策略。- 在
GET /api/policies中,每个策略、策略组和组成员都带有endpoint,即它当前通向的策略——会穿过策略组一路追下去,经由内置的PROXY时追到全局模式所选的策略——以及endpoint_ping,即那个策略的延迟。策略组自己的ping是0,并不测量,所以对策略组或PROXY来说,应该看endpoint_ping。 PUT /api/mode要求 JSON 数字:{"mode": 0}——0规则、1直连、2代理。PUT /api/features/mitm与PUT /api/features/record-traffic接受{"enabled": true}。GET /api/logs接受since(Unix 秒);内存缓冲区保留最近 1000 条,每条为{timestamp, wall_time, level, section, message}——timestamp与wall_time是同一个 Unix 秒数,时钟没有前进时会被往前拨一点,好让各条目严格有序。GET /api/health报告引擎当前持有什么、上一次因何拒绝了请求,以及上次运行是怎么结束的(clean、unclean或suspected_memory——见疑难解答)。addressFamily说明 Chute 如何判断 IPv6 出口——ipv6为healthy、confirming或degraded——并附带它为此采取过的各项操作的计数;在 Apple 引擎上,selfLoop报告自环防护的情况。两者都不含任何地址。GET /api/events返回内存中的事件环;?persisted=1改读本次运行已落盘的历史,关闭记录时返回available: false。- 未配置
[Tailscale]段时,GET /api/tailscale返回state: "idle"——这是正常回答,不是错误。 POST /api/diagnostics/*的各项探测既接受查询参数也接受 JSON 请求体,有 10 秒上限,且只回答一次。url-test/:policy对未定义的策略名直接报错,而不是去测REJECT。GET /api/scripts以{name, type}列出已启用的 generic 脚本;POST /api/scripts/run从请求体或查询字符串取name,上限与各项诊断探测相同,应答为{name, timedOut, result}——timedOut用来区分从未调用$done的脚本和跑完了的脚本。名称不是已启用的 generic 脚本时返回404。没有 Chute Pro 时返回403,script is not available。POST /api/rules/match回答一个请求会走到哪里,不用建立连接。它接受host(或者一个url,从中取主机和端口;URL-REGEX规则拿这个url原样来匹配,尽管在真实流量里它只会见到纯http://请求)、port(默认 443),以及可选的ip、protocol、process、process_path、src_ip、src_port、in_port、in_type、in_user、in_name、network、ssid、bssid、from_tun、user_agent——不认识的字段会连同可接受列表一起被拒绝,而不是被忽略。应答里有命中的规则matched(规则原文、类型、它指名的策略,以及策略组当前实际指向的resolved_policy)、policy、need_resolve,还有这次计算所依据的rule_count与match_generation。因为域名会被匹配两次——一次按名字,地址已知后再一次——所以passes每一轮一项;不传ip时只有解析前那一轮,应答会在note里说明。加explain=true可以拿到同样可能命中的候选规则,最多 50 条,外加没有展开的规则集数量。POST /api/config/validate解析一份配置然后扔掉:运行中的引擎什么都不会采纳。以{"configuration": "<full text>"}或直接裸文本发送。应答是valid、error_count、advisory_count、rule_count、policy_count,以及一个errors列表,每项为{line, severity, content, error}——severity区分被拒绝的行和被接受但有保留的行,content是出问题的那一行的原文(包括凭证,因为一条坏掉的[Proxy]行往往正是坏在存放密码的那个字段上),截断到 4096 个字符。在PUT /api/config之前用它,因为后者会重启你正在调试的这次运行。GET /api/loglevel报告当前的level、nslog_level、正在写入文件的sections,以及你可以设置的available_levels/available_sections。PUT(或PATCH)接受level、sections或两者:sections是分区名数组或字符串"all",空数组会被拒绝——要停止记录请用level为none。这样改级别不会重启本次运行,这正是它的意义:写在文件里的loglevel = verbose需要重载,而重载会把你正想看的东西弄丢。GET /api/rules还会返回rewrite_hits——本次运行命中过的每条改写或模拟响应规则及其次数。没出现在那里的规则从未命中过,这正是「改写看起来没生效」最常见的原因。这张表最多跟踪 512 条不同的规则,超出的部分以rewrite_hit_dropped_rules报告。rules按顺序列出匹配器实际遍历的全部规则:先是 Tailscale 自动规则,然后是通过/api/rules/user添加的规则,然后是模块规则,再是配置中的[Rule]段,最后是FINAL;rule_regions按下标一一对应地标出每一行的来源(front、user、module、configuration)。/api/rules/user保存引擎运行期间添加的规则,不需要重载,也不改动配置文件。它们排在 Tailscale 自动规则之后、模块规则和配置的[Rule]段之前,按给出的顺序匹配。GET列出它们;PUT替换它们,POST追加在已有规则之后,两者都接受{"rules": ["<rule line>", ...]}或单条{"rule": "<rule line>"},写法与配置文件中相同;DELETE全部删除。写入要么全部生效、要么全不生效:有一行无法解析,或者含有FINAL,就会以400拒绝,规则保持原样。策略未在运行中的配置里定义的规则也会被接受——它会以REJECT失败关闭——并在warnings中列出。close_rerouted默认为true,会关闭被改动的规则改道的连接,且只关闭这些连接;false则让所有连接保持打开——DELETE时以?close_rerouted=false传入。每个方法都会以当前的rules应答。这些规则在重载后保留,在引擎停止时消失。此路径不接受PATCH。POST /api/rewrites/:family接受{"rule": "<configuration line>"}——就是你会写进配置文件的那一行。解析不了的行会以400拒绝,而不会被存成一条永远匹配不到的规则。:family取值为url-rewrite、header-rewrite、body-rewrite、mock。这样添加的规则只存在于运行中的引擎,不会写回配置文件。GET /api/connections/export?format=har返回的是一份HAR 1.2 文档,POST /api/diagnostics/bundle返回的是一个zip——两者都是文件,因此与其他端点不同,不套{"ok": ..., "data": ...}信封。export接受source(current,默认;或history)、limit(默认 100,最大 300)、ids,以及bodies=1以包含已捕获的正文。每个条目都带一个_kl对象,装着 HAR 没有字段承载的东西:选中的策略、命中的规则,以及命中的改写。- 串联连接在
GET /api/connections和GET /api/connections/history中的记录带有chainPath,即从本设备到出口的路径,例如Airport/HK-01 → Landing;只用了一个策略的连接为空,HAR 导出中则是_kl.chain。在GET /api/traffic的按策略计数中,上游也会计入它为串联连接承载的字节;全局总量只计一次。
示例——读取状态,然后切换策略组:
curl -H "Authorization: Bearer your-secret-token" http://127.0.0.1:9090/api/status
{"ok":true,"data":{"running":true,"outbound_mode":0,"mitm":false, ...}}
curl -X PUT -H "Authorization: Bearer your-secret-token" \
-d '{"policy": "ProxyB"}' http://127.0.0.1:9090/api/policies/MainGroup
{"ok":true,"data":{"outbound_mode":0,"selectable_groups":[...], ...}}
示例 —— 在发出请求之前先问它会走到哪里:
curl -X POST -H "Authorization: Bearer your-secret-token" \
-d '{"url": "https://api.example.com/v1/orders", "explain": true}' \
http://127.0.0.1:9090/api/rules/match
{"ok":true,"data":{"policy":"MainGroup","matched":{"rule":"DOMAIN-SUFFIX,example.com,MainGroup", ...}, ...}}
复现问题时把日志收窄到某一个子系统,不用重启本次运行:
curl -X PUT -H "Authorization: Bearer your-secret-token" \
-d '{"level": "verbose", "sections": ["MitM", "DNS"]}' \
http://127.0.0.1:9090/api/loglevel
注意:此功能默认禁用。所有响应都使用统一信封:成功为
{"ok": true, "data": {...}},错误为{"ok": false, "error": {"code": "...", "message": "..."}};请求体上限为 1 MB。
PUT端点也接受PATCH。为第三方面板提供了 Clash 兼容的别名路径:/version、/traffic、/connections、/configs、/proxies、/rules——路径可达,但响应使用 Chute 自己的信封和字段名而非 Clash 的 schema(/version返回{"name", "run_id", "egress_probe"},其中egress_probe在 Apple 引擎上是network_address,在 Android 引擎上是egress_ip),因此 Clash 面板无法开箱即用。
本页为英文版的翻译。如内容有出入,以英文版为准。