ByteNoteByteNote
字

字节笔记本

2026年6月21日

hermes教程-凭据池

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

凭据池

凭据池允许您为同一提供商注册多个 API 密钥或 OAuth 令牌。当某个密钥达到速率限制或计费配额时，Hermes 会自动轮换到下一个健康的密钥，从而在不切换提供商的情况下保持会话活跃。

这与回退提供商不同，后者会完全切换到不同的提供商。凭据池是同一提供商内的轮换；回退提供商是跨提供商的故障转移。池会首先尝试——如果所有池密钥都已耗尽，然后才会激活回退提供商。

提示

凭据池主要用于 API 密钥提供商（OpenRouter、Anthropic）。单个 Nous Portal OAuth 可覆盖 300 多个模型，因此大多数用户在使用 Portal 时不需要池。

工作原理

text
您的请求
  → 从池中选择密钥（round_robin / least_used / fill_first / random）
  → 发送给提供商
  → 429 速率限制？
      → 计划/使用量限制已到达（例如 ChatGPT/Codex "使用量限制已到达"）？
          → 立即轮换到下一个池密钥（不重试——重试不会清除上限）
      → 通用/瞬时 429？
          → 重试同一密钥一次（瞬时波动）
          → 第二次 429 → 轮换到下一个池密钥
      → 所有密钥已耗尽 → fallback_model（不同提供商）
  → 402 计费错误？
      → 立即轮换到下一个池密钥（24 小时冷却）
  → 401 认证过期？
      → 尝试刷新令牌（OAuth）
      → 刷新失败 → 轮换到下一个池密钥
  → 成功 → 正常继续

快速开始

如果您已经在 .env 中设置了 API 密钥，Hermes 会自动将其发现为单密钥池。要利用池化功能，请添加更多密钥：

bash
## 添加第二个 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 登录

检查您的池：

bash
hermes auth list

输出：

text
openrouter (2 个凭据):
  #1  OPENROUTER_API_KEY   api_key env:OPENROUTER_API_KEY ←
  #2  backup-key           api_key manual

anthropic (3 个凭据):
  #1  hermes_pkce          oauth   hermes_pkce ←
  #2  claude_code          oauth   claude_code
  #3  ANTHROPIC_API_KEY    api_key env:ANTHROPIC_API_KEY

← 标记当前选中的凭据。

交互式管理

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

bash
hermes auth

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

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

对于同时支持 API 密钥和 OAuth 的提供商（Anthropic、Nous、Codex），添加流程会询问类型：

text
anthropic 同时支持 API 密钥和 OAuth 登录。
  1. API 密钥（从提供商仪表板粘贴密钥）
  2. OAuth 登录（通过浏览器进行身份验证）
输入 [1/2]：

CLI 命令

命令描述
hermes auth交互式池管理向导
hermes auth list显示所有池和凭据
hermes auth list <provider>显示特定提供商的池
hermes auth add <provider>添加凭据（提示输入类型和密钥）
hermes auth add <provider> --type api-key --api-key <key>非交互式添加 API 密钥
hermes auth add <provider> --type oauth通过浏览器登录添加 OAuth 凭据
hermes auth remove <provider> <index>按基于 1 的索引移除凭据
hermes auth reset <provider>清除所有冷却/耗尽状态

轮换策略

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

yaml
credential_pool_strategies:
  openrouter: round_robin
  anthropic: least_used
策略行为
fill_first（默认）使用第一个健康密钥直到耗尽，然后移动到下一个
round_robin均匀循环使用密钥，每次选择后轮换
least_used始终选择请求计数最低的密钥
random在健康密钥中随机选择

错误恢复

池对不同错误的处理方式不同：

错误行为冷却时间
429 速率限制重试同一密钥一次（瞬时）。第二次连续 429 则轮换到下一个密钥1 小时
402 计费/配额立即轮换到下一个密钥24 小时
401 认证过期首先尝试刷新 OAuth 令牌。仅在刷新失败时轮换—
所有密钥已耗尽如果配置了 fallback_model，则回退到该模型—

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

自定义端点池

自定义的 OpenAI 兼容端点（Together.ai、RunPod、本地服务器）拥有自己的池，键值为 config.yaml 中 custom_providers 的端点名称。

当您通过 hermes model 设置自定义端点时，它会自动生成一个名称，例如 "Together.ai" 或 "Local (localhost:8080)"。此名称成为池的键。

bash
## 通过 hermes model 设置自定义端点后：
hermes auth list
## 显示：
## Together.ai (1 个凭据):
## #1  config key    api_key config:Together.ai ←
## 为同一端点添加第二个密钥：
hermes auth add Together.ai --api-key sk-together-second-key

自定义端点池存储在 auth.json 中，键前缀为 custom:：

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

自动发现

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

来源示例自动填充？
环境变量OPENROUTER_API_KEY、ANTHROPIC_API_KEY是
OAuth 令牌（auth.json）Codex 设备码、Nous 设备码是
Claude Code 凭据~/.claude/.credentials.json是（Anthropic）
Hermes PKCE OAuth~/.hermes/auth.json是（Anthropic）
自定义端点配置model.api_key 在 config.yaml 中是（自定义端点）
手动条目通过 hermes auth add 添加持久化在 auth.json 中

自动填充的条目在每次加载池时更新——如果您移除某个环境变量，其池条目会自动清除。手动条目（通过 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：

json
{
  "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）：

yaml
credential_pool_strategies:
  openrouter: round_robin
  anthropic: least_used
Claude Code
上一篇

hermes教程-Google Chat

下一篇

hermes教程-凭据池

分享: