如何5分钟快速安装HOL Guard:面向新手的AI Agent安全保护完整教程
如何5分钟快速安装HOL Guard:面向新手的AI Agent安全保护完整教程
HOL Guard 是一款开源的 AI Agent 杀毒与运行时安全保护工具,能在本地拦截危险命令、密钥泄露、提示词注入和恶意插件。本教程面向新手,用 5 分钟带你完成 HOL Guard 安装、连接 AI 编码助手,并验证保护已生效。
🛡️ HOL Guard 是什么?
HOL Guard 会在 AI Agent 执行动作之前进行审查:Shell 命令、文件访问、软件包安装、MCP 工具调用,然后根据策略放行、拦截或请求审批。全程本地运行,无需注册账号。
| 保护对象 | 典型风险 |
|---|---|
| Shell 命令与文件访问 | 破坏性操作、敏感文件读取、凭证泄露 |
| 软件包安装 | 供应链投毒、恶意依赖 |
| 插件、技能、Agent 配置 | 本地工具被篡改、新增可疑工具 |
| MCP 服务器与工具 | 不受信任的远程服务与工具调用 |
| 提示词与工具结果 | 提示词注入(Prompt Injection) |
📦 安装前准备(30 秒)
只需满足两个前提条件:
- 🐍 Python 3.10 或更高版本(依赖声明见 pyproject.toml)
- 🧰 pipx 包管理器(用于隔离安装命令行工具)
如果尚未安装 pipx,先在你的包管理器中安装它,再继续下面的步骤。
⚡ 5 分钟快速安装步骤
第 1 步:一键安装 HOL Guard
打开终端,执行:
pipx install hol-guard
第 2 步:运行首次配置向导
hol-guard init
向导会先打印一份执行计划,然后逐项征求你的同意:打开本地 Dashboard、安装 Agent 集成、可选的云端同步。每一步都经你确认后才执行,不会偷偷改动任何配置。
💡 如果你只想自动化跑通,可以用
hol-guard init --yes跳过交互确认。
第 3 步:验证安装成功
hol-guard --version
hol-guard status
status 输出显示正在监控哪些对象、同步状态和下一步建议。看到守护进程正常运行,说明安装完成 ✅
🔌 连接你的 AI 编码助手
HOL Guard 支持主流 AI Agent:Codex、Claude Code、GitHub Copilot CLI、Cursor、Cline、Gemini CLI、Grok、Kimi Code、OpenCode、Devin 等。完整覆盖矩阵见 docs/guard/harness-support.md。
以 Codex 为例,只需三条命令:
hol-guard install codex
hol-guard run codex --dry-run
hol-guard run codex
install会安装原生 PreToolUse 钩子,确保 Shell 命令在执行前被审查;--dry-run先记录当前环境基线;- 之后通过
hol-guard run codex启动,Guard 发现新工具或变更时会暂停并请求审批。
📋 日常使用:10 个常用命令
| 我想做的事 | 命令 |
|---|---|
| 查看保护状态 | hol-guard status |
| 诊断某个 Agent 集成 | hol-guard doctor codex |
| 查看启动前变更 | hol-guard diff codex |
| 处理待审批请求 | hol-guard approvals |
| 批准 / 拒绝请求 | hol-guard approvals approve <request-id> |
| 查看决策历史 | hol-guard receipts |
| 列出受跟踪的工具清单 | hol-guard inventory |
| 更新到最新版本 | hol-guard update |
🧪 不执行、先预检:安全测试命令
如果某条命令被 Guard 拦下,可以用 command test / command explain 安全地查看分类结果(不执行命令、不产生审批):
hol-guard command test 'rm -rf ./build'
hol-guard command explain 'git clean -ndx'
你也可以在本地 Dashboard 的 Test Lab 里直接输入命令,看 Guard 会如何判定,例如输入 git reset --hard HEAD~1 会得到 "Guard would ask first"(先询问)的只读评估结果:
❓ 新手常见问题
Q1:必须注册账号或连接云端吗? 不需要。本地保护、CLI、审批、决策记录全部离线可用。Guard Cloud 是可选服务,用于团队共享历史与策略,详见 docs/guard/local-vs-cloud.md。
Q2:Guard 为什么会暂停我的命令?
该动作在当前策略下需要审批,或工具/产物发生了变化。用 hol-guard approvals 查看待处理请求,再用 hol-guard receipts 复查已记录的决策。
Q3:遇到集成问题怎么办?
先跑 hol-guard doctor <harness> 诊断,更多排查方法见 docs/guard/troubleshooting.md。
Q4:如何升级到最新版?
hol-guard update
📚 延伸阅读
- 完整入门指南:docs/guard/get-started.md
- 项目总览与功能清单:README.md
- 架构与决策流程:docs/guard/architecture.md
- 策略配方示例:docs/guard/policy-recipes.md
至此,HOL Guard 的 5 分钟安装就完成了。让 AI Agent 继续高效工作,而把风险拦截交给 HOL Guard!🚀

