Резервные провайдеры

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

  1. Пул учётных данных — ротация нескольких API-ключей для одного и того же провайдера (проверяется в первую очередь)

  2. Резервирование основной модели — автоматическое переключение на другой провайдер:модель при сбое основной модели

  3. Резервирование вспомогательных задач — независимое разрешение провайдера для побочных задач, таких как vision, сжатие и извлечение веб-данных

Пулы учётных данных обрабатывают ротацию в рамках одного провайдера (например, несколько ключей OpenRouter). Эта страница описывает кросс-провайдерное резервирование. Обе опции необязательны и работают независимо.

Резервирование основной модели

Когда ваш основной LLM-провайдер сталкивается с ошибками — ограничениями частоты запросов, перегрузкой сервера, сбоями аутентификации, обрывами соединения — Hermes может автоматически переключиться на резервную пару провайдер:модель прямо в середине сессии, не теряя вашего разговора.

Настройка

Самый простой способ — интерактивный менеджер:

hermes fallback

hermes fallback использует тот же выбор провайдера, что и hermes model — тот же список провайдеров, те же запросы учётных данных, та же валидация. Используйте подкоманды add, list (алиас ls), remove (алиас rm) и clear для управления цепочкой. Изменения сохраняются в списке fallback_providers: верхнего уровня в config.yaml.

Если вы предпочитаете редактировать YAML напрямую, добавьте секцию fallback_model в ~/.hermes/config.yaml:

fallback_model:
  provider: openrouter
  model: anthropic/claude-sonnet-4

Оба поля — provider и modelобязательны. Если хотя бы одного из них нет, резервирование отключается.

note fallback_model против fallback_providers fallback_model (единственное число) — устаревший ключ для одного резервного варианта — Hermes по-прежнему поддерживает его для обратной совместимости. fallback_providers (множественное число, список) поддерживает несколько резервных вариантов, перебираемых по порядку; hermes fallback записывает данные в этот ключ. Если заданы оба, Hermes объединяет их, причём fallback_providers имеет приоритет.

Поддерживаемые провайдеры

Провайдер Значение Требования
AI Gateway ai-gateway AI_GATEWAY_API_KEY
OpenRouter openrouter OPENROUTER_API_KEY
Nous Portal nous hermes auth (OAuth)
OpenAI Codex openai-codex hermes model (ChatGPT OAuth)
GitHub Copilot copilot COPILOT_GITHUB_TOKEN, GH_TOKEN или GITHUB_TOKEN
GitHub Copilot ACP copilot-acp Внешний процесс (интеграция с редактором)
Anthropic anthropic ANTHROPIC_API_KEY или учётные данные Claude Code
z.ai / GLM zai GLM_API_KEY
Kimi / Moonshot kimi-coding KIMI_API_KEY
MiniMax minimax MINIMAX_API_KEY
MiniMax (Китай) minimax-cn MINIMAX_CN_API_KEY
DeepSeek deepseek DEEPSEEK_API_KEY
NVIDIA NIM nvidia NVIDIA_API_KEY (опционально: NVIDIA_BASE_URL)
GMI Cloud gmi GMI_API_KEY (опционально: GMI_BASE_URL)
StepFun stepfun STEPFUN_API_KEY (опционально: STEPFUN_BASE_URL)
Ollama Cloud ollama-cloud OLLAMA_API_KEY
Google Gemini (OAuth) google-gemini-cli hermes model (Google OAuth; опционально: HERMES_GEMINI_PROJECT_ID)
Google AI Studio gemini GOOGLE_API_KEY (алиас: GEMINI_API_KEY)
xAI (Grok) xai (алиас grok) XAI_API_KEY (опционально: XAI_BASE_URL)
AWS Bedrock bedrock Стандартная аутентификация boto3 (AWS_REGION + AWS_PROFILE или AWS_ACCESS_KEY_ID)
Qwen Portal (OAuth) qwen-oauth hermes model (Qwen Portal OAuth; опционально: HERMES_QWEN_BASE_URL)
MiniMax (OAuth) minimax-oauth hermes model (MiniMax portal OAuth)
OpenCode Zen opencode-zen OPENCODE_ZEN_API_KEY
OpenCode Go opencode-go OPENCODE_GO_API_KEY
Kilo Code kilocode KILOCODE_API_KEY
Xiaomi MiMo xiaomi XIAOMI_API_KEY
Arcee AI arcee ARCEEAI_API_KEY
GMI Cloud gmi GMI_API_KEY
Alibaba / DashScope alibaba DASHSCOPE_API_KEY
Alibaba Coding Plan alibaba-coding-plan ALIBABA_CODING_PLAN_API_KEY (запасной вариант: DASHSCOPE_API_KEY)
Kimi / Moonshot (Китай) kimi-coding-cn KIMI_CN_API_KEY
StepFun stepfun STEPFUN_API_KEY
Tencent TokenHub tencent-tokenhub TOKENHUB_API_KEY
Azure AI Foundry azure-foundry AZURE_FOUNDRY_API_KEY + AZURE_FOUNDRY_BASE_URL
LM Studio (локальный) lmstudio LM_API_KEY (или без ключа для локального) + LM_BASE_URL
Hugging Face huggingface HF_TOKEN
Собственный endpoint custom base_url + key_env (см. ниже)

Резервирование через собственный endpoint

Для собственного endpoint'а, совместимого с OpenAI, добавьте base_url и опционально key_env:

fallback_model:
  provider: custom
  model: my-local-model
  base_url: http://localhost:8000/v1
  key_env: MY_LOCAL_KEY              # имя переменной окружения, содержащей API-ключ

Когда срабатывает резервирование

Резервирование активируется автоматически, когда основная модель завершается с ошибкой:

При срабатывании Hermes:

  1. Разрешает учётные данные для резервного провайдера

  2. Создаёт новый API-клиент

  3. Заменяет модель, провайдера и клиент на месте

  4. Сбрасывает счётчик повторных попыток и продолжает разговор

Переключение происходит бесшовно — история разговора, вызовы инструментов и контекст сохраняются. Агент продолжает ровно с того места, где остановился, просто используя другую модель.

info Пошаговое, а не посессионное Резервирование действует в рамках одного шага: каждое новое сообщение пользователя начинается с восстановления основной модели. Если основная модель выходит из строя во время шага, резервирование активируется только для этого шага. При следующем сообщении Hermes снова пробует основную модель. В пределах одного шага резервирование срабатывает не более одного раза — если резервный вариант тоже выходит из строя, вступает в силу обычная обработка ошибок (повторные попытки, затем сообщение об ошибке). Это предотвращает каскадные циклы переключения в рамках одного шага, давая при этом основной модели новый шанс на каждом шаге.

Примеры

OpenRouter как резервный вариант для Anthropic native:

model:
  provider: anthropic
  default: claude-sonnet-4-6

fallback_model:
  provider: openrouter
  model: anthropic/claude-sonnet-4

Nous Portal как резервный вариант для OpenRouter:

model:
  provider: openrouter
  default: anthropic/claude-opus-4

fallback_model:
  provider: nous
  model: nous-hermes-3

Локальная модель как резервный вариант для облачной:

fallback_model:
  provider: custom
  model: llama-3.1-70b
  base_url: http://localhost:8000/v1
  key_env: LOCAL_API_KEY

Codex OAuth как резервный вариант:

fallback_model:
  provider: openai-codex
  model: gpt-5.3-codex

Где работает резервирование

Контекст Резервирование поддерживается
CLI-сессии
Мессенджеры (Telegram, Discord и др.)
Делегирование сабэдженту ✘ (сабэдженты не наследуют конфигурацию резервирования)
Cron-задачи ✘ (выполняются с фиксированным провайдером)
Вспомогательные задачи (vision, сжатие) ✘ (используют свою цепочку провайдеров — см. ниже)
Для `fallback_model` не существует переменных окружения — он настраивается исключительно через `config.yaml`. Это сделано намеренно: конфигурация резервирования — это осознанный выбор, а не то, что может переопределить устаревший экспорт оболочки.

Резервирование вспомогательных задач

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

Задачи с независимым разрешением провайдера

Задача Что делает Ключ конфигурации
Vision Анализ изображений, скриншоты браузера auxiliary.vision
Web Extract Суммаризация веб-страниц auxiliary.web_extract
Compression Суммаризация для сжатия контекста auxiliary.compression
Session Search Суммаризация прошлых сессий auxiliary.session_search
Skills Hub Поиск и обнаружение навыков auxiliary.skills_hub
MCP Вспомогательные операции MCP auxiliary.mcp
Approval Умная классификация подтверждения команд auxiliary.approval
Title Generation Суммаризация названий сессий auxiliary.title_generation
Triage Specifier hermes kanban specify / кнопка ✨ на дашборде — превращает однострочную задачу триажа в полноценную спецификацию auxiliary.triage_specifier

Цепочка автоопределения

Когда для задачи задан провайдер "auto" (по умолчанию), Hermes перебирает провайдеров по порядку, пока один из них не сработает:

Для текстовых задач (сжатие, извлечение веб-данных и т.д.):

OpenRouter → Nous Portal → Custom endpoint → Codex OAuth →
API-key providers (z.ai, Kimi, MiniMax, Xiaomi MiMo, Hugging Face, Anthropic) → give up

Для задач vision:

Main provider (if vision-capable) → OpenRouter → Nous Portal →
Codex OAuth → Anthropic → Custom endpoint → give up

Если разрешённый провайдер в момент вызова выдаёт ошибку, Hermes также выполняет внутреннюю повторную попытку: если провайдер не OpenRouter и не задан явный base_url, он пробует OpenRouter как запасной вариант.

Настройка вспомогательных провайдеров

Каждая задача может быть настроена независимо в config.yaml:

auxiliary:
  vision:
    provider: "auto"              # auto | openrouter | nous | codex | main | anthropic
    model: ""                     # например "openai/gpt-4o"
    base_url: ""                  # прямой endpoint (имеет приоритет над provider)
    api_key: ""                   # API-ключ для base_url

  web_extract:
    provider: "auto"
    model: ""

  compression:
    provider: "auto"
    model: ""

  session_search:
    provider: "auto"
    model: ""
    timeout: 30
    max_concurrency: 3
    extra_body: {}

  skills_hub:
    provider: "auto"
    model: ""

  mcp:
    provider: "auto"
    model: ""

Каждая задача выше следует одному и тому же шаблону provider / model / base_url. Сжатие контекста настраивается в auxiliary.compression:

auxiliary:
  compression:
    provider: main                                    # Те же опции провайдера, что и для других вспомогательных задач
    model: google/gemini-3-flash-preview
    base_url: null                                    # Собственный endpoint, совместимый с OpenAI

А резервная модель использует:

fallback_model:
  provider: openrouter
  model: anthropic/claude-sonnet-4
  # base_url: http://localhost:8000/v1               # Опциональный собственный endpoint

Для auxiliary.session_search Hermes также поддерживает:

Пример:

auxiliary:
  session_search:
    provider: main
    model: glm-4.5-air
    max_concurrency: 2
    extra_body:
      enable_thinking: false

Если ваш провайдер не поддерживает нативное поле управления рассуждениями, совместимое с OpenAI, extra_body в этой части не поможет; в таком случае max_concurrency всё ещё полезен для уменьшения пиковых ошибок 429.

Все три — вспомогательные задачи, сжатие и резервирование — работают одинаково: укажите provider для выбора того, кто обрабатывает запрос, model для выбора модели и base_url для указания собственного endpoint'а (переопределяет провайдера).

Параметры провайдера для вспомогательных задач

Эти опции применяются только к конфигурациям auxiliary:, compression: и fallback_model:"main" не является допустимым значением для вашего model.provider верхнего уровня. Для собственных endpoint'ов используйте provider: custom в секции model: (см. AI Providers).

Провайдер Описание Требования
"auto" Перебирать провайдеров по порядку, пока один не сработает (по умолчанию) Хотя бы один настроенный провайдер
"openrouter" Принудительно использовать OpenRouter OPENROUTER_API_KEY
"nous" Принудительно использовать Nous Portal hermes auth
"codex" Принудительно использовать Codex OAuth hermes model → Codex
"main" Использовать того же провайдера, что и основной агент (только для вспомогательных задач) Активный основной провайдер
"anthropic" Принудительно использовать Anthropic native ANTHROPIC_API_KEY или учётные данные Claude Code

Прямое указание endpoint'а

Для любой вспомогательной задачи установка base_url полностью обходит разрешение провайдера и отправляет запросы напрямую на указанный endpoint:

auxiliary:
  vision:
    base_url: "http://localhost:1234/v1"
    api_key: "local-key"
    model: "qwen2.5-vl"

base_url имеет приоритет над provider. Hermes использует настроенный api_key для аутентификации, а при его отсутствии — OPENAI_API_KEY. Он не использует OPENROUTER_API_KEY для собственных endpoint'ов.


Резервирование сжатия контекста

Сжатие контекста использует блок конфигурации auxiliary.compression для управления тем, какая модель и провайдер обрабатывают суммаризацию:

auxiliary:
  compression:
    provider: "auto"                              # auto | openrouter | nous | main
    model: "google/gemini-3-flash-preview"

info Миграция устаревших конфигураций Старые конфигурации с compression.summary_model / compression.summary_provider / compression.summary_base_url автоматически мигрируются в auxiliary.compression.* при первой загрузке (версия конфигурации 17).

Если ни один провайдер не доступен для сжатия, Hermes удаляет промежуточные повороты разговора без генерации суммаризации, а не прерывает сессию.


Переопределение провайдера для делегирования

Сабэдженты, порождённые delegate_task, не используют резервную модель основной модели. Однако их можно направить на другую пару провайдер:модель для оптимизации затрат:

delegation:
  provider: "openrouter"                      # переопределение провайдера для всех сабэджентов
  model: "google/gemini-3-flash-preview"      # переопределение модели
  # base_url: "http://localhost:1234/v1"      # или используйте прямой endpoint
  # api_key: "local-key"

См. Subagent Delegation для полной информации о настройке.


Провайдеры для Cron-задач

Cron-задачи выполняются с тем провайдером, который настроен на момент выполнения. Они не поддерживают резервную модель. Чтобы использовать другого провайдера для cron-задач, настройте переопределение provider и model непосредственно в задаче:

cronjob(
    action="create",
    schedule="every 2h",
    prompt="Check server status",
    provider="openrouter",
    model="google/gemini-3-flash-preview"
)

См. Scheduled Tasks (Cron) для полной информации о настройке.


Краткий обзор

Функция Механизм резервирования Расположение в конфигурации
Основная модель агента fallback_model в config.yaml — пошаговое переключение при ошибках (основная модель восстанавливается на каждом шаге) fallback_model: (верхний уровень)
Vision Цепочка автоопределения + внутренняя повторная попытка OpenRouter auxiliary.vision
Извлечение веб-данных Цепочка автоопределения + внутренняя повторная попытка OpenRouter auxiliary.web_extract
Сжатие контекста Цепочка автоопределения, понижение до отсутствия суммаризации, если недоступно auxiliary.compression
Поиск по сессиям Цепочка автоопределения auxiliary.session_search
Skills hub Цепочка автоопределения auxiliary.skills_hub
MCP-помощники Цепочка автоопределения auxiliary.mcp
Классификация подтверждений Цепочка автоопределения auxiliary.approval
Генерация названий Цепочка автоопределения auxiliary.title_generation
Спецификатор триажа Цепочка автоопределения auxiliary.triage_specifier
Делегирование Только переопределение провайдера (без автоматического резервирования) delegation.provider / delegation.model
Cron-задачи Только переопределение провайдера на задачу (без автоматического резервирования) provider / model задачи