杂项选项

[General]
ipv6 = true
loglevel = notify

skip-proxy = 127.0.0.1, 192.168.0.0/16, 10.0.0.0/8, 172.16.0.0/12, 100.64.0.0/10, localhost, *.local

tun-excluded-routes = 192.168.0.0/16, 10.0.0.0/8, 172.16.0.0/12
tun-included-routes = 192.168.1.12/32

通用选项

启用完整 IPv6 支持（默认：true）

ipv6 = true

loglevel（默认：warning）

loglevel = notify

可选值：none、fatal、warning、notify、info 或 verbose。不建议在日常使用中启用 verbose，因为这会显著降低性能。

skip-proxy

skip-proxy = 127.0.0.1, 192.168.0.0/16, 10.0.0.0/8, 172.16.0.0/12, 100.64.0.0/10, localhost, *.local

在 iOS 版本中，此选项强制将这些域名/IP 范围的连接交给 Chute TUN 处理，而非 Chute 代理。在 macOS 版本中，当启用「设为系统代理」时，这些设置将应用于系统。此选项用于解决某些应用程序的兼容性问题。

• 要指定单个域名，输入域名 - 例如 apple.com。
• 要指定域名下的所有网站，在域名前使用星号 - 例如 *apple.com。
• 要指定域名的特定部分，指定每个部分 - 例如 store.apple.com。
• 要通过 IP 地址指定主机或网络，输入特定 IP 地址（如 192.168.2.11）或地址范围（如 192.168.2.* 或 192.168.2.0/24）。

注意：如果你输入 IP 地址或地址范围，仅当你使用该地址连接到该主机时才能绕过代理，而通过解析到该地址的域名连接时不会绕过代理。

代理服务器监听

interface = 127.0.0.1
port = 8118
socks-interface = 127.0.0.1
socks-port = 8119

interface / port 控制 HTTP 代理服务器的监听地址和端口（默认 127.0.0.1:8118）。socks-interface / socks-port 控制 SOCKS5 代理服务器（默认 127.0.0.1:8119）。

兼容性别名：doh-server 可作为 doh 的别名；http-listen / socks5-listen（例如 0.0.0.0:6152、[::]:6153 或单独的端口号）会被映射到上述 interface/port 设置。使用通配监听地址（0.0.0.0、:: 或 *）还会同时设置 allow-wifi-access = true。

入站代理鉴权

http-auth = username:password

要求客户端在使用 Chute 的 HTTP 和 SOCKS5 代理服务器之前进行身份验证。该行可以重复出现以允许多组凭据。

绕过系统请求

bypass-system = true

启用后，系统进程发出的请求将绕过 Chute 处理。

默认：true。

始终使用真实 IP

always-real-ip = *.example.com, tracker.example.org

当 Chute 为被劫持的 DNS 查询提供虚拟 IP 地址时（见 hijack-dns），匹配此逗号分隔列表的主机名将始终以其真实解析出的 IP 地址应答。支持通配符。

中断现有连接

interrupt-exist-connections = true

启用后，在任何策略组中更改所选策略（通过 URL Test、Fallback、Load Balance、SSID 或手动选择）将优雅地断开使用旧策略的现有连接。这确保连接立即使用新选择的代理，而不是继续使用旧代理。

每个受影响的连接会以 3 秒超时优雅关闭，之后强制关闭。

默认：false。这是一个全局设置——影响所有策略组。

Network Framework（macOS / tvOS）

network-framework = true

为出站连接启用 Apple Network.framework。使用 Network.framework 可以在支持的平台上提供更好的性能和现代化的 TLS 栈集成。

默认：macOS 上为 true，iOS 和 tvOS 上为 false。

排除简单主机名

exclude-simple-hostnames = true

启用后，对简单主机名（不含点的单标签名称，例如 localhost）的请求将绕过代理规则并在本地解析。这有助于避免对本地网络名称进行不必要的 DNS 查询。

在 Chute Mac 上，首次运行时会通过一次性迁移默认启用此选项；用户显式关闭的设置会被尊重。

默认：false。

禁用数据库记录

disable-db-record = true

启用后，Chute 停止将流量记录写入本地数据库。这可以提高性能并减少存储使用，但流量历史将无法在 Chute Dashboard 中使用。

默认：false。

菜单栏速度显示（仅 Mac）

menu-bar-show-speed = true

启用后，Chute Mac 在菜单栏中显示当前的上下行速度。

默认：false。

劫持其他 DNS 服务器

hijack-dns = 8.8.8.8:53

默认情况下，Chute 仅为发送到 Chute DNS 地址（198.18.0.2）的 DNS 查询返回虚拟 IP 地址。发送到标准 DNS 的查询将被直接转发。

某些设备或软件始终使用硬编码的 DNS 服务器（例如，Google 音箱始终使用 8.8.8.8）。你可以使用此选项劫持查询以获取虚拟地址。

你可以使用 hijack-dns = *:53 来劫持所有 DNS 查询。

排除路由

tun-excluded-routes = 192.168.0.0/16, 10.0.0.0/8, 172.16.0.0/12

Chute VIF 只能处理 TCP 和 UDP 协议。使用此选项绕过特定 IP 范围，允许所有流量直接通过。

注意：此选项仅对增强模式的 VIF（utun）类型生效——使用 PacketTunnel VPN 类型时无效。由 Chute 代理服务器处理的请求不受影响。结合使用「skip-proxy」和「tun-excluded-routes」以确保某些 HTTP 流量完全绕过 Chute。

此选项可能导致系统错误 ENOMEM（无法分配内存）。这似乎是 iOS 系统中的一个错误。如有可能，请勿使用此选项。

包含路由

tun-included-routes = 192.168.1.12/32

默认情况下，Chute VIF 接口将声明自身为默认路由。但由于 Wi-Fi 接口具有更小的路由，某些流量可能不会通过 Chute VIF 接口。使用此选项添加更小的路由。

注意：此选项仅对增强模式的 VIF（utun）类型生效——使用 PacketTunnel VPN 类型时无效。

协议嗅探

sniffing-enabled = true
sniffing-timeout = 100

Chute 可以通过检查连接的初始字节来检测实际协议。这使得像 PROTOCOL,TLS,Proxy 这样的规则即使对非 HTTP 入站连接也能正常工作。

sniffing-enabled（默认：false）

sniffing-enabled = true

启用 TCP 连接的协议检测。

sniffing-timeout（默认：100ms）

sniffing-timeout = 200

等待初始数据以确定协议的最大时间（毫秒）。如果协议检测在慢速连接上失败，请增大此值。

阻断 QUIC

block-quic = auto

控制 Chute 是否拒绝检测到的 QUIC（包括 HTTP/3）流量。QUIC 基于 UDP，无法由 Chute 的 HTTP MitM 解密。拒绝 QUIC 可促使兼容的客户端改用 TCP，从而应用基于 TCP 的代理处理，并在已配置时进行 HTTPS 解密。

对经 TUN 进入的流量，Chute 会向被拒绝的 QUIC 流返回 ICMP/ICMPv6 Port Unreachable 消息，使兼容的客户端无需等待 QUIC 超时即可回退到 TCP。

block-quic 使用自动 QUIC 检测，不需要 sniffing-enabled；sniffing-enabled 只控制 TCP 协议嗅探。如需按规则处理单个 QUIC 流，请使用 PROTOCOL,QUIC,... 规则。

Bypass TUN

bypass-tun = 192.168.0.0/16, 10.0.0.0/8

类似于 skip-proxy，但在 TUN/VIF 路由层面工作。到这些 IP 范围的连接将完全绕过 TUN 接口，直接通过系统网络栈传输。

注意：此选项仅对增强模式的 VIF（utun）类型生效，使用 PacketTunnel VPN 类型时无效。

拒绝时显示错误页面

show-error-page-for-reject = true

启用后，Chute 对被拒绝的请求返回用户友好的错误页面，而不是直接丢弃连接。

乐观 DNS

optimistic-dns = false

启用后，Chute 立即返回缓存的 DNS 结果，同时在后台刷新记录。这减少了连接延迟，但可能返回过时的 DNS 记录。

默认：true。设置 optimistic-dns = false 可禁用。

允许 Wi-Fi 访问

allow-wifi-access = true

让同一网络中的其他设备可以访问 Chute 的 HTTP 与 SOCKS5 代理端口——把两个监听器的绑定地址放宽到 0.0.0.0。Surge 风格的配置（以及 sing-box 导入时映射的 allow-lan）只带这个标志，interface 仍停在默认的 127.0.0.1，所以必须由标志本身去放宽绑定地址。

这个标志与显式写通配 interface 是同一意图的两种写法，Chute 取并集：已经写了 0.0.0.0 的配置行为完全不变。改动该标志会重新绑定两个监听器，因此收回访问在重载时即刻生效，不必等到下次启动。

这些是代理端口，除非设置了 http-auth，否则没有任何鉴权。在你不掌控的网络上，请同时设置凭据。

托管配置

#!MANAGED-CONFIG https://example.com/config.conf interval=86400 strict=false

首行带有 #!MANAGED-CONFIG 头的配置会自动从该 URL 重新获取。头部参数与更新行为详见托管配置。

副本 / 流量录制

replica = true

[General] 中的 replica 键（replica = true）启用流量录制；[Replica] 部分负责过滤 Chute Dashboard 显示的内容，其键详见 Replica。

外部控制器访问（Chute Dashboard）

external-controller-access = password@0.0.0.0:6155

启动供 Chute Dashboard 使用的远程控制服务器。值的格式为 password@host:port；密码前可以选择性地加上用户名（user:password@host:port）。在 iOS 上，还会在 port + 1 上开启一个配套的 USB 通道（macOS 上没有）。连接方法见 Chute Dashboard 页。

HTTP 控制 API 和 Web UI

[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 的管理 UI，类似于 Clash 和 Surge 面板。API 通过 REST 端点暴露内核状态、流量、连接、DNS、策略控制和配置管理。

external-http-controller（默认：禁用）

external-http-controller = 127.0.0.1:9090

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 兼容别名受鉴权保护；Web UI 的静态资源不需要令牌（external-http-ui = false 时它们根本不存在——页面返回 404）。

未写这一项时，Chute 会生成一个令牌，而不是不加鉴权地提供服务。 生成的令牌以仅属主可读的权限写入 Chute 共享目录下的 control-token 文件——不在配置旁边：iOS 与 tvOS 上是 App Group 容器，Android 上是应用的私有数据目录——重启后继续沿用，各端 App 会展示给你——见打开 Web 控制台。控制 API 可以交出连接数据库，而其中的记录带有本次运行见过的每一条 URL、请求头和进程名，所以「默认开放」不是一个合理的默认值。

如果确实要不加鉴权地提供服务，请在配置里明说：

external-http-secret = none

该写法仅在回环绑定时被接受。在非回环地址上，none 和「不写」都不够：控制服务器会拒绝启动，并说明它需要什么。

升级提示：如果你此前依赖「不写 external-http-secret 即不鉴权」，本机脚本会开始收到 401。要么从 App 里读出生成的令牌，要么写上 external-http-secret = none，明确保留旧行为。

external-http-ui（默认：true）

external-http-ui = true

启用后，Chute 在控制器地址提供内嵌的 Web UI。Web UI 提供概览仪表板、连接管理、DNS 检查、流量监控、策略控制和配置编辑。设置为 false 则仅启用 API 而禁用 UI。

打开 Web 控制台

控制台就在控制服务器的地址上，各端 App 都能把地址和令牌交给你——包括自动生成的那一个，否则你没有别的办法读到它：

• Chute Mac：菜单栏 → 打开 Web 控制台，以及 复制 Web 控制台令牌。连接详情窗口里还有 请求与历史，同样会打开控制台——打开的是首页，不是那条连接。
• Chute iOS：控制面板 → Web UI 那一行 → 打开、复制地址 或 复制访问令牌。
• Chute tvOS：控制面板在 Web UI 开关下方另有一行 Web UI 地址，显示主机与端口。选中它时，若监听器能被其他设备访问，就显示二维码——登录令牌只藏在二维码里，不显示在屏幕上；若控制器绑定在回环地址，则显示一段说明，因为回环上的控制台没法从手机打开。
• Chute Android：控制面板把地址显示为 HTTP API 开关的副标题，另有一行 生成的访问令牌，点按即复制——这一行只在令牌由内核生成时出现；你自己配置的 secret 永远不会被显示。

这些入口给出的地址把令牌带在查询参数里。页面加载时会消费掉它并从地址栏移除，所以打开链接就是一次完整登录，没人需要手抄 32 位十六进制。

external-http-cors（默认：false）

external-http-cors = true

在 API 响应中启用 CORS（跨域资源共享）头。当 Web UI 或第三方工具需要从不同源访问 API 时非常有用。

API 端点：

端点说明：

• GET /api/connections 接受 limit（正整数，默认与上限均为 1000）和 cursor（只返回 id 大于游标的连接）。响应 data 包含 connections、total、page_size、has_more，还有更多分页时附带 next_cursor。
• GET /api/connections/history 接受 limit（默认 100，上限 1000）和 cursor/before（同义参数；同时传两个会被拒绝）。
• GET /api/connections/:id/request 与 .../response 返回 {"connection_id": <id>, "data": "<base64>"}。捕获内容超过 2 MiB 时返回 413。
• GET /api/config 返回的配置中，敏感值（http-auth、external-http-secret、ca-p12、ca-passphrase、WireGuard 密钥等）会被替换为 <redacted>——不要把结果原样回传给 PUT /api/config，否则这些占位符会被逐字写进配置。
• PUT /api/config 接受 JSON {"configuration": "<full text>"} 或直接以请求体承载裸配置文本（上限 1 MB）。成功后内核会重新加载——若尚未运行则直接启动。
• PUT /api/policies/:group 按 policy、name、selected、select 的顺序取请求体中第一个存在的键作为选择值；取值可以是策略名，也可以是数字下标的字符串。特殊组名 GLOBAL 用于设置全局选中策略。
• 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, level, section, message}。
• GET /api/health 报告引擎当前持有什么、上一次因何拒绝了请求，以及上次运行是怎么结束的（clean、unclean 或 suspected_memory——见故障排查）。
• GET /api/events 返回内存中的事件环；?persisted=1 改读本次运行已落盘的历史，关闭记录时返回 available: false。
• 未配置 [Tailscale] 段时，GET /api/tailscale 返回 state: "idle"——这是正常回答，不是错误。
• POST /api/diagnostics/* 的各项探测既接受查询参数也接受 JSON 请求体，有 10 秒上限，且只回答一次。url-test/:policy 对未定义的策略名直接报错，而不是去测 REJECT。
• POST /api/rules/match 回答一个请求会走到哪里，不用建立连接。它接受 host（或者一个 url，从中取主机和端口）、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] 行往往正带着让它变坏的那个密码）。在 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——本次运行命中过的每条改写或 Mock 规则及其次数。没出现在那里的规则从未命中过，这正是「改写看起来没生效」最常见的原因。这张表最多跟踪 512 条不同的规则，超出的部分以 rewrite_hit_dropped_rules 报告。
• 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 没有字段承载的东西：选中的策略、命中的规则，以及命中的改写。

示例——读取状态，然后切换策略组：

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"}），因此 Clash 面板无法开箱即用。

客户端指纹

global-client-fingerprint = chrome

为所有未自行指定 fingerprint 的策略设置 TLS 客户端指纹。 策略自身的取值始终优先，所以这是默认值而不是强制覆盖。

可用取值为 chrome、firefox、safari、ios，以及 edge、360、 qq、android、random——后面这几个都按 Chrome 处理。无法识别的取值会被忽略， 此时使用系统 TLS 栈。

默认：留空，即使用系统 TLS 栈。 只有 Trojan、VMess、VLESS 和 ShadowTLS 策略会读取它。