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

npm

npm install -g failproofai

bun add -g failproofai

---

​

Bắt đầu nhanh

1. Kích hoạt policies

   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.

   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.

   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
   
2. Xác minh

   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.

3. Khởi chạy bảng điều khiển

   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.

4. Chạy agent của bạn

   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:

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.

1. Tạo thư mục policies

   mkdir -p .failproofai/policies
   
2. Thêm tệp policies

   Sao chép các ví dụ khởi đầu hoặc viết của riêng bạn:

   cp node_modules/failproofai/examples/convention-policies/*.mjs .failproofai/policies/
   

   Hoặc tạo một tệp mới:

   // .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();
     },
   });
   
3. Commit vào git

   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

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

Configuration

Scopes và định dạng tệp config

Built-in policies

Tất cả 26 policies với tham số

Custom policies

Viết policies của riêng bạn trong JavaScript

Agent monitor

Giám sát phiên và xem xét hoạt động policy