> ## Documentation Index
> Fetch the complete documentation index at: https://exosphere-auto-translate-docs-20260623-1106.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Bắt đầu
> Cài đặt failproofai, kích hoạt policies, 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 khi build từ source)
***
## Cài đặt
```bash npm theme={null}
npm install -g failproofai
```
```bash bun theme={null}
bun add -g failproofai
```
***
## Bắt đầu nhanh
Policies là những quy tắc chạy trước và sau mỗi lần agent gọi công cụ. Chúng bắt các lệnh có khả năng gây hủy hoại, rò rỉ bí mật, và các tình huống thất bại khác trước khi chúng gây ra thiệt hại.
```bash theme={null}
failproofai policies --install
```
Điều này ghi hook entries vào các agent CLIs đã cài đặt của bạn (tệp `~/.claude/settings.json` của Claude Code, `~/.codex/hooks.json` của OpenAI Codex, `~/.copilot/hooks/failproofai.json` của GitHub Copilot CLI, `~/.cursor/hooks.json` của Cursor Agent, plugin shim được tạo tại `~/.config/opencode/plugins/failproofai.mjs` của OpenCode cộng với entry đăng ký trong mảng `plugin` của `~/.config/opencode/opencode.json`, `~/.pi/agent/settings.json` của Pi, hoặc `~/.gemini/settings.json` của Gemini CLI). Khi có nhiều hơn một được cài đặt, bạn sẽ được hỏi; truyền `--cli claude codex copilot cursor opencode pi gemini` (bất kỳ subset nào) để bỏ qua lời nhắc.
Hỗ trợ cho GitHub Copilot CLI, Cursor Agent, OpenCode, Pi, và Gemini CLI là **beta** — cài đặt với `--cli copilot`, `--cli cursor`, `--cli opencode`, `--cli pi`, hoặc `--cli gemini`.
```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 gemini --scope project
failproofai policies --install block-sudo block-rm-rf sanitize-api-keys
```
```bash theme={null}
failproofai policies
```
Hiển thị mỗi policy, cho dù nó được kích hoạt hay không, và bất kỳ tham số nào được cấu hình.
```bash theme={null}
failproofai
```
Mở một bảng điều khiển cục bộ tại `http://localhost:8020` nơi bạn có thể duyệt phiên, kiểm tra các lệnh gọi công cụ, và quản lý policies.
Khởi chạy Claude Code như bình thường. Nếu agent cố gắng làm điều gì đó rủi ro, failproofai sẽ chặn nó tự động. Để nó chạy không tham dự và xem xét những gì đã xảy ra trên bảng điều khiển.
***
## Policies hoạt động như thế nào
Mỗi khi một agent chạy một công cụ, Claude Code gọi failproofai như một subprocess:
```text theme={null}
Claude Code → failproofai --hook PreToolUse → đọc JSON từ stdin
đánh giá policies
ghi quyết định vào stdout
```
Mỗi policy 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
Policies chạy trong quá trình cục bộ của bạn. Không có gì được gửi tới dịch vụ từ xa.
***
## Thiết lập team policies với convention-based policies
Cách nhanh nhất để thiết lập các tiêu chuẩn chất lượng trên toàn team là convention `.failproofai/policies/`. Thả các tệp policy vào thư mục này và chúng sẽ được tải tự động — không có flags, không có thay đổi config, không có lệnh cài đặt.
```bash theme={null}
mkdir -p .failproofai/policies
```
Sao chép các ví dụ khởi đầu hoặc viết 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 tệp 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("Chạy tests trước khi commit.");
}
return allow();
},
});
```
```bash theme={null}
git add .failproofai/policies/
git commit -m "Thêm team quality policies"
```
Mỗi thành viên trong team có failproofai được cài đặt sẽ tự động nhận các policies này. Không cần thiết lập cho từng developer.
Commit `.failproofai/policies/` vào repo của bạn để toàn bộ team chia sẻ các tiêu chuẩn giống nhau. Khi team của bạn phát hiện ra các tình huống thất bại mới, thêm policies 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 policies này trở thành một tiêu chuẩn chất lượng sống động luôn được cải thiện.
***
## Lưu trữ dữ liệu
Tất cả các cấu hình và logs vẫn ở trên máy của bạn:
| Đường dẫn | Nội dung lưu trữ |
| ----------------------------------------- | ------------------------------------ |
| `~/.failproofai/policies-config.json` | Cấu hình policy toàn cầu |
| `~/.failproofai/hook-activity.jsonl` | Lịch sử thực thi hook |
| `~/.failproofai/hook.log` | Debug log cho các lỗi hook tùy chỉnh |
| `.failproofai/policies-config.json` | Cấu hình cho mỗi dự án (committed) |
| `.failproofai/policies-config.local.json` | Overrides 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
Scopes và định dạng tệp config
Tất cả 26 policies với tham số
Viết policies của riêng bạn trong JavaScript
Giám sát phiên và xem xét hoạt động policy