Secrets
Kopi Agent 可以在进程启动时从外部 secret manager(密钥管理器)拉取 API key,而不必将它们存储在 ~/.kopi/.env 中。secret manager 的 bootstrap token 存放在 .env 中;其余的 provider(服务提供商)key(OpenAI、Anthropic、OpenRouter 等)都可以留在管理器里,并集中轮换。
受支持的有:
- Bitwarden Secrets Manager —
bwsCLI,懒安装,免费套餐即可使用。 - 1Password — 通过官方
opCLI 引用op://;支持 service-account 或桌面会话认证。
同时使用多个来源
你可以同时启用多个 secret 来源 —— 例如一个团队的 Bitwarden 项目搭配一个个人 vault plugin。各来源按 env var 逐个组合,并遵循确定性的优先级阶梯:
- 你的
.env/ shell 默认优先。 只有当来源自身设置了override_existing: true时(Bitwarden 默认为 true,以便集中轮换生效),它才会替换已有的值。 - 映射型来源优先于批量型来源。 当你显式地将 env var 绑定到引用(一个
env:映射)的来源,无论顺序如何,都优先于隐式注入整个项目 secret 的来源。 - 先声明的来源优先。 在同一形态内,由可选的
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)中分享它们。