<!-- Source: https://hermesbible.com/docs/user-guide/features/credential-pools -->

Section: Core Features · URL: https://hermesbible.com/docs/user-guide/features/credential-pools

憑證池（Credential Pools）

憑證池讓你可以為同一個供應商註冊多組 API 金鑰或 OAuth 令牌。當某一組金鑰觸及速率限制或計費配額時，Hermes 會自動輪替到下一組健康的金鑰——無需更換供應商即可維持你的工作階段。

這與備援供應商不同。備援供應商是切換到另一個供應商，而憑證池是同供應商內部的金鑰輪替。系統會先嘗試憑證池——只有當所有池中金鑰都用盡時，才會啟動備援供應商。

提示

憑證池主要適用於使用 API 金鑰的供應商（OpenRouter、Anthropic）。單一 Nous Portal OAuth 即可涵蓋 300+ 個模型，因此大多數使用者在使用 Portal 時不需要建立憑證池。

運作原理

你的請求
  → 從池中選擇金鑰（round_robin / least_used / fill_first / random）
  → 傳送至供應商
  → 429 速率限制？
      → 方案／用量已達上限（例如 ChatGPT/Codex "usage limit reached"）？
          → 立即輪替至下一個池中金鑰（不重試——重試也不會解除上限）
      → 一般／暫時性 429？
          → 對同一金鑰重試一次（暫時性波動）
          → 第二次 429 → 輪替至下一個池中金鑰
      → 所有金鑰用盡 → fallback_model（不同供應商）
  → 402 計費錯誤？
      → 立即輪替至下一個池中金鑰（24 小時冷卻期）
  → 401 驗證過期？
      → 嘗試刷新令牌（OAuth）
      → 刷新失敗 → 輪替至下一個池中金鑰
  → 成功 → 正常繼續

快速開始

如果你已經在 .env 中設定了 API 金鑰，Hermes 會自動將它識別為單金鑰池。若要善用池化功能，請新增更多金鑰：

# 新增第二組 OpenRouter 金鑰
hermes auth add openrouter --api-key sk-or-v1-your-second-key

# 新增第二組 Anthropic 金鑰
hermes auth add anthropic --type api-key --api-key sk-ant-api03-your-second-key

# 新增 Anthropic OAuth 憑證（需要 Claude Max 方案 + 額外用量點數）
hermes auth add anthropic --type oauth
# 開啟瀏覽器進行 OAuth 登入

檢視你的憑證池：

hermes auth list

輸出：

openrouter (2 credentials):
  #1  OPENROUTER_API_KEY   api_key env:OPENROUTER_API_KEY ←
  #2  backup-key           api_key manual

anthropic (3 credentials):
  #1  hermes_pkce          oauth   hermes_pkce ←
  #2  claude_code          oauth   claude_code
  #3  ANTHROPIC_API_KEY    api_key env:ANTHROPIC_API_KEY

← 標記目前選用的憑證。

互動式管理

不帶子命令執行 hermes auth 可啟動互動式精靈：

hermes auth

會顯示完整的憑證池狀態並提供選單：

What would you like to do?
  1. Add a credential
  2. Remove a credential
  3. Reset cooldowns for a provider
  4. Set rotation strategy for a provider
  5. Exit

對於同時支援 API 金鑰與 OAuth 的供應商（Anthropic、Nous、Codex），新增流程會詢問要使用哪種類型：

anthropic supports both API keys and OAuth login.
  1. API key (paste a key from the provider dashboard)
  2. OAuth login (authenticate via browser)
Type [1/2]:

CLI 指令

輪替策略

透過 hermes auth →「Set rotation strategy」或在 config.yaml 中設定：

credential_pool_strategies:
  openrouter: round_robin
  anthropic: least_used

錯誤復原

憑證池對不同錯誤採取不同的處理方式：

has_retried_429 標記會在每次成功 API 呼叫後重置，因此單次暫時性 429 不會觸發輪替。

自訂端點池

自訂 OpenAI 相容端點（Together.ai、RunPod、本地伺服器）會有自己的憑證池，以 config.yaml 中 custom_providers 的端點名稱作為金鑰。

透過 hermes model 設定自訂端點時，會自動產生一個名稱（如「Together.ai」或「Local (localhost:8080)」）。這個名稱即為池的金鑰。

# 透過 hermes model 設定自訂端點後：
hermes auth list
# 顯示：
#   Together.ai (1 credential):
#     #1  config key    api_key config:Together.ai ←

# 為同一端點新增第二組金鑰：
hermes auth add Together.ai --api-key sk-together-second-key

自訂端點池儲存在 auth.json 的 credential_pool 下，使用 custom: 前綴：

{
  "credential_pool": {
    "openrouter": [...],
    "custom:together.ai": [...]
  }
}

自動探索

Hermes 會自動從多個來源探索憑證，並在啟動時初始化憑證池：

自動初始化的條目會在每次載入憑證池時更新——如果你移除了某個環境變數，其對應的池中條目會自動清除。手動條目（透過 hermes auth add 新增）則永遠不會被自動清除。

借用的運行時密鑰（例如環境變數、Bitwarden/Vault/keyring/systemd 引用，以及自訂設定值）在 auth.json 邊界僅作為參考。Hermes 可在當次執行期間於記憶體中使用解析後的值，但只持久化中繼資料，例如來源引用、標籤、狀態、請求計數器，以及不可逆的指紋。手動條目與 Hermes 擁有的 OAuth/裝置代碼狀態則保留其所需的可刷新令牌。

委派與子代理共享

當代理透過 delegate_task 產生子代理時，父代理的憑證池會自動與子代理共享：

• 同一供應商 — 子代理接收父代理的完整憑證池，可在觸及速率限制時進行金鑰輪替
• 不同供應商 — 子代理載入該供應商自己的憑證池（如有設定）
• 未設定憑證池 — 子代理回退至繼承的單一 API 金鑰

這意味著子代理無需額外設定即可享有與父代理相同的速率限制容錯能力。逐任務的憑證租用機制確保子代理在同時輪替金鑰時不會互相衝突。

執行緒安全

憑證池對所有狀態變更操作（select()、mark_exhausted_and_rotate()、try_refresh_current()、mark_used()）使用執行緒鎖。這確保了閘道同時處理多個聊天工作階段時的安全並行存取。

架構

完整的資料流程圖請參見倉庫中的 docs/credential-pool-flow.excalidraw。

憑證池整合於供應商解析層：

1. agent/credential_pool.py — 池管理器：儲存、選取、輪替、冷卻期
2. hermes_cli/auth_commands.py — CLI 指令與互動式精靈
3. hermes_cli/runtime_provider.py — 池感知的憑證解析
4. run_agent.py — 錯誤復原：429/402/401 → 池輪替 → 備援

儲存

憑證池狀態儲存在 ~/.hermes/auth.json 的 credential_pool 鍵下：

{
  "version": 1,
  "credential_pool": {
    "openrouter": [
      {
        "id": "abc123",
        "label": "OPENROUTER_API_KEY",
        "auth_type": "api_key",
        "priority": 0,
        "source": "env:OPENROUTER_API_KEY",
        "secret_source": "bitwarden",
        "secret_fingerprint": "sha256:12ab34cd56ef7890",
        "last_status": "ok",
        "request_count": 142
      }
    ],
    "anthropic": [
      {
        "id": "manual1",
        "label": "personal-api-key",
        "auth_type": "api_key",
        "priority": 0,
        "source": "manual",
        "access_token": "sk-ant-api03-..."
      }
    ]
  }
}

上圖中的 OpenRouter 條目是從外部來源借用的，因此原始金鑰不會儲存在 auth.json 中。而 Anthropic 的手動條目是明確新增至 Hermes 的憑證儲存中，因此其令牌會被持久化。

策略則儲存在 config.yaml（而非 auth.json）：

credential_pool_strategies:
  openrouter: round_robin
  anthropic: least_used

---

---

Codex App-Server Runtime