H繁中版
文件密鑰管理bitwarden
<!-- Source: https://hermesbible.com/docs/user-guide/secrets/bitwarden -->

Section: Secrets · URL: https://hermesbible.com/docs/user-guide/secrets/bitwarden

Bitwarden Secrets Manager

在程式啟動時，從 Bitwarden Secrets Manager 拉取 API 金鑰，而非將它們以明文形式儲存在 ~/.hermes/.env 中。一個啟動用的密鑰（機器帳號的存取權杖）取代了 N 個供應商的金鑰，而且只要在 Bitwarden 網頁應用程式中旋轉一次憑證，就能完成所有金鑰的更新。

運作方式

  1. 你在 Bitwarden Secrets Manager 中建立一個機器帳號，賦予它對某個專案的讀取權限，並產生一個存取權杖。
  2. Hermes 將這個單一權杖儲存在 ~/.hermes/.env 中，環境變數名稱為 BWS_ACCESS_TOKEN。
  3. 每次 hermes（或閘道器、排程作業）啟動時，在 ~/.hermes/.env 載入之後，Hermes 會呼叫 bws secret list <project_id> 並將回傳的金鑰設定到 os.environ 中。
  4. 預設情況下，Hermes 會覆蓋環境變數中已存在的值，因此 Bitwarden 是唯一的真實來源——只要在网页應用程式中旋轉一次金鑰，下一次啟動時所有 Hermes 進程都會取得新值。如果你希望 .env 的值優先，可在設定中將 override_existing 設為 false。

bws 執行檔會在首次使用時自動下載到 ~/.hermes/bin/ —— 無需 apt、brew 或 sudo。

為什麼使用機器帳號（以及為何不會觸發 2FA 提示）

Bitwarden Secrets Manager 專為非互動式工作負載設計：機器帳號無法啟用 2FA，因為整個流程中沒有真人參與。存取權杖本身就是憑證。任何取得該權杖的人都能讀取機器帳號有權存取的所有密鑰，因此請將它視為高價值的 Bearer Token —— 儲存在 .env 中（而非 config.yaml），如果洩露了，請在 Bitwarden 網頁應用程式中撤銷並重新產生。

你需要在網頁應用程式中設定機器帳號，那裡會套用你一般的 2FA 驗證。設定完成後，權杖即可自主運作。

設定

1. 建立機器帳號和存取權杖

在 Bitwarden 網頁應用程式（歐洲帳號請使用 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 分頁 → 授予你專案的 Read 權限。
  5. Access tokens 分頁 → Create access token → Never 過期（或選擇日期）→ 複製權杖（以 0. 開頭）。Bitwarden 無法再次取得此權杖——請妥善保存副本。

Secrets Manager 包含在 Bitwarden 免費方案中（有使用限制）；無需付費方案即可試用。

2. 執行設定精靈

hermes secrets bitwarden setup

它將會：

  1. 下載並驗證 bws v2.0.0 到 ~/.hermes/bin/bws。
  2. 提示你輸入存取權杖（輸入時不會顯示）。儲存在 ~/.hermes/.env 中，環境變數名稱為 BWS_ACCESS_TOKEN。
  3. 詢問你的機器帳號所屬的 Bitwarden 區域——US Cloud、EU Cloud 或 self-hosted / custom URL。儲存在 config.yaml 的 secrets.bitwarden.server_url 中，並透過 BWS_SERVER_URL 傳遞給 bws。
  4. 列出機器帳號可見的專案；選擇一個。儲存在 config.yaml 的 secrets.bitwarden.project_id 中。
  5. 試抓取專案的密鑰，並顯示將會解析哪些環境變數。
  6. 將 secrets.bitwarden.enabled 設為 true。

也支援透過參數進行非互動式設定：

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

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: ""
    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）。歐洲 Cloud 請設為 https://vault.bitwarden.eu，自架環境請設為你自己的 URL。此值會作為 BWS_SERVER_URL 傳遞給 bws 子程序。
cache_ttl_seconds300進程內快取結果的重用時間。設為 0 可停用快取。快取為進程級別；新的 hermes 呼叫會重新開始。
override_existingtrue設為 true 時，Bitwarden 的值會覆蓋環境變數中已存在的值（因此在網頁應用程式中旋轉金鑰後確實會生效）。如果你希望 .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"}權杖所屬的 Bitwarden 區域與 bws 呼叫的區域不符（例如歐洲權杖打到美國身分驗證端點）重新執行設定並選擇正確的區域，或將 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 重新設為 true
Checksum mismatch下載檔案損壞或被篡改重新執行，會自動重試；如果問題持續存在，請提交 issue

安全注意事項

  • 啟動用的權杖（BWS_ACCESS_TOKEN）本身就很敏感——任何取得它的人都能讀取機器帳號有權存取的所有密鑰。請像對待任何其他 API 金鑰一樣保護它。
  • 即使設定了 override_existing: true，Hermes 也拒絕讓 Bitwarden 覆寫啟動用的權杖本身。如果你將 BWS_ACCESS_TOKEN 作為專案內的密鑰儲存，它會在套用時被靜默跳過。
  • bws 執行檔的下載會根據同一 GitHub Release 公佈的 SHA-256 校驗碼進行驗證。校驗碼不符時會中止安裝。
  • 鎖定的版本（撰寫本文時為 bws v2.0.0）透過此儲存庫的 PR 進行更新——Hermes 不會自動將 bws 升級到「最新版」，因為上游的 Release 格式可能會變動。

不建議使用的場景

  • 單機個人設定，~/.hermes/.env 已綽綽有餘的情況。這只是用一個憑證換成另一個，並在啟動時增加了網路相依性。
  • 氣隔環境，無法連線到 api.bitwarden.com。
  • CI/CD，已有既有的密鑰注入機制（GitHub Actions secrets、Vault 等）——選擇其中一條路就好，不要兩條都走。

適合使用的場景是多機器部署、共用開發機器、閘道器 VPS，或是任何你想要在多個 Hermes 安裝之間集中管理旋轉與撤銷的環境。

Secrets

toolsets referenceindex