HOL Guard首次运行向导实战:从hol-guard init到10分钟跑通第一个受保护的AI Agent
HOL Guard首次运行向导实战:从hol-guard init到10分钟跑通第一个受保护的AI Agent
一、HOL Guard 是什么?
HOL Guard 是一款开源的 AI Agent 杀毒与运行时保护工具,它能拦截危险 shell 命令、密钥泄露、提示词注入(prompt injection)、恶意依赖包、MCP 服务器和插件,在动作真正执行前给出"放行 / 拦截 / 请求审批"的决策。它的核心卖点可以概括为一句话:本地优先、无需账号,装完即用。
而本文的主角就是它的首次运行向导——一条命令 hol-guard init,自动完成"打开本地面板 → 安装 Agent 集成 → 可选云同步 → 桌面通知"的全部配置。跟着下面 10 分钟左右的流程走一遍,你就能跑通第一个受保护的 AI Agent(以 Codex 为例)。
二、开始前的准备工作
安装 HOL Guard 只需满足两个前提:
| 依赖 | 要求 |
|---|---|
| Python | 3.10 或更新版本 |
| pipx | 用于隔离安装 CLI 工具 |
三、三步安装并启动首次运行向导
第 1 步:一键安装
pipx install hol-guard
第 2 步:运行 hol-guard init
hol-guard init
这就是 HOL Guard 首次运行向导的入口。它的工作方式很讲究:
- 先打印计划:向导会先展示它准备做什么,而不是闷头执行;
- 逐项确认副作用:打开本地 Dashboard、安装 Agent 集成、连接可选的 Guard Cloud、配置桌面通知——每一步都先询问,你批准后才执行,并且每一步完成后才出现下一个提示。
向导的初始化逻辑位于 src/codex_plugin_scanner/guard/cli/commands_dispatch_local.py,如果你想了解它内部如何串联 store、config 和 harness 上下文,可以从这个入口读起。
几个常用参数,适合不同场景:
# 跳过 Agent 自动安装
hol-guard init --skip-apps
# 跳过 Guard Cloud 配对
hol-guard init --skip-cloud
# 自动化/CI 场景:全部步骤免确认
hol-guard init --yes
第 3 步:验证安装
hol-guard --version
hol-guard status
hol-guard status 会告诉你当前机器处于什么保护状态、守护进程是否在运行、下一步该做什么。
上图是 init 完成后本地 Dashboard 中的保护中心:顶部状态条显示"Guard is actively applying the trusted protection settings on this device",右侧"Protected"徽章表示本机已进入受保护状态,无需任何额外操作(No action required)。
四、跑通第一个受保护的 AI Agent
以 Codex 为例,手动路径只需三条命令:
hol-guard install codex # 在 Agent 中安装 Guard 钩子
hol-guard run codex --dry-run # 空跑一次,记录当前工件状态快照
hol-guard run codex # 从此之后通过 Guard 启动 Codex
执行 install codex 后,Guard 会在 Codex 配置中启用 PreToolUse 钩子——它能在 shell 启动之前拿到完整的 Bash 命令,因此调试陷阱、shell 启动文件都绕不过防护边界。如果原生钩子缺失或被禁用,hol-guard run codex 会直接拒绝启动,保证"没有防护就不放行"。
之后只要某个工具是新增的或发生过变更,Guard 就会暂停启动并向你发起审批。
五、命令被暂停了?三步看懂并处理
HOL Guard 审批中心支持三种投递渠道:Agent 原生权限弹窗、本机 127.0.0.1 上的审批中心页面、以及纯终端的 hol-guard approvals 命令。终端路径最常用:
hol-guard approvals # 查看等待中的审批
hol-guard approvals approve <request-id> # 批准
hol-guard approvals deny <request-id> # 拒绝
如果只是想"看看"一条命令会被怎么判,而不真正执行、也不产生审批记录:
hol-guard command test 'rm -rf ./build'
hol-guard command explain 'git clean -ndx'
上图是面板中的 Test Lab:输入 git reset --hard HEAD~1 后点"Check safely",Guard 只读评估并回答"Guard would ask first"——命令没有真正执行,也不会留下副作用,非常适合新手熟悉判定逻辑。
每次决策都会落成本地回执(receipt),随时可查:
hol-guard receipts # 查看本机决策历史
hol-guard diff codex # 对比自上次快照以来发生了什么变化
六、常用命令速查表
| 你想做什么 | 命令 |
|---|---|
| 查看保护状态 | hol-guard status |
| 诊断某个 Agent 集成 | hol-guard doctor codex |
| 处理待审批请求 | hol-guard approvals |
| 解读一条被暂停的命令 | hol-guard command explain '<命令>' |
| 查看决策历史 | hol-guard receipts |
| 扫描工作区供应链风险 | hol-guard supply-chain scan |
| 连接可选的云端同步 | hol-guard connect |
更多细节可阅读官方入门文档 docs/guard/get-started.md,支持的 Agent 矩阵见 docs/guard/harness-support.md,本地与云端能力边界见 docs/guard/local-vs-cloud.md,遇到问题优先翻 docs/guard/troubleshooting.md。
七、总结
回到开头的问题:10 分钟真的够吗?够。整个路径就是——
pipx install hol-guard安装hol-guard init走首次运行向导,逐项确认、自动配好本地保护hol-guard install codex+hol-guard run codex让 Agent 进入受保护状态- 遇到暂停时用
approvals/command explain/receipts完成"看懂 → 决策 → 留痕"闭环
全程无需注册账号,所有保护、审批、证据都留在本机。如果你的 Agent 每天在替你敲命令、装依赖、读文件,那么这层"AI Agent 杀毒"值得在第一次安装 Agent 时就一并部署好。🛡️

