Como configurar o Hermes Agent com a OmniaKey: endpoint OpenAI-compatible

Atualizado em 30 de outubro de 2026: quatro erros de configuração comuns do Hermes agora trazem o sintoma, a causa e a solução, com base na documentação oficial do Hermes Agent.

Para configurar Hermes Agent API, basta adicionar um endpoint personalizado compatível com OpenAI. O Hermes Agent, da Nous Research, pode alternar entre Claude, GPT, Gemini e Grok pelo model ID.

Caminho rápido: hermes model

hermes model

Escolha Custom endpoint (self-hosted / VLLM / etc.) e informe:

• Base URL: https://api.omniakey.com/v1
• API key: sua chave OmniaKey
• Model: por exemplo claude-opus-4-8

Configuração em config.yaml

Para uma configuração persistente com vários modelos, use ~/.hermes/config.yaml:

model:
  provider: custom
  base_url: https://api.omniakey.com/v1
  api_key: your-omniakey-api-key
  default: claude-opus-4-8
models:
  - claude-opus-4-8
  - gpt-5.5
  - gemini-3.1-pro-preview
  - grok-4.5

provider: custom faz o Hermes chamar diretamente seu endpoint. A lista models: preenche o seletor /model; reinicie o Hermes depois de editar e troque entre claude-opus-4-8, gpt-5.5, gemini-3.1-pro-preview e grok-4.5 sem sair da sessão.

Uma chave, quatro famílias

A OmniaKey escolhe o modelo pelo model ID no endpoint compatível com OpenAI. Um endpoint cobre as quatro famílias, com cobrança por token a partir de um saldo pré-pago. O ID configurado é o que roda, sem fallback silencioso para um modelo “equivalente”. O catálogo de modelos lista todos os ids que você pode definir, e preços mostra a tarifa por token de cada um. A mesma chave funciona em outros agentes; veja os guias de configuração do OpenClaw, chave API personalizada no Cline e configuração do Claude Code.

Erros de configuração comuns

Estes quatro aparecem com frequência quando o Hermes aponta para um endpoint personalizado. A causa e a solução vêm da documentação de provedores do Hermes e da referência de configuração.

/model não oferece o endpoint personalizado

Sintoma: você digita /model numa sessão aberta e a OmniaKey não aparece na lista.

Causa: /model dentro de uma sessão só alterna entre provedores que você já configurou. Ele não adiciona provedor, não roda OAuth e não pede chave de API.

Solução: saia da sessão, rode hermes model no terminal, configure o endpoint personalizado e comece uma sessão nova.

Uma chave no .env é ignorada e as requisições vão para outro provedor

Sintoma: você coloca a base URL ou a chave em ~/.hermes/.env e o Hermes continua chamando um provedor embutido.

Causa: o LLM_MODEL no .env foi removido, o config.yaml é a única fonte para o modelo e o endpoint, e o OPENAI_BASE_URL só vale para o provedor openai-api.

Solução: coloque base_url e api_key no bloco model: de ~/.hermes/config.yaml ou aponte key_env para a variável que guarda a chave. Com base_url definido, o Hermes chama esse endpoint direto e autentica com api_key ou OPENAI_API_KEY.

O Hermes não inicia com provider: main

Sintoma: a inicialização falha, ou o seletor de modelos fica vazio, depois de você colocar provider: main no bloco model: de topo.

Causa: main significa "use o provedor do meu agente principal" e só vale dentro de auxiliary:, compression: ou de uma entrada de fallback.

Solução: coloque provider: custom em model:, junto da base_url e da chave da OmniaKey.

/model custom escolhe outro modelo

Sintoma: /model custom pega um modelo que você não pediu ou dá erro.

Causa: /model custom sem nome consulta a API /models do endpoint e só escolhe sozinho quando há exatamente um modelo carregado; a OmniaKey serve vários.

Solução: informe o modelo, por exemplo /model custom:claude-opus-4-8.

Perguntas frequentes

Como conectar o Hermes Agent à OmniaKey?

Rode hermes model, escolha Custom endpoint (self-hosted / VLLM / etc.) e informe https://api.omniakey.com/v1 como base URL, sua chave OmniaKey e um model ID como claude-opus-4-8. Os mesmos três valores em ~/.hermes/config.yaml resolvem se você preferir editar o arquivo.

Por que o Hermes retorna 404 com minha base URL da OmniaKey?

A base URL precisa terminar em /v1. O Hermes adiciona /chat/completions sozinho, então uma URL que já traz esse caminho, ou com barra no fim, é a causa comum do 404.

Uma chave da OmniaKey cobre Claude, GPT, Gemini e Grok?

Sim. A OmniaKey escolhe o modelo pelo ID no endpoint compatível com OpenAI, então um endpoint cobre as quatro famílias: você troca o ID, não o bloco de provedor. Coloque os IDs que quiser na lista models: e eles aparecem no seletor /model.

Como trocar de modelo no meio da sessão?

Digite /model custom:<model ID>, por exemplo /model custom:gpt-5.5. Reinicie o Hermes uma vez depois de editar a lista models: e o seletor e o /model passam a ver os IDs novos.

Fontes verificadas

• Nous Research: provedores de LLM e modelos
• Nous Research: configuração do Hermes Agent

O guia de agentes de programação cobre as outras ferramentas.