learn ← Hermes: modelos por ação, OpenAI API e x_search
Hermes Agent · Modelos · Providers

Hermes: modelos por ação, OpenAI API e x_search

Uma leitura operacional da configuração real desta instância: o que está claro, o que está ambíguo e o que vale separar melhor.

O ponto mais importante aqui é simples: no Hermes, nome de modelo, provider, rota auxiliar e toolset são coisas diferentes. Quando aparecem rótulos parecidos — openai-codex, openai-api, auto, gpt-5.4, gpt-5.4-mini, openai/gpt-5-mini — a sensação é de redundância. Mas não é redundância; é roteamento. E, se esse roteamento não ficar explícito, ele vira confusão operacional.

TL;DR Hoje o seu Hermes está bem funcional: chat principal em openai-codex com gpt-5.4, auxiliares misturados entre openai-api e auto, e x_search configurado no YAML, mas desligado no runtime e sem credencial xAI ativa. O ponto mais incisivo é este: a sua OPENAI_API_KEY não é só “backup passivo”; com a configuração atual, ela já é a rota natural de várias ações auxiliares via openai-api.

De onde esta análise saiu

Esta página foi escrita a partir da inspeção da instalação real. Os fatos principais vieram de:

  • ~/.hermes/config.yaml;
  • hermes config, hermes status e hermes tools list;
  • código do Hermes em agent/auxiliary_client.py, hermes_cli/providers.py e tools/x_search_tool.py;
  • docs locais do projeto em website/docs/.

Trecho real do modelo principal

model:
  default: gpt-5.4
  provider: openai-codex
  base_url: https://chatgpt.com/backend-api/codex

Trecho real dos auxiliares mais relevantes

auxiliary:
  vision:
    provider: auto
    model: openai/gpt-5-mini
  web_extract:
    provider: auto
    model: openai/gpt-5-mini
  compression:
    provider: openai-api
    model: gpt-5.4-mini
  approval:
    provider: openai-api
    model: gpt-5.4-mini
  title_generation:
    provider: openai-api
    model: gpt-5.4-mini

Estado real do x_search nesta instância

$ hermes tools list
✗ disabled  x_search  🐦 X (Twitter) Search

$ hermes status
xAI OAuth     ✗ not logged in
x_search.model: grok-4.20-reasoning

Mapa atual: quem faz o quê

Bloco Configuração atual Leitura operacional
Chat principal openai-codex + gpt-5.4 é a rota cognitiva principal do agente
Compressão openai-api + gpt-5.4-mini usa a API direta da OpenAI para resumir contexto
Approval openai-api + gpt-5.4-mini rota auxiliar de decisão/avaliação
Títulos openai-api + gpt-5.4-mini nomeação automática de sessão
Vision provider: auto + openai/gpt-5-mini não é uma rota fixa; depende do resolvedor auxiliar
Web extract provider: auto + openai/gpt-5-mini também depende do resolvedor auxiliar
Delegation sem override herda o principal por padrão
x_search grok-4.20-reasoning é uma ferramenta separada, não o modelo principal
Principal openai-codex gpt-5.4 Auxiliares fixos openai-api gpt-5.4-mini Auxiliares auto provider: auto openai/gpt-5-mini X Search xAI tool grok-4.20-reasoning Chat conversa principal Side tasks compressão · approval · título Rota incerta vision · web extract
Hoje o seu Hermes já opera com quatro camadas mentais diferentes: principal, auxiliares fixos, auxiliares em auto-routing e uma ferramenta externa especializada para X.

O ponto mais traiçoeiro: nomes parecidos que não significam a mesma coisa

Aqui está a confusão central.

  • openai-codex é um provider do Hermes. Na sua instância, ele aponta para https://chatgpt.com/backend-api/codex e usa o login Codex/OAuth.
  • openai-api é outro provider. Ele aponta para https://api.openai.com/v1 e usa API key.
  • auto não é um provider real. É um resolvedor que tenta encontrar a melhor rota auxiliar disponível.
  • gpt-5.4 e gpt-5.4-mini são nomes de modelo.
  • openai/gpt-5-mini é um identificador de modelo escrito num formato que parece provider/model, mas ele está guardado sob um bloco com provider: auto. Portanto, a rota efetiva depende do resolvedor, não só do texto do nome.
Leitura incisiva O maior risco operacional aqui não é “config errada”. É config que funciona, mas não comunica bem a própria intenção. Quando o nome parece dizer OpenAI em três lugares diferentes, você perde clareza sobre qual OpenAI está sendo usada em cada passo.

A sua OPENAI_API_KEY é backup ou uso real?

A resposta curta é: hoje ela já participa do desenho operacional. Não faz sentido tratá-la apenas como um backup morto.

O motivo é direto. Você configurou estes auxiliares com provider: openai-api:

  • auxiliary.compression;
  • auxiliary.approval;
  • auxiliary.title_generation.

O provider openai-api no código do Hermes é a rota para https://api.openai.com/v1. E a documentação local deixa claro que, para endpoints diretos por tarefa, o Hermes usa a chave configurada na tarefa ou a OPENAI_API_KEY.

Leitura técnica importante

"openai-api": HermesOverlay(
    transport="codex_responses",
    base_url_override="https://api.openai.com/v1",
    base_url_env_var="OPENAI_BASE_URL",
)

Em outras palavras: mesmo que o seu modelo principal esteja em openai-codex, a sua API key da OpenAI já é a rota natural dos auxiliares fixos configurados como openai-api.

Conclusão prática Se você quer pensar nessa chave como backup, o desenho atual não comunica isso. O desenho atual comunica outra coisa: “o principal está no Codex; várias side tasks estão na API direta”.

O que significa provider: auto de verdade

No Hermes, auto não quer dizer “qualquer coisa da OpenAI”. Quer dizer “siga a cadeia de resolução auxiliar”. O próprio código local documenta a ordem.

Trecho do resolvedor auxiliar

Resolution order for text tasks (auto mode):
  1. User's main provider + main model
  2. OpenRouter
  3. Nous Portal
  4. Custom endpoint
  5. Native Anthropic
  6. Direct API-key providers
  7. None

Para tarefas multimodais/vision, a cadeia também tenta o provider principal primeiro, depois outras rotas compatíveis.

Portanto, quando você vê isto: 

auxiliary:
  vision:
    provider: auto
    model: openai/gpt-5-mini

não dá para ler como “vision está cravado na OpenAI API”. A leitura correta é: “vision quer esse modelo nominal, mas a rota exata depende do roteador auxiliar e do backend disponível”.

Como eu avaliaria o desenho atual

O estado atual não está ruim. Pelo contrário: ele faz sentido e já separa trabalho principal de side tasks. O problema não é qualidade; é legibilidade arquitetural.

Aspecto Como está Minha leitura
Principal claro openai-codex + gpt-5.4 está inequívoco
Auxiliares fixos claros há intenção nítida de usar uma rota menor para compressão/título/approval
Auxiliares em auto ambíguos o nome do modelo é explícito, mas a rota final não é
Delegation implícita sem override, fica fácil gastar “modelo principal” em subtarefa que poderia ser menor
OPENAI_API_KEY subestimada na prática ela já é rota auxiliar, não mero cofre de backup
x_search desconectado do uso atual está configurado no YAML, mas desligado e sem auth válida

Um probe útil: o que o Codex da sua conta aceita de fato

Como o provider openai-codex com conta ChatGPT tem allow-list variável, eu fiz uma checagem barata antes de recomendar rotas. O resultado mais importante foi este: 

$ hermes chat -q 'Respond only OK.' --provider openai-codex -m gpt-5.4-mini -Q
OK

$ hermes chat -q 'Respond only OK.' --provider openai-codex -m gpt-5.4-nano -Q
400 - model not supported when using Codex with a ChatGPT account

$ hermes chat -q 'Respond only OK.' --provider openai-codex -m gpt-5-mini -Q
400 - model not supported when using Codex with a ChatGPT account

Isso importa bastante. Significa que, nesta conta e neste momento, gpt-5.4-mini está funcional em openai-codex, enquanto gpt-5.4-nano e gpt-5-mini não estão.

Minhas recomendações

Vou separar em três estratégias. A terceira é a que eu mais recomendaria para você hoje.

Estratégia 1 — manter quase como está, mas com leitura correta

É a opção de menor mudança. Você mantém:

  • principal em openai-codex + gpt-5.4;
  • compressão, approval e title em openai-api + gpt-5.4-mini;
  • vision/web extract em auto.

Funciona. Só exige aceitar uma verdade arquitetural: o seu Hermes já opera em duas superfícies OpenAI diferentes — Codex OAuth e API key direta.

Estratégia 2 — clareza máxima: consolidar os auxiliares menores no Codex

Como gpt-5.4-mini respondeu com sucesso em openai-codex, você já tem base para uma consolidação mais elegante. A ideia seria usar:

  • principal: openai-codex + gpt-5.4;
  • compressão: openai-codex + gpt-5.4-mini;
  • approval: openai-codex + gpt-5.4-mini;
  • title_generation: openai-codex + gpt-5.4-mini.

Vantagem: você reduz a sensação de “OpenAI em duplicidade”.

Risco: o allow-list do Codex pode mudar com o tempo, então esse arranjo precisa ser tratado como compatível hoje, não eternamente garantido.

Comandos para essa consolidação

hermes config set auxiliary.compression.provider openai-codex
hermes config set auxiliary.compression.model gpt-5.4-mini

hermes config set auxiliary.approval.provider openai-codex
hermes config set auxiliary.approval.model gpt-5.4-mini

hermes config set auxiliary.title_generation.provider openai-codex
hermes config set auxiliary.title_generation.model gpt-5.4-mini

Estratégia 3 — a que eu recomendo: separar intenção por função

Esta é a arquitetura que me parece mais madura para o seu caso.

  • principal: manter openai-codex + gpt-5.4;
  • delegation: definir explicitamente openai-codex + gpt-5.4-mini;
  • compression / approval / title: escolher conscientemente entre
    a) consolidar tudo em openai-codex + gpt-5.4-mini, se você quiser clareza de superfície;
    b) manter openai-api + gpt-5.4-mini, se você quiser isolar side tasks numa API direta.
  • vision / web_extract: sair do ambíguo e tornar explícito o que você quer.
Minha recomendação objetiva O primeiro ajuste que eu faria não é em vision nem em x_search. É em delegation. Hoje os subagentes herdam o principal. Isso é elegante por simplicidade, mas ruim por controle. Eu deixaria delegation explicitamente em gpt-5.4-mini.

Comandos sugeridos para o primeiro ajuste

hermes config set delegation.provider openai-codex
hermes config set delegation.model gpt-5.4-mini
hermes config set delegation.reasoning_effort medium

Se você quiser máxima previsibilidade também em vision e web extract, eu prefiro duas opções mais limpas do que o meio-termo atual:

  1. ou deixar auto de propósito e aceitar a flexibilidade como feature;
  2. ou explicitar provider e modelo de forma inequívoca, para saber exatamente que backend está fazendo o trabalho.

O que eu não acho tão bom é um estado híbrido em que o nome do modelo parece específico, mas o provider continua auto. Funciona, porém comunica pouco.

O x_search não é “trocar o modelo principal do Hermes para Grok”. Também não é “usar X como provider do chat”. Ele é uma ferramenta especializada de pesquisa no X/Twitter.

No código local, o tool é descrito assim: ele usa o tool built-in x_search da Responses API da xAI. Ou seja, é uma integração de pesquisa, não a sua rota principal de conversa.

Partes centrais do x_search

DEFAULT_X_SEARCH_MODEL = "grok-4.20-reasoning"

tool_def = {"type": "x_search"}
payload = {
  "model": _get_x_search_model(),
  "input": [{"role": "user", "content": query.strip()}],
  "tools": [tool_def],
  "store": False,
}

A rota de credencial aceita duas formas:

  • xAI OAuth via SuperGrok/Premium+;
  • XAI_API_KEY direta.

Hoje, na sua instância, ele está em três estados ao mesmo tempo:

  • configurado no YAML com grok-4.20-reasoning;
  • desabilitado como toolset no runtime;
  • sem auth xAI ativa, segundo hermes status.
Leitura correta Hoje o seu x_search é mais uma intenção de capacidade do que uma capacidade operacional ativa.

Quando o x_search faz sentido

  • acompanhar reação pública a um produto ou anúncio;
  • achar posts, perfis e threads sobre um tema muito recente;
  • ver alegações circulando no X antes de abrir a web geral;
  • filtrar por handles específicos ou intervalos de data.

O que ele não é

  • não é substituto do web_search;
  • não é o modelo principal do Hermes;
  • não é uma melhoria geral de qualidade do chat;
  • não “entra em ação sozinho” só porque existe um bloco x_search: no YAML.

Um detalhe bom do x_search no Hermes

O código local marca respostas degradadas quando filtros estão ativos e a xAI responde sem citações. Isso é excelente, porque evita confundir resposta “plausível” com resposta realmente apoiada pelo índice do X.

Sinal de resposta degradada

degraded = bool(active_filters) and not citations and not inline_citations

degraded_reason = (
  "no citations returned despite filters ..."
)

Em português claro: se você filtra por datas ou handles e a resposta vem sem citação, o Hermes consegue te avisar que aquilo pode ter vindo mais da memória do modelo do que da busca no X em si.

O que eu faria no seu lugar

  1. Explicitaria delegation com gpt-5.4-mini.
  2. Escolheria uma filosofia para os auxiliares fixos: ou Codex consolidado, ou OpenAI API direta claramente assumida.
  3. Decidiria se vision/web_extract devem ser previsíveis ou flexíveis. Se previsíveis, sairia do auto. Se flexíveis, manteria auto mas aceitando a ambiguidade como escolha consciente.
  4. Não mexeria em x_search ainda, a menos que você queira realmente usar X como fonte recorrente.

Se a sua pergunta for “qual é a melhor arquitetura para mim hoje?”, minha resposta é esta:

Arquitetura recomendada Principal em openai-codex + gpt-5.4, delegation em openai-codex + gpt-5.4-mini, e decisão consciente entre consolidar auxiliares menores no Codex ou assumir a OpenAI API direta como camada auxiliar oficial. O que eu evitaria é deixar a API key tratada mentalmente como “backup” se, arquiteturalmente, ela já está servindo side tasks reais.

Próximos passos práticos

Se eu fosse evoluir a instância em etapas curtas, faria assim:

  1. ajustar delegation.*;
  2. escolher se auxiliary.compression, approval e title_generation ficam em Codex ou OpenAI API;
  3. deixar documentado para você mesmo: “esta chave OpenAI é backup puro” ou “esta chave OpenAI é a camada oficial dos auxiliares”;
  4. só depois decidir se vale habilitar x_search e autenticar xAI.

A ordem importa. Primeiro vem clareza da arquitetura principal. Depois vêm as integrações especializadas.