跳转到主要内容
AI 智能体不只是生成文本——它会行动。它会调用 shell.exec、 查询数据库、抓取一个 URL、通过 MCP 服务器派发一个工具。 这其中每一项都是带有真实世界后果的动作，而提示词级别的 防护栏 看不到它们。智能体防火墙 就是治理它们的动作层平面：一个工作区限定的、命名的策略，网关会在 每一次工具调用时对其进行评估，在它到达工具之前。 本页是防火墙这一章节的中枢——策略模型、判定、执行面，以及一条策略 如何绑定到一个密钥。每一条辐射页面都更深入，而完整的引擎参考则位于 防火墙 与 防火墙规则。

​
1. 智能体防火墙做什么

你在工作区控制台中编写一次策略，把一个 API 密钥绑定到它 （或将某个设为工作区默认），从那之后，该密钥发出的每一次工具调用 都会在网关上被对照策略检查。无需重新部署，无需修改智能体代码—— 你的智能体像以前一样继续发出工具调用，而编辑策略会在下一次调用时对 绑定到它的每个密钥生效。 一条策略是一个有序的规则列表。每条规则决定它适用于哪些工具调用 以及如何处理它们。引擎按优先级顺序遍历规则，首个匹配生效， 如果没有任何匹配则回退到策略的默认判定。
检测发生在网关上，于首次使用时——而非安装时。智能体自行安装的某个 工具、MCP 服务器或技能，会在它的调用首次穿越网关时被捕获。那是那个 能看到每一个供应商、每一个智能体、每一次工具调用的唯一咽喉点， 无论该能力是如何进来的。

​
2. 一个具体示例

假设你想拦截破坏性 shell 命令，但放行其他一切并置于审计之下。在控制台 中你创建一条 default_verdict = audit 的策略，并加上一条规则： 
{
  "label": "block rm -rf",
  "tool_name_glob": "*.exec",
  "args_match_json": "{\"clauses\":[{\"path\":\"$.command\",\"op\":\"regex\",\"value\":\"rm -rf|drop table\"}]}",
  "verdict": "deny"
}
args_match_json 是一个 JSON 编码的字符串（网关在保存时会对照 子句 schema 验证它）：path 是指向该调用参数的一个 JSONPath，op 是 eq、contains、regex、in、cidr_match、gt、lt 之一。 把一个密钥绑定到该策略（在密钥上设置 firewall_policy_id）。现在当一个 智能体发出带有 command: "rm -rf /" 的 shell.exec 时，网关返回 HTTP 400，带有错误码 firewall_blocked 和一条点名该工具的原因—— 而该调用永远不会到达 shell。其他每一次工具调用都被放行并记录以供审查。
先在 影子模式 下上线一条新策略： 它会完全像在生产中那样进行评估和记录，但每个执行性判定都被降级为 audit，原因前缀为 [shadow] would …。观察事件信息流，然后关闭 影子模式以开始执行。

​
3. 策略、规则与解析

一条策略是工作区限定且命名的，具有 enabled、is_default、一个 default_verdict（allow / audit / deny，默认 audit），以及一个 shadow_mode 标志。一条规则是它内部的一项检查——参见 创建策略 与 规则 schema。 对于任何一次工具调用，网关按此顺序解析活跃策略：
  1. 密钥绑定——发起调用的密钥的 firewall_policy_id，当该策略存在 且已启用时。
  2. 工作区默认值——否则，工作区已启用的 is_default 策略。
一条被禁用的绑定防火墙策略会回退到工作区默认值——这与防护栏 不同，在防护栏中一个被禁用的绑定会解析为无。一个密钥防火墙上的关闭 开关意味着”使用默认值”，而非”不执行”。参见 管理策略。
当根本没有策略解析出来时，行为取决于工作区的 firewall_observe_mode 设置：在观察模式开启时，该调用被放行但记录为一个覆盖缺口 （它会出现在 Discovered Tools 中）；在它关闭时，该调用被静默放行。

​
4. 判定（Verdict）

一条规则——或默认判定——产生以下之一：
判定它做什么
allow放行，会被记录。
audit放行 + 记录以供审查。通常的默认值。
deny拦截。inbound 上返回 HTTP 400 firewall_blocked；MCP 上返回工具错误。
sanitize从工具参数中脱敏匹配的子串并转发。
pending_approval为人工挂起；HTTP 400 firewall_approval_pending。
cap_cost一旦该运行的花费越过某条规则的上限就拒绝。
一个 sanitize 判定只脱敏调用参数——绝不脱敏工具返回的内容。在 inbound 执行面上，此时还没有调用时参数，sanitize 会升级为拦截。参见 判定 与 脱敏响应。

​
5. 四个执行面

每一次工具调用都恰好对照一个**执行面（surface）**进行评估——用 stage 字段把一条规则钉在某一个上，或留空以适用于所有执行面。

inbound

智能体在请求上向模型声明的工具。在模型甚至还没选中之前就拦截一个 危险工具。

response

模型在其回复中发出的 tool_calls。

mcp

通过 MCP 网关派发的一次 tools/call。参见 MCP 服务器。

egress

某个工具触及的一个出站 host / IP / CIDR——即 SSRF 与数据外泄的 执行面。

​
6. 匹配

规则用一套小而确定、在热路径上安全的词汇表来表达它们捕获哪些工具 调用：
针对工具名的一个大小写敏感 glob（shell.*、*.delete），可选地与 针对所属技能的一个 glob 做 AND。参见 Glob 语法 与 工具白名单。
针对调用参数的 JSONPath 谓词，运算符为 eq、contains、regex、 in、cidr_match、gt、lt——这是”拦截 shell.exec”与”只在命令是 rm -rf 时拦截它”之间的差别。子句故障关闭（影响规则，而非请求）。 参见 验证参数。
在 egress 执行面上的 Host / IP / CIDR 白名单与黑名单。你可以为 云元数据或 RFC-1918 范围编写你自己的拒绝规则。参见 Egress 控制。
一条 sequence 规则在一个窗口内匹配一连串有序的调用（被动执行）； 一条 cap_cost 规则在一次智能体运行累积的花费越过分（cents）上限后 拒绝。参见 序列规则 与 封顶成本。

​
7. 人工审批、自治与异常

  • 人工介入（Human-in-the-loop）。 一个 pending_approval 判定挂起该 调用并返回它的审批 id。一名审查者在控制台（Developer+）中或通过一个 HMAC 签名的 webhook 回调解决它；智能体轮询并携带一个一次性的 X-OrcaRouter-Firewall-Approval 头重新提交。参见 审批 与 审批 webhook。
  • 自治级别（Autonomy levels）。 一个开关设置你的整体姿态：tight （默认拒绝 + 拒绝破坏性 shell + 拒绝 fetch 形态的工具 （http_fetch/web_search/fetch_url/request，即 SSRF 向量）+ 执行 PII Shield + Secrets Blocker）、balanced（默认审计、拒绝破坏性 shell、PII Shield 仅审计），或 permissive（仅观察）。每一项都写入 真实、可编辑的策略与防护栏行，并支持从审计快照一键撤销。
  • 异常检测（Anomaly detection）。 在静态规则之外，防火墙会对照一个 学习到的周内小时基线（14 天）为工具使用评分，并在一个 Member 可读的 信息流上标记速率/成本尖峰、retry_loop 和 novel_path，你可以将其 贪睡最多 7 天。

​
8. 防火墙的定位

防火墙是两个相邻平面的动作层对等物：
平面治理何时使用它
防护栏提示词与响应的文本PII、密钥、越狱、注入意图
智能体防火墙工具动作哪些工具、MCP 调用、主机以及成本
合规证据与框架SOC 2 / HIPAA / EU AI Act 就绪度
内容平面和动作平面都可以作用于单个请求，而一个自治级别会一起配置 它们。参见 防护栏 vs. 防火墙 与 控制栈。

​
9. 绑定与连接

一条策略通过 firewall_policy_id 绑定到一个密钥（在控制台中配置；绑定 关系存在于网关的密钥上）。一次工具调用有两种方式到达引擎，两者都需要 一个 firewall-gateway-scoped 密钥（is_firewall_gateway = true）—— 一个普通中继密钥在这些路由上会得到 403：
  • MCP 网关——把你的 MCP 客户端指向统一的 ANY /api/v1/firewall/mcp 端点；每一次 tools/call 都会就地被评估。 参见 MCP 服务器。
  • Evaluate hook——在派发之前，从你自己的智能体循环中调用 POST /api/v1/firewall/evaluate（或对一个多步计划调用 /evaluate_plan），并根据判定采取行动。
所有控制台配置都通过 /api/workspace/firewall/* 在你的会话下运行。 对策略、设置、discovered tools、只读自治模拟器以及异常信息流的读取对 每个工作区成员开放；dry-run Test 沙箱、Events / Runs 日志以及所有 写入都需要 Developer+。参见 网关密钥 与 测试规则。

​
10. 此平面应对的威胁

危险工具调用

按 glob + 参数拒绝破坏性 shell、DB drop 以及高风险动词。

数据外泄

Egress 列表与 read-then-export 序列规则。

MCP 工具投毒

在 mcp 执行面上于派发前进行逐次调用评估。

过度代理（Excessive agency）

审批、成本上限以及默认拒绝姿态。

​
下一步

创建策略

编写你的第一条策略与规则。

判定

每个判定在线上的实际表现。

事件日志

读懂防火墙判定了什么以及为什么。