Provedores de reserva

O Hermes Agent tem três camadas de resiliência que mantêm suas sessões rodando quando os provedores dão problema:

1. Pools de credenciais — rodízio entre várias chaves de API do mesmo provedor (tentado primeiro)
2. Reserva do modelo principal — troca automaticamente para um par provedor:modelo diferente quando o seu modelo principal falha
3. Reserva de tarefas auxiliares — resolução de provedor independente para tarefas secundárias, como visão e compressão

Os pools de credenciais cuidam do rodízio dentro do mesmo provedor (por exemplo, várias chaves do OpenRouter). Esta página cobre a reserva entre provedores. As duas coisas são opcionais e funcionam de forma independente.

Reserva do modelo principal

Quando o seu provedor principal de LLM encontra erros — limites de taxa, sobrecarga do servidor, falhas de autenticação, quedas de conexão — o Hermes pode trocar automaticamente para um par provedor:modelo reserva no meio da sessão, sem perder a sua conversa.

Configuração

O caminho mais fácil é o gerenciador interativo:

hermes fallback

O hermes fallback reaproveita o seletor de provedores do hermes model — mesma lista de provedores, mesmos pedidos de credenciais, mesma validação. Use os subcomandos add, list (apelido ls), remove (apelido rm) e clear para gerenciar a cadeia. As mudanças persistem na lista de nível superior fallback_providers: do config.yaml.

Se você preferir editar o YAML direto, adicione uma lista fallback_providers de nível superior ao ~/.hermes/config.yaml:

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

Cada entrada precisa de provider e model. Entradas sem um dos dois campos são ignoradas.

fallback_model vs fallback_providers

fallback_providers (plural, lista) é o formato atual de configuração e suporta várias reservas tentadas em ordem. fallback_model (singular) é a chave legada de reserva única — o Hermes ainda a respeita por compatibilidade retroativa, mas o hermes fallback grava a chave atual fallback_providers e migra a configuração legada ao escrever. Quando as duas estão definidas, fallback_providers tem prioridade.

Provedores suportados

Provedor	Valor	Requisitos
AI Gateway	ai-gateway	AI_GATEWAY_API_KEY
OpenRouter	openrouter	OPENROUTER_API_KEY
Nous Portal	nous	hermes setup --portal (do zero) ou hermes auth add nous (OAuth)
OpenAI Codex	openai-codex	hermes model → ChatGPT or Codex Subscription (OAuth do ChatGPT)
GitHub Copilot	copilot	COPILOT_GITHUB_TOKEN, GH_TOKEN ou GITHUB_TOKEN
GitHub Copilot ACP	copilot-acp	Processo externo (integração com editor)
Anthropic	anthropic	ANTHROPIC_API_KEY ou credenciais do Claude Code
z.ai / GLM	zai	GLM_API_KEY
Kimi / Moonshot	kimi-coding	KIMI_API_KEY
MiniMax	minimax	MINIMAX_API_KEY
MiniMax (China)	minimax-cn	MINIMAX_CN_API_KEY
DeepSeek	deepseek	DEEPSEEK_API_KEY
NVIDIA NIM	nvidia	NVIDIA_API_KEY (opcional: NVIDIA_BASE_URL)
GMI Cloud	gmi	GMI_API_KEY (opcional: GMI_BASE_URL)
Upstage Solar	upstage (apelido solar)	UPSTAGE_API_KEY (opcional: UPSTAGE_BASE_URL)
StepFun	stepfun	STEPFUN_API_KEY (opcional: STEPFUN_BASE_URL)
Ollama Cloud	ollama-cloud	OLLAMA_API_KEY
Google AI Studio	gemini	GOOGLE_API_KEY (apelido: GEMINI_API_KEY)
xAI (Grok)	xai (apelido grok)	XAI_API_KEY (opcional: XAI_BASE_URL)
xAI Grok OAuth (SuperGrok)	xai-oauth (apelido grok-oauth)	hermes model → xAI Grok OAuth (login pelo navegador; assinatura SuperGrok)
AWS Bedrock	bedrock	Autenticação padrão do boto3 (AWS_REGION + AWS_PROFILE ou AWS_ACCESS_KEY_ID)
Qwen Portal (OAuth)	qwen-oauth	hermes model (OAuth do Qwen Portal; opcional: HERMES_QWEN_BASE_URL)
MiniMax (OAuth)	minimax-oauth	hermes model (OAuth do portal MiniMax)
OpenCode Zen	opencode-zen	OPENCODE_ZEN_API_KEY
CommandCode	commandcode (apelido commandcode-chat; Claude via commandcode-anthropic)	COMMANDCODE_API_KEY
OpenCode Go	opencode-go	OPENCODE_GO_API_KEY
OpenCode Free	opencode-free	— (sem chave, sem credencial)
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 (recorre a DASHSCOPE_API_KEY)
Kimi / Moonshot (China)	kimi-coding-cn	KIMI_CN_API_KEY
StepFun	stepfun	STEPFUN_API_KEY
Tencent TokenHub	tencent-tokenhub	TOKENHUB_API_KEY
Microsoft Foundry	azure-foundry	AZURE_FOUNDRY_API_KEY + AZURE_FOUNDRY_BASE_URL
LM Studio (local)	lmstudio	LM_API_KEY (ou nenhuma, no uso local) + LM_BASE_URL
Hugging Face	huggingface	HF_TOKEN
Endpoint personalizado	custom	base_url + key_env (veja abaixo)

Reserva com endpoint personalizado

Para um endpoint personalizado compatível com OpenAI, adicione base_url e, opcionalmente, key_env:

fallback_providers:
  - provider: custom
    model: meu-modelo-local
    base_url: http://localhost:8000/v1
    key_env: MY_LOCAL_KEY            # nome da variável de ambiente com a chave de API

Quando a reserva dispara

A reserva é ativada automaticamente quando o modelo principal falha com:

• Limites de taxa (HTTP 429) — depois de esgotar as tentativas de repetição
• Erros de servidor (HTTP 500, 502, 503) — depois de esgotar as tentativas de repetição
• Falhas de autenticação (HTTP 401, 403) — imediatamente (não adianta repetir)
• Não encontrado (HTTP 404) — imediatamente
• Respostas inválidas — quando a API retorna respostas malformadas ou vazias repetidamente

Quando dispara, o Hermes:

1. Resolve as credenciais do provedor de reserva
2. Constrói um novo cliente de API
3. Troca modelo, provedor e cliente no lugar
4. Zera o contador de repetições e continua a conversa

A troca é transparente — seu histórico de conversa, chamadas de ferramenta e contexto são preservados. O agente continua exatamente de onde parou, só que usando um modelo diferente.

A reserva zera o cache de prompt

Caches de prompt são indexados pelo modelo (e, na maioria dos provedores, pela conta) que atende a requisição. Quando a reserva dispara, o novo par provedor:modelo não tem prefixo em cache para a sua conversa, então a próxima requisição relê o histórico inteiro pelo preço cheio de tokens de entrada, em vez da tarifa em cache com desconto de cerca de 75 a 90%. O mesmo vale quando o turno termina e o principal é restaurado — essa primeira requisição de volta no principal também é uma releitura completa (a menos que o TTL do cache do principal ainda não tenha expirado). Isso é inevitável — é o custo de continuar vivo durante uma queda — mas é por isso que uma sessão longa que fica pulando entre provedores pode sair bem mais cara do que uma que fica parada.

Por turno, não por sessão

A reserva tem escopo de turno: cada nova mensagem do usuário começa com o modelo principal restaurado. Se o principal falha no meio do turno, a reserva é ativada só para aquele turno. Na mensagem seguinte, o Hermes tenta o principal de novo. Dentro de um único turno, a reserva é ativada no máximo uma vez — se a reserva também falha, o tratamento normal de erro assume (repetições e depois mensagem de erro). Isso evita laços de failover em cascata dentro de um turno e ainda dá ao modelo principal uma chance nova a cada turno.

A repetição por turno é consciente do reset: quando as credenciais do principal informam um horário de reset do limite de taxa que ainda não passou (janelas de assinatura, como os blocos de 5 horas do Claude Pro/Max ou os limites semanais do Codex, reportam isso em horas ou dias), o Hermes pula a repetição fadada ao fracasso e permanece na reserva até o reset passar — evitando duas trocas inúteis de provedor (e duas invalidações de cache de prompt) por turno. No momento em que o horário de reset passa, o turno seguinte volta ao principal automaticamente. Erros 429 transitórios sem horário de reset mantêm o comportamento existente: um breve resfriamento e depois repetição a cada turno.

Exemplos

OpenRouter como reserva para o Anthropic nativo:

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

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

Nous Portal como reserva para o OpenRouter:

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

fallback_providers:
  - provider: nous
    model: nous-hermes-3

Modelo local como reserva para a nuvem:

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

Codex OAuth como reserva:

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

Onde a reserva funciona

Contexto	Reserva suportada
Sessões da CLI	✔
Gateway de mensagens (Telegram, Discord etc.)	✔
Delegação a subagentes	✔ (subagentes herdam a cadeia de reserva do pai)
Tarefas de cron	✔ (agentes de cron herdam os provedores de reserva configurados)
Tarefas auxiliares em provider: auto	✔ (tenta a reserva por tarefa e depois a cadeia de reserva principal, antes da descoberta auxiliar embutida)

dica

Não existem variáveis de ambiente para a cadeia de reserva principal — configure-a exclusivamente pelo config.yaml ou pelo hermes fallback. Isso é intencional: a configuração de reserva é uma escolha deliberada, não algo que um export de shell antigo deva sobrescrever.

---

Reserva de tarefas auxiliares

O Hermes usa modelos leves separados para tarefas secundárias. Cada tarefa tem sua própria cadeia de resolução de provedor, que funciona como um sistema de reserva embutido.

Tarefas com resolução independente de provedor

Tarefa	O que faz	Chave de configuração
Visão	Análise de imagens, capturas de tela do navegador	auxiliary.vision
Compressão	Resumos de compressão de contexto	auxiliary.compression
Skills Hub	Busca e descoberta de skills	auxiliary.skills_hub
MCP	Operações auxiliares de MCP	auxiliary.mcp
Aprovação	Classificação inteligente de aprovação de comandos	auxiliary.approval
Geração de título	Resumos de título de sessão	auxiliary.title_generation
Revisão	Subagente revisor do /review (um agente completo, não uma única chamada de LLM)	auxiliary.review
Especificador de triagem	hermes kanban specify / botão ✨ do painel — transforma uma tarefa de triagem de uma linha em uma especificação de verdade	auxiliary.triage_specifier

Cadeia de detecção automática

Quando o provedor de uma tarefa está definido como "auto" (o padrão), o Hermes tenta primeiro o provedor principal + modelo principal para aquela tarefa auxiliar. Se essa rota não estiver disponível ou falhar depois com um erro do tipo capacidade, o Hermes agora respeita a política de reserva configurada pelo usuário antes de usar a cadeia de descoberta embutida:

Provedor principal + modelo principal → auxiliary.<task>.fallback_chain →
fallback_providers / fallback_model → cadeia de descoberta auxiliar embutida

A cadeia específica da tarefa é a mais precisa e vence quando está presente. A cadeia de nível superior fallback_providers é a mesma política que o agente principal usa, então regras de reserva do tipo "só gratuitos" ou "mesmo provedor" valem também para as tarefas auxiliares em auto.

Cadeia embutida de descoberta para texto (compressão, extração da web, geração de título etc.):

OpenRouter → Nous Portal → Endpoint personalizado → Codex OAuth →
provedores com chave de API (z.ai, Kimi, MiniMax, Xiaomi MiMo, Hugging Face, Anthropic) → desiste

Cadeia embutida de descoberta para visão:

Provedor principal (se tiver visão) → OpenRouter → Nous Portal →
Codex OAuth → Anthropic → Endpoint personalizado → desiste

Essas cadeias embutidas são uma reserva de conveniência para quem não declarou uma política de reserva específica da tarefa nem principal.

Configurar provedores auxiliares

Cada tarefa pode ser configurada de forma independente no config.yaml:

auxiliary:
  vision:
    provider: "auto"              # auto | openrouter | nous | codex | main | anthropic
    model: ""                     # por exemplo, "openai/gpt-4o"
    base_url: ""                  # endpoint direto (tem precedência sobre provider)
    api_key: ""                   # chave de API para o base_url

  compression:
    provider: "auto"
    model: ""
    fallback_chain:              # opcional, política de reserva específica da tarefa
      - provider: openrouter
        model: inclusionai/ring-2.6-1t:free

  skills_hub:
    provider: "auto"
    model: ""

  mcp:
    provider: "auto"
    model: ""

Toda tarefa acima segue o mesmo padrão provider / model / base_url. Cada tarefa também pode declarar a própria fallback_chain; se você omitir, provider: auto usa a cadeia de nível superior fallback_providers antes da cadeia de descoberta auxiliar embutida do Hermes.

A compressão de contexto é configurada em auxiliary.compression:

auxiliary:
  compression:
    provider: main                                    # Mesmas opções de provedor das outras tarefas auxiliares
    model: google/gemini-3-flash-preview
    base_url: null                                    # Endpoint personalizado compatível com OpenAI

E a cadeia de reserva principal usa:

fallback_providers:
  - provider: openrouter
    model: anthropic/claude-sonnet-4
    # base_url: http://localhost:8000/v1             # Endpoint personalizado opcional

As três coisas — auxiliar, compressão, reserva — funcionam do mesmo jeito: defina provider para escolher quem atende a requisição, model para escolher qual modelo e base_url para apontar para um endpoint personalizado (que sobrepõe o provedor).

Opções de provedor para tarefas auxiliares

Estas opções valem só para entradas de auxiliary:, compression: e fallback_providers: — "main" não é um valor válido para o seu model.provider de nível superior. Para endpoints personalizados, use provider: custom na sua seção model: (veja Provedores de IA).

Provedor	Descrição	Requisitos
"auto"	Tenta os provedores em ordem até um funcionar (padrão)	Pelo menos um provedor configurado
"openrouter"	Força o OpenRouter	OPENROUTER_API_KEY
"nous"	Força o Nous Portal	hermes auth
"codex"	Força o Codex OAuth	hermes model → ChatGPT or Codex Subscription
"main"	Usa o provedor que o agente principal usa (só em tarefas auxiliares)	Provedor principal ativo configurado
"anthropic"	Força o Anthropic nativo	ANTHROPIC_API_KEY ou credenciais do Claude Code

Sobrescrita por endpoint direto

Em qualquer tarefa auxiliar, definir base_url contorna a resolução de provedor por completo e envia as requisições direto para aquele endpoint:

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

O base_url tem precedência sobre provider. O Hermes usa a api_key configurada para autenticação, recorrendo a OPENAI_API_KEY se ela não estiver definida. Ele não reaproveita a OPENROUTER_API_KEY para endpoints personalizados.

---

Reserva auxiliar por erro de capacidade

Quando você define um provedor auxiliar explícito (por exemplo, auxiliary.vision.provider: glm), o Hermes trata isso como a sua escolha preferida — mas, se o provedor literalmente não puder atender a requisição por causa de um erro de capacidade (HTTP 402 pagamento necessário, HTTP 429 por cota diária esgotada, falha de conexão), o Hermes recorre a uma cadeia em camadas em vez de falhar em silêncio:

1. Provedor auxiliar principal — o que você configurou (tentado primeiro, sempre)
2. auxiliary.<task>.fallback_chain — a sua lista de sobrescrita por tarefa, se você escreveu uma
3. Provedor + modelo do agente principal — rede de segurança de último recurso (sempre tentada, mesmo se você não escreveu uma cadeia)
4. Avisar e relançar — se todas as camadas falham, o Hermes registra Auxiliary <task>: ... all fallbacks exhausted no nível WARNING e relança o erro original

Limites de taxa HTTP 429 transitórios (Retry-After: ...) são tratados como restrições de requisição, não como problemas de capacidade — eles respeitam a sua escolha explícita de provedor e não disparam a escada de reserva. Só esgotamento de cota diária/mensal, erros de pagamento e falhas de conexão passam por cima da trava do provedor explícito.

Para quem está em provider: auto (sem provedor auxiliar explícito), a cadeia de detecção automática existente roda no lugar dos passos 2 e 3. O primeiro passo dela já é o modelo do agente principal, então quem usa auto chega ao mesmo resultado sem nenhuma configuração.

Opcional: cadeia de reserva por tarefa

Se você quer uma ordem de reserva diferente de "modelo do agente principal primeiro", configure fallback_chain explicitamente. Cada entrada precisa pelo menos de provider; model, base_url e api_key são opcionais.

auxiliary:
  vision:
    provider: glm
    model: glm-4v-flash
    fallback_chain:
      - provider: openrouter
        model: google/gemini-3-flash-preview
      - provider: nous
        model: anthropic/claude-sonnet-4

  compression:
    provider: openrouter
    fallback_chain:
      - provider: openai
        model: gpt-4o-mini
        timeout: 240            # opcional — prazo próprio deste candidato (segundos)

Você não precisa configurar fallback_chain para ter reserva — a rede de segurança do agente principal roda de qualquer jeito. Use apenas quando você quiser especificamente uma ordem diferente do padrão.

Cada entrada de fallback_chain também pode declarar o próprio timeout (em segundos). Sem ele, um candidato de reserva herda o tempo limite da tarefa — que pode estar ajustado para o provedor principal. Declarar um timeout por entrada permite que uma reserva mais lenta, porém confiável (por exemplo, um sumarizador de contexto grande), receba o orçamento de que realmente precisa, em vez de morrer no relógio do principal.

Erros de cota do provedor que disparam a reserva

O Hermes reconhece estes como equivalentes de capacidade ao esgotamento de crédito 402 (e não como limites de taxa transitórios):

• Bedrock / LiteLLM: Too many tokens per day, daily limit, tokens per day
• Vertex AI / GCP: quota exceeded, resource exhausted, RESOURCE_EXHAUSTED
• Genéricos: daily quota, quota_exceeded

Se o seu provedor retorna uma frase diferente para esgotamento de cota diária e o Hermes não dispara a reserva, isso é um bug — abra uma issue com a string exata do erro.

---

Reserva na compressão de contexto

A compressão de contexto usa o bloco de configuração auxiliary.compression para controlar qual modelo e qual provedor cuidam da sumarização:

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

Migração de configuração legada

Configurações antigas com compression.summary_model / compression.summary_provider / compression.summary_base_url são migradas automaticamente para auxiliary.compression.* no primeiro carregamento (versão 17 da configuração).

Se nenhum provedor estiver disponível para a compressão, o Hermes descarta turnos do meio da conversa sem gerar um resumo, em vez de derrubar a sessão.

---

Sobrescrita de provedor na delegação

Subagentes iniciados por delegate_task herdam a cadeia de reserva principal do agente pai. Mesmo assim, você pode rotear os subagentes para outro par provedor:modelo principal para otimizar custos:

delegation:
  provider: "openrouter"                      # sobrescreve o provedor de todos os subagentes
  model: "google/gemini-3-flash-preview"      # sobrescreve o modelo
  # base_url: "http://localhost:1234/v1"      # ou use um endpoint direto
  # api_key: "chave-local"

Veja Delegação a subagentes para os detalhes completos de configuração.

---

Provedores das tarefas de cron

Tarefas de cron herdam a cadeia fallback_providers que você configurou (ou o legado fallback_model) quando criam um agente. Para usar outro provedor principal em uma tarefa de cron, configure as sobrescritas provider e model na própria tarefa:

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

Veja Tarefas agendadas (cron) para os detalhes completos de configuração.

---

Resumo

Recurso	Mecanismo de reserva	Local da configuração
Modelo do agente principal	fallback_providers no config.yaml — failover por turno em caso de erro (o principal é restaurado a cada turno)	fallback_providers: (lista de nível superior)
Tarefas auxiliares (todas) — usuários em auto	Cadeia completa de detecção automática (modelo do agente principal primeiro, depois a cadeia de provedores) em erros de capacidade	auxiliary.<task>.provider: auto
Tarefas auxiliares (todas) — provedor explícito	fallback_chain (se definida) → modelo do agente principal → avisar e lançar, só em erros de capacidade	auxiliary.<task>.fallback_chain
Visão	Em camadas (veja acima) + repetição interna no OpenRouter	auxiliary.vision
Compressão de contexto	Em camadas (veja acima); degrada para "sem resumo" se todas as camadas estiverem indisponíveis	auxiliary.compression
Skills hub	Em camadas (veja acima)	auxiliary.skills_hub
Auxiliares de MCP	Em camadas (veja acima)	auxiliary.mcp
Classificação de aprovação	Em camadas (veja acima)	auxiliary.approval
Geração de título	Em camadas (veja acima)	auxiliary.title_generation
Especificador de triagem	Em camadas (veja acima)	auxiliary.triage_specifier
Delegação	Herda a cadeia fallback_providers do pai; sobrescrita opcional de provedor/modelo	delegation.provider / delegation.model
Tarefas de cron	Herdam a cadeia fallback_providers configurada; sobrescrita opcional de provedor por tarefa	provider / model por tarefa

---