跳到主要内容

Secrets

Kopi Agent 可以在进程启动时从外部 secret manager(密钥管理器)拉取 API key,而不必将它们存储在 ~/.kopi/.env 中。secret manager 的 bootstrap token 存放在 .env 中;其余的 provider(服务提供商)key(OpenAI、Anthropic、OpenRouter 等)都可以留在管理器里,并集中轮换。

受支持的有:

  • Bitwarden Secrets Manager — bws CLI,懒安装,免费套餐即可使用。
  • 1Password — 通过官方 op CLI 引用 op://;支持 service-account 或桌面会话认证。

同时使用多个来源​

你可以同时启用多个 secret 来源 —— 例如一个团队的 Bitwarden 项目搭配一个个人 vault plugin。各来源按 env var 逐个组合,并遵循确定性的优先级阶梯:

  1. 你的 .env / shell 默认优先。 只有当来源自身设置了 override_existing: true 时(Bitwarden 默认为 true,以便集中轮换生效),它才会替换已有的值。
  2. 映射型来源优先于批量型来源。 当你显式地将 env var 绑定到引用(一个 env: 映射)的来源,无论顺序如何,都优先于隐式注入整个项目 secret 的来源。
  3. 先声明的来源优先。 在同一形态内,由可选的 secrets.sources 列表的顺序(或注册顺序)决定。对已被占用的变量,后来的声明会被跳过 —— 并给出启动警告,绝不会静默处理。

override_existing 绝不允许某个来源覆盖已被另一来源占用的变量,任何来源也永远无法覆盖其他来源的 bootstrap token(例如 BWS_ACCESS_TOKEN)。

secrets:
sources: [bitwarden] # optional explicit ordering
bitwarden:
enabled: true
project_id: "..."

由来源注入的每个 credential 都会标注其出处 —— 安装流程和 kopi model 会在检测到的 key 旁显示 (from Bitwarden),让你始终知道某个值来自哪里。

添加你自己的后端​

第三方 secret manager 以独立 plugin 的形式提供,而不是提交到核心仓库的 PR。一个后端需要继承 agent.secret_sources.base.SecretSource(只有一个必需方法:fetch(cfg, home_path) -> FetchResult),并通过 plugin 的 register(ctx) 中的 ctx.register_secret_source(MySource()) 完成注册。编排器负责优先级、冲突处理、超时和来源追踪 —— 你的来源只需负责获取。完整的指南(包含契约规则、subprocess 安全辅助工具和一致性测试套件)见:构建 Secret Source Plugin。

内置集合是刻意封闭的(与 memory provider 相同的策略):Bitwarden 和 1Password 内置在仓库中。其他所有 —— Infisical、Proton Pass、HashiCorp Vault、AWS Secrets Manager、OS 密钥库 —— 都属于 plugin 仓库的范畴;欢迎在 Kopi Ai Agent Pte Ltd Discord(#plugins-skills-and-skins)中分享它们。