9. 调用方与 API 密钥

完整版章节。内容按 2026.10 主线代码与运行环境界面核对；具体入口以当前许可、账号权限和交付环境为准。

返回概览 · 完整版目录 · 下载完整 PDF

本章内容：本章面向租户管理员和负责对接业务系统的开发、运维人员，说明一次模型调用经过的三道判断、用什么凭据调用网关、API 密钥从签发到轮换、禁用、删除的完整生命周期，以及密钥挂靠的「客户端」是什么、调用方身份在记录里如何呈现、个人归属与公共归属有什么区别。

成员在自己的工作台上创建密钥、复制接入配置的操作见第 8 章；各协议的路径、请求头写法与统一错误格式见第 10 章；授权的可用范围与配额配置见第 7 章。

9.1 一次调用经过的三道判断

网关收到请求后依次判断三件事，任一环节不通过就拒绝，并在响应中给出对应的错误原因：

1. 认证：调用方是否携带有效凭据，网关据此确定「是谁在调用」。凭据无效时返回 401。
2. 授权：调用方能否使用所请求的模型——由包含该模型的模型分组的可用范围决定，同时受密钥绑定分组的限制。不通过时返回 403。
3. 额度与流量：模型名是否属于这把密钥所属的服务（不属于返回 404）、额度池是否还有余量、是否命中流量规则（限速与超限返回 429、400、413）。

三道判断都通过后，请求才被转发到上游供应商。每次已识别出调用方的请求，无论放行还是被拒绝，都会记入「运行总览 › 请求」，可按「接入凭据」或发起人筛选；凭据本身无效、无法归属到任何调用方的请求不进入请求记录。

9.2 凭据与调用方身份

9.2.1 网关接受的凭据

模型网关只接受模型 API 密钥。密钥是一段以 lp_ 开头的字符串，由成员在工作台创建，绑定一个模型分组与一个计费归属；持有人、可调用的模型、计费去向、当前状态，都在密钥详情里能查到。

工作台的登录会话不能用来调用模型接口；「个人设置 › 访问密钥」（AccessKeyId / SecretAccessKey）用于签名调用平台管理接口，也不能调用模型网关。这两类凭据与模型 API 密钥互不通用，排障时先分清请求用的是哪一种。

9.2.2 调用方身份从哪来

调用方身份只来自平台的认证结果：网关凭请求头里的密钥查出这把密钥的所有者，把它作为发起人记入调用记录。请求体中或自定义请求头里自行声明的用户身份不参与身份判定。

因此调用记录里看到的「发起方类型」「发起人」「发起人邮箱」「接入凭据」四项，反映的是密钥持有人，而不是某次请求自称的使用者。按人核算用量、按人排查问题时都以这四项为准。

注意：客户端自带的、非平台约定的自定义请求头会被原样转发给上游模型供应商。不要把内部用户标识、手机号、会话令牌一类的信息放在自定义请求头里传递。

9.3 个人归属与公共归属

密钥的「计费归属」决定它的用量算在谁头上、占用哪个额度池，也决定谁能创建这种密钥。常见归属分两类：

你会看到：同一成员在同一模型下可以同时创建个人归属与公共归属的密钥；在「模型用量」的「计费归属」占比里，个人、公共、部门各自的消费分开统计。

注意

• 归属在创建时确定，之后不能更改。需要换归属时请新建密钥、切换业务，再撤销旧的。
• 公共归属被多个业务共用时，一个业务的突发流量会消耗掉其他业务的额度。互不相关的业务应各自使用独立的密钥，必要时请管理员为单把密钥单独设置额度池。
• 个人专属归属的密钥不能转移给其他成员。人员调岗或离职时，由接任者以自己的身份重新创建。

9.4 查看并管理已签发的密钥

适用场景：业务系统报错需要确认密钥状态；交接时盘点有哪些密钥在跑、分别挂在哪个服务上；怀疑某把密钥泄露，需要核对它最近的调用。

前提：以租户管理员登录管理后台。新建密钥的入口只在成员工作台，管理后台不提供新建。

操作步骤

1. 进入「管理后台 › 组织与权限 › 模型分组 › API 密钥管理」页签。
2. 在搜索框中输入名称或前缀，或用「筛选」按状态、模型分组、调用方过滤。
3. 点击一把密钥打开详情抽屉。

你会看到

列表显示「名称」（含密钥前缀）、「状态」「模型分组」「计费对象」（含是否配置了额度池）、「调用方」「累计消耗」（费用、Token 与调用次数）和「创建时间」。

详情的分区如下：

密钥状态含义

注意

• 业务系统报错时先看「可用状态」：额度状态为「已用尽」说明额度池没余量；密钥状态正常但可用状态显示不可用，通常是持有人已不在模型分组的可用范围内，或授权已到期。
• 界面不提供 IP 或网段白名单。需要限制来源网段时，由管理员在流量规则中按「客户端 IP 网段」条件实现。

9.5 轮换密钥与宽限期

适用场景：定期更换密钥，或业务系统迁移、交接时需要不中断地换一把新密钥。

前提：以租户管理员登录；宽限期在「系统设置 › 全局设置 ›「账号与会话安全」页签 › 安全策略」中设置，默认 24 小时，可调整。

操作步骤

1. 在「API 密钥管理」中打开目标密钥详情，点击底部「轮换密钥」。
2. 确认框说明「将签发新密钥。旧密钥在租户安全策略配置的宽限期内仍可用（默认 24 小时），新密钥同样加密保存，本人与管理员之后仍可在密钥列表中查看。」点击「轮换密钥」。
3. 页面弹出「新 API 密钥」，并标明旧密钥的失效时刻（例如「旧密钥将于 2026/10/23 02:16:24 失效」）。复制新密钥。
4. 在宽限期内把业务系统切换到新密钥，并验证调用正常。

你会看到

• 列表中同一条记录的前缀变为新前缀，计费归属、额度池、所有者与历史用量保持不变。
• 宽限期内新旧密钥都能调用成功；宽限期结束后旧密钥失效，调用返回 401。
• 在「运行总览 › 请求」中按新前缀筛选，可以看到业务流量已经切到新密钥。

注意

• 怀疑密钥泄露时不要用轮换处理：旧密钥在宽限期内仍然有效。此时应直接禁用（见 9.6）。
• 切换窗口要短于宽限期。业务系统有多处配置引用同一把密钥时，逐处替换并用新前缀核对流量，确认全部切完后再让宽限期自然结束。
• 成员不能在工作台轮换密钥；成员自行更换时，先创建新密钥并完成切换验证，再在「首页 › 模型与凭据 › API keys」中「撤销」旧密钥（见 8.4 节）。

9.6 禁用与批量禁用

适用场景：密钥泄露、业务下线、人员交接后需要回收访问能力。

操作步骤（单把密钥）

1. 核对后确认，列表中状态随即变化。

操作步骤（批量）

1. 在列表中勾选多把密钥，工具栏出现「批量禁用」。管理台不删除成员的密钥，删除由密钥所有者在工作台自行操作。
2. 点击后在确认框中核对受影响的密钥与所属成员。
3. 确认后，被勾选的密钥状态变为「已禁用」；未勾选的密钥不受影响。

你会看到

• 禁用后约一分钟内生效，期间同一把密钥的新调用被拒绝；其他密钥的调用不受影响。
• 删除后该密钥立刻不可用，使用它的调用返回 401 并提示凭据无效或已过期。
• 已经产生的调用记录、用量与审计记录全部保留，删除密钥不会删除历史数据。

注意

• 禁用与删除的效果都是「后续调用被拒」，区别在于能否恢复：删除不可逆，禁用也不能在详情里重新启用。需要恢复调用时，只能重新签发一把密钥。
• 密钥被禁用后，调用返回的是 403「无权限」，与「不在可用范围内」的表现相同。业务系统看到 403 时，应先到「API 密钥管理」核对这把密钥的状态，再判断是不是授权问题。
• 应急处置建议顺序：禁用泄露的密钥 → 在「运行总览 › 请求」中按该前缀查泄露时段的调用 → 为业务系统签发新密钥 → 确认新密钥调用正常。不要先删后查，删除后按前缀筛选会失去对照。
• 如果禁用后仍有请求成功，先确认是不是业务还在用另一把密钥，或该请求恰好命中了宽限期内的旧密钥。

9.7 客户端的含义

适用场景：同一个工具在多台机器、多个项目上使用；需要按工具区分数用量与会话。

前提：已在工作台「获取 API 密钥」时选择新建客户端，或在「洞察 › 我的客户端」中创建（见第 8 章）。

客户端的含义：客户端代表一个具体的工具实例——例如某台电脑上的 Claude Code、某个项目里的 Codex。把 API 密钥挂到客户端后，平台可以按客户端统计用量与会话、在运行总览里按客户端名称筛选请求，并在客户端停用时单独处理它，不影响其他工具。

密钥与客户端是多对一的关系：一把密钥挂在一个客户端上，一个客户端下可以有多把密钥。创建密钥时「挂到哪个客户端」可选 Claude Code、Codex、Grok、OpenCode、婉儿、通用观测协议等类型；只有事先指定了类型，调用记录里才显示对应的客户端名称，未指定或与实际使用的工具不一致时显示为「未知客户端」。

注意

• 客户端类型只用于标识与统计，不影响密钥能否调用。选错类型不会导致调用失败，但会让按客户端的统计失真。
• 新建客户端时给出的观测上报配置里，上报密钥与模型 API 密钥是两回事：前者用于上报链路与日志，后者用于模型调用，轮换其中一项不影响另一项。
• 同一把密钥被多个客户端共用时，记录只能体现密钥层面的归属。需要区分具体工具时，为每个工具各建一把密钥。

9.8 认证方式与拒绝语义

适用场景：自建客户端接入前，确认该用哪个请求头；调用被拒时，判断是凭据问题还是授权问题。

各协议的鉴权请求头

注意：OpenAI 兼容路径只认 Authorization: Bearer。在 OpenAI 路径上使用 x-api-key 会返回 401，即使密钥本身有效。同一个请求不要同时携带两种取值不同的凭据。

被拒绝时的表现

三种协议各自用自己原生的错误信封返回，reason 字段里的原因码一致，可用来区分问题类别：

错误信息中不包含上游地址、上游密钥或内部堆栈。

9.9 在调用记录中核对调用方

适用场景：需要确认某次调用是谁、用哪把密钥发起的，或者要核对某个时段某把密钥被用了多少次。

操作步骤

1. 进入「管理后台 › 观测中心 › 运行总览 › 请求」。
2. 在搜索框中按发起人或接入凭据筛选，或用「筛选」按时间范围、状态、模型分组等条件收窄。
3. 点击一行打开请求详情，查看「概要」页签。

你会看到

「概要」页签按两组信息呈现身份与请求：「身份归属」列出「发起方类型」（API 密钥调用）、「发起人」「发起人邮箱」、「客户端识别」、「接入凭据」（密钥前缀）、「客户端 IP」；「调用对象」列出「事件类型」「请求造型」「对象类型」「调用对象」（如模型名）。

注意

• 「发起人」来自密钥的所有者，与请求里自带的任何用户标识无关。用同一把密钥发起的调用，发起人只有一位。
• 「客户端识别」为「未知客户端」时，说明创建密钥时没有指定客户端类型，或实际使用的工具与创建时选的类型不一致。这不影响调用，只影响按客户端的统计。
• 需要核对的请求较多时，先在列表页导出结果，再按接入凭据分组统计，比逐条点开更快。

9.10 鉴权问题定位

能力说明

---

上一章：8. 成员使用模型 · 下一章：10. 调用接口