跳转到主要内容

​
系统要求

  • Node.js >= 20.9.0
  • Bun >= 1.3.0（可选 - 仅从源码构建时需要）

​
安装

npm install -g failproofai

​
快速开始

1

启用策略

策略是在每次 Agent 工具调用前后执行的规则，能够在破坏性命令、密钥泄露及其他故障模式造成损害之前将其拦截。
failproofai policies --install
此命令会将 hook 条目写入 Claude Code 的 settings.json。你也可以针对单个项目安装，或选择特定策略：
failproofai policies --install --scope project
failproofai policies --install block-sudo block-rm-rf sanitize-api-keys
2

验证

failproofai policies
显示所有策略、是否已启用以及已配置的参数。
3

启动仪表板

failproofai
在 http://localhost:8020 打开本地仪表板，你可以在此浏览会话、查看工具调用详情并管理策略。
4

运行你的 Agent

像往常一样启动 Claude Code。如果 Agent 尝试执行高风险操作，failproofai 会自动拦截。让它在无人值守的情况下运行，之后在仪表板中查看执行记录。

​
策略的工作原理

每当 Agent 运行工具时，Claude Code 会将 failproofai 作为子进程调用： 
Claude Code  →  failproofai --hook PreToolUse  →  reads stdin JSON
                                                 evaluates policies
                                                 writes decision to stdout
每个策略返回以下三种决策之一：
  • allow - Agent 正常继续执行
  • deny - 操作被阻止，并告知 Agent 原因
  • instruct - 向 Agent 的提示词中追加额外上下文
策略在你的本地进程中运行，不会向任何远程服务发送数据。

​
数据存储

所有配置和日志均保存在本地：
路径存储内容
~/.failproofai/policies-config.json全局策略配置
~/.failproofai/hook-activity.jsonlHook 执行历史记录
~/.failproofai/hook.log自定义 hook 错误的调试日志
.failproofai/policies-config.json项目级配置（可提交至版本库）
.failproofai/policies-config.local.json个人覆盖配置（已被 gitignore）

​
卸载

failproofai policies --uninstall
从 ~/.claude/settings.json 中移除 hook 条目，~/.failproofai/ 中的配置文件将保留。

​
下一步

配置

作用域与配置文件格式

内置策略

全部 26 个策略及其参数说明

自定义策略

用 JavaScript 编写你自己的策略

Agent 监控

监控会话并查看策略活动记录