跳转到主要内容
阻止一个智能体做危险事情最快的方式，就是点名那个工具并拒绝它。一个 针对工具名 glob 的 deny 判定就是 智能体防火墙 的黑名单原语：一条规则、一个 glob、判定 deny，绑定到一个密钥——从那之后 网关在每一次调用上拒绝那个工具，而无需改变你的智能体代码。 本页涵盖黑名单这个用例，以及它强加的那一个决定：你在哪个执行面上拦截 ——你声明的工具（inbound）还是模型发出的工具调用（response）。 关于完整的匹配词汇表和判定语义，参见 规则 schema 与 判定。

​
1. 拦截一个 AI 智能体发出的工具调用

一条黑名单规则是一条防火墙策略能表达的最简单的东西：按名称匹配一个工具， 返回 deny。当一个工具对一个给定密钥永远不应该触发时使用它—— shell.exec、*.delete、一个你不信任的社区插件——无论参数如何。 在你的工作区控制台中，打开一条策略（或 创建一条）并添加一条规则： 
{
  "label": "block destructive shell",
  "tool_name_glob": "*.exec",
  "verdict": "deny"
}
tool_name_glob 是一个小而大小写敏感的 glob——shell.* 捕获一整个 家族，*.delete 跨服务器捕获一个动词，* 捕获一切。无需参数子句：一个 裸 glob + deny 无条件拦截该工具。仅当你想总体上允许该工具但拒绝一种 调用形态时，才添加一个 参数子句。
引擎按优先级顺序遍历一条策略的规则，首个匹配生效。把窄的 allow 例外 放在更低的 priority 数字上（它们先运行），把你宽泛的 deny 放在它们 下面——例如允许来自一个受信任 builtin.* 技能的 shell.exec，在其他 所有地方拒绝它。参见 规则优先级。

​
2. Inbound vs response：挑选执行面

一个拒绝可以落在请求生命周期中两个不同的点上，而这个差别很重要。用 stage 字段把规则钉住，或留空以覆盖两者。

inbound

你的智能体在请求上向模型声明的工具（工具定义）。此处的一个拒绝 在模型甚至还没能选中它之前就剥除该工具——模型从未把它当作一个选项 看到。

response

模型在其回复中发出的 tool_calls。此处的一个拒绝在该调用到达 工具之前捕获模型已经决定要做的调用。
当你想让一个工具不可见时，优先用 inbound——模型不能调用从未提供给 它的东西，所以你避免了它选中一个工具却被拒绝的浪费回合。当该工具在某些 请求中正当出现而你想捕获实际发出的调用时，或当你只控制智能体循环而非 声明的工具集时，使用 response（或把 stage 留空）。
一条没有 stage 的规则适用于所有执行面——同一个拒绝覆盖一个工具， 无论它是被声明、被发出，还是 通过 MCP 派发。这是双保险的默认；仅当一个 拒绝应限定到一个执行面时才钉住一个执行面。参见 执行面。

​
3. 绑定策略并观察它触发

一条策略在某个密钥解析到它之前什么都不做。在控制台中通过在 密钥 上设置 firewall_policy_id 来 绑定，或将该策略设为工作区默认。解析是：密钥绑定的策略（当它存在且已启用 时），否则工作区默认值。（一条被禁用的绑定策略会回退到默认值——参见 管理策略。） 一旦绑定，inbound 执行面上一次被拒绝的调用返回 HTTP 400，带有 错误码 firewall_blocked 和一条点名工具的原因——例如 tool "shell.exec" blocked by firewall。该错误被标记为 skip-retry （重新运行相同的调用只会再次被拦截），且不消耗任何模型 token，因为一次 inbound 拦截在上游调用之前就触发。一个 通过 MCP 网关派发 的拒绝则作为一个工具错误 浮现，所以模型能看到这次拒绝并作出反应。
inbound 执行面上的一个拒绝会从提供给模型的内容中移除该工具。如果你的 智能体框架要求它声明的某个工具是可调用的，在 inbound 上拦截它可能会让 循环困惑——那种情况下改在 response 上拦截，这样工具仍被声明但实际 调用被拒绝。在上线之前测试这个差别（参见 §5）。

​
4. Deny 是若干判定之一

Deny 是黑名单上最直接的工具。当一个硬拦截过头时，同一个 glob 可以携带一个 更柔和的判定：
判定何时改用它而非 deny
audit你想看到该工具触发但还不想拦截它。
sanitize该工具没问题但它的参数可能携带密钥/PII——脱敏参数，绝不脱敏工具结果。
pending_approval一名人工应该带外批准每一次调用。
cap_cost允许，直到一次智能体运行的花费越过一个分上限。
所有这些都在 判定 中有文档。一个黑名单 不过是判定为 deny 的那个子集。对于一种白名单姿态（拒绝一切，允许一个 点名的集合），把策略的 default_verdict 切换为 deny 并添加窄的 allow 规则——参见 工具白名单。

​
5. 安全地上线它

控制台 Test 标签对一个样本工具调用 dry-run 一条策略，并返回判定、 匹配到的规则和原因——不派发任何内容，不持久化任何内容。在绑定一个 密钥之前，确认你的 glob 匹配你想要的工具（且只有那个工具）。参见 测试规则。
在该策略上打开 影子模式，那么每个 执行性判定——包括你的拒绝——都被降级为 audit，原因前缀为 [shadow] would …。你对照真实流量准确衡量该拒绝本来会拦截什么， 然后关闭影子以执行。
不确定要 glob 的确切工具名？Discovered Tools 视图列出工作区见过的 每一个工具，标记为 covered 或 gap。直接从实际出现的名称编写你的拒绝。 参见 分析。
每一次评估都写入一个带有判定、执行面、工具和匹配规则的防火墙事件。在 你执行之后，按判定 deny 过滤 事件日志 以查看该规则在你预期的调用上触发。

​
6. 谁能做什么

所有黑名单配置都在控制台中于你的会话下运行 （/api/workspace/firewall/*）：
操作角色
读取策略、预设、discovered tools、SimulateMember
Dry-run 一条策略（Test）Developer+
创建 / 编辑 / 删除规则和策略Developer+
读取事件日志和运行汇总Developer+
编写或更改一条 deny 规则是一个 Developer+ 写入，控制台 Test dry-run 也是。读取一条策略和只读的 Simulate（“假设”）视图对每个成员 开放。

​
相关

Glob 语法

shell.*、*.exec 和 *.shell.* 究竟如何匹配。

工具白名单

反向姿态：默认拒绝，允许一个点名的集合。

验证参数

只拒绝一种调用形态，而非整个工具。

危险工具调用

黑名单应对的威胁。

判定

deny 及其更柔和的兄弟们在线上做什么。

防火墙参考

完整的规则 + 匹配参考。