HOL Guard首次运行向导实战:从hol-guard init到10分钟跑通第一个受保护的AI Agent

原创2026-10-22 22:52:201,740 阅读

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 首次运行向导的入口。它的工作方式很讲究:

  1. 先打印计划:向导会先展示它准备做什么,而不是闷头执行;
  2. 逐项确认副作用:打开本地 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 会告诉你当前机器处于什么保护状态、守护进程是否在运行、下一步该做什么。

HOL Guard AI Agent保护中心面板,显示本机已处于Protected受保护状态

上图是 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'

HOL Guard AI Agent保护面板测试实验室,展示git reset命令的安全检测流程

上图是面板中的 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 分钟真的够吗?够。整个路径就是——

  1. pipx install hol-guard 安装
  2. hol-guard init 走首次运行向导,逐项确认、自动配好本地保护
  3. hol-guard install codex + hol-guard run codex 让 Agent 进入受保护状态
  4. 遇到暂停时用 approvals / command explain / receipts 完成"看懂 → 决策 → 留痕"闭环

全程无需注册账号,所有保护、审批、证据都留在本机。如果你的 Agent 每天在替你敲命令、装依赖、读文件,那么这层"AI Agent 杀毒"值得在第一次安装 Agent 时就一并部署好。🛡️

登录后查看全文
hol-guard