0015-api-key-profiles.md 1.8 KB

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,从而跳过审批,这是安全缺口