跳转到主要内容
智能体防火墙以两种方式配置：通过控制台（你的会话，和你用于仪表板的 同一登录），以及通过网关（你的智能体在运行时呈现的一个专用的 firewall-scoped API 密钥）。这两族存在于不同的路径前缀下、采用不同的认证、 回答不同的问题——“编辑策略” 对 “评估这次工具调用”。本页是两者逐路由的 地图。 关于策略意味着什么——判定、执行面、规则、解析——请从 防火墙 和 防火墙规则 开始。本页只涉及 API 表面。

​
1. 两族路由

控制台 —— 配置

/api/workspace/firewall/*。由你的会话 / 访问令牌（UserAuth）认证， 限定到你的活跃工作区。编写策略、读取事件、注册 MCP 服务器、解决审批。 每个动作都受角色门控。

网关 —— 执行

/api/v1/firewall/*。由一个 firewall-gateway-scoped 密钥（一个设置了 is_firewall_gateway 的密钥）认证。这是你的智能体或 MCP 客户端在运行时 调用的机器对机器表面。一个普通中继密钥在这里会得到 403。
控制台路由从不接受 sk-orca-… 中继密钥，网关路由从不接受会话令牌。把它们 弄混是首次接通防火墙时最常见的 401/403。唯一能用在 /v1/firewall/* 调用上的 sk-orca-… 密钥，是一个以 is_firewall_gateway 开启而铸造的密钥 ——参见 范围、密钥与策略。

​
2. 角色一览

控制台路由会解析你的工作区角色并据此门控。不携带工具调用来源（provenance） 的读取对任何成员开放；写入以及任何暴露工具调用参数的内容需要 Developer+。
角色能做什么
Viewer / 成员读取设置、策略、预设、已发现工具、simulate、异常。
Developer+以上全部，外加每一项写入、events/runs/trace 表面，以及 test dry-run。
Admin+额外地，在一个密钥上设置 is_firewall_gateway 标志并读取一个网关密钥的明文。
这种划分是有意为之的：一名 viewer 可以看到一条策略存在以及它会拦截 什么，但看不到一个事件背后的原始工具调用参数。如果你在为非开发者构建 仪表板，那些读取开放的路由就是安全的那一组。

​
3. 从控制台配置一条策略

控制台路由是你编写和检视策略的方式。你在仪表板 UI 里配置一切——这些就是 它调用的同一批端点。

​
策略与设置

方法与路径角色用途
GET /api/workspace/firewall/settingsMember观察模式 + 计数。
PUT /api/workspace/firewall/settingsDeveloper+更新工作区防火墙设置。
GET /api/workspace/firewall/policiesMember列出策略。
GET /api/workspace/firewall/policies/:idMember单条策略详情。
POST /api/workspace/firewall/policiesDeveloper+创建一条策略。
PUT /api/workspace/firewall/policiesDeveloper+更新一条策略。
DELETE /api/workspace/firewall/policies/:idDeveloper+删除一条策略。
POST /api/workspace/firewall/rulesDeveloper+添加一条规则。
PUT /api/workspace/firewall/rulesDeveloper+更新一条规则。
DELETE /api/workspace/firewall/rules/:idDeveloper+删除一条规则。

​
姿态、预设与沙箱

方法与路径角色用途
GET /api/workspace/firewall/presetsMember内置规则预设。
GET /api/workspace/firewall/templatesMember用例模板库。
POST /api/workspace/firewall/templates/applyDeveloper+应用一个模板 → 一条策略 + 它的规则。
POST /api/workspace/firewall/autonomyDeveloper+应用一个自治级别（tight / balanced / permissive）。
POST /api/workspace/firewall/autonomy/undo/:audit_idDeveloper+从审计快照一键撤销。
GET /api/workspace/firewall/simulateMember某个级别会拦截什么（?level=）。
POST /api/workspace/firewall/testDeveloper+针对一个样本调用对一条策略做 dry-run。

​
可观测性

方法与路径角色用途
GET /api/workspace/firewall/discovered-toolsMember见过的工具，标记 covered / gap。
GET /api/workspace/firewall/eventsDeveloper+列出防火墙事件（可过滤）。
GET /api/workspace/firewall/events/by-request/:request_idDeveloper+一个请求的事件。
GET /api/workspace/firewall/events/aggregateDeveloper+运行 / 会话汇总。
GET /api/workspace/firewall/trace/by-runDeveloper+一次运行的 trace 节点（?run_id=）。
GET /api/workspace/firewall/anomaliesMember异常信息流。
POST /api/workspace/firewall/anomalies/snoozeDeveloper+贪睡信息流（≤ 7 天）。

​
MCP 服务器

在单一受审计的网关后注册你的智能体所触达的 Model Context Protocol 服务器。 凭据加密存储并在读取时被脱敏。
方法与路径角色用途
GET /api/workspace/firewall/mcp_serversMember列出已注册的服务器。
GET /api/workspace/firewall/mcp_servers/:idMember服务器详情。
POST /api/workspace/firewall/mcp_serversDeveloper+注册一个服务器（name 重复时返回 409）。
PUT /api/workspace/firewall/mcp_serversDeveloper+更新一个服务器。
DELETE /api/workspace/firewall/mcp_servers/:idDeveloper+移除一个服务器。
POST /api/workspace/firewall/mcp_servers/:id/probeDeveloper+可达性 + tools/list 握手。
一个服务器携带一个唯一的 name、一个 endpoint、一个 auth_mode （none / bearer / oauth / basic），以及一个健康 status （ok / degraded / down）。完整的生命周期与技能隔离，参见 防火墙 MCP。

​
4. 在网关上执行

这些运行在一个 firewall-gateway-scoped 密钥上，而非你的会话。它们就是你的 智能体循环或 MCP 客户端在运行时调用的对象。
方法与路径用途
POST /api/v1/firewall/evaluate对一次工具调用做派发前判定。
POST /api/v1/firewall/evaluate_plan对一个多步计划做执行前检查。
ANY /api/v1/firewall/mcp统一的 MCP 网关端点。
GET /api/v1/firewall/mcp_servers枚举工作区已注册的服务器。
GET /api/v1/firewall/approvals/:id轮询一次被挂起调用的审批状态。
POST /api/v1/firewall/approvals/:id/callbackHMAC 签名的审批回调。

​
一个具体例子：评估一次工具调用

在你的智能体派发一个工具之前，向网关请求一个判定。传入 firewall-gateway-scoped 密钥——而非你的中继 sk-orca-… 密钥： 
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 /" }
  }'
响应携带判定——allow、audit、deny、sanitize 或 pending_approval。 在 deny 上你跳过该调用并向模型浮现原因；在 sanitize 上你转发网关交回的 清理后的参数（sanitize 只脱敏工具调用参数——绝不脱敏一个工具返回 的内容）；在 pending_approval 上你进入下面的审批环路。
网关评估那些穿越它的调用——evaluate hook、MCP 网关，以及中继路径。一个 由你的智能体完全在它自己进程内运行、从不接触 OrcaRouter 的工具，在它的 视野之外。把那些重要的调用（模型中介的工具、MCP 派发、网络 egress）路由 经过网关，它们就受到治理。

​
5. 审批握手（HITL）

一个 pending_approval 判定为人工挂起这次调用。挂起期间的 HTTP 错误是 firewall_approval_pending。清除它是一个跨两族路由的三步环路：
1

一名审查者解决这次挂起

从控制台（PATCH /api/workspace/firewall/approvals/:id，Developer+）， 或者你自己的系统向 POST /api/v1/firewall/approvals/:id/callback 发出 一个 HMAC 签名的回调。该回调就地验证 HMAC——不接受其他任何认证。
2

你的智能体轮询审批

用网关密钥调用 GET /api/v1/firewall/approvals/:id，直到状态翻转为 approved 或 rejected。
3

携带一次性令牌重新提交

一旦获批，携带带审批 id 的 X-OrcaRouter-Firewall-Approval 头重新发出 原始调用。网关认出它并放行那一次调用。该头是一次性的。
决策是首个写入者生效（first-writer-wins）且幂等的——对同一次挂起的第二次 解决是一个 no-op。完整的端到端流程参见 防火墙 —— 人工审批，读取一个判定 参见 为什么这次被拦下了？。

​
6. 一次拦截是什么样子

结果HTTP错误码
被拒绝的工具调用（inbound 执行面）400firewall_blocked
经由 MCP 网关被拒绝工具错误firewall deny: <reason>
被挂起等待审批400firewall_approval_pending
firewall_blocked 被标记为 skip-retry——重新运行那个完全相同的调用 只会再次被拦，因此一个会重试的客户端应当退避而不是猛击。完整的错误码 列表在 错误码。

​
7. 相关参考

防护栏 API

内容策略的对等物——文本平面的 /api/guardrail/* 路由。

判定词汇表

每一个判定，以及它对一次调用做什么。

Glob 与 JSONPath

tool_name_glob 和 args_match 背后的匹配语法。

合规 API

合规包、签名报告、数据居住与擦除。

​
8. FAQ

网关路由需要一个 firewall-gateway-scoped 密钥——一个以 is_firewall_gateway 开启而铸造的密钥（一个 Admin+ 动作）。一个普通 中继密钥，即便有效，也会得到 403。为你的智能体运行时铸造一个专用的 网关密钥。
不能。events、events/aggregate 和 trace 路由是 Developer+，因为 这些记录携带工具调用参数来源。Viewer 可以读取设置、策略、预设、已发现 工具、simulate，以及异常信息流。
都可以。人工在控制台里经由 PATCH /api/workspace/firewall/approvals/:id（Developer+）解决它， 或者你自己的系统向 POST /api/v1/firewall/approvals/:id/callback 发出 一个 HMAC 签名的决策。无论哪条路径解决了它，智能体都轮询 GET /api/v1/firewall/approvals/:id。
不会。一个 sanitize 判定只脱敏工具调用参数——绝不脱敏一个工具 返回的内容。在 inbound 执行面上，此时还没有调用时参数，sanitize 会 升级为一次拦截。参见 防火墙规则。
关于这些控制如何与防护栏以及网关其余部分组合，参见 保护 AI 智能体 和 防护栏 vs 防火墙。