跳转到主要内容
failproofai 使用 JSON 配置文件来控制哪些策略处于激活状态、策略的行为方式以及自定义策略的加载位置。配置设计便于与团队共享——将其提交到代码仓库，每位开发者都能获得相同的智能体安全防护网。

​
配置作用域

共有三个配置作用域，按优先级顺序进行评估：
作用域文件路径用途
project.failproofai/policies-config.json每个代码仓库的配置，提交到版本控制
local.failproofai/policies-config.local.json个人级别的仓库覆盖配置，已加入 .gitignore
global~/.failproofai/policies-config.json适用于所有项目的用户级默认配置
当 failproofai 接收到 hook 事件时，会加载并合并当前工作目录下存在的所有三个文件。

​
合并规则

enabledPolicies — 取三个作用域的并集。在任意级别启用的策略均处于激活状态。 
project:  ["block-sudo"]
local:    ["block-rm-rf"]
global:   ["block-sudo", "sanitize-api-keys"]

resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"]  ← 去重后的并集
policyParams — 最先定义某策略参数的作用域完全优先。策略参数内部的值不进行深度合并。 
project:  block-sudo → { allowPatterns: ["sudo apt-get update"] }
global:   block-sudo → { allowPatterns: ["sudo systemctl status"] }

resolved: { allowPatterns: ["sudo apt-get update"] }   ← project 优先，global 被忽略

project:  （无 block-sudo 条目）
local:    （无 block-sudo 条目）
global:   block-sudo → { allowPatterns: ["sudo systemctl status"] }

resolved: { allowPatterns: ["sudo systemctl status"] }  ← 向下回落到 global
customPoliciesPath — 最先定义该字段的作用域优先。 llm — 最先定义该字段的作用域优先。

​
配置文件格式

{
  "enabledPolicies": [
    "block-sudo",
    "block-rm-rf",
    "block-push-master",
    "sanitize-api-keys",
    "sanitize-jwt",
    "block-env-files",
    "block-read-outside-cwd"
  ],
  "policyParams": {
    "block-sudo": {
      "allowPatterns": ["sudo systemctl status", "sudo journalctl"]
    },
    "block-push-master": {
      "protectedBranches": ["main", "release", "prod"]
    },
    "block-rm-rf": {
      "allowPaths": ["/tmp"]
    },
    "block-read-outside-cwd": {
      "allowPaths": ["/shared/data", "/opt/company"]
    },
    "sanitize-api-keys": {
      "additionalPatterns": [
        { "regex": "myco_[A-Za-z0-9]{32}", "label": "MyCo API key" }
      ]
    },
    "warn-large-file-write": {
      "thresholdKb": 512
    }
  },
  "customPoliciesPath": "/home/alice/myproject/my-policies.js"
}

​
字段参考

​
enabledPolicies

类型：string[] 要启用的策略名称列表。名称必须与 failproofai policies 显示的策略标识符完全匹配。完整列表请参阅内置策略。 不在 enabledPolicies 中的策略处于非激活状态，即使在 policyParams 中有对应条目也同样如此。

​
policyParams

类型：Record<string, Record<string, unknown>> 各策略的参数覆盖配置。外层键为策略名称，内层键为策略专属参数。每个策略的可用参数详见内置策略。 如果某策略有参数但未指定，则使用该策略的内置默认值。未配置 policyParams 的用户将获得与之前版本完全相同的行为。 策略参数块中的未知键在 hook 触发时会被静默忽略，但运行 failproofai policies 时会显示为警告。

​
hint（通用字段）

类型：string（可选） 当策略返回 deny 或 instruct 时，附加到原因末尾的消息。使用它可以在不修改策略本身的情况下，为 Claude 提供可操作的指导建议。 适用于任何类型的策略——内置策略、自定义策略（custom/）、项目约定策略（.failproofai-project/）或用户约定策略（.failproofai-user/）。 
{
  "policyParams": {
    "block-force-push": {
      "hint": "Try creating a fresh branch instead."
    },
    "block-sudo": {
      "allowPatterns": ["sudo apt-get"],
      "hint": "Use apt-get directly without sudo."
    },
    "custom/my-policy": {
      "hint": "Ask the user for approval first."
    }
  }
}
当 block-force-push 拒绝操作时，Claude 会看到：“Force-pushing is blocked. Try creating a fresh branch instead.” 非字符串值和空字符串会被静默忽略。若未设置 hint，行为保持不变（向后兼容）。

​
customPoliciesPath

类型：string（绝对路径） 包含自定义 hook 策略的 JavaScript 文件路径。此字段由 failproofai policies --install --custom <path> 自动设置（路径在存储前会解析为绝对路径）。 每次 hook 事件触发时都会重新加载该文件，不存在缓存机制。关于编写自定义策略的详情，请参阅自定义策略。

​
基于约定的策略

除显式指定的 customPoliciesPath 外，failproofai 还会自动发现并加载 .failproofai/policies/ 目录中的策略文件：
级别目录作用域
项目.failproofai/policies/通过版本控制与团队共享
用户~/.failproofai/policies/个人级别，适用于所有项目
文件匹配规则： 仅加载符合 *policies.{js,mjs,ts} 模式的文件（例如 security-policies.mjs、workflow-policies.js），目录中的其他文件将被忽略。 无需配置： 约定策略无需在 policies-config.json 中添加任何条目。只需将文件放入对应目录，下次 hook 事件触发时即可自动加载。 联合加载： 项目级和用户级约定目录都会被扫描。两个级别中所有匹配的文件都会被加载（与 customPoliciesPath 的首个作用域优先规则不同）。 更多详情和示例请参阅自定义策略。

​
llm

类型：object（可选） 适用于需要进行 AI 调用的策略的 LLM 客户端配置。大多数场景下无需配置。 
{
  "llm": {
    "model": "claude-sonnet-4-6",
    "apiKey": "sk-ant-..."
  }
}

​
通过 CLI 管理配置

policies --install 和 policies --uninstall 命令会写入 Claude Code 的 settings.json（hook 入口点），而 policies-config.json 则是由你直接管理的文件。两者相互独立：
  • settings.json — 告知 Claude Code 在每次工具调用时执行 failproofai --hook <event>
  • policies-config.json — 告知 failproofai 要评估哪些策略以及使用什么参数
你可以随时直接编辑 policies-config.json，修改将在下次 hook 事件触发时立即生效，无需重启。

​
示例：包含团队默认值的项目级配置

将 .failproofai/policies-config.json 提交到代码仓库： 
{
  "enabledPolicies": [
    "block-sudo",
    "block-rm-rf",
    "block-push-master",
    "sanitize-api-keys",
    "block-env-files"
  ],
  "policyParams": {
    "block-push-master": {
      "protectedBranches": ["main", "release", "hotfix"]
    }
  }
}
每位开发者可以在此基础上创建 .failproofai/policies-config.local.json（已加入 .gitignore）进行个人覆盖配置，而不会影响其他团队成员。