20. 调用方与 API 密钥

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

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

本章内容：本章面向租户管理员和负责对接业务系统的开发、运维人员，说明平台里有哪几类调用方、一次模型调用经过的三道判断、各类凭据分别用在哪里、模型 API 密钥从签发到轮换、禁用、删除的完整生命周期，以及调用方身份在调用记录里如何呈现。

成员自行创建密钥与复制接入配置见第 19 章；各协议的路径、请求头写法与统一错误格式见第 21 章；可用范围与配额见第 7 章；同一场对话的多次调用如何归入一个会话，见第 26 章。

20.1 平台中的调用方

平台不要求管理员维护单独的「消费者」名册。员工、智能体、业务系统都可以成为调用方，在流量规则和调用记录中统称为「调用方」：

在流量规则中按调用方设置条件时，「调用方类型」可选 API 密钥、平台用户、智能体、外部 MCP 服务、工作空间、消费者分组等（见第 26 章）。不同类型约束的流量不同：按「智能体」设置的条件不会约束直接使用 API 密钥访问网关的流量；按「API 密钥」设置的条件不会约束平台内对话与智能体发起的调用。

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

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

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

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

20.3 各类凭据的用途

注意

• 这几类凭据互不通用。登录会话和访问密钥都不能调用模型接口；排障时先分清请求用的是哪一种。
• 调用方身份只来自平台的认证结果。网关凭密钥查出它的所有者，作为发起人记入调用记录；请求体或自定义请求头中自行声明的用户身份不参与身份判定。
• 客户端自带的、非平台约定的自定义请求头会原样转发给上游供应商。不要把内部用户标识、手机号、会话令牌一类信息放在自定义请求头里。

20.4 个人归属与公共归属

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

你会看到：创建密钥时页面提示「此密钥用量同时计入：…」，列出本服务总量、工作空间、部门「某部门」及其上级、职能组、个人或密钥自身等额度池。

注意

• 归属在创建时确定，之后不能更改。
• 公共归属被多个业务共用时，一个业务的突发流量会消耗其他业务的额度。互不相关的业务应各用一把密钥，必要时为单把密钥单独设置额度池（见 20.5）。
• 个人专属归属的密钥不能转移。人员调岗或离职时，由接任者以自己的身份重新创建。

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

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

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

操作步骤

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

你会看到

列表显示「名称」（含密钥前缀）、「状态」「模型分组」「计费对象」「调用方」「累计消耗」和「创建时间」。详情分区如下：

密钥状态

注意

• 业务系统报错时先看「可用状态」：额度状态为「已用尽」说明额度池没余量；密钥状态正常但不可用，通常是持有人已不在模型分组的可用范围内，或授权已到期。
• 成员在工作台创建的密钥默认不设到期时间；需要定期换新时按轮换流程处理（见 20.6）。
• 界面不提供密钥级的 IP 或网段白名单，需要时在流量规则中使用「客户端 IP 网段」条件。

20.6 轮换密钥与宽限期

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

前提：以租户管理员登录。宽限期在「管理后台 › 系统设置 › 全局设置 ›「账号与会话安全」页签 › 安全策略」的「外部访问」中设置（「模型 API 密钥轮换宽限期」），默认 24 小时，范围 0～168 小时，0 表示旧密钥立即失效。

操作步骤

1. 在「API 密钥管理」中打开目标密钥详情，点击底部「轮换密钥」。
2. 确认框说明「将签发新密钥。旧密钥在租户安全策略配置的宽限期内仍可用……」，点击「轮换密钥」。
3. 页面显示新 API 密钥，并标明旧密钥的失效时刻。复制新密钥。
4. 在宽限期内把业务系统切换到新密钥并验证调用正常。

你会看到

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

注意

• 怀疑泄露时不要用轮换处理，旧密钥在宽限期内仍有效。应直接禁用（见 20.7）。
• 不强制轮换：存量密钥继续可用，只有主动轮换时才用到宽限期。
• 成员不能在工作台轮换密钥；成员自行更换时先创建新密钥、完成切换，再「撤销」旧密钥（见第 19.4.2 节）。

20.7 禁用与批量禁用

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

操作步骤

1. 单把密钥：在「API 密钥管理」中打开详情，点击「禁用」，核对确认框中的密钥名称与所有者后确认。
2. 批量：在列表中勾选多把密钥，工具栏出现「批量禁用」，核对后确认。
3. 管理台不删除成员的密钥；删除由密钥所有者在工作台自行操作（见第 19.4.2 节）。

你会看到

• 禁用在各网关节点同步后生效，通常在一分钟内。
• 已产生的调用记录、用量与审计记录全部保留。

注意

• 禁用与删除都不能恢复，需要恢复调用时只能重新签发。
• 密钥被禁用后调用返回 403，与「不在可用范围内」表现相同。看到 403 时先核对密钥状态，再判断授权问题。
• 应急处置顺序：禁用泄露的密钥 → 在「运行总览 › 请求」中按该前缀查泄露时段的调用 → 签发新密钥 → 确认新密钥调用正常。不要先删后查。

20.8 客户端的含义

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

客户端代表一个具体的工具实例，例如某台电脑上的 Claude Code、某个项目里的 Codex。把 API 密钥挂到客户端后，平台可按客户端统计用量与会话，在运行总览里按客户端筛选请求。客户端在成员获取密钥时新建，或在「洞察 › 我的客户端」中管理。

密钥与客户端是多对一的关系。创建密钥时「挂到哪个客户端」可选 Claude Code、Codex、Grok、OpenCode、婉儿、通用观测协议等类型；未指定或与实际工具不一致时，调用记录显示「未知客户端」。

注意

• 客户端类型只用于标识与统计，选错不会导致调用失败，但会让按客户端的统计失真。
• 观测上报配置中的上报密钥与模型 API 密钥是两回事，轮换其中一项不影响另一项。

20.9 认证方式与拒绝语义

各协议的鉴权请求头

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

被拒绝时的表现

三种协议各用原生错误信封返回，reason 字段中的原因码一致：

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

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

适用场景：确认某次调用是谁、用哪把密钥或哪个智能体发起的。

操作步骤

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

你会看到

• 「身份归属」列出「发起方类型」「发起人」「发起人邮箱」「客户端识别」「接入凭据」「客户端 IP」；「调用对象」列出「事件类型」「请求造型」「对象类型」「调用对象」。
• 「发起方类型」的取值包括「API 密钥调用」「智能体」「用户」「委托服务」「系统」等。智能体发起的调用同时显示「智能体」与「所属空间」，可据此定位到具体智能体和工作空间。

注意

• 「发起人」来自密钥的所有者，与请求自带的任何用户标识无关；同一把密钥发起的调用，发起人只有一位。
• 「客户端识别」为「未知客户端」只影响按客户端的统计，不影响调用。
• 需要核对的请求较多时，先导出列表，再按接入凭据分组统计。

20.11 鉴权问题定位

能力说明

---

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