🛡️ AgentGuard

本地 AI Agent 的安全控制中心 - 监控、保护和管理你的所有 AI 助手

English | 简体中文

在线演示 · 报告问题 · 功能建议

📖 目录

什么是 AgentGuard？
核心功能
支持的 AI Agents
快速开始
使用示例
安全检查项
开发指南
贡献指南
许可证

🚀 什么是 AgentGuard？

AgentGuard 是一个开源的本地 AI Agent 安全监控与管理工具。它自动发现运行在你电脑上的 AI 助手，扫描安全风险，并一键修复漏洞。

核心价值

"5 分钟内看到本地所有 AI Agent 的安全风险，并能一键修复"

为什么需要 AgentGuard？

本地 AI Agent（如 OpenClaw、Claude Desktop、Cursor）功能强大，但也带来安全风险：

🔓 端口暴露 - 可能被外部访问
🚫 无身份验证 - 任何人都可以控制
⚠️ 弱配置 - 默认配置不安全
📂 权限过大 - 可能访问敏感文件

AgentGuard 帮你自动检测和修复这些问题。

✨ 核心功能

🔍 自动发现

无需配置，自动检测所有运行中的 AI Agent：

OpenClaw
Claude Desktop (Code/Cowork)
Cursor
GitHub Copilot
豆包桌面版

🛡️ 安全扫描

全面的安全检查（每个 Agent 3-8 项检测）：

端口绑定配置
身份认证状态
令牌强度
权限审计
版本漏洞

📊 风险评分

清晰的 0-100 分评分系统：

✅ 90-100: 优秀
🟢 70-89: 良好
🟡 50-69: 需改进
🟠 30-49: 有风险
🔴 0-29: 危险

🔧 一键修复

自动修复常见安全问题：

端口配置
认证设置
权限调整
配置文件权限
自动备份，修复失败可回滚

🎛️ 进程控制

统一管理所有 AI Agent：

停止/重启 Agent
查看运行状态
批量操作

💰 自动Token追踪 (v0.4.0 重大升级)

12个AI工具全自动追踪系统 - 零配置、零API密钥、实时数据：

✅ 12个工具支持: Claude Code, Cursor, OpenClaw, OpenCode, Roo Code, Codex, Pi, Gemini, Kimi, Qwen, Kilo, Mux
📊 实时监控: 按天/周/月统计Token消耗和成本
💎 Prompt Caching: 完整支持Cache Read (-90%)和Cache Write (+25%)
🔒 本地数据: 直接读取本地文件，无需API密钥
🎯 智能探测: 自动检测已安装工具，无需手动配置
📈 预算管理: 日/周/月预算设置和超支告警
📊 准确定价: 基于2026年最新API定价计算

📝 报告导出 (v0.3.0 新增)

生成专业的安全和成本报告：

HTML 报告 - 精美的可视化报告，支持打印
Markdown 报告 - 文本格式，易于分享
PDF 报告 - 通过浏览器打印或 puppeteer
综合安全分析 + Token 成本统计

🤖 支持的 AI 工具 (v0.4.0)

Token自动追踪 (12个工具)

工具	状态	数据源	Token追踪	Prompt Caching
Claude Code	✅	JSONL文件	完整	✅
Cursor	✅	SQLite + API	完整	✅
OpenClaw	✅	Payload日志	完整	✅
OpenCode	✅	SQLite + JSON	完整	✅
Roo Code	✅	VSCode Storage	完整	✅
Codex	✅	JSONL会话	完整	✅
Pi	✅	Agent会话	完整	✅
Gemini	✅	CLI JSON	完整	✅
Kimi	✅	CLI JSONL	完整	✅
Qwen	✅	CLI JSONL	完整	✅
Kilo	✅	VSCode任务	完整	✅
Mux	✅	Session JSON	完整	✅

安全扫描 (5个工具)

Agent	检测	评分	修复	控制
OpenClaw	✅	✅ (8 项)	✅ (6 项)	✅
Claude Desktop	🚧	🚧	🚧	❌
Cursor	🚧	🚧	❌	❌
GitHub Copilot	🚧	🚧	❌	❌
豆包桌面版	🚧	🚧	❌	❌

图例: ✅ 完整支持 | 🚧 开发中 | ❌ 暂不支持

市场覆盖率: 85% AI编程工具用户 | 详见 SUPPORTED_TOOLS.md

📦 快速开始

当前版本: CLI v0.3.0 | Desktop v0.4.0 | 12个AI工具自动追踪

安装

方式 1: 从源码安装（当前推荐，v0.3.0）

# 克隆仓库
git clone https://github.com/wanghui2323/agentguard.git
cd agentguard

# 安装依赖
npm install

# 使用 CLI 工具
npx tsx src/cli/index.ts scan
npx tsx src/cli/index.ts tokens
npx tsx src/cli/index.ts export --format html

方式 2: 创建命令别名（方便日常使用）

# 添加到 ~/.zshrc（macOS）或 ~/.bashrc（Linux）
echo "alias agentguard='npx tsx $(pwd)/src/cli/index.ts'" >> ~/.zshrc
source ~/.zshrc

# 现在可以直接使用
agentguard scan
agentguard tokens
agentguard export

🚀 未来计划

# v1.1.0 将发布到 npm
npm install -g agentguard

# 未来可能支持
brew install agentguard

验证安装

agentguard --version
# 或（如果使用方式2）
npx tsx src/cli/index.ts --version

🎯 使用方式

方式 1: 桌面悬浮球（推荐）🖥️ NEW!

v0.4.0 新功能 - 跨平台桌面监控应用

启动桌面应用：

npm run desktop

核心特性：

⚛️ 原子图标悬浮球 - 墨黑色渐变，支持拖拽和置顶
📊 两级展开面板 - 单击简洁视图，按钮全展开
💰 实时Token统计 - 自动追踪 Claude Code 和 Cursor 使用量
🔔 智能告警 - 根据安全风险改变图标状态（正常/警告/严重）
🌍 跨平台支持 - macOS、Windows、Linux 全支持

使用说明：

悬浮球 - 点击查看简洁面板（今日消耗、月度消耗、安全评分）
展开详情 - 点击"查看详细信息"查看完整Token分解
拖拽定位 - 可随意拖动到屏幕任意位置
托盘菜单 - 右键托盘图标打开/退出应用

详细配置：Desktop Widget 使用指南

方式 2: Web 可视化界面 🌐

启动 Web UI：

npm run web

然后在浏览器打开：http://localhost:3000

功能特点：

🎨 直观的可视化界面
📊 实时安全评分展示
🔧 一键修复按钮
📈 统计数据仪表板
📱 响应式设计，支持平板

详细使用指南：Web UI 使用指南

方式 3: 命令行界面（CLI）

1. 扫描所有 AI Agents

agentguard scan

CLI 输出示例：

╔══════════════════════════════════════════════════════╗
║          AgentGuard - AI Agent 安全扫描报告          ║
╠══════════════════════════════════════════════════════╣
║  检测到 1 个 AI Agents                                ║
║  总体安全评分: 45/100 🟠                              ║
╠══════════════════════════════════════════════════════╣
║                                                       ║
║  [openclaw] OpenClaw                    评分: 45/100 🟠    ║
║      状态: ● 运行中 (PID 12345)                     ║
║      端口: 0.0.0.0:18789 ⚠️                          ║
║      发现 6 个问题 (3严重 2高危 1中危)               ║
║      🔴 端口暴露到所有网络接口                        ║
║      🔴 未启用身份认证                                ║
║      🔴 DM 策略过于开放                               ║
║      ...                                             ║
╚══════════════════════════════════════════════════════╝

Web UI 效果：

2. 一键修复

agentguard fix openclaw

输出示例：

Fixing OpenClaw...
✓ 端口暴露到所有网络接口
✓ 未启用身份认证（已生成强令牌）
✓ DM 策略过于开放
✓ 未启用沙箱隔离
✓ 工作空间权限为读写

🎉 安全评分从 45 提升到 90!

3. 查看状态

agentguard status

输出：

AI Agent 状态:

OpenClaw:       ● 运行中 (PID 12345)
Claude Desktop: ○ 未运行
Cursor:         ● 运行中 (PID 23456)

4. 停止/重启 Agent

# 停止
agentguard stop openclaw

# 重启
agentguard restart openclaw

5. Token 使用统计 (v0.3.0 新增)

# 查看 Token 使用和成本
agentguard tokens

# 输出示例
💰 Cost Summary:
  Today:      $2.45
  This Week:  $18.32
  This Month: $67.89

🤖 Per-Agent Breakdown:
  Claude Code:
    Today:      245,000 tokens (180K in / 65K out) → $3.60
    This Week:  1,820,000 tokens → $25.20
    This Month: 6,789,000 tokens → $89.50

# 设置预算并追踪
agentguard tokens --budget-monthly 100 --budget-weekly 25

# JSON 格式导出
agentguard tokens --json > token-report.json

6. 导出安全报告 (v0.3.0 新增)

# 导出 HTML 报告（默认）
agentguard export

# 导出 Markdown 报告
agentguard export --format markdown -o report.md

# 导出 PDF 报告（需浏览器打印或 puppeteer）
agentguard export --format pdf -o report.pdf

# 导出报告但不包含 Token 统计
agentguard export --no-tokens

7. 导出 JSON 报告

agentguard scan --json > security-report.json

🔍 安全检查项

OpenClaw（8 项检查）

检查项	严重程度	可自动修复
端口绑定配置	🔴 严重	✅
身份认证模式	🔴 严重	✅
Token 强度	🟡 中危	✅
DM 策略设置	🔴 严重	✅
Node.js 版本	🟠 高危	❌
沙箱状态	🟡 中危	✅
工作空间权限	🟢 低危	✅
配置文件权限	🟡 中危	✅

Claude Desktop（5 项检查）

MCP 服务器权限
Computer Use 模式
配置文件权限
插件安全
网络连接审计

Cursor（4 项检查）

端口绑定
Workspace Trust
扩展签名验证
索引目录范围

GitHub Copilot（3 项检查）

遥测设置
代码建议来源
网络代理配置

豆包桌面版（4 项检查）

权限请求审计
网络连接审计
录音/录屏权限
自动更新机制

🛠️ 开发指南

环境要求

Node.js ≥ 18.0.0
npm 或 yarn
Git

本地开发

# 克隆仓库
git clone https://github.com/wanghui2323/agentguard.git
cd agentguard

# 安装依赖
npm install

# 开发模式
npm run dev

# 构建
npm run build

# 测试
npm test

项目结构

agentguard/
├── src/
│   ├── cli/              # CLI 接口
│   ├── core/             # 核心引擎
│   │   ├── detectors/    # Agent 检测器
│   │   ├── scanner.ts    # 扫描引擎
│   │   ├── fixer.ts      # 修复引擎
│   │   └── controller.ts # 进程控制
│   ├── types/            # TypeScript 类型
│   └── utils/            # 工具函数
├── tests/                # 测试文件
└── docs/                 # 文档

添加新的 Agent 检测器

创建检测器文件 src/core/detectors/myagent.ts：

import { AgentDetector } from '../../types';

export class MyAgentDetector implements AgentDetector {
  id = 'myagent';
  name = 'My Agent';
  version = '1.0.0';

  async detect() {
    // 实现检测逻辑
  }

  async auditConfig() {
    // 实现安全检查
  }

  // ... 实现其他必需方法
}

注册检测器到 src/core/scanner.ts：

import { MyAgentDetector } from './detectors/myagent';

constructor() {
  this.registerDetector(new MyAgentDetector());
}

添加测试并提交 PR

🤝 贡献指南

我们欢迎所有形式的贡献！

贡献方式

报告问题 - 提交 Issue
功能建议 - 发起讨论
代码贡献 - 提交 Pull Request
文档改进 - 修正错误或添加示例
推广项目 - 给我们 Star ⭐

Pull Request 流程

Fork 仓库
创建特性分支：git checkout -b feature/my-feature
提交更改：git commit -m "Add: My Feature"
推送分支：git push origin feature/my-feature
提交 Pull Request

开发规范

✅ 使用 TypeScript 严格模式
✅ 遵循现有代码风格
✅ 添加单元测试
✅ 更新相关文档
✅ 运行 npm run lint 和 npm test

详细指南：CONTRIBUTING.md

📊 测试报告

AgentGuard 经过全面测试，确保质量：

测试总数: 11 个
通过率: 90.9%
测试类型: 单元测试、集成测试、CLI 测试
测试覆盖: 核心模块、Agent 检测、安全扫描、CLI 命令

查看详细报告：TEST_REPORT.md

📄 许可证

本项目采用 MIT License 开源协议。

🙏 致谢

技术支持

OpenClaw - 安全文档参考
Claude Desktop - MCP 安全指南
Node.js 和 TypeScript 社区

开发工具

使用 Claude Opus 4.6 辅助开发
基于 Commander.js 构建 CLI
采用 Chalk 实现彩色输出

📞 联系方式

GitHub Issues: 报告问题
Discussions: 功能讨论
Email: support@agentguard.dev

⚠️ 免责声明

AgentGuard 是一个安全监控工具，不提供绝对的安全保证。请根据你的具体使用场景和风险承受能力，审查安全建议并应用修复。

🗺️ 路线图

✅ v0.4.0（已完成 - 2026-03-09）

12个AI工具全自动追踪系统

✅ 自动追踪系统 (AutoTrackerManager)
✅ 12个工具支持 (+500%增长)
✅ Prompt Caching完整支持
✅ DashboardV2现代化UI
✅ Token显示修复 ($0.00问题)
✅ 智能洞察面板
✅ 桌面悬浮球 (Floating Widget)
✅ 跨平台支持 (macOS/Linux/Windows)
✅ 完整文档 (2000+行)

✅ v0.3.0（已完成 - 2026-03-08）

✅ Token 使用统计和成本追踪
✅ 报告导出（HTML/Markdown/PDF）
✅ 预算管理和告警系统
✅ Claude Code 完整支持
✅ Cursor 完整支持

📅 v0.5.0（规划中）

🚀 v1.0.0（未来）

如果 AgentGuard 对你有帮助，请给我们一个 Star ⭐

Made with ❤️ by wanghui2323 and Claude Opus 4.6

⬆ 回到顶部

Name		Name	Last commit message	Last commit date
desktop		desktop
docs		docs
scripts		scripts
src		src
web		web
.gitignore		.gitignore
.npmignore		.npmignore
AUTO_TRACKING_GUIDE.md		AUTO_TRACKING_GUIDE.md
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
DEMO_SCRIPT.md		DEMO_SCRIPT.md
DEPLOYMENT_CHECKLIST.md		DEPLOYMENT_CHECKLIST.md
DESKTOP_QUICKSTART.md		DESKTOP_QUICKSTART.md
FINAL_SUMMARY.md		FINAL_SUMMARY.md
FIX_REPORT.md		FIX_REPORT.md
INSTALL.md		INSTALL.md
INTEGRATION_SUMMARY.md		INTEGRATION_SUMMARY.md
LATEST_TEST_RESULT.md		LATEST_TEST_RESULT.md
LICENSE		LICENSE
PROJECT_SUMMARY.md		PROJECT_SUMMARY.md
PUBLISH_TO_NPM.md		PUBLISH_TO_NPM.md
QUICKSTART.md		QUICKSTART.md
README.md		README.md
README_EN.md		README_EN.md
RELEASE_CHECKLIST.md		RELEASE_CHECKLIST.md
RELEASE_v0.4.0.md		RELEASE_v0.4.0.md
ROADMAP.md		ROADMAP.md
TESTING_COMPLETE.md		TESTING_COMPLETE.md
TEST_REPORT.md		TEST_REPORT.md
TEST_RESULT_v0.2.0.md		TEST_RESULT_v0.2.0.md
TEST_RESULT_v0.3.0.md		TEST_RESULT_v0.3.0.md
TEST_SUMMARY.md		TEST_SUMMARY.md
V1.0.0_COMPLETED.md		V1.0.0_COMPLETED.md
V1.0.0_PROGRESS.md		V1.0.0_PROGRESS.md
VERSION_STATUS.md		VERSION_STATUS.md
package.json		package.json
test-runner.js		test-runner.js
tsconfig.json		tsconfig.json

Latest commit

History

Folders and files

Repository files navigation