Configurar modelos

O Hermes usa dois tipos de vaga de modelo:

• Modelo principal — aquele com que o agente pensa. Toda mensagem de usuário, todo laço de chamada de ferramenta, toda resposta em streaming passa por este modelo.
• Modelos auxiliares — trabalhinhos menores que o agente descarrega. Compressão de contexto, visão (análise de imagem), sumarização de página web, pontuação de aprovação, roteamento de ferramentas MCP, geração de título de sessão e busca de skills. Cada um tem a sua própria vaga e pode ser sobrescrito de forma independente.

Esta página cobre como configurar os dois pelo painel. Se você prefere arquivos de configuração ou a CLI, pule para Métodos alternativos lá embaixo.

Caminho mais rápido: Nous Portal

O Nous Portal oferece mais de 300 modelos em uma assinatura só. Numa instalação nova, rode hermes setup --portal para entrar e definir a Nous como seu provedor em um comando só. Veja o que ficou configurado com hermes portal info.

• Assinantes do Portal também ganham 10% de desconto em provedores cobrados por token.

Esquema de model: — string vazia vs. mapeamento

Numa instalação novinha, a configuração padrão que vem junto tem model: "" (uma string vazia sentinela, que significa "ainda não configurado"). Na primeira vez que você roda hermes setup ou hermes model, essa chave é promovida no lugar para um mapeamento com as subchaves provider, default, base_url e api_mode — o formato mostrado ao longo desta página e em profiles.md / configuration.md. Se algum dia você vir uma string vazia no config.yaml, rode hermes model (ou clique em Change no painel) e o Hermes escreve a forma de dicionário para você.

A página Models

Abra o painel e clique em Models na barra lateral. Você tem duas seções:

1. Model Settings — o painel de cima, onde você atribui modelos às vagas.
2. Usage analytics — cartões ranqueados mostrando todo modelo que rodou uma sessão no período selecionado, com contagem de tokens, custo e selos de capacidade.

O cartão de cima é o painel Model Settings. A linha principal sempre mostra o que o agente vai subir para sessões novas. Clique em Change para abrir o seletor.

Definir o modelo principal

Clique em Change na linha Main model:

O seletor tem duas colunas:

• À esquerda — provedores autenticados. Só aparecem aqui os provedores que você configurou (chave de API definida, OAuth feito ou endpoint personalizado declarado). Se faltar um provedor, vá em Keys e adicione a credencial dele.
• À direita — a lista curada de modelos do provedor selecionado. São os modelos agênticos que o Hermes recomenda para aquele provedor, não o despejo bruto de /models (que no OpenRouter inclui mais de 400 modelos, entre eles TTS, geradores de imagem e rerankers).

Digite na caixa de filtro para restringir por nome de provedor, slug ou ID de modelo.

Escolha um modelo, aperte Switch, e o Hermes o grava em ~/.hermes/config.yaml, na seção model. Isso vale só para sessões novas — qualquer aba de conversa já aberta continua rodando o modelo com que começou. Para trocar a conversa atual a quente, use o comando de barra /model dentro dela.

Trocas no meio da sessão e avisos de contexto

Quando você troca de modelo dentro de uma sessão ativa (seletor de modelo da Herm TUI, CLI hermes ou /model no Telegram/Discord), o Hermes estima se a sua próxima mensagem vai disparar compressão de contexto de pré-voo contra a janela do novo modelo. Se a sessão já está perto ou acima do limiar de compressão daquele modelo (veja Compressão de contexto), a resposta da troca inclui um aviso — o mesmo caminho de warning_message usado nos avisos de modelo caro. A troca ainda se aplica na hora; a compressão roda na primeira mensagem de usuário depois da troca, antes de o modelo responder.

Trocas no meio da sessão zeram o cache de prompt

Caches de prompt são indexados pelo modelo que atende a requisição, então qualquer mudança de modelo no meio da conversa — uma troca explícita por /model, um fallback automático ou uma rotação de pool de credenciais para outra conta — significa que a próxima mensagem relê a conversa inteira pelo preço cheio de token de entrada, em vez da tarifa em cache (com ~75–90% de desconto). Numa sessão longa, essa releitura única pode ser muito maior que a diferença por token entre os dois modelos. Troque quando precisar, mas prefira fazer isso cedo na conversa ou logo depois de começar uma sessão nova.

Faixas de dados usados para treino sem supervisão

Modelos como o muse-spark-1.2-contributor são mais baratos porque o fornecedor pode treinar com seus prompts e suas respostas. A seleção interativa de modelo sempre mostra uma confirmação. Caminhos de inicialização não interativos, como trabalhadores do Kanban e agentes de cron, falham fechado porque não têm como fazer essa pergunta.

Se treinar com os dados da carga sem supervisão for aceitável, registre um reconhecimento persistente:

hermes config set security.allow_data_training_tiers_noninteractive true

O Hermes ainda imprime o aviso completo de política de dados e a chave de reconhecimento em toda inicialização sem supervisão, então os logs dos trabalhadores mantêm a trilha de auditoria. Essa configuração não aprova avisos de modelo caro nem de roteamento de provedor, e não substitui a confirmação interativa. Revogue com hermes config unset security.allow_data_training_tiers_noninteractive.

Definir os modelos auxiliares

Clique em Show auxiliary para revelar as 11 vagas de tarefa:

Toda tarefa auxiliar começa em auto — ou seja, o Hermes tenta usar o seu modelo principal também nesse trabalho. Se essa rota estiver indisponível ou bater numa falha do tipo capacidade, o auto segue qualquer auxiliary.<task>.fallback_chain específica da tarefa, depois a cadeia principal de fallback_providers / fallback_model e, então, a cadeia de descoberta auxiliar embutida do Hermes. Sobrescreva uma tarefa específica quando quiser um modelo mais barato ou mais rápido para um trabalho paralelo.

Padrões comuns de sobrescrita

Tarefa	Quando sobrescrever
Title Gen	Quando latência ou custo do título importam mais do que combinar com o modelo principal. Fixe um modelo flash conhecido, ou defina auxiliary.title_generation.prefer_fast_model: true para deixar o Hermes escolher a faixa rápida do provedor.
Vision	Quando o seu modelo principal não tem suporte a visão. Aponte para google/gemini-2.5-flash ou gpt-4o-mini.
Compression	Quando você está queimando tokens de raciocínio no Opus/M2.7 só para resumir contexto. Um modelo de chat rápido faz o serviço por 1/50 do custo.
Approval	Para approval_mode: smart — um modelo rápido/barato (haiku, flash, gpt-5-mini) decide se aprova automaticamente comandos de baixo risco. Modelos caros aqui são desperdício.
Web Extract	Quando você usa muito o web_extract. Mesma lógica da compressão — sumarizar não precisa de raciocínio.
Skills Hub	O hermes skills search usa isto. Normalmente vai bem em auto.
MCP	Roteamento de ferramentas MCP. Normalmente vai bem em auto.
Triage Specifier	Roteia o especificador de triagem do Kanban (hermes kanban specify), que expande uma frase solta em uma especificação concreta. Um modelo barato e competente funciona bem.
Kanban Decomposer	Roteia a decomposição de tarefas do Kanban — divide uma tarefa de triagem em um grafo de tarefas filhas para perfis especialistas.
Profile Describer	Roteia a geração de descrição de perfil (hermes profile describe --auto / o botão de gerar automaticamente no painel). Chamada curta e barata.
Curator	Roteia a passagem de revisão de uso de skills do curador. Pode rodar por minutos em modelos de raciocínio, então um modelo auxiliar mais barato costuma valer a pena.

Sobrescrita por tarefa

Clique em Change em qualquer linha auxiliar. Abre o mesmo seletor, com o mesmo comportamento — escolha provedor + modelo e aperte Switch. A linha passa a mostrar provedor · modelo em vez de auto (use main model).

Resetar tudo para auto

Se você ajustou demais e quer recomeçar, clique em Reset all to auto no topo da seção auxiliar. Toda vaga volta a usar o seu modelo principal.

O atalho "Use as"

Todo cartão de modelo da página tem um menu Use as. Este é o caminho rápido — escolha um modelo que você vê na sua análise de uso, clique em Use as e atribua-o à vaga principal ou a qualquer tarefa auxiliar específica em um clique:

O menu tem:

• Main model — igual a clicar em Change na linha principal.
• All auxiliary tasks — atribui este modelo às 11 vagas auxiliares de uma vez. Útil quando você só quer todo trabalho paralelo em um modelo flash barato.
• Opções de tarefa individual — Vision, Web Extract, Compression etc. O modelo atualmente atribuído a cada tarefa é marcado como current.

Os cartões recebem o selo main ou aux · <task> quando estão atribuídos a alguma coisa — assim você vê num relance quais dos seus modelos históricos estão ligados onde.

O que é gravado no config.yaml

Quando você salva pelo painel, o Hermes escreve em ~/.hermes/config.yaml:

Modelo principal:

model:
  provider: openrouter
  default: anthropic/claude-opus-4.7
  base_url: ''        # limpo na troca de provedor
  api_mode: chat_completions

Sobrescrita auxiliar (exemplo — visão no gemini-flash):

auxiliary:
  vision:
    provider: openrouter
    model: google/gemini-2.5-flash
    base_url: ''
    api_key: ''
    timeout: 120
    extra_body: {}
    download_timeout: 30

Auxiliar em auto (padrão):

auxiliary:
  compression:
    provider: auto
    model: ''
    base_url: ''
    # ... outros campos sem mudança

provider: auto com model: '' diz ao Hermes para usar o modelo principal naquela tarefa, ainda respeitando a política de fallback se a rota principal não puder atender a chamada auxiliar.

Cadeias de fallback opcionais específicas da tarefa ficam sob a mesma tarefa auxiliar:

auxiliary:
  title_generation:
    provider: auto
    model: ''
    fallback_chain:
      - provider: openrouter
        model: inclusionai/ring-2.6-1t:free

Quando não há fallback_chain, o auto usa a cadeia fallback_providers de nível superior antes da cadeia de descoberta auxiliar embutida.

Opções de requisição por provedor

Entradas de provedor (providers.<name> no dicionário providers:, ou itens na lista legada custom_providers) aceitam dois botões que moldam como o Hermes conversa com o endpoint:

extra_headers — um mapeamento de cabeçalhos HTTP extras anexados a toda requisição de LLM roteada para a URL base daquele provedor. Eles são aplicados por último, depois dos padrões de URL/perfil e das sobrescritas de cabeçalho do usuário, então sobrevivem a trocas de credencial e reconstruções de cliente. Útil para tokens de serviço do Cloudflare Access, autenticação de proxy ou esquemas de bearer personalizados:

providers:
  my-gateway:
    api: https://llm.internal.example.com/v1
    api_key: sk-...
    extra_headers:
      CF-Access-Client-Id: "xxxx.access"
      CF-Access-Client-Secret: "yyyy"

Valores de cabeçalho costumam carregar credenciais — o Hermes nunca os registra em log. extra_headers vale para rotas compatíveis com a OpenAI; os modos de API anthropic_messages e bedrock_converse não o usam.

discover_models — defina como false (padrão true) para pular a consulta à listagem /models do endpoint e usar apenas os models que você configurou na entrada. Prático para gateways cuja listagem de modelos é lenta, instável ou barulhenta:

providers:
  my-gateway:
    api: https://llm.internal.example.com/v1
    discover_models: false
    models:
      - my-finetune-v2
      - my-finetune-v1

Com a descoberta desligada, o seletor de modelo (hermes model, /model) mostra a lista configurada em vez de uma sondagem ao vivo.

Para um gateway que só resolve um alias simples de modelo depois de receber a requisição, habilite o alias para marcadores de cache de prompt com a capacidade prompt_caching por modelo:

providers:
  model-proxy:
    api: https://gateway.example.com/v1
    transport: openai_chat  # ou anthropic_messages
    models:
      fable:
        context_length: 1000000
        prompt_caching: true

O Hermes casa essa declaração com a rota exata do provedor e o id de modelo em runtime, sem reescrever o alias nem inferir suporte a partir do nome do provedor, do host ou da família do modelo. O layout dos marcadores segue o transporte configurado: openai_chat usa o layout de envelope compatível com a OpenAI e anthropic_messages usa o layout nativo de bloco interno. Defina prompt_caching: false para desligar explicitamente os marcadores de cache de um modelo; quando omitido, o Hermes mantém a detecção normal de capacidade de provedor e de modelo.

Formato legado

Configurações mais antigas usavam uma lista custom_providers: de nível superior (com base_url em vez de api). Ela ainda funciona e é migrada automaticamente para o dicionário providers: no hermes update (config v12).

Quando isso passa a valer?

• CLI (hermes chat): na próxima invocação de hermes chat.
• Gateway (Telegram, Discord, Slack etc.): na próxima sessão nova. Sessões existentes mantêm o modelo delas. Reinicie o gateway (hermes gateway restart) se quiser forçar todas as sessões a pegar a mudança.
• Aba de conversa do painel (/chat): no próximo PTY novo. A conversa aberta agora mantém o modelo dela — use /model dentro dela para trocar a quente.

As mudanças nunca invalidam caches de prompt de sessões em execução. Isso é de propósito: trocar o modelo principal dentro de uma sessão exige zerar o cache (o prompt de sistema tem conteúdo específico do modelo), e reservamos isso para o comando de barra /model explícito dentro da conversa.

Resolução de problemas

"No authenticated providers" no seletor

O Hermes lista um provedor só se ele tiver uma credencial funcionando. Confira Keys na barra lateral — você deve ver uma destas coisas: uma chave de API, um OAuth bem-sucedido ou uma URL de endpoint personalizado. Se o provedor que você quer não está lá, rode hermes setup para configurá-lo, ou vá em Keys e adicione a variável de ambiente.

O modelo principal não mudou na minha conversa em andamento

É o esperado. O painel escreve o config.yaml, que as sessões novas leem. A conversa aberta agora é um processo de agente vivo — ela mantém o modelo com que foi criada. Use /model <nome> dentro da conversa para trocar a quente naquela sessão específica.

A sobrescrita auxiliar "não pegou"

Três coisas para conferir:

1. Você começou uma sessão nova? Conversas existentes não releem a configuração.
2. O provider está com algo diferente de auto? Se o campo mostra auto, a tarefa ainda está usando o seu modelo principal. Clique em Change e escolha um provedor de verdade.
3. O provedor está autenticado? Se você atribuiu minimax a uma tarefa mas não tem chave de API da MiniMax, aquela tarefa cai para o padrão do openrouter e registra um aviso no agent.log.

Escolhi um modelo mas o Hermes trocou o provedor por mim

No OpenRouter (ou em qualquer agregador), nomes simples de modelo resolvem dentro do agregador primeiro. Então claude-sonnet-4 no OpenRouter vira anthropic/claude-sonnet-4.6, ficando na sua autenticação do OpenRouter. Mas se você digitasse claude-sonnet-4 numa autenticação nativa da Anthropic, ele continuaria claude-sonnet-4-6. Se você vir uma troca inesperada de provedor, confira se o seu provedor atual é o que você espera — o seletor sempre mostra o principal atual no topo do diálogo.

Métodos alternativos

Comando de barra na CLI

Dentro de qualquer sessão de hermes chat:

/model gpt-5.4 --provider openrouter             # só nesta sessão
/model gpt-5.4 --provider openrouter --global    # também persiste no config.yaml
/model claude-opus-4.6 --once                    # só no próximo turno, depois restaura sozinho

O --global faz a mesma coisa que o botão Change do painel, e ainda troca a sessão em execução no lugar.

O --once troca por um único turno e restaura o modelo anterior depois — no sucesso, no erro ou na interrupção. Nada é persistido: um reinício de gateway no meio do turno volta no modelo original. Útil para escalar uma pergunta difícil a um modelo caro ("pergunte ao Opus só desta vez") ou cair para um modelo barato numa consulta descartável.

Custo do cache de prompt

Uma troca de um turno quebra o prefixo do cache de prompt do provedor duas vezes (ao sair e ao voltar). Numa sessão longa em um provedor com prefixo em cache (Anthropic, OpenAI), o turno seguinte repaga o custo cheio de entrada — o --once ganha em sessões curtas ou em escalada de barato→caro, mas uma perguntinha lateral dentro de uma sessão longa e cara pode custar mais do que economiza.

Aliases personalizados

Defina os seus próprios nomes curtos para os modelos que você mais usa e então use /model <alias> na CLI ou em qualquer plataforma de mensagens. Existem dois formatos equivalentes — escolha o que combina com o seu fluxo.

Canônico (model_aliases: de nível superior) — controle completo de provedor + base_url:

# ~/.hermes/config.yaml
model_aliases:
  fav:
    model: claude-sonnet-4.6
    provider: anthropic
  grok:
    model: grok-4
    provider: x-ai

Forma curta em string (model.aliases.<name>: provider/model) — conveniente pelo shell, porque o hermes config set escreve escalares e agora também interpreta literais inline de lista/mapeamento, ainda que essa forma curta de alias continue sem poder carregar um base_url personalizado:

hermes config set model.aliases.fav anthropic/claude-opus-4.6
hermes config set model.aliases.grok x-ai/grok-4

O hermes config set também aceita literais de lista/mapeamento inline (estilo de fluxo JSON/YAML). Coloque entre aspas para o seu shell repassá-los intactos:

hermes config set platform_toolsets.line '["clarify", "file", "web"]'
hermes config set display.tool_progress_overrides '{"terminal": "off"}'

Os dois caminhos alimentam o mesmo carregador (hermes_cli/model_switch.py). Entradas declaradas em model_aliases: têm precedência sobre entradas de model.aliases: com o mesmo nome.

Depois é só /model fav ou /model grok na conversa. Aliases de usuário sombreiam os nomes curtos embutidos (sonnet, kimi, opus etc.). Veja Aliases personalizados de modelo para a referência completa.

Subcomando hermes model

hermes model            # Seletor interativo de provedor + modelo (a forma canônica de trocar os padrões)

O hermes model conduz você pela escolha de um provedor, pela autenticação (fluxos OAuth abrem o navegador; provedores por chave de API pedem a chave) e então pela escolha de um modelo específico no catálogo curado daquele provedor. A escolha é gravada em model.provider e model.default no ~/.hermes/config.yaml.

Para listar provedores/modelos sem abrir o seletor, use o painel ou os endpoints REST abaixo. Para inspecionar o que a CLI vai de fato usar agora: hermes config get model --json e hermes status.

Edição direta da configuração

Edite o ~/.hermes/config.yaml e reinicie o que quer que o leia. Veja a referência de Configuração para o esquema completo.

API REST

O painel usa três endpoints. Útil para automação:

# Lista provedores autenticados + listas curadas de modelos
curl -H "X-Hermes-Session-Token: $TOKEN" http://localhost:PORT/api/model/options

# Lê as atribuições atuais de principal + auxiliares
curl -H "X-Hermes-Session-Token: $TOKEN" http://localhost:PORT/api/model/auxiliary

# Define o modelo principal
curl -X POST -H "Content-Type: application/json" -H "X-Hermes-Session-Token: $TOKEN" \
  -d '{"scope":"main","provider":"openrouter","model":"anthropic/claude-opus-4.7"}' \
  http://localhost:PORT/api/model/set

# Sobrescreve uma única tarefa auxiliar
curl -X POST -H "Content-Type: application/json" -H "X-Hermes-Session-Token: $TOKEN" \
  -d '{"scope":"auxiliary","task":"vision","provider":"openrouter","model":"google/gemini-2.5-flash"}' \
  http://localhost:PORT/api/model/set

# Atribui um modelo a toda tarefa auxiliar
curl -X POST -H "Content-Type: application/json" -H "X-Hermes-Session-Token: $TOKEN" \
  -d '{"scope":"auxiliary","task":"","provider":"openrouter","model":"google/gemini-2.5-flash"}' \
  http://localhost:PORT/api/model/set

# Reseta todas as tarefas auxiliares para auto
curl -X POST -H "Content-Type: application/json" -H "X-Hermes-Session-Token: $TOKEN" \
  -d '{"scope":"auxiliary","task":"__reset__","provider":"","model":""}' \
  http://localhost:PORT/api/model/set

O token de sessão é injetado no HTML do painel na inicialização e rotaciona a cada reinício do servidor. Pegue-o pelas ferramentas de desenvolvedor do navegador (window.__HERMES_SESSION_TOKEN__) se você estiver automatizando contra um painel em execução.

---