kanlac/clash-verge-config

这个 skill 解决什么

Clash Verge Rev 是个 Tauri GUI，底层跑 mihomo 内核。它的配置系统有几个反直觉但有据可查的行为，不了解会浪费大量时间瞎试。这个 skill 把这些行为的「方向」沉淀下来，让你在改配置、做自动化、排查路由时直接走对路，而不是凭印象猜。

核心原则贯穿全篇：遇到不确定的工具行为，去查一手来源（官方文档 + 源码），不靠猜。 下面每条结论都可以、也应该在当前版本上复核。

心智模型一：字段归属（最重要）

运行时配置由内部函数 enhance() 生成，顺序大致是：

订阅 profile → 扩展配置(Merge) → 扩展脚本(Script) → ★ Verge 接管保留字段 ★ → 内置脚本 → tun/dns

最后那一步会无条件覆盖一批「保留字段」——external-controller、secret、各 *-port、log-level 等。官方文档原话：这些字段「由程序自身控制以保证正常功能，无法被成功覆盖」。

这意味着：

• 保留字段，扩展脚本/扩展配置改不动。 写在脚本里也会被抹掉，不是 bug。要改它们，写进 Clash Verge 自己的 clash 配置文件（应用数据目录里那个带 # Generated by Clash Verge 头、持久化的配置），并配合相应开关（如 external controller 的启用开关）。
• 其余一切（proxies / proxy-groups / rules / dns / tun / sniffer …）才归扩展脚本管，重新生成后才会进运行时配置。

写配置前先问自己：这个字段属于「Verge 保留」还是「脚本可控」？ 归属错了，后面怎么试都不生效。具体字段清单、文件角色、源码位置见 references/internals.md。

推荐配置方式：用全局扩展脚本叠加订阅

一套行之有效的组织方式：把「全局扩展脚本」当成你自己规则与节点的单一事实来源（一个叠加层），让它作用在任意机场订阅之上。

• 订阅负责提供机场的节点与基础规则；
• 全局扩展脚本在其上叠加：注入自建节点、把自建节点和机场节点编进策略组、前置你自己的分流规则（哪些域名/进程走自建、走机场、直连）、统一 DNS / TUN / sniffer 等。

好处：既能用机场供应商的配置，又能用自己的一套规则和节点覆盖它——换机场、机场更新订阅都不影响你的叠加层，你的规则与自建节点始终生效，维护成本集中在一处脚本，而不是每换一个订阅就重配一遍。

实现上把脚本写成「读入当前 config → 做幂等叠加 → 返回」的转换器：典型操作是先按名字移除同名旧节点再 unshift 自己的节点、把自建策略组插到最前、prepend 自己的规则、必要时把订阅的 MATCH 兜底改写到你选定的出口。因为是全局脚本，它对所有订阅 profile 一视同仁。配合心智模型三的「重新生成」闭环，换订阅后跑一次即可让叠加层重新生效。

心智模型二：改了不生效，先分层定位

「我改了 X 但没生效」有三种完全不同的原因，别混为一谈：

1. 改错了层：X 是保留字段 → 改脚本无效，得改 clash 配置文件（见上）。
2. 没重新生成：运行时配置只在「重新生成」时才更新。光改源文件、没触发重新生成，旧配置还在跑（见心智模型三）。
3. 生效了但被规则盖过：配置确实变了，但行为不符预期——这通常是路由/规则问题，不是配置没生效（见心智模型四）。

心智模型三：不依赖 GUI 让改动生效

关键事实（务必在当前版本复核）：

• 重启 App 会触发 enhance() 重新生成运行时配置（启动流程里会调用生成函数）。所以「重启」是最可靠、可脚本化的「让改动生效」手段。
• 没有任何 HTTP / CLI 端点能直接触发 enhance() 重新生成。 App 内「重新激活配置」按钮是 Tauri IPC 命令，外部够不到；它是 Tauri（系统 WebView）不是 Electron，没有 Chromium 远程调试端口可注入。deeplink（clash://...）只能导入订阅。
• 改 clash 配置文件要在 App 停止时改：运行中 App 可能回写该文件；启动时它才读这个文件。先退出、再改、再启动，改动才会被读到。

因此纯命令行闭环是：

退出 App  →  重新生成扩展脚本（你管理 dotfiles 的方式，模板替换或直接编辑）
          →  （需要时）改 clash 配置文件里的保留字段
          →  重新打开 App   # 触发 enhance() → 新运行时配置 → 内核加载

macOS 上「退出 / 打开」用 osascript -e 'quit app "<AppName>"' 与 open -a "<AppName>"，并轮询确认进程退出/端口起来；其他平台机制不同，按平台调整。退出 GUI 后内核可能被特权服务保活，但重启 GUI 会重新生成并 reload 内核，不影响结果。

心智模型四：external controller = 内核的 RESTful API

external-controller（如 0.0.0.0:9097 + secret）是 mihomo 内核对外的 HTTP API，独立于 Verge GUI——GUI 只是众多前端之一。用它可以：

• 运行时控制：切节点/策略组、切模式、看实时连接、读日志，全部免重启。
• 热重载配置：PUT /configs（按文件路径或 payload 重载内核当前配置）。注意它重载的是「内核当前配置文件」，不会替你跑 Verge 的 enhance() 重新生成——要套用模板改动，仍需先重新生成（见心智模型三），或自己生成完整配置再灌进去。
• 自托管 Web 面板：设 external-ui 指向一个放了面板静态文件的目录，内核就用 HTTP 在 /ui/ 直接托管面板（如 MetaCubeXD / yacd / zashboard）。优先用这个而不是在线 HTTPS 面板——在线面板是 HTTPS，连你的 HTTP 控制器会被浏览器「混合内容」拦截，得手动放行；/ui/ 同源 HTTP，点开即用。
• 远程访问：绑 0.0.0.0 让局域网/VPN 可达，配合 Tailscale / WireGuard 即可异地访问 http://<对端IP>:<port>/ui/。绑 0.0.0.0 时务必用强 secret（暴露面 = 整个代理的控制权）。

API 端点、external-ui 落地、面板下载、连自身 VPN IP 的 hairpin 坑等细节见 references/internals.md。

心智模型五：判断「走没走代理」要看命中哪条规则

排查某网站/某进程是否走代理时，只确认「走没走代理」是不够的——同样「走了代理」，命中不同规则会去到完全不同的出口（DIRECT / 某机场 / 某自建节点），表现天差地别。

所以排查路由问题，始终要定位流量落到了哪条规则上：

• 用 external controller 的连接信息（GET /connections）看每条连接实际匹配的 rule 和 rulePayload、出站 chains。
• 看内核日志里规则匹配行（必要时临时把 log-level 调高——它是保留字段，改 clash 配置文件 + 重启）。
• 规则是从上到下首命中：怀疑某域名走错出口时，往上找第一条能匹配它的规则（GEOIP、DOMAIN-KEYWORD、MATCH 兜底等都可能先截胡）。

「网站没走代理」常常其实是「命中了某条 DIRECT 规则」或「被某机场策略组接管」，而不是代理整体没工作。先定位规则，再下结论。

参考资料

• references/internals.md：保留字段清单、各配置文件角色与典型位置、enhance() 管线与源码位置、mihomo 常用 API 端点与 PUT /configs、external-ui 自托管面板落地步骤、常见坑（混合内容、VPN 自连 hairpin、TUN 与 VPN 路由共存）。需要动手做某个具体操作时再读它。