AI Guardian

AI Guardian

免责声明：由社区维护的开源项目。**与 Ollama、IGEL 或任何 AI 安全厂商均无关联，也未获得其认可或赞助。**产品名称和商标归其所有者所有。采用 MIT 许可证。

用于本地端点大模型的受治理可观测性 + 治理。它可以观察 + 审计实际提供给本地模型的内容，并控制提示词中允许传出的内容——是 IGEL AI Armor 的补充。AI Armor 管控本地模型是否可以在端点上运行；ai-guardian 记录模型做了什么，并控制提示词中包含什么（机密、PII、源代码、越狱内容），以及哪些模型可以提供服务。自包含：它与各运行时的 REST API 通信，除 httpx 和 MCP SDK 外无需其他依赖。v0.1 提供可选择启用的经由路由内容治理，以及一个透明的捕获代理，供未选择启用的客户端使用。

支持的运行时

一个工具支持多个本地运行时，可在 config.yaml 中为每个目标通过 runtime 字段选择（init 向导会询问）。Ollama 使用其原生 API；其他三个共用一种兼容 OpenAI 的传输方式（/v1/models + /v1/chat/completions）。

运行时	runtime	默认端口	列表 / 策略	扫描 + 经由路由防护	来源信息
Ollama	ollama	11434	✅	✅	摘要（内容哈希 — 强）
llama.cpp（llama-server）	llamacpp	8080	✅	✅	属性 — /props 模型路径/大小 → 可固定 ID
LM Studio	lmstudio	1234	✅	✅	仅 ID — 较弱；固定项报告为 unverifiable
vLLM（本地单节点）	vllm	8000	✅	✅	仅 ID — 较弱；固定项报告为 unverifiable

允许/拒绝模型策略、确定性提示词扫描器、经由路由防护（guarded_generate / observe_chat）、来源漂移和 doctor 适用于所有运行时。模型生命周期写入操作（pull / remove / unload）仅适用于 Ollama——兼容 OpenAI 的服务端会在启动时加载模型，且不提供生命周期端点，因此这些写入操作会被拒绝，并显示清晰的提示信息。

来源信息如实说明：只有 Ollama（内容摘要）和 llama.cpp（基于 /props 的路径/大小身份信息）提供了可固定的信息。LM Studio 和 vLLM 仅提供模型 ID，因此固定的摘要会报告为 unverifiable，而不会错误地报告为 DRIFT。

此处的 vLLM 用于本地端点防护场景。 GPU 推理集群操作（自动扩缩、排空、Ray Serve/Jobs、大规模模型生命周期管理）属于该系列中的另一种工具——GPU 集群运维 → inference-aiops。

功能说明

Ollama 不会持久保存可查询的提示词/响应历史记录——每次请求的对话上下文都由客户端提供。因此，ai-guardian 从两个方面进行观察：

• 被动清单 / 状态审计——通过 /api/tags、/api/ps、 /api/show、/api/version 检查：已安装和正在运行的模型、它们的 VRAM 驻留情况、许可证/参数/能力，以及它们的来源摘要。每个模型都会标注允许/拒绝的策略判定，因此影子（未经批准的）模型会显示 allowed: false。
• 选择启用的路由式内容治理——调用方通过 ai-guardian 发送提示词 （guarded_generate / observe_chat）。它会扫描文本（机密信息 / 个人身份信息 / 源代码 / 越狱内容）、检查模型是否符合策略、记录交互到自己的使用日志（~/.ai-guardian/usage.db），然后才调用 Ollama——当风险等级过高或模型不允许时阻止请求。原始提示词绝不会被存储（只保存长度和经过脱敏的发现结果）。

现已推出（ai-guardian proxy serve）：一个透明捕获代理，可将相同的扫描、模型策略和记录功能应用于从未选择启用的客户端流量——让它们连接到代理，而非运行时。它会检查请求，并原样转发流式响应；它是一个流量关口，而非强制执行边界：如果客户端仍能访问运行时的真实端口，就可以完全绕过代理。proxy_guidance 会返回命令及相关注意事项；CLI 每次启动时都会打印这些信息。

主要功能

• 确定性离线提示词扫描器——不进行 I/O 或网络操作，因此可完全离线测试。可标记机密信息（AWS AKIA、私钥块、GitHub / Slack / OpenAI / Google 令牌、JWT、赋值形式的 api_key=…、高熵回退检测）、个人身份信息（电子邮件、美国 SSN、通过 Luhn 校验的信用卡号）、源代码/配置泄露启发式特征，以及越狱 / 提示词注入特征签名——并汇总为加权风险等级（低 / 中 / 高 / 严重；任何严重项都会决定最终等级）。发现结果会经过脱敏——扫描器绝不会重新输出捕获到的机密信息。
• 模型允许/拒绝策略（shell 通配符模式），可将影子 / 未经批准的模型标记为 allowed: false；还支持来源摘要固定，用于标记摘要发生变化（重新拉取 / 已篡改）的模型。
• 路由式防护——guarded_generate / observe_chat 会执行扫描、策略门控、记录，并在获准时运行；当风险等级 >= block_threshold（默认为 high）或模型不允许时阻止请求。
• 随包提供的治理框架——包含审计日志、令牌/失控预算防护、描述性风险等级和撤销令牌记录（无外部依赖）。
• 高度可自测——API 部分可免费使用本地 Ollama；扫描器、策略和风险等级逻辑都是纯粹的确定性离线逻辑。

此工具会决定和不会决定什么

它会准确地提供本地 LLM 的可观测性与运维能力——读取和写入——并记录每一次操作。它不会决定是否允许对模型环境进行写入。那由 Agent 自行判断，或由你运行它所用的主机和账户权限决定：将它指向该账户无权管理的运行时——例如，用户无法修改模型存储的 Ollama 守护进程，或 Agent 只能以只读方式访问的端点——写入就会在运行时失败，因为权限实际由运行时控制。最简单的办法是只向连接的 Agent 提供扫描／观察工具。

因此，工具框架无需配置只读开关、拒绝规则文件或审批关卡。（内容治理是独立的产品级功能，仍会保留：模型允许／拒绝策略和 guarded_generate 阻止阈值仍会扫描并限制模型被要求执行的操作。）工具框架唯一能保证的是，任何操作都不会悄无声息：每一次调用，无论通过 MCP 还是 CLI，都会写入一条审计记录，保存到 ~/.ai-guardian/audit.db；破坏性写入仍会捕获操作前的状态，并在存在逆操作时记录该操作。

每个工具都会声明一个 risk_level，并通过测试确保它与 [READ]／[WRITE] 文档标签一致；该级别也会作为描述性等级写入审计记录，让审查者一眼就能看出某条记录属于高风险删除操作。这只是标签，不是关卡。

使用较小的／本地模型？请参阅 agent-guardrails.md——其中列出了此工具现在会为你强制执行的防护措施（这样你就不必在提示词中重复说明），并提供了一份现成的系统提示词，用于补充剩余要求。

能力矩阵（21 个 MCP 工具）

读取（11 个）

工具	风险	返回内容
list_models	低	已安装的模型，以及每个模型的允许／拒绝判定（影子模型 → allowed:false）
running_models	低	已加载的模型：VRAM 占用 + 驻留到期时间
model_details	低	单个模型的许可证／参数／能力
server_status	低	Ollama 可访问性 + 版本
vram_usage	低	已加载模型使用的 VRAM 总量；标记是否超出预算
policy_view	低	当前允许／拒绝策略 + 来源摘要固定值
model_provenance	低	每个已安装摘要与其固定值的对比；标记偏差
scan_prompt	低	纯文本扫描 → 发现项 + 加权风险等级（不调用模型）
usage_events	低	查询已观察到的使用日志
anomaly_report	低	汇总：影子模型、摘要偏差、高风险提示词 + 被阻止的提示词
proxy_guidance	低	proxy serve 命令 + 客户端变更，并明确说明代理是关节点，而非强制执行边界；不写入任何内容，也不启动任何内容

写入（8 个）

工具	风险	撤销／安全措施
pull_model	中	若违反策略则拒绝
remove_model	高	试运行 + 撤销（重新拉取）
unload_model	中	从 VRAM 中移除（keep_alive:0）
set_model_allowlist	中	撤销 → 恢复先前的允许列表
set_model_denylist	中	撤销 → 恢复先前的拒绝列表
pin_model_digest	中	固定模型预期的来源摘要
guarded_generate	中	路由守卫：扫描 + 策略审核 + 记录 + 仅在允许时运行
observe_chat	中	同上，适用于 /api/chat 消息

撤销（2 个）

工具	风险	功能
undo_list	低	列出已记录的撤销令牌
undo_apply	中	重放已记录的逆操作描述符

风险等级拦截：当提示词的风险等级 >= block_threshold（默认值为 high）或模型不被允许时，guarded_generate／observe_chat 会阻止调用。被阻止的调用不会到达 Ollama，并会在使用日志中记录为已阻止。

快速开始

作为 Claude Code 插件

安装一次，即可让 Agent 同时获得技能和 MCP 服务：

/plugin marketplace add AIops-tools/marketplace
/plugin install ai-guardian@aiops-tools

MCP 服务通过 uv 获取，并固定到此插件声明的程序包版本，因此可以将审计记录追溯到写入它的代码。凭据仍通过 ai-guardian init 配置——见下文。

作为 OpenClaw 插件

同一套插件包发布在 ClawHub，安装一次即可同时获得技能和 MCP 服务：

openclaw plugins install clawhub:@zw008/ai-guardian
openclaw skills info ai-guardian          # expect: Visible to model: yes

之后请重启 OpenClaw 网关，以便加载插件。MCP 服务通过 uv 获取，并固定到此确切版本，因此 uvx 必须位于 PATH 中——否则仍会安装技能，但会报告 Visible to model: no。凭据按下文所述配置。

作为 CLI 或独立 MCP 服务

uv tool install ai-guardian-aiops          # or: pipx install ai-guardian-aiops
ai-guardian doctor                   # Ollama reachability + policy summary (works zero-config)
ai-guardian overview                 # models installed/running, shadow count, usage stats
ai-guardian model list               # installed models with allow/deny verdicts
ai-guardian guard scan "my key is AKIAIOSFODNN7EXAMPLE"   # deterministic scan → risk band

命令和程序包的名称不同。 CLI、技能和此仓库的名称都是 ai-guardian；PyPI 发行包名为 ai-guardian-aiops，因为 ai-guardian 已被占用。下面的两种拼法都正确且有意为之——安装 ai-guardian-aiops，然后运行 ai-guardian。

通过 MCP 将提示词路由到防护机制（扫描 + 策略门控 + 记录 + 获准后运行）：

guarded_generate(model="llama3.2:3b", prompt="…", block_threshold="high")

作为 MCP 服务运行（stdio）——提供完整的 21 个工具；CLI 仅包含其中的便捷子集：

export AI_GUARDIAN_AIOPS_MASTER_PASSWORD=...   # only if a target has a stored token
ai-guardian mcp                                # or: ai-guardian-mcp

之后密码会存放在哪里：导出的变量可被此 Shell 启动的每个进程读取，也会记录在 Shell 历史中。在共享主机或长期运行的主机上，建议使用交互式提示，或通过密钥管理器将密码注入仅需它的那条命令的运行环境中。

治理

每项操作——MCP 和 CLI——都会经过内置的 @governed_tool 框架。它负责记录，不负责授权（见上文）。

• 审计——每次调用（参数、结果、状态、耗时、风险级别，以及操作员提供的审批人／理由）都会记录到 ~/.ai-guardian/audit.db（可通过 AI_GUARDIAN_AIOPS_HOME 更改位置）。该数据库与存放观测到的本地大模型使用情况的 ~/.ai-guardian/usage.db 相互独立。
• 失控防护——这是一道安全后备措施，而非授权门控：如果同一调用在短时间内被反复触发，就会触发断路器，避免卡住的 Agent 无限消耗调用次数／时间。可通过 AI_GUARDIAN_RUNAWAY_MAX=0 禁用；也可设置可选的硬性上限 AI_GUARDIAN_MAX_TOOL_CALLS / AI_GUARDIAN_MAX_TOOL_SECONDS。
• 撤销记录——可逆写入会记录一个基于获取的操作前状态构建的逆向描述符。
• 风险级别——审计记录上根据 risk_level 得出的描述性标签；不会门控任何操作。

支持范围与限制

• 范围：端点上的本地大模型——Ollama，以及兼容 OpenAI 的 llama.cpp / LM Studio / 本地单节点 vLLM；提供单端点本地大模型可观测性与内容治理。不涵盖 GPU 推理集群运维（→ inference-aiops）。
• v0.1 = 被动盘点／状态审计 以及可选启用的路由式内容治理。面向其他客户端流量的透明捕获代理属于 v0.2 路线图，而非 v0.1。
• IGEL AI Armor 互操作目前仅为文档层面的定位（角色互补），并非已接入的集成。
• 验证状态——扫描器、策略和风险等级带均为纯确定性离线逻辑，并由测试套件按此方式测试。核心 Ollama 路由流程（实际生成 + 策略拒绝 + 撤销捕获）已于 2026-07-13 在运行中的 Ollama 0.24.0 上测试；其余 Ollama 功能以及兼容 OpenAI 的方言（llama.cpp / LM Studio / 本地 vLLM）目前仍仅通过模拟响应测试。ai-guardian doctor 是最快的实时检查方式；具体已验证的项目请见 docs/VERIFICATION.md。

缺少某项能力？

想要被动捕获代理、其他扫描器签名、更丰富的策略模型或 AI Armor 钩子？欢迎提交议题或 PR，反馈和贡献都备受欢迎。