防火墙

防护栏筛查流经模型的文本。防火墙则治理智能体所采取的 动作——它调用的工具、它访问的 MCP 服务器、它加载的技能， 以及它通信的主机。它是 防护栏 在动作层的 对等物：相同的工作区限定范围、相同的”绑定一次”模型、相同的 “策略存在于网关而非你的应用”承诺。 本页是概念概览和操作参考。另有三篇配套页面深入讲解 各个组成部分：

​

1. 什么是防火墙

AI 智能体不只是生成文本——它会行动。它会调用 shell.exec、 查询 db.query、抓取一个 URL、加载一个社区技能，或将一次工具 调用通过第三方 MCP 服务器路由出去。这些每一项都是带有真实世界 后果的动作，而提示词级别的防护栏看不到它们。 防火墙是一个工作区级别的、命名的策略，网关会在每一次 工具调用时对其进行评估。你编写一次策略，将一个 API 密钥绑定到 它（或将某个设为工作区默认），从那之后，该密钥发出的每一次 工具调用都会被对照策略进行检查——在它到达工具之前。 每条策略是一个有序的规则列表。一条规则决定一件事—— 它适用于哪些工具调用（一个工具名 glob，可选地限定到某个 技能和某个执行面），以及如何处理它们（一个判定（verdict）： allow、audit、deny、sanitize、hold for approval 或封顶成本）。引擎 按优先级顺序遍历规则，首个匹配生效（first match wins），如果 没有任何规则匹配，则回退到策略的默认判定。 编辑一条策略会在下一次调用时对绑定到它的每个密钥生效。 无需重新部署。无需修改智能体代码。策略在网关上执行——你的 智能体像以前一样继续发出工具调用。

​

2. 四个执行面（surface）

每一次工具调用都恰好对照一个**执行面（surface）**进行评估—— 即防火墙在请求生命周期中看到它的那个点： 没有指定 stage 的规则适用于所有执行面；当某个判定只在一个 执行面上有意义时（例如 egress 白名单），就把规则钉在那一个 执行面上。

​

3. 核心概念

​

限定范围与解析

策略的解析方式与防护栏和 API 密钥完全相同——当你有活跃工作区 时为工作区共享。对于任何一次工具调用，网关按此顺序解析策略：

1. 密钥绑定——如果发起调用的密钥有 firewall_policy_id，则 该策略适用（当它存在且已启用时）。
2. 工作区默认值——否则，工作区已启用的 is_default 策略适用。
3. 两者皆无——不执行。在观察模式开启时，该调用被放行 并记录为一个缺口；在它关闭时，该调用被静默放行（与从未 启用该功能的工作区字节相同）。

每个工作区最多只能有一个策略作为默认值；晋级一个新默认值会在 同一事务中降级旧的那个。

​

4. 判定（Verdict）

一条规则（或默认判定）产生以下之一： 在影子模式下，deny / sanitize / pending_approval 都被降级为 audit，这样你就能在策略改变流量之前先衡量它的影响。

​

5. 一次工具调用是如何被评估的

1. 一次工具调用到达网关（在 inbound 上被声明、在响应中被发出、 通过 MCP 网关被派发，或作为 egress 被报告）。
2. 引擎解析活跃策略（§3）。
3. 它按优先级顺序遍历策略的规则（优先级越低越先；同级 由规则 id 打破平局）。当一条规则的执行面、它的工具名 glob、 它可选的技能名 glob、它可选的参数子句以及它可选的 egress 范围全部匹配时，该规则才匹配。
4. 首个匹配生效 → 该规则的判定适用。如果没有规则匹配 → 策略的 default_verdict。
5. 如果该调用归属于一个受治理的 技能， 则技能的执行模式会被叠加在其上——一个处于 block 模式的 技能强制 deny；一个处于 quarantine 模式的技能会把任何 未到 deny 程度的判定升级为 pending_approval。
6. 该决策被记录为一个防火墙事件（除非它是一次 dry run），并 关联到对应的智能体运行和会话。

​

6. 拦截的表现形式

inbound 执行面上一次被拒绝的调用返回 HTTP 400，带有一个 OpenAI 形态的错误体、错误码 firewall_blocked，以及一条点明 工具和原因的消息——例如 tool "shell.exec" blocked by firewall: destructive shell command。该错误携带结构化的 metadata （原因码、风险因子、得分），并被标记为 skip-retry（重新 运行同一个调用只会再次被拦截）。 通过 MCP 网关派发的一次调用会作为一个工具错误 （firewall deny: <reason>）被拦截，而不是一次传输失败，因此 模型能看到这次拒绝并作出反应——换一个工具、询问用户，或者 停止——而不是崩溃。 一次被挂起的调用（pending_approval）返回 HTTP 400，带有 错误码 firewall_approval_pending 和一个客户端用于轮询的审批 id。

​

7. 人工审批（HITL）

一个 pending_approval 判定会把一次工具调用变成一次带外审查：

1. 引擎将一条审批记录入队，并返回一个携带其 id 的”已挂起” 响应；该调用不会到达工具。
2. 一名审查者解决它——从控制台（Developer+），或通过一个 HMAC 签名的 webhook 回调到你自己的审批系统。
3. 你的智能体（或 MCP SDK）轮询该审批 id；一旦获批，它就 携带一个一次性的 X-OrcaRouter-Firewall-Approval 头重新提交 原始调用，网关便放行这一次。

决策是首个写入者生效（first-writer-wins）且幂等的。如果底层 规则在挂起后被编辑过，富化信息会标注 rule_changed，让审查者 知道上下文已发生变化。

​

8. 自治级别（Autonomy levels）——管控你整体姿态的一个开关

逐条调优策略是精确的路径；自治级别则是快速的那条。一个 单一控制项会在一个事务中原子地替换你工作区的防火墙以及 防护栏姿态，并支持一键撤销： 撤销会从审计快照恢复到此前的确切状态。

​

9. 异常检测（Anomaly detection）

在静态规则之外，防火墙会学习每个工作区正常的工具使用形态， 并在一个查看者可读的信息流上标记偏离：

• 速率 / 成本尖峰——按工具的活动会对照一个学习到的 周内小时基线（hour-of-week baseline）（一个 14 天滚动平均） 进行评分，因此即便每次调用单独都被允许，“周日凌晨 3 点 100 次 db.query 调用”也会显得突出。
• retry_loop——一个智能体反复猛击同一个失败的工具。
• novel_path——本工作区从未做过的一次工具到工具的转移。

该信息流只报告工具名、脱敏后的令牌 id 和计数。你可以在调查 期间将一个异常**贪睡（snooze）**最多 7 天。

​

10. 可观测性

防火墙会留下可供你行动的踪迹，全部为工作区限定：

​

11. 与网关其他部分的关系

​

12. 将一个智能体连接到防火墙网关

一次工具调用有两种方式到达引擎：

• MCP 网关——把你的 MCP 客户端（Claude Desktop、Cursor、某个 智能体框架）指向 https://api.orcarouter.ai/api/v1/firewall/mcp。 网关以 <server>.<tool> 命名空间暴露每一个可达的已注册服务器 的工具，并就地评估每一次 tools/call。参见 MCP 服务器。
• Evaluate hook——在派发一次工具调用之前，从你自己的智能体 循环中调用 POST /api/v1/firewall/evaluate，并根据判定采取行动。

两者都需要一个 firewall-gateway-scoped 令牌——为此目的专门 铸造的一个 API 密钥。普通密钥在这些路由上会得到 403。

​

13. API 参考

所有控制台路由都通过工作区上下文进行工作区限定，并一致地 执行 RBAC：读取以及 test/simulate 沙箱对每个成员开放；写入 需要 Developer+。

​

策略与设置

​

姿态、预设与沙箱

​

可观测性

规则、MCP 服务器和技能各自有独立的端点——参见 规则、 MCP 服务器 和 技能。

​

网关（机器对机器）

这些运行在一个 firewall-gateway-scoped 令牌上，而非控制台会话：

​

14. FAQ

​

另请参阅

想更深入地了解智能体安全？**保护你的智能体（零信任）**指南会把这项功能放进一套零信任工作流中。