# Como configurar o Hermes Agent com a OmniaKey: endpoint OpenAI-compatible > Conecte o Hermes Agent a um endpoint OmniaKey compatível com OpenAI. Use hermes model ou config.yaml, troque modelos e evite erros 404. - Canonical HTML: https://omniakey.com/pt-BR/blog/hermes-setup - Markdown: https://omniakey.com/pt-BR/blog/hermes-setup.md - Published: 2026-05-24 (updated 2026-10-30) - Author: Kiki, COO at OmniaKey - Language: pt-BR - Category: Guide - Reading time: 4 min - All posts: https://omniakey.com/blog/llms.txt --- 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` ```bash 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` > Termine a Base URL em `/v1`. O Hermes adiciona `/chat/completions`; um caminho completo ou uma barra final costuma causar 404. ## Configuração em `config.yaml` Para uma configuração persistente com vários modelos, use `~/.hermes/config.yaml`: ```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](https://omniakey.com/pt-BR/models) lista todos os ids que você pode definir, e [preços](https://omniakey.com/pt-BR/pricing) mostra a tarifa por token de cada um. A mesma chave funciona em outros agentes; veja os guias de [configuração do OpenClaw](https://omniakey.com/pt-BR/blog/openclaw-setup), [chave API personalizada no Cline](https://omniakey.com/pt-BR/blog/cline-custom-api-key) e [configuração do Claude Code](https://omniakey.com/pt-BR/blog/claude-code-setup). - **OpenAI-compatible**: - **Anthropic-native**: - **Gemini-native**: ## 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](https://hermes-agent.nousresearch.com/docs/integrations/providers) e da [referência de configuração](https://hermes-agent.nousresearch.com/docs/user-guide/configuration). ### `/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:`, 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](https://hermes-agent.nousresearch.com/docs/integrations/providers) - [Nous Research: configuração do Hermes Agent](https://hermes-agent.nousresearch.com/docs/user-guide/configuration) O [guia de agentes de programação](https://docs.omniakey.com/en/coding) cobre as outras ferramentas.