Failproof AI CLI

使用 npm install -g failproofai 安装本地 CLI。不带任何参数运行将打开本地策略仪表板。此软件包需要 Node.js 20.9 或更高版本。开发和源码安装支持 Bun 1.3 或更高版本。failproofai configure 和 failproofai setup 是 failproofai config 的别名；failproofai p 是 failproofai policies 的别名。

配置一台机器

npm install -g failproofai
failproofai config \
  --connect https://app.befailproof.ai \
  --token <machine-key> \
  --machine-label checkout-prod-01
failproofai policies --install
failproofai config --status

不带参数运行 failproofai 可打开本地策略仪表板。

命令	功能说明
`failproofai config`	运行交互式机器配置
`failproofai config --connect <url> --token <key>`	连接云端数据采集和策略下发
`failproofai config --status`	显示连接、守护进程、下发及暂停状态
`failproofai policies`	列出内置、自定义、约定、扩展包及云端托管策略
`failproofai policies --install`	安装钩子并启用策略
`failproofai policy add <name>`	启用单条策略——内置策略或已安装扩展包中的 `<pack-id>:<name>`
`failproofai policy remove <name>`	禁用单条策略，命名规则相同
`failproofai policies --uninstall`	禁用策略或移除挂载钩子
`failproofai pack list`	列出已安装的策略包及其包含的所有策略
`failproofai pack add <source>`	从 GitHub Release 安装策略包；不指定标签则使用最新版本并固定
`failproofai pack add --bundled`	从本软件包安装内置策略包，无需网络
`failproofai pack build <entry.mjs>`	为自定义策略包构建三个发布产物
`failproofai pack remove <publisher/name>`	停用已安装的策略包
`failproofai audit`	扫描本地 Agent 历史记录并打开本地审计视图
`failproofai audit --schedule [days] --email <address>`	定期安排本地扫描并将结果发送至邮件地址
`failproofai audit --status`	显示报告邮箱、周期及下次计划扫描时间
`failproofai audit --no-schedule`	停止定期扫描但不删除审计历史记录
`failproofai harness list`	列出额外的捕获路径
`failproofai flush --wait`	立即投递当前事件队列
`failproofai backfill --since 30d`	重新读取此前已处理的历史记录
`failproofai config --pause [duration]`	暂停当前本地会话，默认 30 分钟，最长 8 小时
`failproofai config --resume`	恢复已暂停的本地会话；加 `--all` 可清除所有暂停
`failproofai update`	完成包迁移并更新守护进程
`failproofai migrate --dry-run`	预览或执行待处理的 home 目录布局迁移
`failproofai uninstall`	在移除软件包前卸载钩子和守护进程
`failproofai --version`	打印已安装的软件包版本
`failproofai --help`	显示命令及全局用法

配置标志

标志	用途
`--connect <url> --token <key>`	非交互式连接
`--machine-id <id>`	设置稳定的机器 ID
`--machine-label <name>`	设置或修改仪表板标签
`--no-transcripts`	仅发送决策结果，不包含会话内容
`--disconnect`	停止云端策略拉取和事件投递
`--status`	显示当前机器状态
`--pause [duration]`	暂停当前目录中最新的会话；接受秒、分钟或小时为单位，默认 30 分钟
`--resume`	提前结束匹配的暂停
`--session <id>`	为暂停或恢复指定明确的会话
`--all`	配合 `--resume` 使用，结束所有活跃的暂停

本地暂停会针对单个会话暂停内置、自定义、约定及扩展包策略。暂停始终会过期，且不会禁用云端托管策略。block-failproofai-commands——始终开启且本身无法被禁用或暂停——可防止被监控的 Agent 自行利用此逃脱通道。

策略标志

标志	用途
`--install`, `-i`	启用策略并安装挂载钩子
`--uninstall`, `-u`	禁用策略或移除钩子
`--cli <names...>`	指定一个或多个支持的挂载目标
`--scope user\|project\|local\|all`	选择配置作用域；`all` 用于卸载
`--beta`	包含测试版策略
`--custom`, `-c <path>`	验证并加载自定义策略文件；可重复使用

数据投递与维护标志

命令	标志
`backfill`	`--since <30d\|6m\|YYYY-MM-DD>`, `--dry-run`
`flush`	`--wait`, `--timeout <seconds>`
`update`	`--no-daemon`
`migrate`	`--dry-run`
`uninstall`	`--purge`, `--dry-run`, `--yes`

failproofai update 应在执行 npm install -g failproofai@latest 后运行；它会执行 home 目录布局迁移、安装匹配的守护进程二进制文件并重启服务。--no-daemon 仅执行布局迁移。

挂载路径

failproofai harness list [harness]
failproofai harness add-path <harness> [label=]<path>
failproofai harness remove-path <harness> <path-or-label>

支持的挂载目标名称包括 claude、codex、copilot、cursor、opencode、pi、hermes、openclaw、factory、devin、antigravity 和 goose。当两个根目录包含同一项目的副本时，标签用于区分派生的 Agent ID 命名空间。系统会拒绝重叠的根目录和重复标签，以防止重复采集或游标损坏。额外路径配置无需重启守护进程即可重新加载。容器环境可使用以逗号分隔的变量 FAILPROOFAI_<HARNESS>_EXTRA_PATHS 替代文件配置的额外路径，例如：

export FAILPROOFAI_OPENCLAW_EXTRA_PATHS="user1=/srv/openclaw-a,user2=/srv/openclaw-b"

环境变量

持久化机器行为请使用配置文件。环境变量最适合用于容器、测试和单进程场景。

变量	用途
`FAILPROOFAI_HOME`	重新定位完整的 `~/.failproofai` 目录布局
`FAILPROOFAI_LOG_LEVEL`	设置本地日志详细级别
`FAILPROOFAI_HOOK_LOG_FILE`	将钩子诊断信息写入指定文件
`FAILPROOFAI_TELEMETRY_DISABLED=1`	为当前进程禁用匿名遥测
`FAILPROOFAI_NO_FIRST_RUN=1`	跳过交互式首次运行配置
`FAILPROOFAI_NO_AUTO_AUDIT=1`	跳过配置后的本地自动审计
`FAILPROOFAI_LLM_BASE_URL`	覆盖 LLM 策略使用的 OpenAI 兼容端点
`FAILPROOFAI_LLM_API_KEY`	提供 LLM 策略使用的 API 密钥
`FAILPROOFAI_LLM_MODEL`	选择 LLM 策略使用的模型
`FAILPROOFAI_POLICY_LOAD_TIMEOUT_MS`	限制自定义策略模块的加载超时时间
`FAILPROOFAI_NO_DOWNLOAD=1`	拒绝获取策略包和守护进程二进制文件；已安装的内容继续生效
`FAILPROOFAI_PACK_BASE_URL`	从镜像站点而非 `github.com` 获取策略包
`FAILPROOFAI_<HARNESS>_EXTRA_PATHS`	替换指定挂载目标已配置的额外捕获路径
`NO_COLOR`	禁用终端彩色输出

Agent 专属的 home 变量（如 CLAUDE_PROJECTS_PATH、CURSOR_HOME、HERMES_HOME 和 OPENCLAW_HOME）会覆盖 Failproof AI 发现该挂载目标本地会话的路径。

安全地暂停或移除机器

failproofai config --pause
failproofai config --status
failproofai config --resume

本地会话暂停不会禁用云端托管策略。若问题出在发布流程本身，请通过云端强制执行工作流恢复云端部署。移除 npm 软件包之前，请先卸载已安装的钩子和守护进程：

failproofai uninstall --dry-run
failproofai uninstall --yes
npm rm -g failproofai

运行 failproofai <command> --help 可查看特定版本的详细说明。

请在执行 npm rm -g failproofai 之前先运行 failproofai uninstall；npm 不会自动移除已安装的 Agent 钩子或守护进程服务。

Connect your agents

Reference

配置一台机器

配置标志

策略标志

数据投递与维护标志

挂载路径

环境变量

安全地暂停或移除机器

​配置一台机器

​配置标志

​策略标志

​数据投递与维护标志

​挂载路径

​环境变量

​安全地暂停或移除机器

配置一台机器

配置标志

策略标志

数据投递与维护标志

挂载路径

环境变量

安全地暂停或移除机器