BYOK 自带密钥怎么接：用自己的供应商账号走 OpenRouter

先说这件事是给谁准备的

有一类很具体的处境：你在某家供应商那边已经有账号了——可能是公司统一签的，也可能只是你早就把配额和限流调好了不想再折腾一遍。现在你想用 OpenRouter 这一层统一收口调用，但不想把已有账号的关系推倒重来。

OpenRouter 官方文档《BYOK》页（openrouter.ai/docs/guides/overview/auth/byok）写明它支持两种付费路径：用 OpenRouter credits，或者带上你自己的供应商密钥（BYOK）。差别文档写得直白：用 OpenRouter credits 时，你对每家供应商的 rate limit 由 OpenRouter 管理；用自己的密钥则是通过自己的供应商账号直接控制 rate limit 与成本。文档还写明，供应商密钥会被加密存储，并用于所有路由到该供应商的请求。

这篇只讲两件事：密钥配置的流程，以及配上之后它在多大范围内生效。后者是最容易想当然的部分——很多人默认「我配了 key，那我指定的路由顺序就该照办」，而文档明写的恰恰相反。

前置条件

这一段别跳过，因为 BYOK 的配置层级跟大多数人预期的不一样。

它是 workspace 级的，不是单个 API key 级的。 文档给出的管理入口是 workspace 的 BYOK 设置页（形如 openrouter.ai/workspaces/default/byok），每家供应商还有自己的详情页（形如 openrouter.ai/workspaces/default/byok/openai）。也就是说，你得先有一个 workspace，并且有权限改它的设置。文档没有说明具体需要什么角色或权限位，这一点核不出来，别听人瞎猜。

BYOK 本身不是白用的。 文档写明，通过自带密钥调用仍会从你的 OpenRouter credits 里扣一笔费用，计费基准是「同一模型/供应商在 OpenRouter 上正常调用会花多少钱」的一个比例；同时有一份免费额度，文档明确说这份额度取决于你的套餐，并且按 list-price 推理成本计量，不按请求数计量。具体比例与额度数字本文不写，请以官方定价页为准。要记住的是两点：BYOK 不等于绕开 OpenRouter 计费；额度耗的是按目录价折算的推理成本，所以大量小请求和少量大请求消耗得完全不是一回事。

你得先在供应商那边把凭据和权限准备好。 后面第三节按 Azure、AWS Bedrock、Google Vertex 分别说，这三家的凭据形态各不相同。

配置流程：三家的凭据长什么样

文档只给了凭据的结构，没有给出任何需要在你本机执行的安装命令，所以这里不存在 Windows 与 Linux/macOS 的差异。唯一一条 shell 命令出现在 Vertex 的 Batch 场景里（见下），那是 Google Cloud CLI 的命令，官方文档只给了单行写法，没有区分 Windows 与 Linux/macOS，也没有说明各平台换行续行符的差别，所以本文照原样按单行抄录，Windows 的 PowerShell / CMD 侧也按这一行执行，不要自行拆行。

Azure

文档写明 Azure 有两种资源类型，分别对应不同域名：Azure AI Foundry 的资源在 *.services.ai.azure.com，走模型目录，不需要按模型建 deployment；Azure OpenAI 的资源在 *.openai.azure.com，需要显式的按模型 deployment。

文档推荐的是 Foundry 配置：

[
  {
    "api_key": "your-azure-api-key",
    "resource_name": "your-resource-name",
    "resource_type": "ai_foundry"
  }
]

三个字段的语义：api_key 是 Azure 门户里「Keys and Endpoint」下的密钥；resource_name 是你的资源名，也就是 endpoint URL 里的子域名部分；resource_type 取 "ai_foundry" 或 "openai"，省略时默认为 "openai"。这个默认值值得记一下——如果你用的是 Foundry 资源却漏写了 resource_type，它会按 Azure OpenAI 处理。这是文档写明的默认值，随版本可能变动，配置前建议回官方文档确认一次。文档同时写明，Foundry 这一份配置对你 Azure 资源里可用的模型都成立，不需要按模型再做一遍设置。

另一种是按 deployment 配置，文档把它标为 Legacy（旧式），每条需要 endpoint_url（含 /chat/completions 和 API 版本的完整地址）、api_key、model_id（你在 Azure 里的 deployment 名字）、model_slug（你希望这把密钥对应的 OpenRouter 模型标识）。文档写明两种配置可以混在同一个数组里，当模型 slug 匹配上时，按 deployment 的配置优先。

AWS Bedrock

两条路。一是 Bedrock API key，直接把密钥当字符串填进去即可。这里有个坑文档专门点了名：Bedrock API key 绑定在特定 AWS 区域上，不能用它切换区域；要跨区域就得走第二条路。

二是传统 AWS 凭据，JSON 形态：

{
  "accessKeyId": "your-aws-access-key-id",
  "secretAccessKey": "your-aws-secret-access-key",
  "region": "your-aws-region"
}

权限侧，文档写明至少需要 bedrock:InvokeModel，流式响应还需要 bedrock:InvokeModelWithResponseStream。文档同时建议为对接 OpenRouter 单独创建权限受限的 IAM 用户。

Google Vertex

Vertex 用的是服务账号密钥的 JSON，包含标准的 Google Cloud 服务账号字段，另有两个与 OpenRouter 相关的可选/条件字段：

• region：可选。填 "global" 表示允许请求在任意可用区域运行，也可以填具体区域。
• bucket：只有走 Batch API 的 Vertex BYOK 才需要，用于批处理任务的产物。文档写明它接受 bucket 名（"my-batch-bucket"）或 bucket URI（"gs://my-batch-bucket"，尾部斜杠可选），但不接受带对象路径的写法（"gs://my-batch-bucket/prefix" 会被拒绝）。同步请求会忽略这个字段；而一把没有 bucket 的密钥在你提交 Vertex batch 时会被拒绝。

权限侧文档写明需要 aiplatform.endpoints.predict。Batch 场景另需把 roles/storage.objectUser 授予该 bucket 上的密钥服务账号与 Vertex 的服务代理；代理不存在时，文档给出的创建命令是：

gcloud beta services identity create --service=aiplatform.googleapis.com --project=YOUR_PROJECT

注意这条是 gcloud beta 子命令，属于 Google Cloud CLI 的 beta 通道，照实标出来。上面的字段组合均为按官方文档中的参数语义整理的示例，未经实测，以官方文档与工具的实际输出为准。

生效范围：这才是容易翻车的地方

密钥填进去只是第一步。真正决定「它什么时候会被用上」的，是下面这几条规则。

一、两个分区 + 一个开关

文档写明每把 BYOK 密钥属于两个分区之一：Prioritized（优先，在回落到 OpenRouter 端点之前按顺序尝试）与 Fallback（回落，只在 OpenRouter 端点尝试过之后才按顺序尝试）。默认行为是：两个分区里的密钥全都遇到限流或失败时，OpenRouter 会回落到共享的 OpenRouter 端点。

所以完整的默认尝试链是：Prioritized 分区的各把密钥 → OpenRouter 共享端点 → Fallback 分区的各把密钥。文档举的例子是三把 OpenAI 密钥，两把在 Prioritized、一把在 Fallback，尝试顺序即「第一把 → 第二把 → OpenRouter 端点 → 备用那把」。文档写明密钥可以在供应商详情页上拖拽在两个分区之间移动，同一分区内的顺序也由你定义。

不想让请求落到共享端点上，文档给出的开关是在单把优先级密钥上打开 “Always use for this provider”。代价文档也写清楚了：开启后该供应商的请求只会走你的密钥，密钥耗尽时可能直接报限流错误，换来的是所有请求都确实走你自己的账号。

二、BYOK 会盖过你写的 provider order

这条最反直觉。文档原话是：当 BYOK 密钥与 provider ordering 组合时，OpenRouter 总是优先 BYOK 端点，不管那家供应商在你指定的顺序里排第几；BYOK 端点全部耗尽之后，才按你指定的顺序回落到共享容量。文档还补了一句：目前没有办法改变这个行为。

文档给的例子是这样的请求体：

{
  "provider": {
    "allow_fallbacks": true,
    "order": ["amazon-bedrock", "google-vertex"]
  }
}

假设你只对 Google Vertex 有 BYOK 密钥，实际路由顺序是：Google Vertex（你的密钥）→ Amazon Bedrock（共享容量）→ Google Vertex（共享容量）。也就是说，尽管 order 数组里 Amazon Bedrock 写在前面，带 BYOK 密钥的 Vertex 端点仍然排在最前。上面这些供应商标识是官方文档用来讲解匹配语义的示例值，平台上可用的供应商随时在变，不要当名单用。

三、BYOK 不放宽数据策略

这条是安全侧最要紧的。文档写明：BYOK 端点仍然受你的数据策略约束；自带密钥改变的是用哪个凭据去认证上游请求，不改变你被允许路由到哪些端点。你的供应商级、账号级、guardrail 级数据策略会在 BYOK 端点被创建之前应用，因此 BYOK 只会路由到那些本来就满足策略的端点。

具体到 ZDR：如果你通过 provider.zdr、账号隐私设置或 guardrail 强制了 Zero Data Retention，而某家供应商的端点会保留提示词，那么即便你为它提供了有效的自有密钥，该端点依然不合格——会在你的 BYOK 密钥被考虑之前就被过滤掉；如果过滤完没有剩下合规端点，请求会直接失败。data_collection 类限制同理。

（哪些供应商满足 ZDR 是平台侧的动态数据，不在文档正文里，本文不列名单。）

四、默认不计入预算

又一条容易踩空的默认值：文档写明，BYOK 的推理花费默认不计入 guardrail 的预算，只有 OpenRouter credit 花费才计入。后果是文档自己点明的——即便 BYOK 用量已经很可观，预算看起来仍然离上限很远。

要让它计入，文档给的做法是在该 guardrail 上开启 Include BYOK spend，或通过管理 API 把 include_byok_in_budgets 设为 true。开启后计入的是「假如这次请求没有用你自己的密钥，OpenRouter 本会收取的金额」，与 credit 花费合并计算，合计触顶后 guardrail 拦截请求。文档写明这个开关在所有带预算的 guardrail 上都有，包括 workspace 默认的那个；对没设预算上限的 guardrail 不起作用。

workspace 预算行为一样，但跟 guardrail 分开控制：默认同样不计入，需要在 workspace 的 Budgets 设置里开启 Include BYOK spend，或在 workspace 预算接口上把 include_byok_in_budgets 设为 true。文档特别写明，workspace 这个开关一次性作用于该 workspace 的全部四个周期：daily、weekly、monthly、lifetime。

五、同一家供应商可以配多把密钥，还能加过滤条件

文档写明同一供应商可以配多把密钥，所有匹配的密钥都参与路由，每把密钥会产生自己的一份端点副本，并在整个请求生命周期里固定绑定到那把密钥。某把失败（比如限流或报错）时，会先落到下一把匹配的密钥，然后才回落到共享容量。

每把密钥支持三种可选过滤条件：

过滤条件	作用
Model filter	限定这把密钥只用于指定模型；设了之后，同一供应商的其它模型会跳过这把密钥
API key filter	限定哪些你自己的 OpenRouter API key 可以使用这把 BYOK 密钥，适合按应用或环境隔离
Member filter	限定哪些 workspace 成员可以使用这把 BYOK 密钥，适合让不同成员用不同的供应商账号

文档写明过滤条件在路由之前评估，只有一把密钥的全部启用中的过滤条件都匹配当前请求时它才会被使用；一个都没设则对所有模型、API key 和成员开放。每把密钥还可以起一个可选的名字，方便区分。

把「Always use for this provider」和 model filter 组合起来会得到一个稍绕的结果，文档举了例：密钥 A 带 model filter 且开了「Always use」，密钥 B 不带 filter。落在 A 的 filter 范围内的请求先试 A、失败后试 B，且因为 A 上开了「Always use」，共享容量被跳过；不在 A 范围内的请求只用 B，并可回落到共享容量。也就是说，「Always use」的作用域是这家供应商，而不只是那把密钥。

怎么确认配对了

文档给出的排错入口只有一个：Activity 页面。它写明的步骤是——进入 OpenRouter 控制台的 Activity 页面，找到要排查的那次生成并打开详情，选择 “View Raw Metadata” 以 JSON 形式查看原始元数据，然后在 JSON 里找 provider_responses 字段。

provider_responses 是一个数组，记录路由过程中尝试过的每一家供应商的响应，每一条包含供应商名与 HTTP 状态码。对 BYOK 来说这就是最直接的判据：你的密钥到底被试过没有、试的结果是什么，都在这里。

文档列出的常见状态码含义如下：

状态码	文档给出的含义
400	请求格式对该供应商无效，检查模型与密钥配置
401	密钥无效或已被吊销，去供应商控制台核对
403	密钥没有访问该资源的权限
429	你的供应商账号侧被限流
500	供应商内部错误，通常是对方的临时问题

其中 403 文档给了针对性的排查方向：AWS Bedrock 侧确认 IAM 策略包含 bedrock:InvokeModel 与 bedrock:InvokeModelWithResponseStream、确认目标模型在指定区域的 AWS 账号里已启用、确认访问密钥有效；Google Vertex 侧确认服务账号有 aiplatform.endpoints.predict。文档还建议先在供应商自己的控制台里直接调用一次模型，确认权限本身没问题，再回来排查 OpenRouter 这一侧。

最后提醒一句口径：想验证「请求确实走了我的账号而不是共享容量」，光看 OpenRouter 这边不够，还得去供应商账号侧对一下用量——provider_responses 里能看到的是尝试序列与状态码，它证明不了计费归属。文档没有为这种交叉核对给出专门字段，这一条是通用做法上的建议，不是官方文档内容。BYOK 相关的配置项与默认值随平台迭代变动，以官方文档最新内容为准。

---

本文依据 OpenRouter 官方文档（openrouter.ai/docs）于 2026-08-18 的公开内容整理。 该平台闭源，本文只复述官方文档写明的机制，不推断其内部实现； 我们没有对文中涉及的功能做过实测，因此不涉及界面外观与运行表现的任何描述。 该平台的供应商、模型与路由策略随时变动，文中不列具体供应商名单与模型清单； 价格、额度与限流的具体数值请以官方定价页与用量说明为准。

安全与合规相关做法请结合自身环境评估，本文不构成安全方案建议。