🚑 Clash Verge 急救包 · FirstAidKit

解决「我关了 Clash Verge 窗口，但浏览器还卡转圈 — 只有重启电脑才好」的半关僵死态万年老坑

Solve Clash Verge's half-closed zombie state on macOS. GUI closes but the root verge-mihomo kernel, PF divert hooks and System Proxy are still alive → browser traffic silently hijacked to a dead socket and every page hangs.

English · 中文 · 快速开始 · 功能亮点 · 架构原理 · Roadmap

🍎 Apple Silicon (M1 ~ M4) 点这里下载 .zip 绝大多数现代 Mac (2020 年后购买)

💻 Intel (x86_64) ⏳ 即将支持 (v0.2.0) 欢迎发 Issue +1 催促你需要的版本

🔨 源码编译 SwiftPM 一行命令 swift build -c release 即产 310KB 二进制

🔒 首次打开？别慌！macOS Gatekeeper 权限设置 3 步

因为这是个人开源项目（没买每年 99 美元的 Apple Developer 公证证书），第一次双击会提示「无法打开，因为无法验证开发者」。解决办法（只需要做一次，以后双击就能直接打开）：

1. 右键 → 选中 ClashVerge急救包.app → 点 「打开」（不是双击！）
2. 弹出的对话框里再点 「打开」（你会看到对话框比双击时多了一个「打开」按钮）
3. 后续正常双击即可。如果还被拦 → 打开 系统设置 → 隐私与安全性，往下滚你会看到「已阻止 ClashVerge急救包」，点 「仍要打开」 就 OK 。

✅ 说明： 我们用 codesign --sign - 做了 ad-hoc 匿名签名，所以上面 3 步就够，不需要 xattr -cr 清属性。

---

🧊 Why you need it / 为什么需要它

中文说明 — 是不是你本人？↓

场景 1： 你用 Clash Verge 看完 YouTube / 刷完抖音，点窗口左上角那个红色 ❌ 把窗口关了，以为"代理彻底关了"。

实际情况： GUI 窗口是没了，但 root 权限的 verge-mihomo 内核进程还在跑、PF 防火墙 divert 钩子没清、系统代理开关还开着 — 这三条流量劫持钩子至少一条还活着。

结果： 豆包 / Chrome / Safari 所有浏览器每一次 HTTP 请求还在往已经死掉的代理 socket 里送 → 卡 30 秒超时 → 你以为"今天网络怎么了" → 重启电脑才好。这就叫半关僵死态 🟡。

场景 2： 关了 Clash Verge 之后打开知乎，永远白屏转圈。curl zhihu.com 终端里 0.1 秒就返回，偏偏浏览器打不开 → 这就是最典型的半关态症状。

本项目就是解决这个问题的外挂级急救包。 不用你记一堆 sudo kill -9 verge-mihomo、pfctl -d、networksetup -setwebproxystate off。点一下「一键彻底关闭」就行，弹个 Touch ID 指纹框搞定。

English — The pain point in 10 seconds

You close the Clash Verge window on macOS. You think the proxy is OFF.

Reality: the root-owned verge-mihomo kernel is still alive, the PF divert rule is still loaded, the System Proxy switch is still ON — all silently hijacking every browser request.

Result: curl google.com in the terminal returns in 0.1 seconds (direct DNS + direct route), but every browser hangs for 30s then times out. The only cure you know is reboot your Mac.

This app fixes it in one click + one Touch ID prompt.

---

✨ 功能亮点 · Features

图标	功能	说明	Feature in English
🟢🟡🧟⚪	四层红绿灯状态	每 10 秒巡检 GUI进程 / Mihomo内核 / 系统代理+PF钩子 / 保姆服务(clash-verge-service)，四种判定一目了然	4-layer health check, 4-state traffic-light indicator (incl. 🧟 zombie-nanny)
🗑️	一键彻底关闭	先停保姆服务(防内核复活) → 关GUI → 关所有接口系统代理 → 重置PF → 杀root内核 → 刷DNS，原子执行	One-click atomic cleanup (nanny service FIRST, then GUI + Proxy + PF + kernel + DNS)
🚀	一键启动	自动定位 /Applications/Clash Verge.app，已运行则切前台；被停用的保姆服务会自动恢复	One-click launch / foreground-activate; auto-restores the nanny service if disabled
🔔	异常态系统通知	半关🟡 / 僵尸保姆🧟 都会弹原生通知，15 分钟去重防骚扰	Native notifications for both half-closed & zombie-nanny states, 15-min dedup
🧪	--self-test 自检模式	不进UI、终端里直接打印四层状态 JSON 风格文本，适合脚本 / launchd 监控	Headless CLI self-test mode for scripts & LaunchD watchdogs
🆔	Touch ID 原生权限	管理员操作走 AppleScript do shell script with administrator privileges，不用手动 sudo	Native macOS permission dialog — supports Touch ID & Watch unlock
🦊	零第三方依赖	只用系统框架 SwiftUI / AppKit / Foundation / UserNotifications，编译产物 310KB	No Carthage / CocoaPods / SPM packages. Pure system frameworks. 310 KB release binary.

---

🚀 快速开始 · Quick Start

Option 1 · 普通用户（双击运行 🔥 推荐）

1. 去 Releases ↗ 下载最新版 ClashVerge急救包-vX.Y.Z.dmg 或 .zip
2. 解压 → 拖进 应用程序 (Applications) 文件夹
3. 双击打开 → 第一次运行右键 → 打开（绕过公证警告）
4. 顶部菜单栏立刻出现 🦊🚑🚦 图标，根据你的四层状态显示 🟢 / 🟡 / 🧟 / ⚪ 四种颜色
5. 平时不用管它，它在后台悄悄每 10 秒巡检一次。哪天浏览器突然卡了，先看它是不是亮了黄灯 🟡，点一下「一键彻底关闭」就完事儿。

Option 2 · 开发者（从源码自己编）

需要 macOS 14+ / Swift 6.0 / Xcode Command Line Tools：

git clone https://github.com/CHANGGELY/ClashVerge-FirstAidKit.git
cd ClashVerge-FirstAidKit

# ① Debug 编译 (fast compile)
swift build
./.build/debug/ClashVerge急救包 --self-test    # 终端跑自检 (不进UI)
./.build/debug/ClashVerge急救包                  # 正常菜单栏模式

# ② Release 编译 (310 KB 精简版)
swift build -c release
./.build/release/ClashVerge急救包

Option 3 · 脚本 / 监控模式

把 --self-test 接进你的自动化脚本、launchd 看门狗、或者 Monitority 等本地监控工具：

# 退出码语义: 0 = 自检完成(结论看打印), 2 = 自检超时(shell卡住)
./ClashVerge急救包 --self-test ; echo "exit=$?"

---

🖼️ 截图 · Screenshots

🟡 半关僵死态（黄灯警告）	🧟 僵尸保姆态（v0.1.2 新增）	🟢 正常工作态（绿灯）	⚪ 彻底关闭态（灰灯）
菜单栏图标黄色 + 显示"GUI已关，内核进程还在跑"	菜单栏图标僵尸绿 + 显示"内核已死但保姆还活着，随时会复活内核"	菜单栏图标绿色 + 显示"代理引擎运行中，系统代理已开"	菜单栏图标灰色 + 显示"四层全部清理干净，直连"

👉 展开看下拉菜单完整5行状态 + 4个操作按钮 + 自动巡检开关

┌─────────────────────────────────────────────┐
│  🟡 检测到半关僵死态：GUI窗口已关，内核进程还在跑，浏览器会被卡   │
├─────────────────────────────────────────────┤
│  ❌  GUI窗口进程        已关闭                │
│  ✅  Mihomo内核进程     运行中  ← 问题在这儿    │
│  ❌  系统代理开关        已关闭                │
│  ❌  PF流量劫持钩子      已清（正常）           │
│  ✅  保姆服务(看守内核)   运行中  ← v0.1.2新增  │
├─────────────────────────────────────────────┤
│  🔴 🗑️ 一键彻底关闭 Clash Verge（弹密码框）     │
│     停保姆 + 关GUI + 关代理 + 重置PF + 杀内核 + 刷DNS│
│  🚀 一键正常启动 Clash Verge                   │
│     从 /Applications 启动；已运行则激活窗口      │
│  🔄 手动刷新四层状态（立即检查一次）              │
│  🛡️ 自动巡检（每10秒检查一次）        [开关] ON  │
├─────────────────────────────────────────────┤
│  Clash Verge 急救包 v0.1.2 · 四层检测    退出急救包 │
└─────────────────────────────────────────────┘

---

🧠 原理白话图解 · Architecture

Clash Verge 的设计就是四层架构叠在一起，各层状态各自独立、没有原子同步机制 —— 这就是半关态的根因：

┌─────────────────────────────────────────────────────────────────────┐
│  Layer 1 · GUI 窗口进程  ("Clash Verge")     ← 你点红叉❌只关了这一层   │
├─────────────────────────────────────────────────────────────────────┤
│  Layer 2 · Mihomo 内核进程 (verge-mihomo)   ← root权限跑, 你普通权限碰不到│
├─────────────────────────────────────────────────────────────────────┤
│  Layer 3 · macOS 系统钩子 (两条独立链路)                                │
│           3a) scutil --proxy   系统代理开关 (HTTPEnable / HTTPSEnable)  │
│           3b) pfctl -s rules   PF divert 流量改道钩子 (劫持全部包)       │
├─────────────────────────────────────────────────────────────────────┤
│  Layer 4 · 保姆服务 (clash-verge-service)   ← KeepAlive常驻LaunchDaemon│
│           内核一死它就把内核重新拉起 → 只杀内核 = 白杀 🧟 (v0.1.2 真实踩坑)│
└─────────────────────────────────────────────────────────────────────┘
          ▲
          └── 四层不同步 = 半关僵死态 🟡 / 僵尸保姆态 🧟 = 关了窗口 ≠ 真退出

🧟 v0.1.2 真实踩坑（2026-08-15）：用户点完「一键彻底关闭」，内核几秒内被 clash-verge-service（KeepAlive 常驻的系统性 LaunchDaemon）自动拉起 —— 只杀内核不停保姆 = 白杀。所以现在一键关闭的执行顺序铁律是：先停保姆（launchctl bootout），再杀内核；一键启动时再把保姆 bootstrap 恢复回来，TUN 模式照常可用。

本急救包做的事 = 让四层状态永远保持一致：要么全部活着（🟢正常），要么一口气原子性地全部清干净（⚪全关，含停保姆）。绝不留中间态。

判定规则：

• 🟢 正常工作态：内核还活着（代理在跑），或者 GUI 开着 + 钩子正常
• 🟡 半关僵死态（重点！）：GUI死了，但内核/系统代理/PF钩子至少一条还活着
• 🧟 僵尸保姆态（v0.1.2 新增）：内核死了、钩子全清，但保姆服务还活着 —— 它随时会复活内核，「彻底关闭」名不副实
• ⚪ 彻底关闭态：GUI死 + 内核死 + 系统代理关 + PF钩子清 + 保姆服务停

---

🛣️ Roadmap

优先级	功能	目标用户	Status
P0	launchd 崩溃恢复守护进程（急救包自己崩了，launchd 也能监控到三层不一致自动清）	硬核用户	Planned
P1	自定义域名白名单 / 自动检测 "curl zhihu.com 浏览器卡但终端通" 的双轨异常	高级用户	Planned
P2	DMG 自动构建 Release + Apple Developer ID 签名 + 公证（Notarization）	普通用户	Planned
P3	clash-verge-rev / verge-mihomo config 一键导入 + fake-ip-filter 语法错误检测	全体用户	Planned
P4	Homebrew Cask 一键安装：brew install --cask clash-verge-firstaidkit	Mac 老用户	Planned
P5	i18n 英文 / 日文界面 + Windows 移植思路文档（Linux 不做，Clash 本身的）	海外用户	Planned

---

📊 社区 / 影响力

• Star History — 如果本项目帮你省过一次重启，请顺手点个 ⭐，让更多人看到
• 技术社区发帖模板（欢迎转发 / 二创）：

  【解决了！】Clash Verge 关窗口后浏览器卡转圈的万年老坑终于不用重启了，自己写了个菜单栏急救包外挂，紫狐狸+急救箱+红绿灯图标可爱到爆 https://github.com/CHANGGELY/ClashVerge-FirstAidKit

• QQ / Telegram / V2EX / 什么值得买 / 小众软件 / 知乎：任何一个中文技术社区发一贴，附上你自己的使用截图，能让这个工具更快到达被坑了很久的用户 🙏

---

📦 发布流程 · Release SOP（一键自动打包）

本项目的 GitHub Actions Release 流水线已经全自动帮你完成「编译 → 组装.app → ad-hoc签名 → ZIP打包 → SHA256 → 创建Release → 上传附件」全部步骤。作为维护者，你只需要打一个 Git Tag + push 就行：

cd ClashVerge急救包

# ① (可选) 先本地确保 Release 编译通过
swift build -c release && ./.build/release/ClashVerge急救包 --self-test

# ② 打语义化版本 tag (vX.Y.Z，必须 v 开头！)
git tag -a v0.1.0 -m "release(开源): v0.1.0 MVP · 三层红绿灯 + 一键清理"

# ③ push tag 到 GitHub → 立刻触发 .github/workflows/release.yml
git push origin v0.1.0

然后去 Actions ↗ 看 3~5 分钟，自动跑完后在 Releases ↗ 就会出现一个最新版，附两个附件：

附件	用途
ClashVerge-FirstAidKit-v0.1.0-macOS-arm64.zip	用户直接下载解压即用（Apple Silicon M1~M4，右键打开即可）
ClashVerge-FirstAidKit-v0.1.0-macOS-arm64.zip.sha256	安全用户下载 ZIP 后用来校验 SHA256 哈希，确认文件没被篡改

💡 手动触发（不想打 tag）：仓库 Settings → Actions → 左边选「Release」→ 右边 Run workflow 按钮，手动填版本号就行，适合第一次调试流水线。

---

🤝 Contributing

中文命名、中文注释、中文 commit message 都可以 — 对高中生 / 大学生开源新人极度友好。详细看 CONTRIBUTING.md，只需要记住三条：

1. 文件开头必须有中文文件头（解释这个文件干嘛的 + 为什么这么写）
2. 变量 / 函数 / 类名优先中文（不会拼英文没关系，拼音也行，中文最直接）
3. 提 PR 前本地跑一遍 swift build -c release && ./.build/release/ClashVerge急救包 --self-test 退出码 0

---

📜 License

GPL-3.0-only — 与上游 Clash Verge rev 保持一致。详细看 LICENSE。

🙏 Acknowledgments

• clash-verge-rev/clash-verge-rev — 原版 Clash Verge 延续项目（GPL-3.0）
• MetaCubeX/mihomo — 我们守护的内核（Clash.Meta 延续）
• 所有踩过「关了还是卡」坑的中文 Clash 用户，你们的吐槽就是这个项目诞生的源动力 💪

---

Made with 💜 + SwiftUI in China.

↑ Back to top