Chuyển đến nội dung chính
failproofai sử dụng các tệp cấu hình JSON để kiểm soát các chính sách nào được kích hoạt, cách chúng hoạt động và nơi tải các chính sách tùy chỉnh. Cấu hình được thiết kế để dễ dàng chia sẻ với nhóm của bạn - cam kết nó vào repo của bạn và mỗi nhà phát triển sẽ nhận được cùng một lưới an toàn tác nhân.

​
Phạm vi cấu hình

Có ba phạm vi cấu hình, được đánh giá theo thứ tự ưu tiên:
Phạm viĐường dẫn tệpMục đích
project.failproofai/policies-config.jsonCài đặt trên mỗi repo, được cam kết vào kiểm soát phiên bản
local.failproofai/policies-config.local.jsonGhi đè cá nhân trên mỗi repo, được gitignore
global~/.failproofai/policies-config.jsonGiá trị mặc định ở cấp người dùng trên tất cả các dự án
Khi failproofai nhận một sự kiện hook, nó tải và hợp nhất cả ba tệp tồn tại cho thư mục làm việc hiện tại.

​
Quy tắc hợp nhất

enabledPolicies - hợp của tất cả ba phạm vi. Một chính sách được kích hoạt ở bất kỳ mức nào sẽ hoạt động. 
project:  ["block-sudo"]
local:    ["block-rm-rf"]
global:   ["block-sudo", "sanitize-api-keys"]

resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"]  ← loại bỏ trùng lặp
policyParams - phạm vi đầu tiên xác định các tham số cho một chính sách nào đó sẽ chiến thắng hoàn toàn. Không có hợp nhất sâu các giá trị trong tham số của một chính sách. 
project:  block-sudo → { allowPatterns: ["sudo apt-get update"] }
global:   block-sudo → { allowPatterns: ["sudo systemctl status"] }

resolved: { allowPatterns: ["sudo apt-get update"] }   ← project chiến thắng, global bị bỏ qua

project:  (không có mục block-sudo)
local:    (không có mục block-sudo)
global:   block-sudo → { allowPatterns: ["sudo systemctl status"] }

resolved: { allowPatterns: ["sudo systemctl status"] }  ← rơi xuống global
customPoliciesPath - phạm vi đầu tiên xác định nó sẽ chiến thắng. llm - phạm vi đầu tiên xác định nó sẽ chiến thắng.

​
Định dạng tệp cấu hình

{
  "enabledPolicies": [
    "block-sudo",
    "block-rm-rf",
    "block-push-master",
    "sanitize-api-keys",
    "sanitize-jwt",
    "block-env-files",
    "block-read-outside-cwd"
  ],
  "policyParams": {
    "block-sudo": {
      "allowPatterns": ["sudo systemctl status", "sudo journalctl"]
    },
    "block-push-master": {
      "protectedBranches": ["main", "release", "prod"]
    },
    "block-rm-rf": {
      "allowPaths": ["/tmp"]
    },
    "block-read-outside-cwd": {
      "allowPaths": ["/shared/data", "/opt/company"]
    },
    "sanitize-api-keys": {
      "additionalPatterns": [
        { "regex": "myco_[A-Za-z0-9]{32}", "label": "MyCo API key" }
      ]
    },
    "warn-large-file-write": {
      "thresholdKb": 512
    }
  },
  "customPoliciesPath": "/home/alice/myproject/my-policies.js"
}

​
Tham chiếu trường

​
enabledPolicies

Loại: string[] Danh sách tên chính sách cần bật. Tên phải khớp chính xác với các định danh chính sách được hiển thị bởi failproofai policies. Xem Chính sách tích hợp để có danh sách đầy đủ. Các chính sách không nằm trong enabledPolicies không hoạt động, ngay cả khi chúng có mục trong policyParams.

​
policyParams

Loại: Record<string, Record<string, unknown>> Ghi đè tham số cho mỗi chính sách. Khóa bên ngoài là tên chính sách; các khóa bên trong là khóa dành riêng cho chính sách. Mỗi chính sách ghi lại các tham số khả dụng của nó trong Chính sách tích hợp. Nếu một chính sách có các tham số nhưng bạn không chỉ định chúng, các giá trị mặc định tích hợp của chính sách sẽ được sử dụng. Người dùng không cấu hình policyParams sẽ nhận được hành vi giống hệt như các phiên bản trước đó. Các khóa không xác định bên trong khối tham số của một chính sách sẽ bị bỏ qua khi hook được kích hoạt nhưng được đánh dấu là cảnh báo khi bạn chạy failproofai policies.

​
hint (cross-cutting)

Loại: string (tùy chọn) Một thông điệp được thêm vào lý do khi một chính sách trả về deny hoặc instruct. Sử dụng nó để đưa ra hướng dẫn hành động cho Claude mà không cần sửa đổi chính sách. Hoạt động với bất kỳ loại chính sách nào — tích hợp, tùy chỉnh (custom/), quy ước dự án (.failproofai-project/), hoặc quy ước người dùng (.failproofai-user/). 
{
  "policyParams": {
    "block-force-push": {
      "hint": "Try creating a fresh branch instead."
    },
    "block-sudo": {
      "allowPatterns": ["sudo apt-get"],
      "hint": "Use apt-get directly without sudo."
    },
    "custom/my-policy": {
      "hint": "Ask the user for approval first."
    }
  }
}
Khi block-force-push từ chối, Claude sẽ thấy: “Force-pushing is blocked. Try creating a fresh branch instead.” Các giá trị không phải chuỗi và chuỗi rỗng sẽ bị bỏ qua. Nếu hint không được đặt, hành vi không thay đổi (tương thích ngược).

​
customPoliciesPath

Loại: string (đường dẫn tuyệt đối) Đường dẫn đến tệp JavaScript chứa các chính sách hook tùy chỉnh. Điều này được đặt tự động bởi failproofai policies --install --custom <path> (đường dẫn được giải quyết thành tuyệt đối trước khi được lưu trữ). Tệp được tải mới trên mỗi sự kiện hook - không có lưu cache. Xem Chính sách tùy chỉnh để biết chi tiết tác giả.

​
Chính sách dựa trên quy ước

Ngoài customPoliciesPath rõ ràng, failproofai tự động phát hiện và tải các tệp chính sách từ thư mục .failproofai/policies/:
MứcThư mụcPhạm vi
Dự án.failproofai/policies/Chia sẻ với nhóm qua kiểm soát phiên bản
Người dùng~/.failproofai/policies/Cá nhân, áp dụng cho tất cả các dự án
Khớp tệp: Chỉ các tệp khớp *policies.{js,mjs,ts} được tải (ví dụ: security-policies.mjs, workflow-policies.js). Các tệp khác trong thư mục sẽ bị bỏ qua. Không cần cấu hình: Chính sách quy ước không yêu cầu mục nhập trong policies-config.json. Chỉ cần thả các tệp vào thư mục và chúng sẽ được nhận trên sự kiện hook tiếp theo. Tải kết hợp: Cả thư mục quy ước dự án và người dùng đều được quét. Tất cả các tệp phù hợp từ cả hai mức được tải (không giống như customPoliciesPath sử dụng first-scope-wins). Xem Chính sách tùy chỉnh để biết thêm chi tiết và ví dụ.

​
llm

Loại: object (tùy chọn) Cấu hình máy khách LLM cho các chính sách thực hiện các lệnh gọi AI. Không bắt buộc đối với hầu hết các thiết lập. 
{
  "llm": {
    "model": "claude-sonnet-4-6",
    "apiKey": "sk-ant-..."
  }
}

​
Quản lý cấu hình từ CLI

Các lệnh policies --install và policies --uninstall ghi vào settings.json của Claude Code (các điểm vào hook), trong khi policies-config.json là tệp bạn quản lý trực tiếp. Hai cái này là riêng biệt:
  • settings.json - yêu cầu Claude Code gọi failproofai --hook <event> trên mỗi lần sử dụng công cụ
  • policies-config.json - yêu cầu failproofai đánh giá chính sách nào và với những tham số nào
Bạn có thể chỉnh sửa policies-config.json trực tiếp bất kỳ lúc nào; các thay đổi có hiệu lực ngay trên sự kiện hook tiếp theo mà không cần khởi động lại.

​
Ví dụ: cấu hình cấp dự án với giá trị mặc định nhóm

Cam kết .failproofai/policies-config.json vào repo của bạn: 
{
  "enabledPolicies": [
    "block-sudo",
    "block-rm-rf",
    "block-push-master",
    "sanitize-api-keys",
    "block-env-files"
  ],
  "policyParams": {
    "block-push-master": {
      "protectedBranches": ["main", "release", "hotfix"]
    }
  }
}
Mỗi nhà phát triển sau đó có thể tạo .failproofai/policies-config.local.json (được gitignore) cho các ghi đè cá nhân mà không ảnh hưởng đến đồng nghiệp.