> ## Documentation Index
> Fetch the complete documentation index at: https://docs.befailproof.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 快速开始

> 安装 failproofai，启用策略，让你的 Agent 稳定可靠地运行

## 环境要求

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

***

## 安装

<CodeGroup>
  ```bash npm theme={null}
  npm install -g failproofai
  ```

  ```bash bun theme={null}
  bun add -g failproofai
  ```
</CodeGroup>

***

## 快速上手

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

    ```bash theme={null}
    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` 安装用户级作用域，同时也是一个**离线**审计数据源。

    ```bash theme={null}
    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
    ```
  </Step>

  <Step title="验证安装">
    ```bash theme={null}
    failproofai policies
    ```

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

  <Step title="启动控制台">
    ```bash theme={null}
    failproofai
    ```

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

  <Step title="运行你的 Agent">
    像往常一样启动 Claude Code。如果 Agent 尝试执行危险操作，failproofai 会自动拦截。可以让它在无人值守的情况下运行，之后在控制台中查看执行情况。
  </Step>
</Steps>

***

## 策略的工作原理

每当 Agent 执行一个工具时，Claude Code 会将 failproofai 作为子进程调用：

```text theme={null}
Claude Code  →  failproofai --hook PreToolUse  →  reads stdin JSON
                                                 evaluates policies
                                                 writes decision to stdout
```

每条策略会返回以下三种决策之一：

* **allow** - Agent 正常继续执行
* **deny** - 操作被拦截，Agent 会收到拦截原因说明
* **instruct** - 向 Agent 的提示词中添加额外的上下文信息

<Note>
  策略在你的本地进程中运行，不会向任何远程服务发送数据。
</Note>

***

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

在团队中快速统一质量标准的最佳方式是使用 `.failproofai/policies/` 约定。只需将策略文件放入该目录，它们便会自动加载 — 无需任何额外参数、配置修改或安装命令。

<Steps>
  <Step title="创建策略目录">
    ```bash theme={null}
    mkdir -p .failproofai/policies
    ```
  </Step>

  <Step title="添加策略文件">
    复制内置的示例文件，或自己编写：

    ```bash theme={null}
    cp node_modules/failproofai/examples/convention-policies/*.mjs .failproofai/policies/
    ```

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

    ```js theme={null}
    // .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();
      },
    });
    ```
  </Step>

  <Step title="提交到 git">
    ```bash theme={null}
    git add .failproofai/policies/
    git commit -m "Add team quality policies"
    ```

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

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

***

## 数据存储

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

| 路径                                        | 存储内容                     |
| ----------------------------------------- | ------------------------ |
| `~/.failproofai/policies-config.json`     | 全局策略配置                   |
| `~/.failproofai/hook-activity.jsonl`      | Hook 执行历史记录              |
| `~/.failproofai/hook.log`                 | 自定义 hook 错误调试日志          |
| `.failproofai/policies-config.json`       | 项目级配置（可提交至版本库）           |
| `.failproofai/policies-config.local.json` | 个人本地覆盖配置（已加入 .gitignore） |

***

## 卸载

```bash theme={null}
failproofai policies --uninstall
```

从 `~/.claude/settings.json` 中移除 hook 条目。`~/.failproofai/` 中的配置文件将被保留。

***

## 下一步

<CardGroup cols={2}>
  <Card title="配置说明" icon="gear" href="/zh/configuration">
    作用域与配置文件格式
  </Card>

  <Card title="内置策略" icon="shield" href="/zh/built-in-policies">
    全部 26 条策略及其参数说明
  </Card>

  <Card title="自定义策略" icon="code" href="/zh/custom-policies">
    使用 JavaScript 编写你自己的策略
  </Card>

  <Card title="Agent 监控" icon="chart-line" href="/zh/dashboard">
    监控会话并查看策略活动记录
  </Card>
</CardGroup>