ClaudeGuard (Claude 守护器)

macOS 移植预览：仓库现含 macOS 平台适配与深色界面（进程守护模式）。本版不提供系统级按应用网络隔离；客户端升级、回滚与本地自更新已验证，正式远端自更新仍需维护者公钥和 macOS 发布资产。详情与测试方式见 macOS 说明。Windows 版文档如下。

ClaudeGuard (Claude 守护器)

给 AI 桌面应用加一道“网络出口门禁”

一句话定位

ClaudeGuard 是 AI 桌面应用的“网络出口门禁”（Windows 完整支持，macOS 移植预览）：按每个目标自己的域名校验它此刻走的是哪条链路、出口 IP 与地区是否在白名单里；全部通过才允许启动 Claude 等桌面应用，任一启用目标不符合就立即熔断——结束相关进程、用防火墙隔离、必要时直接断网，切回合规节点后自动恢复。

为什么需要它

Claude、ChatGPT、反重力这些客户端对出口环境很敏感，而代理软件经常“整体一个出口”。当节点漂移、断连直连或者某个应用被单独分流时，应用会在你不知情的情况下从非预期出口联网。v3 的核心变化是把“系统出口”拆成每个应用各测各的：Claude 走 claude.ai 的 trace、Codex 走 chatgpt.com 的 trace、反重力测 Google 后端可达性——互不牵连，谁不对谁熔断。

界面预览

_{主界面 · 各目标出口校验通过，一键启动}	_{熔断 · 结束进程 + 隔离，一键解除并恢复网络}
_{设置 · 八个折叠组，组头直接显示当前值}	_{首次向导 · 三步完成配置}

_{详情 · 每个目标的锚点、期望值、耗时与运行参数}

功能亮点

按目标校验出口（v3 核心）：每个监控目标绑定自己的探测地址与期望值。Claude → claude.ai/cdn-cgi/trace，Codex → chatgpt.com/cdn-cgi/trace，反重力 → cloudcode-pa.googleapis.com 可达性，本机出口 → cloudflare.com/cdn-cgi/trace。支持 HTTP trace、JSON IP、页面地区标记、仅可达性四类锚点，自定义目标同样适用。
接入路径检查（v3.7/3.8）：探测流量跟随系统代理（换了端口、换了代理软件也测的是应用真实出口）；系统代理没开时靠 TUN 网卡判定接入，两者都没有 = 应用直连真实出口 → 按熔断阈值处理（杀进程/隔离/断网）。此状态下守护器自身不直连探测——任何状态下守护器流量都不带家宽 IP 出机器。
防火墙兜底封锁（v3.9）：没连代理（系统代理与 TUN 都不在）时，自动给守护对象加防火墙出站 Block——应用直连出不去，走系统代理照常可用，接入后规则自动解除；也支持一键手动封锁/解除。需要时会自动开启 Windows 防火墙（默认出站=允许，不影响其他软件），但绝不替你关掉。
双重白名单：多 IP 列表 + 出口地区（ISO 国家/地区码），任一命中即放行；期望为空的目标会被校验拦下，避免裸连。
防抖熔断：连续 2 次（可调）失败才熔断，任意一次通过清零；探测失败/拿不到出口信息属于“无法确认”，不熔断。
熔断动作：结束 Claude / ChatGPT / 反重力的全部进程 + 按开关做防火墙入/出站隔离 + 断网档位（关闭 / 防火墙全局出站阻断（默认）/ 禁用物理网卡）。
恢复零残留：切回合规节点后下一轮自动解除隔离与断网；托盘“解除隔离并恢复网络”、--restore 急救、程序退出都会恢复网络。
常驻托盘：默认每 15 秒复查一次（5–3600 秒可调），可“暂停守护 30 分钟”（暂停期间照常检测但绝不熔断）。
多 Agent 守护：GUI 应用熔断杀进程，CLI（Claude Code / Codex CLI / Gemini CLI）只提醒不杀，避免误伤终端。
桌面通知 + 飞书群通知：熔断、恢复、启动被阻止、失败预警、客户端更新五类桌面通知；飞书机器人支持签名校验、DPAPI 凭据加密、持久队列与失败补发。见飞书通知。
Claude / Codex 客户端更新：只走官方 MSIX 源，校验签名与包身份后原位升级，注册版本达标才算完成。见客户端更新。
守护器自身更新：基于 GitHub Releases 的版本检测、下载与自替换。
可脚本化：--check 输出 JSON 与退出码，适合批处理和前置流水线。

守护范围与熔断方式

类型	支持目标	熔断机制	说明
GUI 桌面应用	Claude / ChatGPT / 反重力 (Antigravity)	结束进程 + 防火墙隔离	任意组合勾选；熔断时结束全部关联进程，并为其可执行文件添加 Windows 防火墙出/入站阻止规则。
CLI 命令行	Claude Code / Codex / Gemini CLI	仅日志提醒，绝不杀进程	CLI 常驻在终端或 Node 环境里，杀进程会误伤整个终端，因此只记录提醒。

防误杀与放行语义

信息缺失不熔断：探测超时、返回为空、拿不到 IP/地区时判为“无法确认”，只记录不熔断。
期望为空不放行：某个目标的期望 IP 与地区都为空时，该目标永远不通过（宁可错杀），需要补白名单。
连续两次才熔断：单次网络抖动不会立刻熔断；两次检查间隔默认 15 秒。
本机出口默认关闭：本机常规流量出口往往与 AI 代理出口不同，默认开启会在首次启动就熔断；需要监管本机出口时在设置里打开并补齐白名单。

安装与快速上手

仅支持 Windows 10 / 11，界面全中文。在 GitHub Releases 获取最新分发包：

安装版（ClaudeGuard-vX.Y.Z-setup.exe）
- Inno Setup 打包，默认安装到 C:\Program Files\ClaudeGuard，自动检测 WebView2 运行时。
- 需要管理员权限：熔断时要调用 Windows 防火墙与网卡控制接口。
- 卸载可在“安装的应用”中完成，刻意保留 %APPDATA%\ClaudeGuard 里的配置与日志。
便携版（ClaudeGuard-vX.Y.Z.zip）
- 裸 exe，解压即用（同样需要管理员权限）。

首次运行向导

三步完成配置：代理端口 → 出口白名单（IP 可多个，或按地区）/ 守护对象 → 是否安装开机自启。完成后即进入常驻守护。

macOS 版（移植预览）

v3.6.0 起仓库内置 macOS 适配（社区贡献，进程守护模式，深色界面）。暂无预编译包，需从源码构建：

git clone https://github.com/daha1216/ClaudeGuard && cd ClaudeGuard
cargo build --release            # 需要 Xcode Command Line Tools
python3 scripts/package-macos.py # 产出 ClaudeGuard.app（ad-hoc 签名）

把 ClaudeGuard.app 拖入「应用程序」后首次启动，走与 Windows 相同的三步向导。

与 Windows 版的能力对照：

能力	Windows	macOS（移植预览）
按目标出口校验 / 白名单 / 防抖熔断	✅	✅ 同一套语义
熔断动作	结束进程 + 防火墙隔离 + 断网档位	仅结束进程（进程守护模式，不断网）
启动门禁（出口未过禁止启动 Claude）	✅	✅
飞书 / 桌面通知 / 客户端更新	✅ DPAPI / Toast / MSIX 原位升级	✅ Keychain+AES-GCM / 原生通知 / 官方包签名校验升级
守护器自更新	✅ GitHub Releases 自替换	本地签名包流程已验证；远端发布需维护者 Minisign 公钥
登录自启	✅	✅ LaunchAgent

已知边界：无系统级按应用网络隔离（两次检测之间有窗口期）；未做 Developer ID 公证；Intel 产物仅 Rosetta 验证。详见 docs/MACOS.md（使用说明）与 docs/MACOS-VALIDATION.md（验证记录）。

日常使用

主界面：状态圆环 + 状态文案 + 每个目标一行（左：名称/地区，右：出口 IP/耗时），主按钮下「立即检测」随时手动复查。底部“详情 / 设置 / 日志”展开对应卡片。
设置：代理端口、检查间隔、白名单（IP / 地区）、断网档位、熔断动作开关、守护对象、监控目标增删改、桌面通知与飞书、客户端更新、开机自启、关窗到托盘，以及「打开数据文件夹 / 用户指南」。
托盘菜单（右键图标）：显示主窗口 / 立即检测 / 暂停守护 30 分钟（或恢复守护）/ 解除隔离并恢复网络 / 打开数据文件夹 / 退出。

命令行

ClaudeGuard.exe --check        # 单次检测，JSON 输出；退出码 0 通过 / 2 不通过
ClaudeGuard.exe --restore      # 急救：恢复网络 + 解除全部隔离
ClaudeGuard.exe --settings     # 打开/唤起主窗口并展开设置
ClaudeGuard.exe --notify-test trip   # 测试桌面通知（trip/recover/launch_blocked/warning/client_update/self_update）
ClaudeGuard.exe --feishu-status --claude-update-status --codex-update-status
ClaudeGuard.exe --install --uninstall

--check 示例（截断）：

{
  "version": "3.1.0",
  "passed": true,
  "targets": [
    { "id": "local", "name": "本机出口", "enabled": false, "verdict": "disabled" },
    { "id": "claude", "name": "Claude 出口", "enabled": true, "verdict": "pass", "ip": "204.1.100.98" },
    { "id": "codex", "name": "Codex 出口", "enabled": true, "verdict": "pass", "ip": "204.1.100.98" },
    { "id": "antigravity", "name": "反重力出口", "enabled": true, "verdict": "pass", "note": "可达" }
  ]
}

数据与隐私

配置与运行状态位于 %APPDATA%\ClaudeGuard\：
- config.json：v3 配置（旧 v2 配置会在首次启动时自动迁移）。
- guard.log：运行日志（超过 1MB 自动裁剪并保留最近约 400KB）。
- netcut.json：断网现场，用于崩溃/被杀后的启动自愈。
- feishu.json：DPAPI 加密凭据、通知队列与失败记录（队列正文未加密，可能含出口 IP）。
- claude-update.json / codex-update.json：客户端更新状态，不含登录凭据。
探测请求经你配置的本地代理发往各目标自己的探测域名（claude.ai、chatgpt.com、cloudflare.com、cloudcode-pa.googleapis.com），只用于读取出口 IP/地区或判断可达性，不上传任何应用数据。
守护器自身更新查询 GitHub Releases；客户端更新只访问官方 MSIX 源；飞书通知直连 HTTPS 发送事件正文。
不包含任何第三方统计或数据回传。

从源码构建

cargo build --release        # 产物 target/release/claude-guard.exe
cargo test                   # 111 个单元测试
cargo clippy --all-targets -- -D warnings
node --check ui/*.js         # 纯静态前端，无 npm/构建步骤

macOS：cargo build --release && python3 scripts/package-macos.py（详见上节）。

技术栈：Rust + Tauri 2（WebView2，纯静态前端）、sysinfo（进程）、Windows 防火墙与网卡控制、ureq（探测）。
维护者约定、模块地图与已知坑见 AGENTS.md；v3 行为基准见 docs/SPEC-v3.md；用户指南见 docs/GUIDE.md。

版本沿革

v1.x：Rust egui 单文件原型。
v2.x：重写为 Tauri 2 架构，加入多 Agent 守护、飞书通知与客户端更新。
v3.x：从零重构。按目标独立锚点校验、断网两档、桌面通知、A+ 极简仪表盘 UI、断网自愈与 --restore 急救。
v3.1.2：修复桌面通知在未登记过本应用的系统上不弹出（Toast AUMID 需在 HKCU\Software\Classes\AppUserModelId 登记）；测试通知改为后台线程发送，不再卡界面。
v3.5.0：后台每 6 小时静默检查守护器新版本并弹桌面通知（同版本只提醒一次）。
v3.6.0：合并社区 macOS 移植（进程守护模式 + 深色界面，PR #2）；Windows 端无行为变化。
v3.7.0：接入路径检查——探测跟随系统代理；系统代理关闭且没有 TUN 网卡时判为「未接入」并熔断，避免应用绕过代理直连真实出口。
v3.8.0：未接入时守护器自身不再直连探测（隐私加固），判定与熔断完全由注册表/TUN 检查承担。
v3.9.0：防火墙兜底封锁——未接入时按应用 exe 添加出站 Block 规则，接入后自动解除；同时修复防火墙关闭时既有隔离规则不生效的问题。
v3.10.0：修复主线——断网自愈与恢复协议（恢复分「安全恢复」与「停止保护」两条流程）、手动封锁、已停止保护状态、配置 version=4（新装默认不断网，升级前备份旧配置）、守护器空闲开销降到约 0.5% 单核。
v3.11.0：主界面按「主卡 + 分组卡」重构，CTA 移出滚动区，熔断与暂停改用标题与主钮表达。
v3.12.0：新增直连泄露观察（系统代理模式下发现绕过代理的外连即告警）、环境一致性检查，以及时区/默认位置的自动对齐与一键还原（全部走账本，可随时恢复）。
v3.12.4：修复防火墙自愈在非英文系统上从不触发（改按 Get-NetFirewallProfile 的结构化状态判断，不再解析本地化的 netsh 文本）；修正 netsh「找不到规则」提示的匹配串；TLS 栈补丁升级（rustls / rustls-webpki / webpki-roots / tokio）；CI 接入单元测试并新增 macOS job；补 MIT 许可。

Name		Name	Last commit message	Last commit date
.github		.github
assets		assets
capabilities		capabilities
docs		docs
installer		installer
native		native
scripts		scripts
src		src
tests		tests
ui		ui
.gitignore		.gitignore
AGENTS.md		AGENTS.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
LICENSE		LICENSE
README.md		README.md
app.manifest		app.manifest
build.rs		build.rs
claude-guard.iss		claude-guard.iss
tauri.conf.json		tauri.conf.json
tauri.macos.conf.json		tauri.macos.conf.json
使用说明.txt		使用说明.txt

Navigation Menu

Repository navigation

About

Repository files navigation

ClaudeGuard (Claude 守护器)

一句话定位

为什么需要它

界面预览

功能亮点

守护范围与熔断方式

防误杀与放行语义

安装与快速上手

首次运行向导

macOS 版（移植预览）

日常使用

命令行

数据与隐私

从源码构建

版本沿革

许可协议

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

ClaudeGuard (Claude 守护器)

一句话定位

为什么需要它

界面预览

功能亮点

守护范围与熔断方式

防误杀与放行语义

安装与快速上手

首次运行向导

macOS 版（移植预览）

日常使用

命令行

数据与隐私

从源码构建

版本沿革

许可协议

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages