Guardrails theo tầng
Trang này cho bạn biết vì sao một thao tác bị Guardrails chặn, ai quyết định luật nào, và gửi phản hồi ở đâu khi bị chặn nhầm. Trang chỉ nói nguyên tắc, không liệt kê chi tiết từng luật.
Guardrails làm gì
Guardrails là lớp an toàn khi dùng Claude Code trên mã nguồn thật. Nó giữ cho secret và dữ liệu cá nhân không tới model, không để dữ liệu bị đẩy ra ngoài, và ghi nhật ký đã che cho mọi quyết định. Cách làm việc hằng ngày của bạn không đổi.
Guardrails kiểm tra ở bốn thời điểm. Khi bạn gửi prompt, nó có thể chặn hoặc ghi nhận. Khi agent chuẩn bị gọi một tool, nó có thể chặn, hỏi lại bạn hoặc ghi nhận. Khi tool chạy xong, nó che nội dung nhạy cảm trong kết quả trước khi kết quả tới model. Lúc phiên bắt đầu và kết thúc, nó chỉ ghi nhận.
Ba thành phần, không thêm dịch vụ mới
Luật là dữ liệu. Luật nằm trong gói policy chứ không viết cứng trong mã, và bộ máy chung không biết trước mẫu nào cả.
Policy là một tài nguyên trên Tara. Đó là một kit có khai báo metadata.forge.guardrails, nên cũng qua kiểm tra, duyệt, ký số, thu hồi và khóa version như mọi tài nguyên khác. Phần này nằm ở trang Khóa version và chữ ký số.
Hook server chạy trong Phillip, ngay trên máy bạn. Claude Code gọi nó qua managed settings, nó tải policy từ Tara rồi quyết định và ghi nhật ký tại chỗ. Chỉ quản trị máy mới cài được, bằng sudo ph guardrails install.
Ba tầng policy
Tầng nền tảng là mức sàn. Platform staff của PhillipCLI soạn tầng này, và nó áp dụng cho mọi máy cài Guardrails. Tầng tổ chức do Admin của tổ chức đặt, áp dụng cho mọi project của tổ chức. Tầng project do Project admin đặt, chỉ áp dụng cho một project, và gắn vào phillip.lock của project đó.
Nguyên tắc cốt lõi là mỗi tầng chỉ được siết thêm so với tầng trên. Nền tảng đặt mức sàn, còn tổ chức và project tự thêm luật siết của mình, không cần ai duyệt. Muốn nới một luật thì phải xin ngoại lệ riêng (luật allow), do platform staff duyệt và ghi vào audit log, có lý do và có hạn. Trên Portal, bạn xem ba tầng và policy đang áp dụng ở Cài đặt, Guardrails policy. Policy là gói kit gửi lên như tài nguyên khác, với metadata.forge.guardrails.level là platform, organization hoặc project (policy project ghi thêm key project ở project). Giá trị cũ company vẫn đọc được: là platform trong kho chính thức, còn lại là organization.
Vuốt ngang để xem hết sơ đồ.
Các tầng ghép với nhau ra sao
Hook server gom luật của mọi tầng áp dụng cho dự án bạn đang làm, bỏ những luật đã được một ngoại lệ còn hạn miễn trừ, rồi lấy hành động chặt nhất theo thứ tự chặn, hỏi lại, che, ghi nhận.
Nhờ vậy policy project không bao giờ làm mất luật của nền tảng. Nếu bạn gỡ policy dự án khỏi phillip.lock thì chỉ mất phần siết thêm, mức sàn vẫn còn, và việc gỡ này phải qua code review.
Ai duyệt policy nào
Policy chỉ siết thêm thì không qua bước duyệt nào, qua bộ quét tự động là có hiệu lực ngay:
- Nền tảng: chỉ platform staff đăng, vào kho chính thức (
aiforge/). - Tổ chức: Owner hoặc Admin của tổ chức đăng, bất kể tổ chức cho ai được đăng.
- Project: Project admin của đúng project đó, hoặc Owner, Admin của tổ chức đăng.
Gói có luật allow là nới mức sàn, tức ngoại lệ. Gói này chờ ở hàng đợi Platform (Cài đặt, Platform review), chỉ platform staff duyệt được, và Tara ghi audit cả khi gửi lẫn khi quyết định. Không ai tự duyệt bài của mình.
Khi kiểm tra, Tara tự phân loại gói là siết hay nới. Trước khi gửi, bạn kiểm một gói policy bằng lệnh sau.
ph guardrails check ./kit-policy-du-anĐể một repo dùng policy của dự án, bạn gắn thư mục với dự án bằng ph project use <key>. Lệnh này ghi .phillip/project.json, bạn commit tệp đó để cả nhóm dùng chung một dự án. Phillip sẽ nạp tầng dự án cùng với tầng tổ chức và tầng nền tảng. Muốn biết thư mục đang dùng dự án nào, chạy ph project current.
Khi hệ thống hỏng thì sao?
Guardrails đóng cửa khi lỗi (fail-closed). Nếu hook server dừng, hoặc chưa từng nạp được policy nền tảng hợp lệ, Claude Code chặn prompt và tool call chứ không cho qua. Policy dự án không kiểm được, chẳng hạn chữ ký sai hoặc đã bị thu hồi, thì chỉ chặn trong dự án đó. Gói policy nào cũng phải qua kiểm tra chữ ký và danh sách thu hồi như các tài nguyên khác.
Nhật ký và dữ liệu
Nhật ký chạy trên máy bạn và đã che secret. Bạn xem thêm ở trang Audit. Mỗi lần chặn, hỏi lại hay che, Guardrails gửi về Ryoma một sự kiện chỉ có metadata gồm mã luật, quyết định, mức độ, repo và mã task, không có nội dung. Chi tiết ở Dữ liệu thu thập. Kho nhật ký chi tiết của tổ chức, cũng đã che, được tắt mặc định cho tới khi bộ phận pháp chế duyệt.
Bị chặn thì làm gì?
Thông báo chặn có mã luật và lý do. Trước hết hãy đọc lý do, vì phần lớn trường hợp thao tác đó thật sự không nên làm và bạn chỉ cần đổi cách làm. Nếu nghĩ luật chặn nhầm, bạn gửi phản hồi kèm mã luật.
ph guardrails feedback <mã-luật> --note "Vì sao việc này hợp lệ"Phản hồi được che trước khi gửi và tới Security trong vài phút. Sửa luật nghĩa là phát hành version mới của gói policy, và máy bạn nạp bản mới trong khoảng 15 phút. Nếu cần ngoại lệ tạm cho một dự án, bạn nhờ lead soạn ngoại lệ có hạn trong policy dự án. Các bước xử lý cụ thể nằm ở Khi bị Guardrails chặn.
Guardrails không làm được gì
Guardrails không ngăn được người có quyền quản trị máy cố tình vượt qua. Phần đó thuộc về quản trị thiết bị, tường lửa và quy định nội bộ.
Hook server chạy bằng quyền của người dùng. Guardrails có cơ chế tự bảo vệ và báo khi hook server không chạy (xem ph guardrails status và ph forge doctor), nhưng không thay được tường lửa hay proxy. Việc nhận ra đích mạng trong lệnh shell cũng chỉ là suy đoán, không phải rào chắn mạng thật.