Skip to main content

Bitwarden Secrets Manager

Hermes 现在可以在启动时从 Bitwarden Secrets Manager 拉取 API Key。这样，你不需要把一长串 provider 密钥都放在 ~/.hermes/.env 里。

可以把 Bitwarden 理解为密钥仓库。Hermes 启动时先拿一个机器账号 token 打开仓库，再把仓库里的 OpenAI、Anthropic、OpenRouter、xAI 等密钥注入到环境变量中。

工作原理​

流程分四步：

  1. 在 Bitwarden Secrets Manager 中创建 machine account，给它读取某个 project 的权限，并生成 access token。
  2. Hermes 只把这个 access token 存到 ~/.hermes/.env，变量名是 BWS_ACCESS_TOKEN。
  3. 每次 hermes、gateway 或 cron job 启动时，Hermes 会在 .env 加载后调用 bws secret list <project_id>。
  4. 返回的 secret 会写入 os.environ，供各 provider 使用。

首次使用时，bws 二进制会自动下载到 ~/.hermes/bin/。这意味着你通常不需要手动 apt、brew 或 sudo 安装。

为什么使用 machine account？​

Bitwarden Secrets Manager 面向非交互式工作负载。Hermes、gateway 和 cron job 启动时没有人在旁边输入 2FA，因此 machine account 不会走人工 2FA 流程。

重点来了：access token 本身就是凭据。任何拿到它的人，都可以读取该 machine account 有权访问的 secret。因此应该把它当成高价值 bearer token：

  • 只放在 ~/.hermes/.env，不要写进仓库；
  • 不要贴到聊天记录、日志和截图里；
  • 如果怀疑泄露，立刻在 Bitwarden Web App 中撤销并重新生成。

覆盖规则​

默认情况下，Bitwarden 是 source of truth。也就是说，如果本地环境变量和 Bitwarden 里有同名 key，Hermes 会优先使用 Bitwarden 的值。

如果你希望本地 .env 优先，可以在配置中关闭覆盖：

secrets:
  bitwarden:
    override_existing: false

这种模式适合开发环境临时覆盖，生产环境更建议让 Bitwarden 作为唯一来源。

适合哪些场景？​

Bitwarden Secrets Manager 特别适合以下场景：

  • 多 profile 共用同一组 provider key；
  • Gateway、cron、Kanban worker 会在后台反复启动；
  • 团队需要集中轮换 OpenRouter、Anthropic、xAI 等密钥；
  • 希望减少 .env 中明文 secret 的数量。

不用担心一开始就很复杂。先把最常用的 provider key 放进去，跑通后再逐步迁移其他密钥。

参考链接​