跳转到主要内容
你已保存一个防护栏，并且你想让某个 特定的 API 密钥被它筛查——而不是整个工作区。这正是 按 API 密钥设置防护栏绑定的用途：在密钥上设置 guardrail_id， 该密钥发出的每一次 /v1/* 调用都会在下一次请求时被筛查， 无需重新部署，也无需修改 SDK。 本页只涵盖绑定——如何绑定、解析如何选出生效的策略，以及 关闭开关做什么。规则类型、动作和阶段请见 防护栏参考。

​
1. 用 guardrail_id 按 API 密钥绑定防护栏

防护栏是工作区级别的，但执行是按密钥决定的。每个 API 密钥都带有一个 guardrail_id 字段。让它指向某个防护栏，那个密钥——也只有那个 密钥——就会被该策略筛查。 这使得一个工作区可以在不同密钥上运行不同的策略：
  • 一个生产密钥绑定到严格的 pii-blocker，
  • 一个预发密钥绑定到较轻的 flag-only 策略，
  • 一个内部密钥不绑定任何东西。
绑定关系存在于网关的密钥上，因此编辑防护栏会在 绑定密钥的下一次请求时切换它。你的应用继续像以前一样调用 https://api.orcarouter.ai/v1/chat/completions。
中继密钥（sk-orca-…）是你的应用发送的东西。把防护栏 绑定到它是由你的会话鉴权的控制台 / token API 操作——你 永远不会用中继密钥本身去配置防护栏。

​
2. 在控制台中绑定

从控制台配置绑定（受角色门控：编辑密钥和 防护栏需要 Developer+）。
1

打开密钥

前往 /console/token，创建或编辑你想筛查的 API 密钥。
2

选择防护栏

在密钥编辑器中，从 Guardrail 下拉菜单选择你的防护栏。 这会在密钥上设置 guardrail_id。
3

保存

绑定在该密钥的下一次请求时生效。无需重新部署。
之后，用绑定密钥发出的普通中继调用会被自动筛查： 
curl https://api.orcarouter.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-orca-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [
      {"role": "user", "content": "Reply to jane@acme.com please"}
    ]
  }'
如果绑定的防护栏在输入阶段脱敏 email，上游模型看到的是 [EMAIL] 而永远看不到该地址——同一个调用，无需修改客户端。
要筛查工作区中的每一个密钥而不是单个，请将防护栏设为 工作区默认值，而不是逐个绑定密钥。参见 账户默认防护栏。

​
3. 解析如何选出生效的防护栏

在每一次请求上，网关按如下顺序精确解析出一个生效的 防护栏（或无）：
如果密钥的 guardrail_id 指向一个防护栏，并且该防护栏 存在，并且已启用，则它适用。明确绑定是 权威的——它永不静默回退到工作区默认值。
如果密钥没有绑定（guardrail_id 为 0 / 未设置），则 工作区已启用的默认防护栏适用（如果设置了的话）。
不执行。请求与从未启用该功能的工作区字节相同 ——没有拦截、脱敏或记录。
该决策是热路径上的一次索引查找，并且是 fail-open：如果 解析遇到瞬时错误，网关会降级为不执行，而不是让请求 失败。安全性降级；可用性得以保留。

​
4. 关闭开关：禁用绑定，不回退

这是人们容易忽略的部分。一个明确的密钥绑定本身就是 权威——因此禁用绑定的防护栏会为该密钥关闭执行，并且它 不会回退到工作区默认值。
密钥状态谁筛查请求
guardrail_id → 已启用的防护栏该防护栏
guardrail_id → 已禁用的防护栏无（不回退）
guardrail_id → 已删除 / 不存在无（不回退）
guardrail_id = 0 / 未设置工作区默认值（如有）
禁用绑定的防护栏是该密钥的关闭开关，而不是降级到 默认值。如果你想让某个密钥回退到工作区默认值，请清除 它的绑定（将 guardrail_id 设为 0）——不要只是禁用它指向的 防护栏。
这是与防火墙的一个刻意差异：一个绑定了 已禁用防火墙策略的密钥会回退到工作区默认防火墙策略， 而一个被禁用的绑定防护栏解析为无。同样的思路，相反的回退—— 参见防护栏 vs. 防火墙。

​
5. 解绑或清除绑定

要停止用某个特定防护栏筛查一个密钥，你有两种结果不同的 不同操作：
  • 清除绑定——将密钥的 guardrail_id 设为 0。该密钥现在 解析为工作区默认值（如果存在），或解析为无。
  • 禁用防护栏——将防护栏的 enabled 关闭。每个明确绑定到 它的密钥现在都解析为无（按 §4），而那些作为工作区默认值 依赖它的密钥会下沉到不执行。
当你想让密钥落在工作区基线上时选择清除；当你想在它作为 命名绑定的所有地方暂停该策略时选择禁用。

​
6. 一个被筛查的请求会（和不会）花费什么

一旦防护栏解析出来，它的规则就决定请求。对于绑定密钥， 值得了解的两个结果：
  • 一个 block 返回 HTTP 400，错误码为 guardrail_blocked， 并指明触发的防护栏和规则。它不消耗配额——输入阶段的 拦截在计量之前触发，输出阶段的拦截会退回预先扣除的配额—— 并被标记为 skip-retry。
  • 一个 mask 会把匹配项改写为一个带类型的标签（例如 [EMAIL]）， 并放行净化后的请求；上游模型永远看不到原始内容。
完整的响应形态见 guardrail_blocked 错误 页，输出规则在流式响应上的行为见 流式覆盖。

​
7. 接下来去哪里

创建你的第一个防护栏

构建你将绑定到密钥的策略。

账户默认防护栏

一次性筛查工作区中的每一个密钥。

防护栏参考

规则类型、动作、阶段、PII、judge、grounding。

密钥、策略与工作区

绑定如何在网关范围内限定。