快速开始

环境要求

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

安装

npm install -g failproofai

bun add -g failproofai

快速上手

启用策略

策略是在每次 Agent 工具调用前后执行的规则。它们能在破坏性命令、密钥泄露及其他故障模式造成损害之前将其拦截。

failproofai policies --install

此命令会将 hook 条目写入已安装的 Agent CLI 配置文件中（Claude Code 的 ~/.claude/settings.json、OpenAI Codex 的 ~/.codex/hooks.json、GitHub Copilot CLI 的 ~/.copilot/hooks/failproofai.json、Cursor Agent 的 ~/.cursor/hooks.json、OpenCode 在 ~/.config/opencode/plugins/failproofai.mjs 生成的插件 shim 及 ~/.config/opencode/opencode.json 的 plugin 数组注册项、Pi 的 ~/.pi/agent/settings.json，或 Hermes 的 ~/.hermes/config.yaml）。若检测到多个 CLI，系统会提示你选择；也可以通过 --cli claude codex copilot cursor opencode pi hermes（任意子集）跳过提示。GitHub Copilot CLI、Cursor Agent、OpenCode 和 Pi 的支持目前处于 beta 阶段 — 请分别使用 --cli copilot、--cli cursor、--cli opencode 或 --cli pi 进行安装。Hermes（hermes-agent，一个 Slack/Telegram 网关）使用 --cli hermes 安装用户级作用域，同时也是一个离线审计数据源。

failproofai policies --install --scope project
failproofai policies --install --cli codex --scope project
failproofai policies --install --cli copilot --scope project
failproofai policies --install --cli cursor --scope project
failproofai policies --install --cli opencode --scope project
failproofai policies --install --cli pi --scope project
failproofai policies --install --cli hermes --scope user
failproofai policies --install block-sudo block-rm-rf sanitize-api-keys

验证安装

failproofai policies

显示所有策略、各策略的启用状态及已配置的参数。

启动控制台

failproofai

在 http://localhost:8020 打开本地控制台，你可以在此浏览会话记录、检查工具调用详情并管理策略。

运行你的 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/ 约定。只需将策略文件放入该目录，它们便会自动加载 — 无需任何额外参数、配置修改或安装命令。

创建策略目录

mkdir -p .failproofai/policies

添加策略文件

复制内置的示例文件，或自己编写：

cp node_modules/failproofai/examples/convention-policies/*.mjs .failproofai/policies/

或者创建一个新的策略文件：

// .failproofai/policies/team-policies.mjs
import { customPolicies, allow, deny, instruct } from "failproofai";

customPolicies.add({
  name: "test-before-commit",
  match: { events: ["PreToolUse"] },
  fn: async (ctx) => {
    if (ctx.toolName !== "Bash") return allow();
    if (/git\s+commit/.test(ctx.toolInput?.command ?? "")) {
      return instruct("Run tests before committing.");
    }
    return allow();
  },
});

提交到 git

git add .failproofai/policies/
git commit -m "Add team quality policies"

所有已安装 failproofai 的团队成员都会自动获取这些策略，无需每人单独配置。

将 .failproofai/policies/ 提交到代码仓库，让整个团队共享同一套标准。随着团队不断发现新的故障模式，持续添加策略并推送 — 所有人在下次 git pull 时便能自动获取更新。随着时间推移，这些策略将成为一套持续演进的活跃质量标准。

数据存储

所有配置和日志均保存在本地：

路径	存储内容
`~/.failproofai/policies-config.json`	全局策略配置
`~/.failproofai/hook-activity.jsonl`	Hook 执行历史记录
`~/.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 监控

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

核心概念

CLI

工具

进阶

示例

快速开始

环境要求

安装

快速上手

策略的工作原理

通过约定式策略建立团队规范

数据存储

卸载

下一步

配置说明

内置策略

自定义策略

Agent 监控

​环境要求

​安装

​快速上手

​策略的工作原理

​通过约定式策略建立团队规范

​数据存储

​卸载

​下一步

配置说明

内置策略

自定义策略

Agent 监控

环境要求

安装

快速上手

策略的工作原理

通过约定式策略建立团队规范

数据存储

卸载

下一步