跳到主要內容

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 放進去，跑通後再逐步遷移其他密鑰。

參考鏈接​