如何5分钟快速安装HOL Guard:面向新手的AI Agent安全保护完整教程

原创2026-10-22 14:29:451,698 阅读

如何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 发现新工具或变更时会暂停并请求审批。

HOL Guard AI Agent 安全保护本地 Dashboard 扩展管理界面,显示受保护状态

📋 日常使用: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"(先询问)的只读评估结果:

HOL Guard 测试实验室演示 AI Agent 危险命令被判定为“先询问”的截图

❓ 新手常见问题

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

📚 延伸阅读

至此,HOL Guard 的 5 分钟安装就完成了。让 AI Agent 继续高效工作,而把风险拦截交给 HOL Guard!🚀

登录后查看全文
hol-guard