跳转到主要内容
要从模型中继之外把工具调用穿过智能体防火墙——你自己的智能体循环调用 evaluate hook，或一个 MCP 客户端连接到 MCP 网关——你用一个专用的 firewall-gateway-scoped 密钥认证，而非一个普通的 sk-orca-… 中继密钥。 一个普通密钥在令牌认证的防火墙网关路由上得到 403（审批回调是唯一的例外 ——它是 HMAC 签名的，而非令牌门控的）。 本页涵盖一个防火墙网关 API 密钥是什么、如何铸造一个，以及为什么该范围被 门控到 Admin+。关于引擎本身，参见 防火墙概览 以及 防火墙 的深度参考。

​
1. 一个防火墙网关 API 密钥是什么

你工作区中的每个令牌（API 密钥）都携带一个 is_firewall_gateway 标志。当它 为 true 时，该密钥被允许触及防火墙网关执行面：
路由它做什么
POST /api/v1/firewall/evaluate对一次工具调用做派发前判定。
POST /api/v1/firewall/evaluate_plan对一个多步计划做执行前检查。
ANY /api/v1/firewall/mcp统一的 MCP 网关 端点。
GET /api/v1/firewall/mcp_servers枚举工作区已注册的 MCP 服务器（返回解密的上游 auth）。
GET /api/v1/firewall/approvals/:id轮询一个被挂起调用的 审批 状态。
一个 is_firewall_gateway = false（默认）的密钥是一个普通中继密钥——它服务 /v1/* 模型流量，且如果你通过 firewall_policy_id 绑定了一条策略，它的 工具调用会被内联治理。但它不能调用上面的网关路由。
两个不同的密钥，两个不同的职责。 你的中继密钥（绑定了 firewall_policy_id）是你的智能体用来与模型对话的——防火墙自动治理它的 工具调用。一个防火墙网关密钥是你的智能体运行时用来直接向防火墙请求一个 判定，或通过网关代理 MCP tools/call 的。大多数工作区只有在采用 evaluate hook 或 MCP 网关后才需要一个网关密钥。

​
2. 为什么一个普通密钥得到 403

网关范围解锁两项对密钥敏感的能力，所以它被有意地与普通密钥隔开：
  • /evaluate 接受一个调用者提供的 request_id，它流入防火墙事件和 审批记录。任何模型密钥都能伪造审计事件或静默地探测策略结果，会破坏 追踪。
  • /mcp_servers 返回解密的上游凭据，这样 SDK 的代理能派发到你已注册的 MCP 服务器。那是一次凭据读取，而非一次模型 调用。
因此，处理器检查呈递令牌的 is_firewall_gateway 标志，并在它缺失时返回 HTTP 403： 
{
  "success": false,
  "message": "token lacks firewall_gateway scope — mint a dedicated gateway token"
}
不要把一个高流量中继密钥复用为一个网关密钥，也不要把一个网关密钥复用于 中继流量。把动作平面密钥保持独立，这样它的杀伤半径和轮换独立于你的模型 密钥。

​
3. 铸造一个——角色门控到 Admin+

设置 is_firewall_gateway = true 需要工作区 Admin 或更高。一个 Developer 能创建和编辑普通密钥，但不能铸造一个网关限定的——该标志是一个 密钥管理关注点，所以它位于普通令牌写入角色之上。 你在控制台中、在你的工作区 API 密钥下配置密钥。要铸造一个网关密钥：
1

以 Admin 身份打开 API 密钥

以一个工作区 Admin（或更高）登录，并在控制台中打开 API 密钥页面。
2

创建一个带网关范围的密钥

创建一个新密钥并启用它的 firewall gateway 范围 （is_firewall_gateway）。一个 Developer 角色的会话不会看到该范围生效 ——服务器对非 admin 保持该标志为 false。
3

复制该密钥一次

在创建时复制完整的密钥值。之后控制台在显示时遮蔽它，而读回一个 网关密钥的明文本身就是 Admin+——非 admin 在一次”获取我的密钥”响应中 会被省略网关行。
降低该标志比提升它更宽松：清除 is_firewall_gateway（把一个网关密钥 降级回一个普通密钥）对任何能编辑该密钥的角色开放。只有把它提升为 true 才是 Admin+。

​
角色门控一览

操作角色
创建/编辑一个普通密钥Developer+
设置 is_firewall_gateway = trueAdmin+
读回一个网关密钥的明文Admin+
清除 is_firewall_gateway（降级）任何密钥编辑者

​
4. 一个具体示例

你正在运行一个智能体循环，并想在派发一次工具调用之前检查它。作为一个 Admin，在控制台中铸造一个网关密钥，然后用那个密钥从你的运行时调用 evaluate hook： 
curl https://api.orcarouter.ai/api/v1/firewall/evaluate \
  -H "Authorization: Bearer sk-orca-GATEWAY-KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_name": "shell.exec",
    "arguments": { "command": "rm -rf /" },
    "request_id": "run-42-step-3"
  }'
防火墙解析你工作区的活跃策略并返回 判定 ——allow、audit、deny、sanitize、pending_approval，或一个 cap_cost 解析。你的智能体据此行动：在 allow 时派发、在 deny 时跳过、在 pending_approval 时轮询审批 id。同一个网关密钥认证 审批轮询 和 MCP 路由。
把一个 MCP 客户端（Claude Desktop、Cursor、一个智能体框架）指向 https://api.orcarouter.ai/api/v1/firewall/mcp？用网关密钥作为它的 bearer 令牌。那么每一次 tools/call 在它被转发上游之前都会在 mcp 执行面 上被评估。

​
5. 这部分的位置

一个网关密钥认证网关路由。它不替代你用来编写策略的控制台会话： 创建策略、编辑规则、注册 MCP 服务器以及解决审批，全都在你自己的会话下于 /api/workspace/firewall/* 运行（设置、策略和 discovered-tool 读取对每个 成员开放；dry-run 测试沙箱和所有写入需要 Developer+）。网关密钥只从你的 机器对机器运行时承载判定请求和 MCP 派发。

范围：密钥、策略、工作区

一个密钥的 firewall_policy_id 和一个网关范围如何与工作区边界相关。

审批

你的网关密钥轮询和重新提交的被挂起调用流程。

审批 webhook

带外解决一个被挂起调用的 HMAC 签名回调。

MCP 服务器

在网关端点后注册并治理 MCP 服务器。

​
6. FAQ

把 is_firewall_gateway 提升为 true 是 Admin+。一个设置该标志的 Developer 角色写入被静默保持为 false（这样同一个请求上一个无关的 重命名或配额编辑仍然成功）——该密钥只是不会携带该范围。以一个 Admin 身份重新创建或编辑它。
呈递的密钥不是网关限定的。确认它由一个 Admin 以 is_firewall_gateway = true 铸造——一个普通中继密钥在这些路由上总是得到 403。参见 §2。
技术上一个网关限定的密钥也能服务 /v1/* 中继流量，但把它们保持独立： 一个中继密钥（绑定了 firewall_policy_id）用于模型，一个网关密钥用于 evaluate/MCP/审批路由。独立轮换，更小的杀伤半径。
密钥在创建后被遮蔽，而读取一个网关密钥的明文是 Admin+。如果你在铸造时 没复制它，创建一个新的网关密钥并停用旧的。