Credential Pools: ротация API-ключей

Что такое Credential Pools

Credential Pools — механизм Hermes Agent для управления несколькими API-ключами одного провайдера с автоматической ротацией. Когда один ключ исчерпывает лимит запросов, система автоматически переключается на следующий доступный ключ из пула — без прерывания работы.

Это особенно важно для провайдеров с жёсткими лимитами (rate limits) на бесплатных и базовых тарифах: OpenRouter, DeepSeek, Google Gemini и других.

Зачем нужны Credential Pools

• Бесперебойная работа — агент не останавливается при достижении лимита одного ключа
• Масштабирование нагрузки — распределение запросов между несколькими ключами увеличивает общий throughput
• Устойчивость к ошибкам — если ключ заблокирован или истёк, система переключается автоматически
• Прозрачная ротация — пользователь не замечает переключений, ключи меняются «под капотом»

Команды управления

Добавление ключа

hermes auth add

Интерактивный мастер добавления credential. Запрашивает:

• Провайдер (openrouter, anthropic, deepseek, google, xai и др.)
• API-ключ
• Необязательное описание (label) для идентификации

Ключ сохраняется в ~/.hermes/auth.json (или ~/.hermes/profiles/<name>/credentials.json для профиля).

Просмотр ключей

hermes auth list
hermes auth list openrouter

Без аргумента показывает все ключи всех провайдеров. С указанием провайдера — только его ключи. Выводит:

• Индекс ключа в пуле
• Маскированный ключ (первые и последние символы)
• Статус (активен / исчерпан / ошибка)
• Количество успешных запросов

Удаление ключа

hermes auth remove openrouter 0

Удаляет ключ по индексу из пула указанного провайдера. Индекс берётся из вывода hermes auth list.

Сброс статуса

hermes auth reset openrouter

Сбрасывает статус «исчерпан» у всех ключей провайдера. Полезно после того, как лимиты провайдера сбросились (обычно раз в минуту или в день). После сброса ключи снова становятся доступными для использования.

Примеры использования

Настройка пула OpenRouter с несколькими ключами

# Добавить несколько ключей OpenRouter
hermes auth add
# → выбираем openrouter, вставляем ключ-1

hermes auth add
# → выбираем openrouter, вставляем ключ-2

hermes auth add
# → выбираем openrouter, вставляем ключ-3

# Проверить пул
hermes auth list openrouter

Комбинирование провайдеров

# Основной провайдер — OpenRouter (несколько ключей)
hermes auth add  # openrouter, ключ A
hermes auth add  # openrouter, ключ B

# Резервный — DeepSeek напрямую
hermes auth add  # deepseek, ключ C

# Просмотр всех
hermes auth list

Восстановление после rate limit

# Если все ключи исчерпаны после сброса лимита провайдера:
hermes auth reset openrouter

# Проверить что ключи снова активны
hermes auth list openrouter

Как работает ротация

Внутренний механизм credential pool работает следующим образом:

1. При старте — Hermes загружает все ключи из auth.json / credentials.json
2. При запросе к API — берёт следующий активный ключ из пула (round-robin)
3. При ошибке 429 (rate limit) — помечает текущий ключ как «исчерпан» и переключается на следующий
4. При ошибке 401/403 — помечает ключ как «недействительный» и переключается
5. Когда все ключи исчерпаны — Hermes сообщает об ошибке и предлагает hermes auth reset

Файл хранения

Ключи хранятся в JSON-файле с метаданными:

~/.hermes/auth.json                     # Глобальные ключи
~/.hermes/profiles/<name>/credentials.json  # Ключи профиля

Структура файла:

{
  "openrouter": [
    {
      "key": "sk-or-v1-...",
      "label": "основной",
      "status": "active",
      "requests": 142,
      "errors": 0
    },
    {
      "key": "sk-or-v1-...",
      "label": "запасной",
      "status": "exhausted",
      "requests": 500,
      "errors": 12
    }
  ]
}

Провайдеры с поддержкой пулов

Credential pools работают со всеми провайдерами, использующими API-ключи:

Примечание: OAuth-провайдеры (Nous Portal, OpenAI Codex, Qwen) управляются через hermes login и не поддерживают пулы ключей — там используется refresh token flow.

Советы и рекомендации

• Используйте разные аккаунты — ключи из одного аккаунта обычно имеют общий лимит
• Подпишите ключи — используйте label при добавлении, чтобы понимать происхождение каждого ключа
• Мониторьте статус — регулярно проверяйте hermes auth list для отслеживания использования
• Профили для изоляции — разные профили Hermes могут иметь разные пулы ключей
• Не храните ключи в .env напрямую — используйте hermes auth add для управления через credential pool; переменные в .env — для одиночных ключей без ротации