接入供应商与测试连接
当前账号管理员在工作空间的 自带密钥（BYOK） 页面，把自己在服务商处的 API Key 接入为一个 BYOK 通道。编辑器分「服务商与计费方式」「接入凭证」「模型与费用」「使用配置」四步，保存前用 测试连接 确认每个凭证都能访问服务商。保存后几秒内同步到网关，工作空间内所有 API Key 都可以通过它调用所选模型。
开始之前
- 权限：只有当前账号管理员能看到和管理这个页面；普通成员看不到菜单，但可以用自己的 API Key 调用已配置好的 BYOK 来源。
- 准备：服务商的 API Key；接入自定义服务商时，还需要 Base URL 和接口类型。接入 Coding Plan 前先阅读API 按量服务与 Coding Plan。
- 数量：同一工作空间中，每个服务商通道只能接入一个 BYOK，已接入的服务商卡片会变灰；一个 BYOK 下可以添加多个 API Key。个人版账号最多创建 3 个 BYOK（所有工作空间合计）。
点击 添加自带密钥(BYOK) 打开编辑器。完成一步后点 下一步，已完成的步骤可以随时点开回看。
第 1 步：服务商与计费方式
| 选项 | 说明 |
|---|---|
| 「模型官方服务商」 | 平台认定的官方模型服务商，地址和可选模型由平台维护。OpenAI、Anthropic 等不在列表中的服务商，用自定义服务商接入 |
| 「自定义服务商」 | 接入聚合平台、企业代理或列表外的服务商，填写「服务商名称」「接口类型」「Base URL」。创建过的自定义服务商会作为卡片保留在列表中 |
| 计费方式 | 「API 按量计费」或「订阅计费」，区别见API 按量服务与 Coding Plan |
| 「当前接入配置」 | 显示所选计费方式对应的 Base URL。内置服务商的地址只读，自定义服务商可以修改 |
自定义服务商的「接口类型」决定 Base URL 的写法：
| 接口类型 | Base URL 示例 |
|---|---|
| OpenAI 兼容 | https://provider.example/v1 |
| Anthropic 原生 | https://provider.example/v1（网关会在后面拼接 /messages，所以要带 /v1；编辑器的占位示例没有 /v1，以本表为准） |
| OpenAI Responses API | https://provider.example/v1 |
图 1：第 1 步选择服务商和计费方式，并核对「当前接入配置」中的 Base URL。 截图为演示数据，点击图片可查看原图。
第 2 步：接入凭证
每行是一个 API Key，点 添加其他账户凭证 增加一行：
| 列 | 说明 |
|---|---|
| 「优先级」 | 1、2、3…，数字小的先尝试 |
| 「启用」 | 关闭后该凭证不参与调用 |
| 「凭证备注」 | 便于识别，例如「生产主凭证」 |
| 「API Key」 | 服务商密钥。已保存的凭证显示「留空保持原密钥」，不回显明文 |
| 「连接检测」 | 点 检测 单独测试这一行 |
| 「用量与费用限额」 | 仅「API 按量计费」显示，见BYOK 费用与凭证管理 |
| 「顺序」 | 用上移、下移调整优先级，保存后生效 |
- 网关在同一通道内按优先级尝试凭证，前一个失败或已达限额时换下一个，规则见失败重试与备用模型。
- 多数服务商按上游账户限制并发，同一账户多建几个 Key 不会提高总并发；需要更高并发时，添加不同账户生成的 Key。
- 新添加的凭证保存后均为启用状态。需要先停用的，保存后再编辑关闭「启用」。
图 2：第 2 步按优先级管理凭证，已保存的密钥留空即保持不变。 截图为演示数据，点击图片可查看原图。
第 3 步：模型与费用
- 内置服务商：表格列出平台为该通道发布的模型，标注「系统内置，不需要映射」。新建时默认全选，取消勾选不需要的模型。「API 按量计费」时显示输入、输出刊例价和「Channel 价格折扣（%）」（100 表示原价）；刊例价显示「待补充」的模型不能保存，请取消勾选。
- 自定义服务商：点 获取服务商模型列表，把上游模型对应到系统模型，见模型映射与来源配置。
- 订阅计费：填写「订阅金额」「币种」「周期」「开始日期」。
刊例价乘以折扣就是该通道在「最低价」排序中的价格，也用于估算 BYOK 费用。
第 4 步：使用配置
| 开关 | 效果 |
|---|---|
| 「优先使用此 Channel」 | 所选模型优先走这个通道，失败后照常回退到其他通道和默认模型 |
| 「仅用此 BYOK」 | 所选模型只使用这个通道的 BYOK 凭证，不使用平台凭证、其他通道或默认模型，全部失败即结束。通过虚拟模型或 lyrouter/auto 调用时，被限定的模型失败后仍会尝试下一个候选模型，但整个请求不再回退到默认模型。开启后「优先使用此 Channel」随之开启并置灰，模型广场中该通道的平台来源显示「仅允许 BYOK」 |
| 「请求头适配」 | 按平台维护的规则调整发往该服务商的请求头，上游对请求头有特殊要求时开启 |
这两种偏好按模型生效：同一工作空间里，一个模型只能由一个 BYOK 设置「优先」或「仅用」。它们优先于多渠道选路策略，见通道选择与路由策略。
图 3：第 4 步区分优先使用此 Channel 与仅用此 BYOK。 截图为演示数据，点击图片可查看原图。
测试连接
- 底部 测试连接 测试全部凭证，「连接检测」列的 检测 只测一行。
- 测试用该凭证读取服务商的模型列表，内置服务商使用「当前接入配置」中的地址。每行显示「连接正常 · N ms」或「鉴权失败」，底部汇总「测试完成：N/M 个凭证可用」。
- 「鉴权失败」包含所有失败原因：Key 无效、地址或接口类型不对、网络不通，或服务商没有模型列表接口，请逐项核对。
- 测试只用于提示，不阻止保存。有未测试或测试失败的凭证时，需要在「使用配置」中勾选「我已了解连接测试失败或被跳过，仍确认保存此配置」。编辑已有 BYOK 时，本次没有重新测试的凭证也算未测试。
保存与验证
点击 保存配置，提示「自带密钥(BYOK)配置「名称」已保存，正在后台健康检查…」后回到列表。新增的凭证会自动检测一次，结果显示在「状态」列。所选模型会在模型广场获得 BYOK 来源并默认开通。
用该工作空间的 API Key 调用一次所选模型，环境变量的设置见完成第一次模型调用：
curl "$LYROUTER_BASE_URL/v1/chat/completions" \
-H "Authorization: Bearer $LYROUTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"deepseek/deepseek-v4-pro","messages":[{"role":"user","content":"ping"}]}'
在请求日志中，这次调用的「服务商」旁带「BYOK」标记；日志详情「路由追踪」的「命中上游」中，来源显示「用户」。
保存失败的常见提示
| 提示 | 处理 |
|---|---|
| 以下模型暂无运营刊例价，无法保存：… | 取消勾选列出的模型 |
| 请完成自定义服务商模型映射 | 为每个已选上游模型选择系统模型 |
该 Channel 已绑定 BYOK 凭证组；同一 Provider 的其他 Channel 仍可独立绑定 |
本工作空间已接入过这个服务商，在列表中编辑原有 BYOK |
BYOK group limit reached (max 3 for personal tier) |
个人版 BYOK 数量已满，删除不用的 BYOK |
channel_policy_conflict |
另一个 BYOK 已对相同模型开启「优先」或「仅用」，先关闭其中一个 |
routing policy requires selected models and an active BYOK credential |
「仅用此 BYOK」需要至少一个启用的凭证 |
model is unavailable for text chat completions |
映射的系统模型不是文本对话模型，见模型映射与来源配置 |
the selected model has no active operations pricing strategy: <模型> |
该模型没有可用于 BYOK 按量计费的价格，取消选择或联系支持 |
管理已有 BYOK
列表每行的操作按钮依次是编辑、启用 / 停用、删除。停用后立即不再接收新请求，进行中的请求不受影响，可以随时重新启用；删除需要输入服务商名称确认并点击 永久删除，已产生的用量和日志保留。替换密钥、调整顺序和设置限额，见BYOK 费用与凭证管理。