本地配置

Failproof AI 将仓库可提交的内容（钩子连接、策略参数、自定义策略）与机器状态（如凭据、已安装的包及守护进程）分开管理。

选择作用域

作用域决定了钩子的连接位置，以及您在哪个配置文件中写入参数和自定义策略路径：

User：应用于本机上的所有项目。
Project：归属于仓库，可以提交。
Local：为单个用户覆盖某个项目的配置，应保留在 gitignore 中。

failproofai policies --install --cli claude --scope project   # 为此仓库连接钩子
failproofai policies --install --cli claude --scope user      # 或为本机上的所有项目连接钩子
failproofai policies

并非所有 harness 都支持 local 作用域；如果所选 harness 不支持指定的作用域，CLI 会拒绝该请求。包策略的启用状态不受作用域限制。该开关与已安装的包一起记录，因此 failproofai policies add <name> 会在整台机器范围内启用某个策略，无论 --scope 如何设置。

作用域	策略配置文件
Project	`<project>/.failproofai/policies-config.json`
Local	`<project>/.failproofai/policies-config.local.json`
User	`~/.failproofai/policies-config.json`

策略参数按 project → local → user 的顺序，使用第一个为该策略定义了参数的作用域。显式自定义策略路径同样使用第一个定义了路径的作用域。

配置策略参数

控制台
CLI

在本地控制台中打开相应策略，编辑其支持的参数，并保存到所选作用域。运行一个匹配和一个不匹配的 Agent 操作，然后在 Observe → policy 中查看决策结果。

编辑所选作用域的 policies-config.json，然后运行 failproofai policies：如果 policyParams 条目中指定的策略不存在于任何已安装的包中，系统会发出警告。它不会检查条目内部的键名，因此请对照下方表格核对拼写。

{
  "policyParams": {
    "block-rm-rf": {
      "allowPaths": ["/tmp/build-output"]
    }
  }
}

failproofai policies

Failproof AI 策略接受的参数

每个策略会自行验证其参数类型。

策略	参数	类型与默认值
`sanitize-api-keys`	`additionalPatterns`	`pattern[]`，`[]`；条目包含 `regex` 和 `label`
`block-read-outside-cwd`	`allowPaths`	`string[]`，`[]`
`block-sudo`	`allowPatterns`	`string[]`，`[]`
`block-rm-rf`	`allowPaths`	`string[]`，`[]`
基础设施拦截器	`allowPatterns`	`string[]`，`[]`
`block-secrets-write`	`additionalPatterns`	`string[]`，`[]`
`block-push-master`	`protectedBranches`	`string[]`，`["main", "master"]`
`block-work-on-main`	`protectedBranches`	`string[]`，`["main", "master"]`
`prefer-package-manager`	`allowed`，`blocked`	`string[]`，`[]`
`warn-large-file-write`	`thresholdKb`	`number`，`1024`
`require-push-before-stop`	`remote`，`baseBranch`	`string`，`"origin"`；`string`，`"main"`
`require-pr-before-stop`	`baseBranch`	`string`，`"main"`
`require-no-conflicts-before-stop`	`baseBranch`	`string`，`"main"`

允许模式会扩大 Agent 的操作权限。在将其部署到整个集群之前，请先在目标 harness 上测试准确的分词行为和各种命令变体。

了解机器文件

~/.failproofai 针对不同信任边界包含独立文件：

路径	用途
`config.json`	守护进程、审计和遥测的非敏感设置
`credentials.json`	云凭据；以仅限所有者的权限存储
`policies-config.json`	用户作用域的参数及显式自定义策略路径
`policies/`	用户约定策略、已安装的包及其策略启用状态，以及云端管理的策略产物
`hook-activity/`	本地策略决策日志
`state/`	守护进程缓冲区、健康状态、暂停状态及运行时状态

使用 FAILPROOFAI_HOME 可将完整的机器目录布局迁移至容器或隔离测试环境。请勿单独迁移各个状态目录。

切勿提交 credentials.json。项目策略配置和项目约定策略只有在作为执行代码审查完毕后才可提交。

Connect your agents

Reference

选择作用域

配置策略参数

Failproof AI 策略接受的参数

了解机器文件

​选择作用域

​配置策略参数

​Failproof AI 策略接受的参数

​了解机器文件

选择作用域

配置策略参数

Failproof AI 策略接受的参数

了解机器文件