概念说明：API Key、分组与计费
这一页解释你会在控制台里反复见到的几个概念：API Key、分组、渠道、模型、倍率、额度。
理解它们之后，无论用 Codex、Claude Code、OpenCode 还是 GitHub Copilot CLI，配置时都知道每一项在填什么。
一次请求经过哪些环节
你的工具
│ 带上 API Key
▼
API Key（身份识别）
│ 决定用哪个分组
▼
分组（选择渠道 + 决定倍率）
│ 在分组里挑一个可用渠道
▼
渠道（真正连到上游服务商）
│
▼
上游模型（gpt-5、claude-sonnet-4、deepseek-flash…）
│
▼
按用量计费，扣账户余额和令牌额度一句话概括：API Key 证明你是谁，分组决定走哪条路和多少钱，渠道负责真正转发，模型是最终干活的那个。
什么是 API Key
API Key（也叫令牌、Token）是你调用接口时的身份凭证。
- 常见形如
sk-xxxxxxxx，但格式由服务商决定，不一定以sk-开头 - 每个 Key 属于某个用户，可以单独设置额度、过期时间、权限
- 服务端只保存校验所需的信息，完整密钥通常只在创建时显示一次
请求时放在请求头里：
Authorization: Bearer sk-xxxxxxxx密钥只显示一次
创建后多数服务不再回显完整密钥。请立即复制并保存到密码管理器。
如果丢了，只能删除后重新创建。任何拿到这个 Key 的人都能以你的身份消费额度。
为什么要按工具分别建 Key
给 Codex、Claude Code、OpenCode、GitHub Copilot CLI 各建一个独立 Key，好处是：
- 对账：能看出是哪个工具花的钱
- 排障：某个工具出问题，不影响其他工具
- 吊销：某个 Key 泄漏，只删它一个，不用全部重配
创建 API Key 时的字段
下面是创建页里常见的字段，逐个解释。
名称
只是给你自己看的标签，不影响功能。
建议按用途命名，例如 codex-local、claude-code-ci、opencode-笔记本。
分组
决定这个 Key 走哪个分组的渠道、按什么倍率计费。
留空表示跟随你的用户分组。填了就必须是你有权限访问的分组，否则请求会被拒绝（403）。
分组是这一页的重点，下面单独展开讲。
过期时间
- 选 永不过期：在删除前一直有效
- 选具体时间：到期后 Key 自动失效，返回
401
个人本地使用可以不设，团队或 CI 场景建议设置。
数量
一次创建几个 Key。填 N 会生成 N 个同名加随机后缀的 Key，方便批量分发。
通常填 1 即可。
无限配额
- 打开：这个 Key 不单独限额，花的是账户余额
- 关闭：给这个 Key 单独设一个额度，用完后这个 Key 失效
两种额度都会检查
一次请求会同时检查账户余额和令牌额度，任何一边不够都会失败。
无限配额只表示取消令牌这一层的限制，仍然受账户余额约束。 账户余额不足时，即使 Key 开了无限配额，请求也会被拒绝。
额度
关闭无限配额后出现，填写这个 Key 可用多少额度。
单位取决于你的服务配置，可能是金额，也可能是 token 数。
高级设置：模型限制
只允许这个 Key 调用指定的模型。不选表示允许全部模型。可选模型见模型与能力。
适合把不同工具、不同用途的 Key 隔离开，例如只让某个 Key 调 deepseek-flash。
高级设置：IP 白名单
只允许指定 IP 或网段使用这个 Key，支持 CIDR，每行一个。留空表示不限制。
不要过度信任 IP 白名单
IP 白名单依赖网关看到的真实来源 IP；代理、CDN 或公司出口可能改变来源 IP，也可能出现 X-Forwarded-For 处理不当或同出口 IP 共享的情况。请确保网关取到的是真实客户端 IP，不要把它当成唯一的安全手段。
什么是分组
分组是一批渠道 + 一套倍率规则的集合。
一个分组里可以挂多个渠道，同一个模型在同一个分组里可能有多个渠道可用。请求进来后，系统在这个分组里挑一个可用渠道转发。
分组同时决定两件事：
- 走哪些渠道：这个分组里配置了哪些上游
- 按什么倍率计费：同一个模型在不同分组可能价格不同
用户分组 vs 令牌分组
同一个分组名字有两种角色：
| 角色 | 含义 |
|---|---|
| 用户分组 | 你账户所属的分组，决定你默认能用哪些分组 |
| 令牌分组 | 这个 Key 指定的分组，覆盖用户默认值 |
Key 上的分组留空 → 用你的用户分组。 Key 上填了分组 → 用填的那个（前提是你有权限）。
例如你是 default 用户，Key 填 vip，如果 default 用户被允许访问 vip，这个 Key 就按 vip 分组走。
常见分组
| 分组 | 说明 |
|---|---|
default | 默认分组，大多数用户从这里开始 |
vip / svip | 通常是更低倍率或更优质渠道 |
| 自定义分组 | 管理员按渠道、成本或用途自行划分 |
自动分组（auto）
有些服务支持 auto 分组：按顺序依次尝试多个分组，当前分组没有可用渠道时自动换下一个。
对应两个设置：
- 自动分组顺序：按什么顺序尝试哪些分组
- 跨分组重试：当前分组的渠道都失败了，是否继续试下一个分组
适合想要高可用、不想手动切换的场景。
分组不是越多越好
分组越多，计费和排障越复杂。个人使用选一个合适的分组即可，不确定就用默认分组。
什么是渠道
渠道是真正连到上游服务商的那条线，包含：
- 上游地址
- 上游密钥
- 支持的模型
- 所属分组
同一个模型可以有多个渠道，系统会按分组和可用性挑选。
普通用户通常不直接接触渠道，只通过分组间接使用。渠道由管理员配置。
什么是倍率
倍率是计费的乘数。请求最终扣多少额度，由几个倍率共同决定。
| 概念 | 含义 |
|---|---|
| 模型倍率 | 这个模型本身的价格系数 |
| 分组倍率 | 这个分组的整体价格系数 |
| 用户分组倍率 | 针对特定用户分组的覆盖倍率，优先级高于分组倍率 |
| 补全倍率 | 输出 token 相对输入 token 的系数 |
| 缓存倍率 | 命中缓存部分的折扣系数 |
大致公式：
扣费 ≈ 用量 × 模型倍率 × 分组倍率输出 token 会再乘补全倍率，命中缓存的部分乘缓存倍率。
要把倍率落成金额，必须先知道该服务当前使用的基准单价。不同服务的基准单价、计量单位、四舍五入方式和是否区分缓存/推理 token 都可能不同，本文不内置任何平台价格。以下只是算例，数字是假设值：
假设：
- 基准输入单价为
$0.000002 / token - 模型倍率为
1.5 - 分组倍率为
0.8 - 输出 token 的补全倍率为
4 - 本次请求输入
10,000token，输出2,000token，其中缓存命中1,000token - 缓存倍率为
0.25，且缓存命中仍按输入基准单价计费
估算：
输入费用（未缓存） = 9,000 × 0.000002 × 1.5 × 0.8 = 0.0216
缓存输入费用 = 1,000 × 0.000002 × 1.5 × 0.8 × 0.25 = 0.0006
输出费用 = 2,000 × 0.000002 × 1.5 × 0.8 × 4 = 0.0192
估算总额 ≈ 0.0414（以服务商账单为准）真实金额还要以服务商的计费规则、账单精度和最终结算为准。
为什么同一个模型不同分组价格不一样
模型倍率相同，但分组倍率不同，最终价格就不同。
分组倍率越低，同样用量扣得越少。
什么是额度
额度是你能消费的预算。系统里有两层：
| 层级 | 说明 |
|---|---|
| 账户余额 | 整个账户的总预算，所有 Key 共享 |
| 令牌额度 | 单个 Key 的预算上限，可关闭（无限配额） |
一次请求两处都会检查：
- 账户余额不够 → 请求被拒绝
- 令牌额度不够 → 请求被拒绝
- 令牌开了无限配额 → 只检查账户余额
预扣费与结算
流式或长请求通常会先预扣一部分额度，请求结束后按真实用量结算，多退少补。
所以日志里可能先看到预扣金额，随后才是最终金额，这是正常的。
不同服务对以下情况是否计费、计费多少并不统一，以服务商为准：
- 请求失败，但上游已经产生了 token
- 流式请求中途断开，只返回了部分内容
- 客户端超时或主动取消
- 自动重试后只有其中一次成功
- 并发请求占用多笔预扣额度
排查账单时，保留请求时间、模型 ID、请求 ID 和日志里的预扣/结算记录，再对照服务商账单。
额度用尽会怎样
| 情况 | 结果 |
|---|---|
| 令牌额度用尽 | 这个 Key 通常暂时不可用，常见返回 401；是否恢复取决于服务实现 |
| 账户余额不足 | 请求被拒绝，常见返回 401、402 或其他状态 |
| 令牌过期 | 这个 Key 失效，返回 401 |
| 令牌被禁用 | 这个 Key 失效，返回 401 |
额度耗尽后的恢复规则
令牌额度耗尽后，是否能通过调高额度、充值或修改令牌恢复，以服务商实现为准。
如果服务支持调高令牌额度，通常不需要重建 Key；如果服务把额度耗尽视为令牌永久失效，或控制台不允许修改该令牌，则需要删除后重新创建，并更新所有客户端配置。
恢复后是否立即生效、是否需要重启客户端，也以服务商为准。不要通过反复重试来判断，先看控制台和日志。
安全与最佳实践
- 不要把密钥写进会提交到 Git 的文件，例如项目里的
settings.json - 优先用工具的独立凭据文件或环境变量，例如 OpenCode 的
/connect - 按用途、按工具分别建 Key
- 定期轮换密钥
- 用模型限制和 IP 白名单收窄权限
- 发现泄漏立刻删除重建，不要只改配置
常见问题
401 Unauthorized
密钥没带上、填错、过期、被禁用或额度用尽。检查 Key 是否完整，以及是否还在有效期内。
403 Forbidden
通常是权限问题：Key 指定的分组你没有权限访问，或者 IP 不在白名单里。
404 Not Found
Base URL 写错，或带了多余路径。参考选择接入方式。
模型不存在
模型名不在当前分组的可用列表里。先用 /v1/models 查真实可用模型，再检查分组是否有这个模型。
余额还有但请求被拒绝
可能原因：令牌额度用尽、令牌过期、分组无权限、模型被限制、IP 不在白名单。
按这个顺序排查：确认当前凭据 → 看令牌额度 → 看分组权限 → 看模型限制 → 看 IP 白名单。
/status 不是通用 HTTP 接口
/status 是 Claude Code 等客户端里的斜杠命令，用于查看该客户端当前读取到的配置和凭据，不是所有兼容网关都提供的通用 HTTP 接口，也不是本文档定义的接口。其他工具请查看自身的诊断命令或控制台。
速查表
| 概念 | 一句话解释 |
|---|---|
| API Key | 你的身份凭证，常见形如 sk-xxxxxxxx，但不一定以 sk- 开头 |
| 分组 | 一批渠道 + 一套倍率规则 |
| 渠道 | 真正连到上游服务商的那条线 |
| 模型 | 最终处理请求的模型 |
| 倍率 | 计费的乘数 |
| 额度 | 你能消费的预算 |