Chuyển đến nội dung chính
Agent Firewall được cấu hình theo hai cách: qua console (phiên của bạn, cùng đăng nhập bạn dùng cho dashboard) và qua gateway (một API key firewall-scoped chuyên dụng mà agent của bạn trình ra lúc runtime). Hai họ này sống ở các tiền tố path khác nhau, dùng auth khác nhau, và trả lời các câu hỏi khác nhau — “sửa chính sách” so với “đánh giá cuộc gọi tool này.” Trang này là bản đồ theo từng route của cả hai. Về việc chính sách có nghĩa gì — verdict, bề mặt, quy tắc, phân giải — hãy bắt đầu ở Firewall và Quy tắc firewall. Trang này chỉ là bề mặt API.

​
1. Hai họ route

Console — cấu hình

/api/workspace/firewall/*. Xác thực bằng session / access token của bạn (UserAuth), scope theo workspace đang hoạt động. Soạn chính sách, đọc event, đăng ký MCP server, giải quyết phê duyệt. Mọi hành động đều được gate theo vai trò.

Gateway — thực thi

/api/v1/firewall/*. Xác thực bằng một key firewall-gateway-scoped (một key có đặt is_firewall_gateway). Bề mặt máy-tới-máy mà agent hoặc MCP client của bạn gọi lúc runtime. Một relay key thường nhận 403 ở đây.
Các route console không bao giờ nhận một relay key sk-orca-…, và các route gateway không bao giờ nhận một session token. Lẫn lộn chúng là lỗi 401/403 phổ biến nhất khi nối firewall lần đầu. Key sk-orca-… duy nhất thuộc về một cuộc gọi /v1/firewall/* là một key được đúc với is_firewall_gateway bật — xem Scope, key & chính sách.

​
2. Vai trò trong nháy mắt

Các route console phân giải vai trò workspace của bạn và gate tương ứng. Các thao tác đọc không mang provenance cuộc gọi tool đều mở cho mọi thành viên; ghi và bất cứ thứ gì phơi bày argument cuộc gọi tool đều yêu cầu Developer+.
Vai tròCó thể làm gì
Viewer / thành viênĐọc settings, chính sách, preset, discovered tools, simulate, anomaly.
Developer+Tất cả những điều trên, cộng với mọi thao tác ghi, bề mặt events/runs/trace, và dry-run test.
Admin+Bổ sung, đặt cờ is_firewall_gateway trên một key và đọc plaintext của một gateway key.
Sự phân tách là có chủ đích: một viewer có thể thấy rằng một chính sách tồn tại và nó sẽ chặn gì, nhưng không thấy argument cuộc gọi tool thô đằng sau một event. Nếu bạn đang dựng dashboard cho người không phải developer, các route mở-đọc là tập an toàn.

​
3. Cấu hình một chính sách từ console

Các route console là cách bạn soạn và kiểm tra chính sách. Bạn cấu hình mọi thứ trong UI dashboard — đây chính là các endpoint mà nó gọi.

​
Chính sách & settings

Method & pathVai tròMục đích
GET /api/workspace/firewall/settingsMemberObserve-mode + số đếm.
PUT /api/workspace/firewall/settingsDeveloper+Cập nhật settings firewall của workspace.
GET /api/workspace/firewall/policiesMemberLiệt kê chính sách.
GET /api/workspace/firewall/policies/:idMemberChi tiết một chính sách.
POST /api/workspace/firewall/policiesDeveloper+Tạo một chính sách.
PUT /api/workspace/firewall/policiesDeveloper+Cập nhật một chính sách.
DELETE /api/workspace/firewall/policies/:idDeveloper+Xóa một chính sách.
POST /api/workspace/firewall/rulesDeveloper+Thêm một quy tắc.
PUT /api/workspace/firewall/rulesDeveloper+Cập nhật một quy tắc.
DELETE /api/workspace/firewall/rules/:idDeveloper+Xóa một quy tắc.

​
Tư thế, preset & sandbox

Method & pathVai tròMục đích
GET /api/workspace/firewall/presetsMemberCác preset quy tắc dựng sẵn.
GET /api/workspace/firewall/templatesMemberThư viện template theo use-case.
POST /api/workspace/firewall/templates/applyDeveloper+Áp dụng một template → một chính sách + các quy tắc của nó.
POST /api/workspace/firewall/autonomyDeveloper+Áp dụng một autonomy level (tight / balanced / permissive).
POST /api/workspace/firewall/autonomy/undo/:audit_idDeveloper+Hoàn tác một cú nhấp từ snapshot audit.
GET /api/workspace/firewall/simulateMemberMột level sẽ chặn gì (?level=).
POST /api/workspace/firewall/testDeveloper+Dry-run một chính sách đối với một cuộc gọi mẫu.

​
Khả năng quan sát

Method & pathVai tròMục đích
GET /api/workspace/firewall/discovered-toolsMemberCác tool đã thấy, gắn cờ covered / gap.
GET /api/workspace/firewall/eventsDeveloper+Liệt kê firewall event (lọc được).
GET /api/workspace/firewall/events/by-request/:request_idDeveloper+Event cho một request.
GET /api/workspace/firewall/events/aggregateDeveloper+Rollup runs / sessions.
GET /api/workspace/firewall/trace/by-runDeveloper+Các node trace cho một run (?run_id=).
GET /api/workspace/firewall/anomaliesMemberFeed bất thường.
POST /api/workspace/firewall/anomalies/snoozeDeveloper+Tạm tắt feed (≤ 7 ngày).

​
MCP server

Đăng ký các Model Context Protocol server mà agent của bạn vươn tới, đằng sau một gateway được audit duy nhất. Credential được lưu mã hóa và che (mask) khi đọc.
Method & pathVai tròMục đích
GET /api/workspace/firewall/mcp_serversMemberLiệt kê các server đã đăng ký.
GET /api/workspace/firewall/mcp_servers/:idMemberChi tiết server.
POST /api/workspace/firewall/mcp_serversDeveloper+Đăng ký một server (409 nếu name trùng).
PUT /api/workspace/firewall/mcp_serversDeveloper+Cập nhật một server.
DELETE /api/workspace/firewall/mcp_servers/:idDeveloper+Gỡ một server.
POST /api/workspace/firewall/mcp_servers/:id/probeDeveloper+Handshake khả tiếp cận + tools/list.
Một server mang một name duy nhất, một endpoint, một auth_mode (none / bearer / oauth / basic), và một status sức khỏe (ok / degraded / down). Xem Firewall MCP để biết vòng đời đầy đủ và việc cách ly skill.

​
4. Thực thi tại gateway

Những route này chạy trên một key firewall-gateway-scoped, không phải phiên của bạn. Chúng là những gì vòng lặp agent hoặc MCP client của bạn gọi lúc runtime.
Method & pathMục đích
POST /api/v1/firewall/evaluateVerdict trước-dispatch cho một cuộc gọi tool.
POST /api/v1/firewall/evaluate_planKiểm tra trước-thực-thi cho một plan nhiều bước.
ANY /api/v1/firewall/mcpEndpoint MCP gateway hợp nhất.
GET /api/v1/firewall/mcp_serversLiệt kê các server đã đăng ký của workspace.
GET /api/v1/firewall/approvals/:idPoll trạng thái phê duyệt của một cuộc gọi đã giữ.
POST /api/v1/firewall/approvals/:id/callbackCallback phê duyệt ký HMAC.

​
Một ví dụ cụ thể: đánh giá một cuộc gọi tool

Trước khi agent của bạn dispatch một tool, hãy hỏi gateway một verdict. Truyền key firewall-gateway-scoped — không phải relay key sk-orca-… của bạn: 
curl https://api.orcarouter.ai/api/v1/firewall/evaluate \
  -H "Authorization: Bearer <firewall-gateway-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_name": "shell.exec",
    "arguments": { "command": "rm -rf /" }
  }'
Phản hồi mang theo verdict — allow, audit, deny, sanitize, hoặc pending_approval. Với deny bạn bỏ qua cuộc gọi và làm nổi lý do cho model; với sanitize bạn chuyển tiếp các argument đã làm sạch mà gateway trả lại (sanitize chỉ redact các argument của cuộc gọi tool — không bao giờ nội dung mà một tool trả về); với pending_approval bạn bước vào vòng lặp phê duyệt bên dưới.
Gateway đánh giá các cuộc gọi đi qua nó — hook evaluate, MCP gateway, và đường relay. Một tool mà agent của bạn chạy hoàn toàn in-process, không bao giờ chạm tới OrcaRouter, nằm ngoài tầm nhìn của nó. Hãy định tuyến các cuộc gọi quan trọng (tool qua trung gian model, MCP dispatch, egress mạng) qua gateway và chúng được quản trị.

​
5. Handshake phê duyệt (HITL)

Một verdict pending_approval giữ cuộc gọi lại chờ con người. Lỗi HTTP trong khi giữ là firewall_approval_pending. Giải phóng nó là một vòng lặp ba bước trải trên cả hai họ route:
1

Một người duyệt giải quyết lần giữ

Từ console (PATCH /api/workspace/firewall/approvals/:id, Developer+), hoặc hệ thống của riêng bạn post một callback ký HMAC tới POST /api/v1/firewall/approvals/:id/callback. Callback xác minh HMAC ngay tại chỗ — không auth nào khác được chấp nhận.
2

Agent của bạn poll lần phê duyệt

GET /api/v1/firewall/approvals/:id với gateway key, cho tới khi trạng thái lật sang approved hoặc rejected.
3

Gửi lại với token dùng một lần

Một khi được phê duyệt, phát lại cuộc gọi gốc mang theo header X-OrcaRouter-Firewall-Approval với approval id. Gateway nhận ra nó và cho đúng cuộc gọi đó đi qua. Header dùng một lần.
Các quyết định là first-writer-wins và idempotent — một lần giải quyết thứ hai cho cùng lần giữ là một no-op. Xem Firewall — Phê duyệt của con người để biết luồng đầu-cuối và Tại sao bị chặn? để biết cách đọc một verdict.

​
6. Một lần block trông như thế nào

Kết quảHTTPMã
Cuộc gọi tool bị từ chối (bề mặt inbound)400firewall_blocked
Bị từ chối qua MCP gatewaylỗi toolfirewall deny: <reason>
Giữ chờ phê duyệt400firewall_approval_pending
firewall_blocked được đánh dấu skip-retry — chạy lại đúng cùng cuộc gọi chỉ chặn lại, nên một client retry sẽ lùi lại thay vì dập liên tục. Danh sách mã đầy đủ nằm ở Mã lỗi.

​
7. Tham chiếu liên quan

Guardrail API

Đối tác chính sách nội dung — các route /api/guardrail/* cho mặt phẳng văn bản.

Bảng thuật ngữ verdict

Mọi verdict và nó làm gì với một cuộc gọi.

Glob & JSONPath

Ngữ pháp khớp đằng sau tool_name_glob và args_match.

Compliance API

Pack, báo cáo có chữ ký, residency, và xóa bỏ.

​
8. FAQ

Các route gateway yêu cầu một key firewall-gateway-scoped — một key được đúc với is_firewall_gateway đặt (một hành động Admin+). Một relay key thường, kể cả một key hợp lệ, nhận 403. Hãy đúc một gateway key chuyên dụng cho agent runtime của bạn.
Không. Các route events, events/aggregate, và trace là Developer+ vì các bản ghi mang provenance argument cuộc gọi tool. Viewer có thể đọc settings, chính sách, preset, discovered tools, simulate, và feed bất thường.
Cả hai. Một con người giải quyết nó trong console qua PATCH /api/workspace/firewall/approvals/:id (Developer+), hoặc hệ thống của riêng bạn post một quyết định ký HMAC tới POST /api/v1/firewall/approvals/:id/callback. Agent poll GET /api/v1/firewall/approvals/:id bất kể đường nào đã giải quyết nó.
Không. Một verdict sanitize chỉ redact các argument của cuộc gọi tool — không bao giờ nội dung mà một tool trả về. Trên bề mặt inbound, nơi chưa có argument lúc gọi, sanitize leo thang thành một block. Xem Quy tắc firewall.
Về cách các kiểm soát này kết hợp với guardrail và phần còn lại của gateway, xem Bảo mật AI agent và Guardrails vs Firewall.