ByteNoteByteNote
字

字节笔记本

2026年6月21日

hermes教程-Bitwarden Secrets Manager

#Claude Code
API中转
¥120
每日科技简报 · 每天一篇,快速了解科技圈大事

Bitwarden Secrets Manager

在进程启动时从 Bitwarden Secrets Manager 拉取 API 密钥，而不是以明文形式存储在 ~/.hermes/.env 中。一个引导密钥（机器账户访问令牌）取代了每个提供商的多个密钥，轮换凭据只需在 Bitwarden Web 应用中进行一次更改。

工作原理

  1. 你在 Bitwarden Secrets Manager 中创建一个机器账户，授予其对某个项目的读取权限，并生成一个访问令牌。
  2. Hermes 将该单一令牌存储在 ~/.hermes/.env 中，作为 BWS_ACCESS_TOKEN。
  3. 每次 hermes（或网关、或 cron 任务）启动时，在加载 ~/.hermes/.env 后，Hermes 调用 bws secret list <project_id> 并将返回的密钥设置到 os.environ 中。
  4. 默认情况下，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 应用（或欧盟账户使用 vault.bitwarden.eu）中：

  1. 从产品切换器切换到 Secrets Manager。
  2. 创建或选择一个项目（例如 "Hermes keys"）。
  3. 将你的提供商密钥添加为机密。机密的名称将成为环境变量名——使用 OPENROUTER_API_KEY、ANTHROPIC_API_KEY 等。
  4. Machine accounts → New machine account → My Hermes machine → Projects 选项卡 → 授予对项目的读取权限。
  5. Access tokens 选项卡 → Create access token → Never 过期（或选择一个日期）→ 复制令牌（以 0. 开头）。Bitwarden 无法再次检索它——请妥善保管。

Secrets Manager 包含在 Bitwarden 免费套餐中，有使用限制；无需付费计划即可试用。

2. 运行向导

bash
hermes secrets bitwarden setup

它将：

  1. 将 bws v2.0.0 下载并验证到 ~/.hermes/bin/bws。
  2. 提示你输入访问令牌（输入被隐藏）。存储在 ~/.hermes/.env 中，作为 BWS_ACCESS_TOKEN。
  3. 询问你的机器账户属于哪个 Bitwarden 区域——US Cloud、EU Cloud 或自托管/自定义 URL。存储在 config.yaml 的 secrets.bitwarden.server_url 中，并作为 BWS_SERVER_URL 传递给 bws。
  4. 列出机器账户可以查看的项目；选择一个。存储在 config.yaml 的 secrets.bitwarden.project_id 中。
  5. 测试获取项目的机密，并显示哪些环境变量将被解析。
  6. 将 secrets.bitwarden.enabled 设为 true。

也支持通过标志进行非交互式设置：

bash
hermes secrets bitwarden setup \
  --access-token "$BWS_ACCESS_TOKEN" \
  --server-url https://vault.bitwarden.eu \
  --project-id <project-uuid>

3. 确认

bash
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 中的默认值：

yaml
secrets:
  bitwarden:
    enabled: false
    access_token_env: BWS_ACCESS_TOKEN
    project_id: ""
    server_url: ""
    cache_ttl_seconds: 300
    override_existing: true
    auto_install: true
键默认值作用
enabledfalse主开关。为 false 时，从不联系 Bitwarden。
access_token_envBWS_ACCESS_TOKEN保存引导令牌的环境变量名。如果你已经将 BWS_ACCESS_TOKEN 用于其他用途，请更改此项。
project_id""要同步的项目的 UUID。
server_url""Bitwarden 区域或自托管端点。空值 = bws 默认值（US Cloud，https://vault.bitwarden.com）。对于 EU Cloud，设置为 https://vault.bitwarden.eu；对于自托管，设置为你自己的 URL。作为 BWS_SERVER_URL 传递给 bws 子进程。
cache_ttl_seconds300进程内获取结果被重复使用的时长。设置为 0 以禁用缓存。缓存是进程级别的；新的 hermes 调用会重新开始。
override_existingtrue为 true 时，Bitwarden 的值会覆盖环境中已有的任何内容（因此 Web 应用中的轮换实际上会生效）。如果希望 .env / shell 导出在本地优先，请设为 false。
auto_installtrue为 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令牌被撤销或错误生成新令牌，重新运行设置
[400 Bad Request] {"error":"invalid_client"}令牌属于与 bws 调用的 Bitwarden 区域不同的区域（例如，EU 令牌访问了 US 身份端点）重新运行设置并选择正确的区域，或将 secrets.bitwarden.server_url 设置为 https://vault.bitwarden.eu（或你的自托管 URL）
bws timed out网络被阻止或 Bitwarden API 缓慢检查与 api.bitwarden.com（或你的 server_url）的连接
bws binary not availableauto_install: false 且 bws 不在 PATH 中从 github.com/bitwarden/sdk-sm/releases 手动安装，或重新启用 auto_install
Checksum mismatch下载损坏或被篡改重新运行，会重试；如果持续出现，请提交问题

安全说明

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

何时不应使用此功能

  • 单机个人设置，其中 ~/.hermes/.env 已经足够。你只是用一种凭据换另一种，并在启动时增加了网络依赖。
  • 无法访问 api.bitwarden.com 的隔离环境。
  • CI/CD，其中现有的机密注入机制（GitHub Actions 机密、Vault 等）已经设置好——选择一种方式，不要同时使用两种。

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

Claude Code
上一篇

hermes教程-消息网关

下一篇

hermes教程-Bitwarden Secrets Manager

分享: