ADR-0015 API Key 只能使用指定的 Profile;权限模式由 Profile 决定
- 状态:Accepted · 日期:2026-10-23
决策
- 每个 API Key 配置"可用的 Profile"(至少一个)和一个"默认 Profile"(必须在可用列表中),没有其他配置项
GET /v1/profiles 只返回该 Key 可用的 Profile,isDefault 表示该平台的默认 Profile
- 创建会话:不指定 Profile 时用该 Key 的默认 Profile;指定了不可用的 Profile 返回
403 profile_not_allowed
- 引擎:完全由 Profile 决定,平台和后台都不能单独指定(传
provider 返回 400);更换 Profile(尚未开始对话时)引擎随之改变。每个引擎有一个内置的标准 Profile:"通用助手(Claude)"与"通用助手(Codex)",不可删除、引擎不可修改(2026-10-23 补充)
- 模型:平台可以为会话自选模型(创建或修改会话时),范围是设置中该引擎的可选模型加上 Profile 的模型;Profile 只决定默认模型
- 权限模式:完全由 Profile 决定。平台创建或修改会话时传
permissionMode 返回 400;会话在每次运行时读取 Profile 的当前设置,修改 Profile 立即生效。只有后台管理员可以为单个会话临时覆盖(Playground 中可以选回"跟随 Profile")
- 每次发送消息前检查会话的 Profile 是否仍对该 Key 开放,撤销后返回 403,需要新建会话
- 内置 Profile"通用助手"(
builtin)不可删除;被任一 Key 勾选的 Profile 不可删除(需先在 API Keys 页取消勾选)
- 升级迁移:已有 Key 只开放内置 Profile 并设为默认;平台创建的会话改为跟随 Profile
理由
- 平台之间互相隔离,管理员按用途分配 Profile
- 原先平台可以把权限模式改为 auto,从而跳过审批,这是安全缺口