配置

​

配置作用域

​

合并规则

project:  ["block-sudo"]
local:    ["block-rm-rf"]
global:   ["block-sudo", "sanitize-api-keys"]

resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"]  ← 去重后的并集

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

​

配置文件格式

{
  "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

​

policyParams

​

hint（通用参数）

{
  "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."
    }
  }
}

​

customPoliciesPath

​

基于约定的策略

​

llm

{
  "llm": {
    "model": "claude-sonnet-4-6",
    "apiKey": "sk-ant-..."
  }
}

​

通过 CLI 管理配置

• Agent CLI 设置 — 指示 Agent 在每次工具调用时执行 failproofai --hook <event>：
  • Claude Code：~/.claude/settings.json（用户级）、<cwd>/.claude/settings.json（项目级）、<cwd>/.claude/settings.local.json（本地级）
  • OpenAI Codex：~/.codex/hooks.json（用户级）、<cwd>/.codex/hooks.json（项目级）—— Codex 没有 local 作用域
  • GitHub Copilot CLI (beta)：~/.copilot/hooks/failproofai.json（用户级）、<cwd>/.github/hooks/failproofai.json（项目级）—— Copilot 没有 local 作用域。Hook 条目使用 Copilot 的操作系统键化 bash/powershell 命令字段（含 timeoutSec）；文件顶层包含 version: 1 标记。Copilot CLI 支持目前处于 beta 阶段，我们正在对照更多真实场景验证 events.jsonl 记录的 schema（公开文档中未予说明）。
  • Cursor Agent (beta)：~/.cursor/hooks.json（用户级）、<cwd>/.cursor/hooks.json（项目级）—— Cursor 没有 local 作用域。Hook 条目使用 Claude 格式的 {type, command, timeout}（无 bash/powershell 分割），但按照 Cursor 的 hooks schema 以驼峰式事件键（preToolUse、beforeSubmitPrompt 等）存储在平铺数组中；文件顶层包含 version: 1 标记。处理程序通过 CURSOR_EVENT_MAP 将驼峰式名称规范化为 PascalCase，因此现有内置策略无需改动即可正常触发。Cursor Agent 支持目前处于 beta 阶段，我们正在对照更多真实安装验证 Cursor 的转录文件磁盘格式（公开文档中未予说明）。
  • OpenCode (beta)：~/.config/opencode/opencode.json + ~/.config/opencode/plugins/failproofai.mjs（用户级），<cwd>/.opencode/opencode.json + <cwd>/.opencode/plugins/failproofai.mjs（项目级）—— OpenCode 没有 local 作用域。与其他六个 CLI 不同，OpenCode 没有外部命令 hook 系统：它通过 opencode.json 中 plugin: [] 数组显式注册来加载进程内 JS/TS 插件（从 .opencode/plugins/ 自动发现不是 opencode v1.14.33 插件的加载方式）。安装时会生成一个小型插件 shim，以子进程方式调用 failproofai 二进制文件，并将二进制文件的 Claude 格式 JSON 响应转换为插件语义：工具事件拒绝时 throw new Error()（取消工具调用）；instruct 以及 Stop / SubagentStop 拒绝时调用 client.session.prompt(...)（将拒绝原因作为下一条用户消息提交——这是唯一的强制重试通道，因为 session.idle 仅用于通知，从中抛出异常无效）；allow 时为空操作。shim 在转发给二进制文件之前，会将工具名称（小写 → PascalCase，通过 OPENCODE_TOOL_MAP）和工具输入参数键（驼峰式 → 下划线式，通过 OPENCODE_TOOL_INPUT_MAP，适用于 Read / Write / Edit，例如 filePath → file_path、oldString → old_string）进行规范化，因此 block-read-outside-cwd、block-env-files、block-secrets-write 等路径检查内置策略在 OpenCode 工具调用时无需修改即可正常触发。会话保存在 OpenCode 的 SQLite 数据库 ~/.local/share/opencode/opencode.db 中；仪表盘的会话查看器通过 opencode db --format json 和 opencode export <id> 读取这些数据。OpenCode 支持目前处于 beta 阶段，我们正在对照更多真实场景跨版本验证其行为。详见 OpenCode 插件文档。
  • Pi (beta)：~/.pi/agent/settings.json（用户级）、<cwd>/.pi/settings.json（项目级）—— Pi 没有 local 作用域。Pi 在启动时加载 TypeScript 扩展包；设置文件是一个平铺的字符串数组 {"packages": ["./relative/path", …]}。failproofai 会写入一个 packages 数组条目，指向其捆绑的 pi-extension/ 目录。扩展内部订阅 Pi 的 tool_call / user_bash / input / session_start 事件，并调用 failproofai --hook <Event> --cli pi；处理程序通过 PI_EVENT_MAP 将下划线小写命名规范化为 PascalCase，因此现有内置策略无需改动即可正常触发。工具输入参数也通过 PI_TOOL_INPUT_MAP 进行规范化（Pi 的 Read / Write / Edit 使用 path 而非 file_path；映射顶层键可使 block-env-files 和 block-secrets-write 正常触发—— block-read-outside-cwd 已有 path 回退逻辑）。Pi 支持目前处于 beta 阶段，等待 Pi 的扩展 API 和会话日志格式趋于稳定。
  • Gemini CLI (beta)：~/.gemini/settings.json（用户级）、<cwd>/.gemini/settings.json（项目级）—— Gemini 没有 local 作用域（其文档中有位于 /etc/gemini-cli/settings.json 的 system 作用域，failproofai 不对外暴露该作用域）。Hook 条目使用 Claude 的 {type, command, timeout} 格式，包裹在 Gemini 的 {matcher, hooks: [...]} matcher schema 中，默认 matcher: "*"。事件名称为 PascalCase（SessionStart、BeforeAgent、AfterAgent、BeforeModel、AfterModel、BeforeToolSelection、BeforeTool、AfterTool、PreCompress、Notification、SessionEnd）；处理程序通过 GEMINI_EVENT_MAP 映射到 Claude 规范名称。工具名称为 snake_case（run_shell_command、read_file、write_file、replace 等）——处理程序通过 GEMINI_TOOL_MAP 规范化，使现有内置策略无需改动即可正常触发。策略评估器输出 Gemini 的平铺 {decision: "deny", reason} 格式（符合 Gemini 的”黄金规则”退出码 0 约定），在 BeforeAgent / AfterTool / SessionStart 时输出 {hookSpecificOutput: {hookEventName, additionalContext}} 进行上下文注入，在 AfterAgent 时输出 {decision: "block", reason} 以实现强制重试语义。Gemini CLI 支持目前处于 beta 阶段，我们正在扩大真实场景的覆盖范围。详见 Gemini CLI hooks 文档。
• policies-config.json — 告知 failproofai 要评估哪些策略及其参数（在所有 Agent CLI 之间共享）

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 gemini --scope project
failproofai policies --install --cli claude codex copilot cursor opencode pi gemini

• 检测到一个 CLI — 自动选择该 CLI，无需提示。
• 检测到多个 CLI（交互式终端）— 显示方向键单选提示，分组展示：已检测 (N) 部分（包含一个”为所有 N 个已检测 CLI 安装”的聚合选项，以及各已检测 CLI 的单独选项）和未安装 (M) · 提前安装 hooks 部分（列出每个未检测到的受支持 CLI 作为预安装选项；↑↓ 移动，Enter 选择，^C 退出）。卸载流程只显示已检测部分。
• 检测到多个 CLI（非交互式运行，如 CI 或无 TTY）— 为所有已检测 CLI 安装，无需提示。
• 未检测到任何 CLI — 回退至 claude，并警告 PATH 中未找到 Agent 二进制文件；hook 命令仍会写入，待安装后即可激活。

​

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

{
  "enabledPolicies": [
    "block-sudo",
    "block-rm-rf",
    "block-push-master",
    "sanitize-api-keys",
    "block-env-files"
  ],
  "policyParams": {
    "block-push-master": {
      "protectedBranches": ["main", "release", "hotfix"]
    }
  }
}