Bitwarden 密钥管理器（Secrets Manager）

在进程启动时从 Bitwarden 密钥管理器（Secrets Manager）拉取 API 密钥，而无需以明文形式存储在 ~/.hermes/.env 中。一个引导密钥（bootstrap secret，即机器账户访问令牌）可替代 N 个供应商密钥，轮换凭据只需在 Bitwarden Web 应用中做一次更改。

工作原理

在 Bitwarden Secrets Manager 中创建一个机器账户（machine account），授予其对某个项目的读取权限，并生成一个访问令牌（access token）。
Hermes 将该令牌作为 BWS_ACCESS_TOKEN 存储在 ~/.hermes/.env 中。
每次 hermes（或网关、定时任务）启动时，在加载 ~/.hermes/.env 后，Hermes 调用 bws secret list <project_id>，并将返回的密钥设置到 os.environ 中。
默认情况下，Hermes 覆盖环境中已有的值，因此 Bitwarden 是真实数据源——在 Web 应用中轮换一次密钥，所有 Hermes 进程在下次启动时即可获取。如果希望 .env 优先，可在配置中将 override_existing 设为 false。

bws 二进制文件在首次使用时自动下载到 ~/.hermes/bin/——无需 apt、brew 或 sudo。

为什么使用机器账户（以及为什么没有 2FA 提示）

Bitwarden Secrets Manager 专为非交互式工作负载设计：机器账户无法设置 2FA 验证，因为没有人工参与。访问令牌本身就是凭据。任何拥有该令牌的人都可以读取机器账户有权访问的所有密钥，因此请将其视为高价值持有者令牌——存储在 .env（而非 config.yaml）中，一旦泄露，请在 Bitwarden Web 应用中撤销并重新生成。

机器账户的创建在 Web 应用中完成，创建时会应用您正常的 2FA 验证。之后令牌即可自主运行。

设置步骤

1. 创建机器账户和访问令牌

在 Bitwarden Web 应用中：

通过产品切换器切换到 Secrets Manager。
创建或选择一个项目（Project）（例如 “Hermes keys”）。
将您的供应商密钥添加为机密。密钥的**名称（Name）**将成为环境变量名——请使用 OPENROUTER_API_KEY、ANTHROPIC_API_KEY 等。
Machine accounts → New machine account → My Hermes machine → Projects 选项卡 → 授予对项目的读取权限。
Access tokens 选项卡 → Create access token → 选择永不过期（Never）（或指定日期）→ 复制令牌（以 0. 开头）。Bitwarden 无法再次显示该令牌——请妥善保管。

Secrets Manager 在 Bitwarden 免费版中已有包含（有一定限制）；无需付费计划即可试用。

2. 运行配置向导

hermes secrets bitwarden setup

该命令将：

将 bws v2.0.0 下载并验证到 ~/.hermes/bin/bws。
提示输入访问令牌（输入内容隐藏）。以 BWS_ACCESS_TOKEN 形式存入 ~/.hermes/.env。
列出机器账户可查看的项目，选择一个。以 secrets.bitwarden.project_id 形式存入 config.yaml。
测试拉取项目中的密钥，并显示将解析哪些环境变量。
将 secrets.bitwarden.enabled 设置为 true。

3. 确认

hermes secrets bitwarden status

从现在起，每次 hermes 调用在启动时都会拉取最新的密钥。第一次在进程中应用密钥时，stderr 中会显示一行摘要信息。

命令行（CLI）

命令	功能说明
`hermes secrets bitwarden setup`	交互式向导（安装二进制文件、提示输入令牌、选择项目、测试拉取）
`hermes secrets bitwarden status`	显示配置 + 二进制版本 + 令牌是否存在
`hermes secrets bitwarden sync`	试运行：立即拉取密钥，显示将要应用的内容
`hermes secrets bitwarden sync --apply`	拉取密钥并导出到当前 shell 环境中
`hermes secrets bitwarden install`	仅下载固定版本的 `bws` 二进制文件（无需认证）
`hermes secrets bitwarden disable`	将 `enabled` 设为 `false`；保留令牌和项目 ID 不变

配置项

~/.hermes/config.yaml 中的默认值：

secrets:
  bitwarden:
    enabled: false
    access_token_env: BWS_ACCESS_TOKEN
    project_id: ""
    cache_ttl_seconds: 300
    override_existing: true
    auto_install: true

键	默认值	功能说明
`enabled`	`false`	总开关。为 `false` 时从不连接 Bitwarden。
`access_token_env`	`BWS_ACCESS_TOKEN`	存放引导令牌的环境变量名。如果已经将 `BWS_ACCESS_TOKEN` 用于其他用途，可修改此项。
`project_id`	`""`	要同步的项目的 UUID。
`cache_ttl_seconds`	`300`	进程内获取结果的复用时间。设为 `0` 可禁用缓存。缓存是进程级别的；新的 `hermes` 调用会重新获取。
`override_existing`	`true`	为 `true` 时，Bitwarden 中的值会覆盖环境中已有的值（因此 Web 应用中的轮换才会生效）。设为 `false` 则本地 `.env` / shell 导出优先。
`auto_install`	`true`	为 `true` 时，首次使用自动将 `bws` 下载到 `~/.hermes/bin/`。

异常处理

Bitwarden 不会阻止 Hermes 启动。如果出现任何问题，stderr 中会显示一行警告，Hermes 将继续使用 .env 中已有的凭据：

现象	原因	解决方法
`BWS_ACCESS_TOKEN is not set`	配置中已启用，但 `.env` 中的令牌被清除	重新运行 `hermes secrets bitwarden setup`
`bws exited 1: invalid access token`	令牌已被撤销或错误	生成新令牌，重新运行设置
`bws timed out`	网络被阻断或 Bitwarden API 缓慢	检查到 `api.bitwarden.com` 的连接
`bws binary not available`	`auto_install: false` 且 `bws` 不在 PATH 中	从 github.com/bitwarden/sdk-sm/releases 手动安装，或重新开启 `auto_install`
`Checksum mismatch`	下载文件损坏或被篡改	重新运行（会重试）；如果持续存在，请提交 issue

安全说明

引导令牌（BWS_ACCESS_TOKEN）本身是敏感信息——任何持有该令牌的人都可以读取机器账户有权访问的所有密钥。请像对待其他 API 密钥一样妥善保管。
即使设置了 override_existing: true，Hermes 也不会允许 Bitwarden 覆盖引导令牌本身。如果您将 BWS_ACCESS_TOKEN 作为机密存储在项目中，应用时会自动跳过。
bws 二进制文件的下载会与同一 GitHub 版本发布的 SHA-256 校验和进行比对验证。校验不匹配将中止安装。
固定版本（本文撰写时为 bws v2.0.0）通过对此仓库的 PR 进行更新——Hermes 不会自动将 bws 升级到”最新版”，因为上游发布版本可能会发生变化。

何时不应使用此功能

单机个人环境，~/.hermes/.env 已足够。这相当于用一种凭据替换另一种，并在启动时增加了网络依赖。
无法访问 api.bitwarden.com 的离线环境（air-gapped environments）。
CI/CD 环境，如果已有的密钥注入机制（GitHub Actions secrets、Vault 等）已经配置完毕——请选择其中一种方式，不要同时使用两种。

此功能的适用场景是多机器集群、共享开发机、网关 VPS，以及任何需要在多个 Hermes 安装之间实现集中轮换和撤销的配置。

好奇心花园🪴

探索

最近的笔记

note-template

getMoon.js

getWeather.js

bitwarden