跳转到主要内容
单个 API 密钥可以触及你的工作区有权使用的每一个模型。这对一个 控制台会话很方便，对一个长寿命智能体却很危险：一个被提示注入 的、持有不受限密钥的智能体可以悄悄从 gpt-4o-mini 切换到你能 访问的最贵模型，或切换到一个你从未批准其数据处理方式的模型。 修复方法是一个按密钥的模型允许列表。每个密钥携带一个 model_limits 字段（由 model_limits_enabled 门控）。当它开启时， 一个对任何不在列表上的模型的请求会在网关被拒绝——在选择 通道之前、在任何东西发往提供商之前。
这是 密钥对象 上的一个约束。它与 密钥的 IP 允许列表、花费上限、到期，以及附加的防护栏 / 防火墙 策略组合在一起——每一项都独立地缩小该密钥。

​
1. 为什么按 API 密钥限制模型访问

模型选择是一个权限杠杆。一个能调用任何模型的密钥可以被引导至：
  • 成本暴涨——切换到一个高端模型会成倍增加每 token 的账单。
  • 能力蔓延——一个为小模型限定范围的任务被路由到一个能做 远超你意图之事的前沿模型。
  • 合规漂移——把流量发往一个你尚未为某个给定数据类别清审的 模型家族。
把一个密钥限制到一个智能体实际需要的一两个模型，一举关闭这 三者。它是防火墙允许列表工具在模型轴上的等价物——智能体只能 触及你点名的，别无其他。

​
2. 两个字段

模型限制作为一对存在于密钥上：
字段类型含义
model_limits_enabledbool主开关。当为 false 时，密钥可触及工作区允许的每一个模型。
model_limitslist模型名称的允许列表。仅当 model_limits_enabled 为 true 时才有意义。
这两个字段是独立的，而组合很重要： model_limits_enabled = true 搭配一个空列表意味着该密钥 无法触及任何模型——每个请求都会被拒绝，并提示 “This token has no access to any models.”。只有在你点名了至少 一个模型之后才打开这个开关。

​
3. 在密钥上设置它

在控制台密钥编辑器（/console/token）中配置模型限制， 和你设置密钥其他约束的地方相同。创建或编辑一个密钥需要 Developer 角色或以上。
  1. 打开密钥（或 Create key）。
  2. 启用 Model limits。
  3. 挑选这个密钥可以调用的模型——输入以过滤工作区的可用模型。
  4. 保存。变更在该密钥的下一次请求时生效——无需重新部署、 无需密钥轮换。
一个只应触及一个廉价模型的定时汇总器最终会有一个恰好只有一项 条目的允许列表： 
model_limits_enabled: true
model_limits:         ["openai/gpt-4o-mini"]
从那时起，该密钥被钉到 gpt-4o-mini。来自这个密钥的请求上任何 其他模型名称都会被拒绝——没有回退到默认模型，也没有静默降级。
在同一个密钥上把模型限制与一个 credit_limit_usd 上限配对。 模型列表限定一个失控循环能触及哪个模型；花费上限限定它在 密钥停止工作之前能烧掉多少。两个独立的天花板，都在网关 执行。参见 配额上限与到期。

​
4. 一次被拒绝的请求的表现形式

当 model_limits_enabled 开启且一个请求点名了一个列表之外的 模型时，网关以 HTTP 403 和一个 OpenAI 形态的错误体中止该 请求： 
{
  "error": {
    "message": "This token has no access to model claude-opus-4-8 (request id: 2024...abc)",
    "type": "orcarouter_api_error",
    "code": ""
  }
}
该拒绝的关键性质：
该检查在网关仍在选择通道时运行——请求从不触及上游提供商， 因此一个被禁止的模型不消耗模型 token。
在开关开启且允许列表为空的情况下，消息为 “This token has no access to any models”，且每一个请求都被拒绝。这就是 “限制到一个列表” 与 “把密钥完全锁在推理之外” 的区别。
请求的模型名在检查列表之前会被规范化，因此相关变体（例如 thinking 变体）解析为你在允许列表中放入的同一个规范名。 列出控制台向你展示的基础模型名。

​
5. 模型限制 vs. 组权益

两件不同的事情决定一个密钥能否调用一个模型。别把它们混淆：
层范围它回答的问题
工作区权益工作区这个模型对工作区是否可用？
model_limits单个密钥在可用的模型中，这个密钥可以使用哪些？
model_limits 永远只收窄。一个密钥无法利用模型限制去触及一个 工作区自身无权使用的模型——它只能从已被许可的范围中切出一个 更小的允许列表。要给一个密钥不多一分却严格更少，这正是 这个字段的用途。

​
6. 它在最小权限姿态中的位置

模型限制是按智能体密钥配方的其中一行。面向一个自治智能体的 最狭窄而有用的密钥会一次性钉住它的所有轴：
  • model_limits —— 智能体需要的一两个模型（本页）。
  • allow_ips —— 智能体的出口范围，参见 IP 允许列表。
  • credit_limit_usd —— 一个花费天花板，参见 配额上限与到期。
  • expired_time —— 一个自动到期，参见 到期密钥。
  • guardrail_id / firewall_policy_id —— 内容和工具调用 策略，参见 绑定策略到密钥。
当这样一个密钥通过 提示注入 被攻陷时， 影响半径在每一个轴上都被限定——包括攻击者能拿你的预算花在 哪些模型上。
模型限制是密钥上的一个身份约束，而非内容或动作策略。它们不 检查提示词（那是 防护栏）或工具调用 （那是 防火墙）——它们事先决定该密钥 甚至被允许向哪个模型发起请求。

​
7. 下一步

密钥对象

一个密钥携带的每个字段——模型限制、IP 列表、上限、到期， 以及策略附加项——汇于一处参考。

最小权限检查清单

完整的按智能体密钥配方：把每个轴都限定到智能体所需的最小值。

范围、密钥与策略

密钥、防护栏和防火墙策略如何绑定成一个智能体身份。

绑定策略到密钥

把一个防护栏和一个防火墙策略附加到同一个密钥上。
按 API 密钥限制模型访问是你能施加的最廉价的权限控制：一个 允许列表，在网关执行，没有任何被攻陷的智能体能巧言绕过它。