每日提示：您可以使用 Hermes Agent 的凭据池（Credential Pools）为同一 LLM 提供商登录或添加多个 API 密钥，它会在这些密钥之间轮换，以确保操作的稳定性。更多信息请参阅凭据池文档：https://t.co/NbVXcKQlZN

凭据池 | Hermes Agent

来源: https://hermes-agent.nousresearch.com/docs/user-guide/features/credential-pools

凭据池允许您为同一个提供商注册多个 API 密钥或 OAuth 令牌。当某个密钥达到速率限制或计费配额时，Hermes 会自动轮换到下一个健康的密钥——无需切换提供商即可保持会话活跃。这与后备提供商（fallback providers）（https://hermes-agent.nousresearch.com/docs/user-guide/features/fallback-providers）不同，后者会完全切换到不同的提供商。凭据池是同一提供商内部的轮换；后备提供商则是跨提供商的故障转移。系统会优先尝试凭据池——只有当池中所有密钥都用尽时，然后才会激活后备提供商。

工作原理 (https://hermes-agent.nousresearch.com/docs/user-guide/features/credential-pools#how-it-works)

您的请求 → 从池中选取密钥 (round_robin / least_used / fill_first / random) → 发送给提供商 → 遇到 429 速率限制？ → 重试同一密钥一次（瞬时抖动） → 再次出现 429 → 轮换到池中的下一个密钥 → 所有密钥耗尽 → fallback_model (不同提供商) → 遇到 402 计费错误？ → 立即轮换到池中的下一个密钥 (24小时冷却期) → 遇到 401 认证过期？ → 尝试刷新令牌 (OAuth) → 刷新失败 → 轮换到池中的下一个密钥 → 成功 → 继续正常进行

快速入门 (https://hermes-agent.nousresearch.com/docs/user-guide/features/credential-pools#quick-start)

如果您已经在 .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 登录

检查您的池：

输出：

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

← 标记当前选定的凭据。

交互式管理 (https://hermes-agent.nousresearch.com/docs/user-guide/features/credential-pools#interactive-management)

运行 hermes auth 且不带子命令以启动交互式向导：

这将显示您的完整池状态并提供菜单：

您想做什么？
1. 添加凭据
2. 删除凭据
3. 重置提供商的冷却时间
4. 设置提供商的轮换策略
5. 退出

对于同时支持 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 命令 (https://hermes-agent.nousresearch.com/docs/user-guide/features/credential-pools#cli-commands)

轮换策略 (https://hermes-agent.nousresearch.com/docs/user-guide/features/credential-pools#rotation-strategies)

通过 hermes auth → “设置轮换策略” 或在 config.yaml 中配置：

credential_pool_strategies:
  openrouter: round_robin
  anthropic: least_used

错误恢复 (https://hermes-agent.nousresearch.com/docs/user-guide/features/credential-pools#error-recovery)

池会根据不同类型的错误采取不同的处理方式：

has_retried_429 标志会在每次成功的 API 调用后重置，因此单个瞬时的 429 错误不会触发轮换。

自定义端点池 (https://hermes-agent.nousresearch.com/docs/user-guide/features/credential-pools#custom-endpoint-pools)

自定义的 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": [...]
  }
}

自动发现 (https://hermes-agent.nousresearch.com/docs/user-guide/features/credential-pools#auto-discovery)

Hermes 会自动从多个来源发现凭据，并在启动时填充池：

自动填充的条目会在每次加载池时更新——如果您移除了环境变量，其池条目会自动清除。手动条目（通过 hermes auth add 添加）永远不会被自动清除。

委托与子代理共享 (https://hermes-agent.nousresearch.com/docs/user-guide/features/credential-pools#delegation–subagent-sharing)

当代理通过 delegate_task 生成子代理时，父级的凭据池会自动与子级共享：

• 同一提供商——子级接收父级的完整池，从而在遇到速率限制时实现密钥轮换
• 不同提供商——子级加载该提供商自己的池（如果已配置）
• 未配置池——子级回退到继承的单个 API 密钥

这意味着子代理无需额外配置即可享受与父级相同的速率限制弹性。每次任务的凭据租赁确保了子代理在并发轮换密钥时不会相互冲突。

线程安全 (https://hermes-agent.nousresearch.com/docs/user-guide/features/credential-pools#thread-safety)

凭据池对所有状态突变（select()、mark_exhausted_and_rotate()、try_refresh_current()、mark_used()）使用线程锁。这确保了网关同时处理多个聊天会话时的并发访问安全。

架构 (https://hermes-agent.nousresearch.com/docs/user-guide/features/credential-pools#architecture)

查看完整的数据流图，参见存储库中的 docs/credential-pool-flow.excalidraw (https://excalidraw.com/#json=2Ycqhqpi6f12E_3ITyiwh,c7u9jSt5BwrmiVzHGbm87g)。凭据池集成在提供商解析层：

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 → 池轮换 → 后备

存储 (https://hermes-agent.nousresearch.com/docs/user-guide/features/credential-pools#storage)

池状态存储在 ~/.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",
        "access_token": "sk-or-v1-...",
        "last_status": "ok",
        "request_count": 142
      }
    ]
  },
}

策略存储在 config.yaml 中（不在 auth.json 中）：

credential_pool_strategies:
  openrouter: round_robin
  anthropic: least_used