title: Credential Pools description: Pool multiple API keys or OAuth tokens per provider for automatic rotation and rate limit recovery. sidebar_label: Credential Pools sidebar_position: 9 lang: ru

Пулы учетных данных

Пулы учетных данных позволяют зарегистрировать несколько ключей API или токенов OAuth для одного и того же поставщика. Когда один ключ достигает предела скорости или квоты выставления счетов, Hermes автоматически переключается на следующий работоспособный ключ, поддерживая работоспособность вашего сеанса без переключения провайдера.

Это отличается от резервных поставщиков, которые полностью переключаются на другого поставщика. Пулы учетных данных представляют собой ротацию одного и того же поставщика; Резервные поставщики — это аварийное переключение между поставщиками. Сначала проверяются пулы — если все ключи пула исчерпаны, затем активируется резервный поставщик.

Как это работает

Your request
  → Pick key from pool (round_robin / least_used / fill_first / random)
  → Send to provider
  → 429 rate limit?
      → Retry same key once (transient blip)
      → Second 429 → rotate to next pool key
      → All keys exhausted → fallback_model (different provider)
  → 402 billing error?
      → Immediately rotate to next pool key (24h cooldown)
  → 401 auth expired?
      → Try refreshing the token (OAuth)
      → Refresh failed → rotate to next pool key
  → Success → continue normally

Быстрый старт

Если у вас уже есть ключ API, установленный в .env, Hermes автоматически обнаружит его как пул с одним ключом. Чтобы получить выгоду от объединения, добавьте больше ключей:

# Add a second OpenRouter key
hermes auth add openrouter --api-key sk-or-v1-your-second-key

# Add a second Anthropic key
hermes auth add anthropic --type api-key --api-key sk-ant-api03-your-second-key

# Add an Anthropic OAuth credential (requires Claude Max plan + extra usage credits)
hermes auth add anthropic --type oauth
# Opens browser for OAuth login

Проверьте свои бассейны:

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 → «Настроить стратегию ротации» или в config.yaml:

credential_pool_strategies:
  openrouter: round_robin
  anthropic: least_used

Восстановление ошибок

Пул по-разному обрабатывает разные ошибки:

Флаг has_retried_429 сбрасывается при каждом успешном вызове API, поэтому одиночный переходный код 429 не вызывает ротацию.

Пользовательские пулы конечных точек

Пользовательские конечные точки, совместимые с OpenAI (Together.ai, RunPod, локальные серверы), получают свои собственные пулы, ключом которых является имя конечной точки из custom_providers в config.yaml.

Когда вы настраиваете пользовательскую конечную точку через hermes model, она автоматически генерирует имя, например «Together.ai» или «Local (localhost:8080)». Это имя становится ключом пула.

# After setting up a custom endpoint via hermes model:
hermes auth list
# Shows:
#   Together.ai (1 credential):
#     #1  config key    api_key config:Together.ai ←

# Add a second key for the same endpoint:
hermes auth add Together.ai --api-key sk-together-second-key

Пользовательские пулы конечных точек хранятся в auth.json под credential_pool с префиксом custom::

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

Автообнаружение

Hermes автоматически обнаруживает учетные данные из нескольких источников и заполняет пул при запуске:

Записи с автоматическим заполнением обновляются при каждой загрузке пула — если вы удалите переменную env, ее запись в пуле будет автоматически удалена. Записи, введенные вручную (добавленные через hermes auth add), никогда не удаляются автоматически.

Делегирование и совместное использование субагентов

Когда агент создает субагентов через 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",
        "access_token": "sk-or-v1-...",
        "last_status": "ok",
        "request_count": 142
      }
    ]
  },
}

Стратегии хранятся в config.yaml (не auth.json):

credential_pool_strategies:
  openrouter: round_robin
  anthropic: least_used