跳转到主要内容
到达 OrcaRouter 的每个请求都携带一个 API 密钥。那个密钥不只是 凭证——它是一个范围声明：调用者可以使用哪些模型、哪些 IP 可以呈现它、它可以花费多少，以及确切的哪个防护栏和防火墙策略 治理其流量。本页解释三级层次结构以及策略在请求时如何解析。

​
1. 三个范围

三个概念相互嵌套：
  • 工作区——租户边界。工作区的每个成员共享相同的防护栏和 防火墙策略目录。没有任何东西跨越工作区边界——在工作区 A 中编写的策略对工作区 B 不可见。
  • 策略——一个命名的、工作区限定的规则集（防护栏或防火墙 策略）。编辑策略会在下一次请求时对附加到它的每个密钥生效， 无需重新部署。
  • 密钥——身份加附加项。密钥携带自己的约束，并指向治理它的 策略。
工作区是外部边界；策略是其中的共享资源；密钥是将约束和策略 连接在一起的每个智能体身份。

​
2. 密钥携带什么

每个 API 密钥是限制和附加项的捆绑包。在密钥编辑器 （/console/token）中设置这些——创建或编辑密钥需要 Developer 角色或以上。
字段它限制什么设置所需的最低角色
model_limits将密钥限制到特定的模型列表——对该列表之外任何模型的调用在离开网关之前被拒绝。Developer
allow_ipsIP 允许列表。来自任何未列出地址的请求在认证层被拒绝。空意味着允许所有 IP。Developer
credit_limit_usd以 USD 计的消费上限。0 表示无限制。网关对密钥的终身消费执行此上限。Developer
expired_time绝对到期时间戳。-1 表示密钥永不过期。Developer
environment一个自由格式标签（例如 prod、staging、dev），用于组织密钥和过滤日志。Developer
guardrail_id将特定防护栏附加到此密钥。该密钥发出的每一次调用都由该防护栏筛查。Developer
firewall_policy_id将特定防火墙策略附加到此密钥。该密钥发出的每一次工具调用都由该策略评估。Developer
is_firewall_gateway将密钥标记为网关限定令牌——调用 MCP 派发和 evaluate hook 路由所需。普通密钥在那些路由上得到 403。读取网关密钥的明文需要 Admin。Admin（启用和读取明文）
密钥在控制台中显示时被遮盖。明文在创建时显示一次；网关限定 密钥需要 Admin 才能再次检索。

​
3. 策略解析顺序

对于任何请求，OrcaRouter 独立地解析活跃的防护栏和防火墙策略：
  1. 密钥附加——如果密钥有明确的 guardrail_id（或 firewall_policy_id）且该策略存在且已启用，它就适用。
  2. 工作区默认值——如果密钥没有附加，工作区的已启用 is_default 防护栏（或策略）适用。
  3. 无执行——如果两者都没有设置，请求通过，没有内容筛查或 工具调用执行。
当附加的策略被禁用时，两个平面有所不同：
  • 被禁用或删除的防护栏附加意味着密钥得到没有防护栏—— 禁用它就是关闭开关；它不回退到工作区默认值。
  • 被禁用的防火墙附加回退到工作区默认防火墙策略—— 因此禁用防火墙附加会将密钥恢复到工作区默认，而不是关闭执行。
缺失（0/未设置）的附加总是回退到工作区默认；两者都没有意味着 无执行。
每个工作区在任何时候最多只能有一个防护栏和一个防火墙策略作为 默认值。晋级一个新默认值会在同一事务中降级旧的那个——你永远 不会意外地拥有两个默认值。

​
4. 最小权限密钥——每个智能体一个密钥

最安全的配置是给每个智能体其自己的窄范围密钥，而不是在所有 调用者之间共享一个工作区密钥。 一个只调用一个模型并运行计划任务的智能体的精心限定范围的密钥 可能看起来像这样：
  • model_limits：["openai/gpt-4o-mini"]——智能体不能切换到 更昂贵或更强大的模型。
  • allow_ips：调度器的出站 CIDR——没有其他来源可以呈现此密钥。
  • credit_limit_usd：每周预算上限——失控的循环不能耗尽你的 工作区余额。
  • expired_time：冲刺或部署生命周期的结束——密钥自动过期， 不能被重复使用。
  • guardrail_id：针对此智能体数据敏感性的防护栏——比工作区 默认值更严格。
  • firewall_policy_id：只允许此智能体合法需要的工具的策略。
当此智能体通过提示注入被攻破时，爆炸半径是有界的：它只能调用 一个模型，只能从一个 IP 范围，只能到其消费上限，以及只有其 防火墙策略允许的工具。工作区的其余部分不受影响。
仅为 MCP 派发或 evaluate hook 执行面创建网关限定密钥 （is_firewall_gateway）——绝不用于一般推理流量。推理路径上的 网关密钥让调用者访问 /api/v1/firewall/* 路由，这比它需要的 能力更广。一个密钥，一个目的。

​
5. 策略在哪里编写

防护栏和防火墙策略都是工作区限定的，并在所有成员之间共享， 但变更需要正确的角色：
  • 读取任何防护栏、策略或密钥——任何工作区成员。
  • 创建或更改防护栏、防火墙策略、MCP 服务器、自治级别、 审批动作和普通 API 密钥——Developer+。
  • 在密钥上启用 is_firewall_gateway；读取网关密钥的 明文——Admin+。
工作区是协作边界：所有人都能看到策略目录；只有 Developer 及以上 才能更改它；只有 Admin 才能颁发网关凭证。

​
6. 下一步

安全智能体基线

推荐的起始姿态——一个自治级别开关，然后从真实流量调优。

获取 API 密钥

创建你的第一个密钥，并在控制台中附加防护栏或防火墙策略。
范围是控制栈的基础。每个密钥的范围越窄，任何一个智能体被攻破 时的爆炸半径就越小——审计追踪也越清晰，显示每个智能体被授权 做什么。