> ## 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.

# Bắt đầu

> Cài đặt failproofai, bật các chính sách, và để agents của bạn chạy một cách đáng tin cậy

## Yêu cầu

* **Node.js** >= 20.9.0
* **Bun** >= 1.3.0 (tùy chọn - chỉ cần thiết để build từ nguồn)

***

## Cài đặt

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

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

***

## Bắt đầu nhanh

<Steps>
  <Step title="Bật các chính sách">
    Chính sách là những quy tắc chạy trước và sau mỗi lần agent gọi tool. Chúng bắt các lệnh phá hủy, rò rỉ bí mật, và những chế độ lỗi khác trước khi chúng gây thiệt hại.

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

    Lệnh này ghi các hook entries vào CLI agents đã cài đặt của bạn (Claude Code's `~/.claude/settings.json`, OpenAI Codex's `~/.codex/hooks.json`, GitHub Copilot CLI's `~/.copilot/hooks/failproofai.json`, Cursor Agent's `~/.cursor/hooks.json`, OpenCode's generated plugin shim at `~/.config/opencode/plugins/failproofai.mjs` plus a registration entry in `~/.config/opencode/opencode.json`'s `plugin` array, Pi's `~/.pi/agent/settings.json`, or Hermes's `~/.hermes/config.yaml`). Khi có nhiều hơn một cái có mặt, bạn sẽ được nhắc; truyền `--cli claude codex copilot cursor opencode pi hermes` (bất kỳ tập hợp con nào) để bỏ qua lời nhắc.

    GitHub Copilot CLI, Cursor Agent, OpenCode, và Pi support là **beta** — cài đặt với `--cli copilot`, `--cli cursor`, `--cli opencode`, hoặc `--cli pi`. Hermes (hermes-agent, một gateway Slack/Telegram) cài đặt user-scope với `--cli hermes` và là **cũng** một nguồn audit offline.

    ```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="Xác minh">
    ```bash theme={null}
    failproofai policies
    ```

    Hiển thị mỗi chính sách, xem nó có được bật hay không, và bất kỳ tham số nào được cấu hình.
  </Step>

  <Step title="Khởi chạy dashboard">
    ```bash theme={null}
    failproofai
    ```

    Mở dashboard cục bộ tại `http://localhost:8020` nơi bạn có thể duyệt các phiên, kiểm tra các tool calls, và quản lý chính sách.
  </Step>

  <Step title="Chạy agent của bạn">
    Khởi động Claude Code như bình thường. Nếu agent thử một điều gì đó rủi ro, failproofai sẽ chặn nó tự động. Để nó chạy không cần giám sát và xem xét những gì đã xảy ra trong dashboard.
  </Step>
</Steps>

***

## Cách các chính sách hoạt động

Mỗi khi một agent chạy một tool, Claude Code gọi failproofai như một subprocess:

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

Mỗi chính sách trả về một trong ba quyết định:

* **allow** - agent tiếp tục bình thường
* **deny** - hành động bị chặn, agent được thông báo lý do
* **instruct** - ngữ cảnh bổ sung được thêm vào prompt của agent

<Note>
  Các chính sách chạy trong quy trình cục bộ của bạn. Không có gì được gửi đến dịch vụ từ xa.
</Note>

***

## Thiết lập chính sách nhóm với chính sách dựa trên quy ước

Cách nhanh nhất để thiết lập tiêu chuẩn chất lượng trên toàn nhóm của bạn là quy ước `.failproofai/policies/`. Thả các tệp chính sách vào thư mục này và chúng sẽ được tải tự động — không có flag, không có thay đổi config, không có lệnh cài đặt.

<Steps>
  <Step title="Tạo thư mục chính sách">
    ```bash theme={null}
    mkdir -p .failproofai/policies
    ```
  </Step>

  <Step title="Thêm các tệp chính sách">
    Sao chép các ví dụ khởi động hoặc viết chính sách của riêng bạn:

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

    Hoặc tạo một cái mới:

    ```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="Commit vào git">
    ```bash theme={null}
    git add .failproofai/policies/
    git commit -m "Add team quality policies"
    ```

    Mỗi thành viên nhóm có failproofai được cài đặt sẽ nhận các chính sách này tự động. Không cần thiết lập cho từng nhà phát triển.
  </Step>
</Steps>

<Tip>
  Commit `.failproofai/policies/` vào repo của bạn để toàn bộ nhóm chia sẻ các tiêu chuẩn giống nhau. Khi nhóm của bạn phát hiện ra các chế độ lỗi mới, hãy thêm chính sách và push — mọi người sẽ nhận được cập nhật trên lần `git pull` tiếp theo của họ. Theo thời gian, những chính sách này trở thành một tiêu chuẩn chất lượng sống động, liên tục cải thiện.
</Tip>

***

## Lưu trữ dữ liệu

Tất cả cấu hình và log vẫn ở trên máy tính của bạn:

| Đường dẫn                                 | Lưu trữ những gì                      |
| ----------------------------------------- | ------------------------------------- |
| `~/.failproofai/policies-config.json`     | Cấu hình chính sách toàn cầu          |
| `~/.failproofai/hook-activity.jsonl`      | Lịch sử thực thi hook                 |
| `~/.failproofai/hook.log`                 | Log gỡ lỗi cho lỗi hook tùy chỉnh     |
| `.failproofai/policies-config.json`       | Cấu hình trên mỗi dự án (được commit) |
| `.failproofai/policies-config.local.json` | Ghi đè cá nhân (gitignored)           |

***

## Gỡ cài đặt

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

Xóa hook entries từ `~/.claude/settings.json`. Các tệp config trong `~/.failproofai/` được giữ lại.

***

## Bước tiếp theo

<CardGroup cols={2}>
  <Card title="Configuration" icon="gear" href="/vi/configuration">
    Phạm vi và định dạng tệp config
  </Card>

  <Card title="Built-in policies" icon="shield" href="/vi/built-in-policies">
    Tất cả 26 chính sách với tham số
  </Card>

  <Card title="Custom policies" icon="code" href="/vi/custom-policies">
    Viết các chính sách riêng của bạn trong JavaScript
  </Card>

  <Card title="Agent monitor" icon="chart-line" href="/vi/dashboard">
    Giám sát các phiên và xem xét hoạt động chính sách
  </Card>
</CardGroup>