Documentação oficial desta página · v0.20.6
Provedores de LLM e de Modelo
Esta página trata da configuração dos provedores de inferência do Hermes Agent — de APIs na nuvem como OpenRouter e Anthropic, a endpoints auto-hospedados como Ollama e vLLM, até configurações avançadas de roteamento e de recuo. Você precisa de pelo menos um provedor configurado para usar o Hermes.
Provedores de inferência
Você precisa de pelo menos um jeito de se conectar a uma LLM. Use hermes model para trocar de provedor e de modelo de forma interativa, ou configure diretamente:
| Provedor | Configuração |
|---|---|
| Nous Portal | hermes model (OAuth, baseado em assinatura) |
| OpenAI Codex | hermes model → ChatGPT or Codex Subscription (OAuth do ChatGPT, usa modelos Codex) |
| GitHub Copilot | hermes model (fluxo OAuth de código de dispositivo, COPILOT_GITHUB_TOKEN, GH_TOKEN ou gh auth token) |
| GitHub Copilot ACP | hermes model (sobe um copilot --acp --stdio local) |
| Anthropic | hermes model (Claude Max + créditos de uso extra via OAuth; também suporta chave de API da Anthropic ou setup-token manual — veja a nota abaixo) |
| OpenRouter | OPENROUTER_API_KEY em ~/.hermes/.env |
| Fireworks AI | FIREWORKS_API_KEY em ~/.hermes/.env (provedor: fireworks; apelidos: fireworks-ai, fw) |
| NovitaAI | NOVITA_API_KEY em ~/.hermes/.env (provedor: novita, mais de 200 modelos, Model API, Agent Sandbox, GPU Cloud) |
| AI Gateway | AI_GATEWAY_API_KEY em ~/.hermes/.env (provedor: ai-gateway) |
| z.ai / GLM | GLM_API_KEY em ~/.hermes/.env (provedor: zai) |
| Kimi / Moonshot | KIMI_API_KEY em ~/.hermes/.env (provedor: kimi-coding) |
| Kimi / Moonshot (China) | KIMI_CN_API_KEY em ~/.hermes/.env (provedor: kimi-coding-cn; apelidos: kimi-cn, moonshot-cn) |
| Arcee AI | ARCEEAI_API_KEY em ~/.hermes/.env (provedor: arcee; apelidos: arcee-ai, arceeai) |
| GMI Cloud | GMI_API_KEY em ~/.hermes/.env (provedor: gmi; apelidos: gmi-cloud, gmicloud) |
| Actual Computer | ACTUAL_API_KEY em ~/.hermes/.env para o relay hospedado, ou ACTUAL_BASE_URL=http://127.0.0.1:8080 para o daemon local — nenhuma chave é necessária em loopback (provedor: actual; apelidos: actual-computer, actualcomputer, aci) |
| MiniMax | MINIMAX_API_KEY em ~/.hermes/.env (provedor: minimax) |
| MiniMax China | MINIMAX_CN_API_KEY em ~/.hermes/.env (provedor: minimax-cn) |
| xAI (Grok) — Responses API | XAI_API_KEY em ~/.hermes/.env (provedor: xai) |
| xAI Grok OAuth (SuperGrok) | hermes model → "xAI Grok OAuth (SuperGrok / Premium+)" — login pelo navegador, sem chave de API. Veja o guia |
| Qwen Cloud (Alibaba DashScope) | DASHSCOPE_API_KEY em ~/.hermes/.env (provedor: alibaba) |
| Alibaba Cloud (Coding Plan) | DASHSCOPE_API_KEY (provedor: alibaba-coding-plan, apelido: alibaba_coding) — SKU de cobrança separado, endpoint diferente |
| Kilo Code | KILOCODE_API_KEY em ~/.hermes/.env (provedor: kilocode) |
| Xiaomi MiMo | XIAOMI_API_KEY em ~/.hermes/.env (provedor: xiaomi, apelidos: mimo, xiaomi-mimo) |
| Tencent TokenHub | TOKENHUB_API_KEY em ~/.hermes/.env (provedor: tencent-tokenhub, apelidos: tencent, tokenhub, tencentmaas) |
| OpenCode Zen | OPENCODE_ZEN_API_KEY em ~/.hermes/.env (provedor: opencode-zen) |
| CommandCode | COMMANDCODE_API_KEY em ~/.hermes/.env (provedor: commandcode, apelido: commandcode-chat; modelos Claude via commandcode-anthropic, apelido: commandcode-claude). Funciona com os planos GOAT/Pro/Max/Provider (não com o plano Go de US$ 1 — sem acesso à API). |
| OpenCode Go | OPENCODE_GO_API_KEY em ~/.hermes/.env (provedor: opencode-go) |
| OpenCode Free | Sem chave — não precisa de chave de API nem de conta (provedor: opencode-free, apelidos: free, opencode_free). Selecione por hermes model ou /model free; os pedidos são enviados de forma anônima |
| DeepSeek | DEEPSEEK_API_KEY em ~/.hermes/.env (provedor: deepseek) |
| Hugging Face | HF_TOKEN em ~/.hermes/.env (provedor: huggingface, apelidos: hf) |
| Google / Gemini | GOOGLE_API_KEY (ou GEMINI_API_KEY) em ~/.hermes/.env (provedor: gemini) |
| Google Vertex AI | hermes model → "Google Vertex AI" (provedor: vertex; OAuth2 por JSON de conta de serviço ou ADC, cobrança no GCP) |
| OpenAI API (direta) | OPENAI_API_KEY em ~/.hermes/.env (provedor: openai-api, OPENAI_BASE_URL opcional) |
| Azure AI Foundry | hermes model → "Azure AI Foundry" (provedor: azure-foundry; usa o endpoint e a chave do Azure OpenAI / Foundry) |
| AWS Bedrock | hermes model → "AWS Bedrock" (provedor: bedrock; cadeia padrão de credenciais da AWS via boto3) |
| NVIDIA Build | NVIDIA_API_KEY em ~/.hermes/.env (provedor: nvidia; modelos hospedados em NIM no build.nvidia.com) |
| Ollama Cloud | hermes model → "Ollama Cloud" (provedor: ollama-cloud; API do Ollama hospedada na nuvem) |
| Qwen OAuth | hermes model → "Qwen OAuth" (provedor: qwen-oauth; login PKCE pelo navegador) |
| MiniMax OAuth | hermes model → "MiniMax (OAuth)" (provedor: minimax-oauth; login PKCE pelo navegador) |
| StepFun | STEPFUN_API_KEY em ~/.hermes/.env (provedor: stepfun) |
| LM Studio | hermes model → "LM Studio" (provedor: lmstudio, LM_API_KEY opcional) |
| Endpoint personalizado | hermes model → escolha "Custom endpoint" (salvo no config.yaml) |
Para o caminho oficial com chave de API, veja o guia dedicado do Google Gemini.
Na seção de configuração model:, você pode usar tanto default: quanto model: como nome da chave do seu ID de modelo. Tanto model: { default: my-model } quanto model: { model: my-model } funcionam de forma idêntica.
Nous Portal
O Nous Portal é o gateway unificado de assinatura da Nous Research e a forma recomendada de rodar o Hermes Agent. Um único login OAuth cobre mais de 300 modelos agênticos de ponta (Claude, GPT, Gemini, DeepSeek, Qwen, Kimi, GLM, MiniMax, Grok, ...) mais o Tool Gateway (busca na web, geração de imagem, TTS, automação de navegador) — cobrado na sua assinatura Nous, em vez de contas separadas por provedor.
hermes setup --portal # instalação nova — OAuth + provedor + gateway em um comando
hermes model # instalação existente — escolha "Nous Portal" na lista
hermes portal info # inspecione login + roteamento a qualquer momento
Ainda não tem assinatura? Assine em portal.nousresearch.com/manage-subscription.
Para todos os detalhes: veja a página dedicada de integração com o Nous Portal (o que a assinatura inclui, catálogo de modelos, solução de problemas) e o guia passo a passo Rodar o Hermes Agent com o Nous Portal.
Identificação do cliente. Todo pedido ao Portal vindo do Hermes Agent carrega uma etiqueta client=hermes-client-v<versão> (por exemplo, client=hermes-client-v0.13.0), alinhada automaticamente à versão que você instalou. Ela é enviada em todos os caminhos do Portal — laço principal de chat, chamadas auxiliares, sumarizador de compressão, extração web — e permite que a telemetria do lado do Portal distinga o tráfego do Hermes do de outros clientes. Nenhuma configuração é necessária; a etiqueta se atualiza sozinha quando você roda hermes update.
Autenticação JWT (automática). O Hermes prefere JWTs com escopo inference:invoke nos pedidos ao Portal, mantendo o caminho legado de chave de sessão opaca como recuo. Nenhuma configuração é necessária — as credenciais são administradas pelo fluxo OAuth e giram de forma transparente. Refresh tokens revogados ficam em quarentena, para evitar laços de repetição.
O provedor OpenAI Codex se autentica por código de dispositivo (você abre uma URL e digita um código). O Hermes guarda as credenciais resultantes no seu próprio repositório de autenticação, em ~/.hermes/auth.json, e consegue importar credenciais existentes da CLI do Codex a partir de ~/.codex/auth.json, quando elas existem. Não é preciso instalar a CLI do Codex.
Se a renovação de um token falhar com um erro terminal (HTTP 4xx, invalid_grant, concessão revogada etc.), o Hermes marca o refresh token como morto e para de repeti-lo, para você não ver uma enxurrada de falhas de autenticação idênticas. O pedido seguinte mostra uma mensagem tipada pedindo nova autenticação. Rode hermes auth add openai-codex (ou hermes model → ChatGPT or Codex Subscription) para iniciar um novo login por código de dispositivo; a quarentena é limpa na próxima troca bem-sucedida.
Mesmo usando o Nous Portal, o Codex ou um endpoint personalizado, algumas ferramentas (visão, sumarização web, MoA) usam um modelo "auxiliar" separado. Por padrão (auxiliary.*.provider: "auto"), o Hermes roteia essas tarefas para o seu modelo principal de chat — o mesmo que você escolheu em hermes model. Você pode sobrescrever cada tarefa individualmente para roteá-la a um modelo mais barato/rápido (por exemplo, Gemini Flash no OpenRouter) — veja Modelos auxiliares.
Assinantes pagos do Nous Portal também ganham acesso ao Tool Gateway — busca na web, geração de imagem, TTS e automação de navegador roteados pela sua assinatura. Sem precisar de chaves de API extras. Em uma instalação nova, o hermes setup --portal faz o login, define a Nous como provedor e liga o gateway em um comando só. Quem já usa pode habilitar pelo hermes model ou por ferramenta, no hermes tools. Inspecione o roteamento a qualquer momento com hermes portal info.
Dois comandos para administrar modelos
O Hermes tem dois comandos de modelo, que servem a propósitos diferentes:
| Comando | Onde rodar | O que faz |
|---|---|---|
hermes model | No seu terminal (fora de qualquer sessão) | Assistente completo de configuração — adiciona provedores, roda OAuth, recebe chaves de API, configura endpoints |
/model | Dentro de uma sessão de chat do Hermes | Troca rápida entre provedores e modelos já configurados |
Se você está tentando mudar para um provedor que ainda não configurou (por exemplo, só tem o OpenRouter configurado e quer usar a Anthropic), você precisa do hermes model, não do /model. Saia da sessão primeiro (Ctrl+C ou /quit), rode hermes model, conclua a configuração do provedor e então comece uma sessão nova.
Planos de assinatura: o que o seu plano paga
Vários provedores deixam você entrar no Hermes com uma assinatura de consumidor (Claude Max, ChatGPT, SuperGrok / X Premium+, ...) em vez de uma chave de API. O que essa assinatura de fato paga — e o que não paga — muda de provedor para provedor, e é a maior fonte de surpresas na fatura. A tabela abaixo é a versão curta; a seção de cada provedor tem os detalhes.
Células marcadas como ainda não documentado significam exatamente isso: a documentação do Hermes ainda não especifica o comportamento. Não presuma — confira o painel de cobrança do seu provedor e trate isso como uma questão em aberto.
| Plano / caminho | O Hermes consegue usar? | O que é consumido | O que NÃO é consumido | Surpresa comum |
|---|---|---|---|---|
| Anthropic — Claude Max + OAuth | ✅ Sim — hermes model → OAuth da Anthropic. Exige o Max e créditos de uso extra comprados | Os créditos extras/de excedente que você adicionou por cima do plano Max | A franquia base do plano Max (o uso incluso no Claude Code por padrão) | Todo o uso do Hermes é cobrado como "uso extra", mesmo com a sua franquia inclusa do Max intocada |
| Anthropic — Claude Pro | ❌ Não — assinantes do Pro não podem usar o caminho OAuth | Nada (caminho indisponível) | A sua assinatura Pro | O Pro parece que deveria funcionar; não funciona. Use uma ANTHROPIC_API_KEY no lugar (pagamento por token, independente de qualquer assinatura do Claude) |
| OpenAI Codex — OAuth do plano ChatGPT | ✅ Sim — hermes model → ChatGPT or Codex Subscription (login OAuth por código de dispositivo do ChatGPT, usa modelos Codex) | ainda não documentado | ainda não documentado | A documentação cobre só autenticação e renovação de token; a semântica de cota do plano ainda não está documentada |
| xAI — OAuth do SuperGrok / X Premium+ | ✅ Sim — OAuth pelo navegador, sem chave de API | A sua cota da assinatura (documentado explicitamente para o X Search: o OAuth é preferido a uma chave de API e "usa a sua cota de assinatura em vez do gasto de API"). Semântica de cota de inferência além disso: ainda não documentado | XAI_API_KEY / gasto de API por token, quando credenciais OAuth estão configuradas e são preferidas | HTTP 403 depois de um login bem-sucedido — a xAI restringiu o acesso à API por OAuth a certos níveis do SuperGrok, mesmo com uma assinatura ativa no app |
| Google — plano de consumidor Gemini (Google AI Pro / Ultra) | ❌ Nenhum caminho documentado — o provedor gemini é só por chave de API (GOOGLE_API_KEY / GEMINI_API_KEY); o Vertex AI usa a cobrança do GCP | A cota da sua chave de API (nível gratuito ou projeto do Google Cloud com cobrança habilitada) — consumo do plano de consumidor ainda não documentado | ainda não documentado | Chaves do nível gratuito podem se esgotar depois de alguns poucos turnos do agente, porque o Hermes pode fazer várias chamadas de modelo por turno do usuário |
Anthropic. O caminho OAuth roteia como Claude Code contra a sua conta da Anthropic e só funciona em um plano Claude Max com créditos de uso extra comprados — a franquia base do Max nunca é consumida pelo Hermes, apenas os créditos extras/de excedente por cima. Assinantes do Claude Pro não podem usar esse caminho; a alternativa suportada é uma ANTHROPIC_API_KEY, cobrada por token contra a organização daquela chave, no preço padrão da API. Veja Anthropic (nativa) abaixo.
OpenAI Codex. O Hermes se autentica por OAuth de código de dispositivo do ChatGPT, guarda as credenciais em ~/.hermes/auth.json e consegue importar credenciais existentes da CLI do Codex a partir de ~/.codex/auth.json. Quais níveis de plano do ChatGPT são elegíveis, e como o uso do Hermes conta contra os limites do Codex do seu plano, ainda não estão documentados — a nota sobre o Codex em Nous Portal cobre apenas a autenticação e o comportamento de renovação de token.
xAI (SuperGrok / X Premium+). O OAuth pelo navegador funciona tanto com uma assinatura SuperGrok ativa quanto com uma assinatura X Premium+ na conta X vinculada, e o mesmo bearer token é reaproveitado pelas ferramentas que falam direto com a xAI (TTS, geração de imagem, geração de vídeo, transcrição, X Search). Se a inferência devolver HTTP 403 depois de um login bem-sucedido, isso é uma restrição de nível/direito do lado da xAI, não um token velho — o contorno é passar para uma XAI_API_KEY. Veja xAI (Grok) abaixo e o guia de OAuth do xAI Grok.
Google Gemini. Hoje não existe forma de entrar no Hermes com uma assinatura de consumidor do Gemini — o provedor gemini aceita uma chave de API, e o Google Vertex AI cobra no seu projeto do GCP. Um projeto do Google Cloud com cobrança habilitada é o recomendado para uso com agente; as cotas do nível gratuito são pequenas demais para sessões longas de agente. Veja o guia do Google Gemini.
Se você prefere não acompanhar a semântica de plano de cada provedor, o Nous Portal cobre mais de 300 modelos em uma assinatura só, com um único login OAuth.
Anthropic (nativa)
Use modelos Claude diretamente pela API da Anthropic — sem precisar do proxy do OpenRouter. Suporta três métodos de autenticação:
Quando você se autentica via hermes model → OAuth da Anthropic (ou via hermes auth add anthropic --type oauth), o Hermes roteia como Claude Code contra a sua conta da Anthropic. Isso só funciona se você está em um plano Claude Max e comprou créditos de uso extra. A franquia base do plano Max (o uso incluso no Claude Code por padrão) não é consumida pelo Hermes — só os créditos extras/de excedente que você adicionou por cima. Assinantes do Claude Pro não podem usar esse caminho.
Se você não tem Max + créditos extras, use uma ANTHROPIC_API_KEY — os pedidos são cobrados por token contra a organização daquela chave (preço padrão da API, independente de qualquer assinatura do Claude).
# Com uma chave de API (pagamento por token)
export ANTHROPIC_API_KEY=***
hermes chat --provider anthropic --model claude-sonnet-4-6
# Preferido: autentique pelo `hermes model`
# O Hermes usa o repositório de credenciais do Claude Code diretamente quando disponível
hermes model
# Sobrescrita manual com um setup-token (recuo / legado)
export ANTHROPIC_TOKEN=*** # setup-token ou token OAuth manual
hermes chat --provider anthropic
# Detecte automaticamente as credenciais do Claude Code (se você já usa o Claude Code)
hermes chat --provider anthropic # lê os arquivos de credencial do Claude Code automaticamente
Quando você escolhe o OAuth da Anthropic pelo hermes model, o Hermes prefere o próprio repositório de credenciais do Claude Code a copiar o token para o ~/.hermes/.env. Isso mantém renováveis as credenciais renováveis do Claude.
Ou defina de forma permanente:
model:
provider: "anthropic"
default: "claude-sonnet-4-6"
--provider claude e --provider claude-code também funcionam como atalho para --provider anthropic.
GitHub Copilot
O Hermes suporta o GitHub Copilot como provedor de primeira classe, em dois modos:
copilot — API direta do Copilot (recomendado). Usa a sua assinatura do GitHub Copilot para acessar GPT-5.x, Claude, Gemini e outros modelos pela API do Copilot.
hermes chat --provider copilot --model gpt-5.4
Opções de autenticação (conferidas nesta ordem):
- Variável de ambiente
COPILOT_GITHUB_TOKEN - Variável de ambiente
GH_TOKEN - Variável de ambiente
GITHUB_TOKEN - Recuo para a CLI, com
gh auth token
Se nenhum token for encontrado, o hermes model oferece um login OAuth por código de dispositivo — o mesmo fluxo usado pela CLI do Copilot e pelo opencode.
A API do Copilot não suporta Personal Access Tokens clássicos (ghp_*). Tipos de token suportados:
| Tipo | Prefixo | Como obter |
|---|---|---|
| Token OAuth | gho_ | hermes model → GitHub Copilot → Login with GitHub |
| PAT de escopo fino | github_pat_ | GitHub Settings → Developer settings → Fine-grained tokens (precisa da permissão Copilot Requests) |
| Token de GitHub App | ghu_ | Pela instalação de um GitHub App |
Se o seu gh auth token devolve um token ghp_*, use o hermes model para autenticar por OAuth.
O Hermes envia um token do GitHub suportado (gho_*, github_pat_* ou ghu_*) diretamente para api.githubcopilot.com e inclui cabeçalhos específicos do Copilot (Editor-Version, Copilot-Integration-Id, Openai-Intent, x-initiator).
Em um HTTP 401, o Hermes agora faz uma recuperação de credencial de uma tentativa antes do recuo:
- Resolve o token de novo pela cadeia normal de prioridade (
COPILOT_GITHUB_TOKEN→GH_TOKEN→GITHUB_TOKEN→gh auth token) - Reconstrói o cliente OpenAI compartilhado com os cabeçalhos atualizados
- Repete o pedido uma vez
Alguns proxies comunitários mais antigos usam fluxos de troca em api.github.com/copilot_internal/v2/token. Esse endpoint pode estar indisponível para certos tipos de conta (devolve 404). Por isso, o Hermes mantém a autenticação por token direto como caminho principal e conta com a renovação de credencial em tempo de execução + repetição para ser robusto.
Roteamento de API: modelos GPT-5+ (exceto o gpt-5-mini) usam automaticamente a Responses API. Todos os outros modelos (GPT-4o, Claude, Gemini etc.) usam Chat Completions. Os modelos são detectados automaticamente a partir do catálogo ao vivo do Copilot.
copilot-acp — backend de agente ACP do Copilot. Sobe a CLI local do Copilot como subprocesso:
hermes chat --provider copilot-acp --model copilot-acp
# Exige a CLI do GitHub Copilot no PATH e uma sessão existente de `copilot login`
Configuração permanente:
model:
provider: "copilot"
default: "gpt-5.4"
| Variável de ambiente | Descrição |
|---|---|
COPILOT_GITHUB_TOKEN | Token do GitHub para a API do Copilot (primeira prioridade) |
HERMES_COPILOT_ACP_COMMAND | Sobrescreve o caminho do binário da CLI do Copilot (padrão: copilot) |
HERMES_COPILOT_ACP_ARGS | Sobrescreve os argumentos do ACP (padrão: --acp --stdio) |
Provedores de primeira classe com chave de API
Esses provedores têm suporte embutido, com IDs de provedor dedicados. Defina a chave de API e use --provider para selecionar:
# Fireworks AI
hermes chat --provider fireworks --model accounts/fireworks/models/kimi-k2p6
# Exige: FIREWORKS_API_KEY em ~/.hermes/.env
# Model API da NovitaAI
hermes chat --provider novita --model moonshotai/kimi-k2.5
# Exige: NOVITA_API_KEY em ~/.hermes/.env
# z.ai / ZhipuAI GLM
hermes chat --provider zai --model glm-5
# Exige: GLM_API_KEY em ~/.hermes/.env
# Kimi / Moonshot AI (internacional: api.moonshot.ai)
hermes chat --provider kimi-coding --model kimi-for-coding
# Exige: KIMI_API_KEY em ~/.hermes/.env
# Kimi / Moonshot AI (China: api.moonshot.cn)
hermes chat --provider kimi-coding-cn --model kimi-k2.5
# Exige: KIMI_CN_API_KEY em ~/.hermes/.env
# MiniMax (endpoint global)
hermes chat --provider minimax --model MiniMax-M2.7
# Exige: MINIMAX_API_KEY em ~/.hermes/.env
# MiniMax (endpoint da China)
hermes chat --provider minimax-cn --model MiniMax-M2.7
# Exige: MINIMAX_CN_API_KEY em ~/.hermes/.env
# Qwen Cloud / DashScope (modelos Qwen)
hermes chat --provider alibaba --model qwen3.5-plus
# Exige: DASHSCOPE_API_KEY em ~/.hermes/.env
# Xiaomi MiMo
hermes chat --provider xiaomi --model mimo-v2-pro
# Exige: XIAOMI_API_KEY em ~/.hermes/.env
# Tencent TokenHub (Hy3 Preview)
hermes chat --provider tencent-tokenhub --model hy3-preview
# Exige: TOKENHUB_API_KEY em ~/.hermes/.env
# Arcee AI (modelos Trinity)
hermes chat --provider arcee --model trinity-large-thinking
# Exige: ARCEEAI_API_KEY em ~/.hermes/.env
# Meta Model API (família Muse Spark)
hermes chat --provider meta-ai --model muse-spark-1.2
# Exige: MODEL_API_KEY em ~/.hermes/.env
# GMI Cloud
# Use exatamente o ID de modelo devolvido pelo endpoint /v1/models da GMI.
hermes chat --provider gmi --model zai-org/GLM-5.1-FP8
# Exige: GMI_API_KEY em ~/.hermes/.env
A Fireworks usa os IDs nativos de catálogo, no formato com barras, como accounts/fireworks/models/kimi-k2p6. Rode hermes model, escolha Fireworks AI e selecione a partir do catálogo ao vivo, ou informe outro ID de modelo da Fireworks. O endpoint padrão é https://api.fireworks.ai/inference/v1; configure um endpoint diferente por model.base_url no config.yaml, não no .env.
Ou defina o provedor de forma permanente no config.yaml:
model:
provider: "gmi"
default: "zai-org/GLM-5.1-FP8"
As URLs base podem ser sobrescritas pelas variáveis de ambiente NOVITA_BASE_URL, GLM_BASE_URL, KIMI_BASE_URL, MINIMAX_BASE_URL, MINIMAX_CN_BASE_URL, DASHSCOPE_BASE_URL, XIAOMI_BASE_URL, GMI_BASE_URL, META_BASE_URL ou TOKENHUB_BASE_URL.
O muse-spark-1.2-contributor é o nível com desconto da Meta — a Meta pode treinar com os seus prompts e respostas, então a seleção interativa de modelo pede confirmação antes de usá-lo. Use o muse-spark-1.2 (preço padrão, sem treinamento) para trabalho confidencial.
Ao usar o provedor Z.AI / GLM, o Hermes sonda automaticamente vários endpoints (global, China, variantes de coding) para achar um que aceite a sua chave de API. Você não precisa definir GLM_BASE_URL na mão — o endpoint que funciona é detectado e guardado em cache automaticamente.
xAI (Grok) — Responses API + cache de prompt
A xAI é ligada pela Responses API (transporte codex_responses), com suporte automático a raciocínio nos modelos Grok 4 — nenhum parâmetro reasoning_effort é necessário, o servidor raciocina por padrão. Defina XAI_API_KEY em ~/.hermes/.env e escolha a xAI no hermes model, ou use grok como atalho em /model grok-4-fast-reasoning.
Assinantes do SuperGrok e do X Premium+ podem entrar com OAuth pelo navegador, em vez de usar uma chave de API — escolha xAI Grok OAuth (SuperGrok / Premium+) no hermes model, ou rode hermes auth add xai-oauth. O mesmo bearer token de OAuth é reaproveitado automaticamente pelas ferramentas que falam direto com a xAI (TTS, geração de imagem, geração de vídeo, transcrição). Veja o guia de OAuth do xAI Grok para o fluxo completo — e, se o Hermes roda em uma máquina remota, veja também OAuth por SSH / máquinas remotas para o túnel ssh -L necessário.
Ao usar a xAI como provedor (qualquer URL base que contenha x.ai), o Hermes habilita automaticamente o cache de prompt, enviando o cabeçalho x-grok-conv-id em toda chamada de API. Isso roteia os pedidos para o mesmo servidor dentro de uma sessão de conversa, permitindo que a infraestrutura da xAI reaproveite prompts de sistema e histórico de conversa em cache.
Nenhuma configuração é necessária — o cache é ativado automaticamente quando um endpoint da xAI é detectado e existe um ID de sessão disponível. Isso reduz latência e custo em conversas de vários turnos.
A xAI também oferece um endpoint dedicado de TTS (/v1/tts). Selecione xAI TTS em hermes tools → Voice & TTS, ou veja a página de Voz e TTS para a configuração.
Migração de modelos aposentados da xAI (15 de maio de 2026): a xAI vai aposentar grok-4*, grok-3, grok-code-fast-1 e grok-imagine-image-pro em 15/05/2026. Tanto o hermes doctor quanto a inicialização do hermes chat detectam qualquer configuração ainda apontando para uma referência aposentada e imprimem a substituição recomendada. Use hermes migrate xai para uma reescrita de configuração de uma tacada — por padrão é simulação; acrescente --apply para gravar as mudanças (um backup config.yaml.bak-pre-migrate-xai-* com data e hora é criado automaticamente).
hermes migrate xai # veja as substituições
hermes migrate xai --apply # reescreve o ~/.hermes/config.yaml no lugar
Backend de busca na web da xAI. Quando o conjunto de ferramentas de Busca na web está habilitado, web.backend: xai roteia a busca pelo endpoint de busca hospedado da xAI, usando as mesmas credenciais de XAI_API_KEY / OAuth. Nenhuma configuração adicional é necessária se a xAI já está configurada como provedor.
NovitaAI
A NovitaAI é a nuvem nativa de IA para quem constrói e para agentes. Suas três linhas de produto são a Model API, com mais de 200 modelos, o Agent Sandbox, para construir e rodar agentes de IA, e a GPU Cloud, para computação escalável, tudo em uma plataforma só.
# Use qualquer modelo disponível
hermes chat --provider novita --model moonshotai/kimi-k2.5
# Exige: NOVITA_API_KEY em ~/.hermes/.env
# Apelido curto
hermes chat --provider novita-ai --model deepseek/deepseek-v3-0324
Ou defina de forma permanente no config.yaml:
model:
provider: "novita"
default: "moonshotai/kimi-k2.5"
base_url: "https://api.novita.ai/openai/v1"
Pegue a sua chave de API em novita.ai/settings/key-management. A URL base pode ser sobrescrita com NOVITA_BASE_URL.
Ollama Cloud — modelos Ollama gerenciados, OAuth + chave de API
O Ollama Cloud hospeda o mesmo catálogo de pesos abertos do Ollama local, mas sem a exigência de GPU. Escolha-o no hermes model como Ollama Cloud, cole a sua chave de API de ollama.com/settings/keys e o Hermes descobre automaticamente os modelos disponíveis.
hermes model
# → escolha "Ollama Cloud"
# → cole a sua OLLAMA_API_KEY
# → selecione entre os modelos descobertos (gpt-oss:120b, glm-4.6:cloud, qwen3-coder:480b-cloud etc.)
Ou direto no config.yaml:
model:
provider: "ollama-cloud"
default: "gpt-oss:120b"
O catálogo de modelos é buscado dinamicamente em ollama.com/v1/models e guardado em cache por uma hora. A notação model:tag (por exemplo, qwen3-coder:480b-cloud) é preservada na normalização — não use hifens.
Os dois falam a mesma API compatível com a da OpenAI. O Cloud é um provedor de primeira classe (--provider ollama-cloud, OLLAMA_API_KEY); o Ollama local é acessado pelo fluxo de endpoint personalizado (URL base http://localhost:11434/v1, sem chave). Use a nuvem para modelos grandes que você não consegue rodar localmente; use o local para privacidade ou trabalho offline.
AWS Bedrock
Anthropic Claude, Amazon Nova, DeepSeek v3.2, Meta Llama 4 e outros modelos pelo AWS Bedrock. Usa a cadeia de credenciais do SDK da AWS (boto3) — sem chave de API, só a autenticação padrão da AWS.
# Mais simples — perfil nomeado em ~/.aws/credentials
hermes chat --provider bedrock --model us.anthropic.claude-sonnet-4-6
# Ou com variáveis de ambiente explícitas
AWS_PROFILE=meuperfil AWS_REGION=us-east-1 hermes chat --provider bedrock --model us.anthropic.claude-sonnet-4-6
Ou de forma permanente no config.yaml:
model:
provider: "bedrock"
default: "us.anthropic.claude-sonnet-4-6"
bedrock:
region: "us-east-1" # ou defina AWS_REGION
# profile: "meuperfil" # ou defina AWS_PROFILE
# discovery: true # descobre a região automaticamente pelo IAM
# guardrail: # Bedrock Guardrails opcionais
# guardrail_identifier: "seu-id-de-guardrail"
# guardrail_version: "DRAFT"
A autenticação usa a cadeia padrão do boto3: AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY explícitos, AWS_PROFILE de ~/.aws/credentials, papel IAM em EC2/ECS/Lambda, IMDS ou SSO. Nenhuma variável de ambiente é necessária se você já está autenticado na CLI da AWS.
O Bedrock usa a Converse API por baixo dos panos — os pedidos são traduzidos para o formato agnóstico de modelo do Bedrock, então a mesma configuração vale para modelos Claude, Nova, DeepSeek e Llama. Defina BEDROCK_BASE_URL só se você chama um endpoint regional fora do padrão.
Veja o guia do AWS Bedrock para um passo a passo de configuração de IAM, escolha de região e inferência entre regiões.
Google Vertex AI
Modelos Gemini no Google Cloud Vertex AI, pelo endpoint compatível com a OpenAI do Vertex. A autenticação é OAuth2 — um token de acesso de curta duração (cerca de 1 hora) cunhado a partir de um JSON de conta de serviço ou das Application Default Credentials (ADC). Não existe chave de API estática; o Hermes cunha e renova o token para você automaticamente, inclusive recunhando em um 401 no meio da sessão.
# JSON de conta de serviço (recomendado para servidores / gateways)
echo "VERTEX_CREDENTIALS_PATH=/caminho/da/conta-de-servico.json" >> ~/.hermes/.env
# ou Application Default Credentials
gcloud auth application-default login
hermes model # → "Google Vertex AI" → projeto → região → modelo
Ou no config.yaml (projeto/região não são segredos e ficam aqui; o caminho da credencial fica no .env):
model:
provider: "vertex"
default: "google/gemini-3-flash-preview" # o Vertex exige o prefixo google/
vertex:
project_id: "meu-projeto-gcp" # em branco → usa o projeto embutido nas credenciais
region: "global" # obrigatório para as prévias do Gemini 3.x
As variáveis de ambiente VERTEX_PROJECT_ID / VERTEX_REGION sobrescrevem os valores do config.yaml. O Hermes instala o google-auth sob demanda no primeiro uso; rode hermes setup se a instalação gerenciada precisar de conserto. Veja o guia do Google Vertex AI para o passo a passo completo, e o guia do Google Gemini para o caminho do AI Studio com chave de API estática.
Qwen Portal (OAuth)
O Qwen Portal da Alibaba, com login OAuth pelo navegador. Escolha Qwen OAuth (Portal) no hermes model, entre pelo navegador e o Hermes persiste o refresh token.
hermes model
# → escolha "Qwen OAuth (Portal)"
# → o navegador abre; entre com a sua conta Alibaba
# → confirme — as credenciais são salvas em ~/.hermes/auth.json
hermes chat # usa o endpoint portal.qwen.ai/v1
Ou configure o config.yaml:
model:
provider: "qwen-oauth"
default: "qwen3-coder-plus"
Defina HERMES_QWEN_BASE_URL só se o endpoint do portal mudar de lugar (padrão: https://portal.qwen.ai/v1).
O qwen-oauth usa o Qwen Portal voltado ao consumidor, com login OAuth — ideal para usuários individuais. O provedor alibaba usa o Qwen Cloud (Alibaba DashScope) com uma DASHSCOPE_API_KEY — ideal para cargas programáticas / de produção. Os dois roteiam para modelos da família Qwen, mas ficam em endpoints diferentes.
Alibaba Cloud (Coding Plan)
Se você assina o Coding Plan da Alibaba (um SKU de preço separado do acesso padrão à API do DashScope), o Hermes o expõe como provedor de primeira classe próprio: alibaba-coding-plan. Endpoint: https://coding-intl.dashscope.aliyuncs.com/v1. Ele é compatível com a OpenAI, como o provedor alibaba comum, mas com URL base e superfície de cobrança diferentes.
model:
provider: alibaba_coding # apelido de alibaba-coding-plan
model: qwen3-coder-plus
Ou pela CLI:
hermes chat --provider alibaba_coding --model qwen3-coder-plus
O alibaba_coding usa a mesma DASHSCOPE_API_KEY que a sua entrada alibaba já usa — nenhuma chave separada é necessária, só um alvo de roteamento diferente. Antes de esse provedor ser registrado, quem definia provider: alibaba_coding no config.yaml caía silenciosamente no roteamento do OpenRouter.
MiniMax (OAuth)
MiniMax-M2.7 por login OAuth no navegador — sem precisar de chave de API. Escolha MiniMax (OAuth) no hermes model, entre pelo navegador e o Hermes persiste os tokens de acesso + de renovação. Usa por baixo o endpoint compatível com o Messages da Anthropic (/anthropic).
hermes model
# → escolha "MiniMax (OAuth)"
# → o navegador abre; entre com a sua conta MiniMax (região global ou CN)
# → confirme — as credenciais são salvas em ~/.hermes/auth.json
hermes chat # usa o endpoint api.minimax.io/anthropic
Ou configure o config.yaml:
model:
provider: "minimax-oauth"
default: "MiniMax-M2.7"
Modelos suportados: MiniMax-M2.7 (principal) e MiniMax-M2.7-highspeed (ligado como modelo auxiliar padrão). O caminho OAuth ignora MINIMAX_API_KEY / MINIMAX_BASE_URL.
O minimax-oauth usa o portal da MiniMax voltado ao consumidor, com login OAuth — sem precisar configurar cobrança. Os provedores minimax e minimax-cn usam MINIMAX_API_KEY / MINIMAX_CN_API_KEY — para acesso programático. Veja o guia do MiniMax OAuth para um passo a passo completo.
NVIDIA NIM
Nemotron e outros modelos de código aberto pelo build.nvidia.com (chave de API gratuita) ou por um endpoint NIM local.
# Nuvem (build.nvidia.com)
hermes chat --provider nvidia --model nvidia/nemotron-3-super-120b-a12b
# Exige: NVIDIA_API_KEY em ~/.hermes/.env
# Endpoint NIM local — sobrescreva a URL base
NVIDIA_BASE_URL=http://localhost:8000/v1 hermes chat --provider nvidia --model nvidia/nemotron-3-super-120b-a12b
Ou defina de forma permanente no config.yaml:
model:
provider: "nvidia"
default: "nvidia/nemotron-3-super-120b-a12b"
Para implantações no local (DGX Spark, GPU local), defina NVIDIA_BASE_URL=http://localhost:8000/v1. O NIM expõe a mesma API de chat completions compatível com a OpenAI do build.nvidia.com, então alternar entre nuvem e local é uma mudança de uma linha na variável de ambiente.
O Hermes anexa automaticamente o cabeçalho de origem de cobrança do NIM em todo pedido para o build.nvidia.com — sem precisar configurar nada. Isso direciona o consumo à origem correta no painel de cobrança da NVIDIA.
GMI Cloud
Modelos abertos e de raciocínio pela GMI Cloud — API compatível com a OpenAI, autenticação por chave de API.
# GMI Cloud
hermes chat --provider gmi --model deepseek-ai/DeepSeek-V3.2
# Exige: GMI_API_KEY em ~/.hermes/.env
Ou defina de forma permanente no config.yaml:
model:
provider: "gmi"
default: "deepseek-ai/DeepSeek-V3.2"
A URL base pode ser sobrescrita com GMI_BASE_URL (padrão: https://api.gmi-serving.com/v1).
Actual Computer
O seu próprio hardware como cluster privado de inferência, via Actual Computer. Dois modos de serviço, ambos compatíveis com a OpenAI (o Hermes usa o transporte da Responses API):
- Relay hospedado —
https://api.actual.inc, criptografado de ponta a ponta, roteia para o seu cluster. Autentique com uma chave de inferênciaac_de actual.inc/user/keys. - Daemon local — no dispositivo, em
http://127.0.0.1:8080, totalmente offline. Nenhuma chave de API é necessária: o Hermes detecta a URL base de loopback e autentica automaticamente com um marcador interno.
# Relay hospedado (ACTUAL_API_KEY em ~/.hermes/.env)
hermes chat --provider actual --model <id-de-modelo-do-seu-cluster>
# Daemon local (ACTUAL_BASE_URL=http://127.0.0.1:8080 em ~/.hermes/.env, sem chave)
hermes chat --provider actual --model <nome-do-modelo-instalado>
Ou defina de forma permanente no config.yaml:
model:
provider: "actual"
default: "<id-do-modelo>"
Observações:
- Os IDs de modelo vêm do
GET /v1/modelsdo seu cluster — descubra comhermes modeloucurl -s https://api.actual.inc/v1/models -H "Authorization: Bearer $ACTUAL_API_KEY". - Hosts sem caminho são normalizados:
ACTUAL_BASE_URL=http://127.0.0.1:8080virahttp://127.0.0.1:8080/v1automaticamente. - O esforço de raciocínio é limitado à faixa suportada pela Actual (
none/low/medium/high/max) — um ajuste global dexhigh/ultranão vai fazer os pedidos darem 400. - Modelos locais pequenos: o conjunto padrão completo de ferramentas do Hermes mais o prompt de sistema podem passar de uma janela de contexto de 32k, produzindo um erro de stream vazio em servidores da família llama.cpp. Restrinja o conjunto de ferramentas (
-t file,web) ou carregue o modelo com um contexto maior. A skill opcionalactual-setup(hermes skills install official/devops/actual-setup) cobre configuração e solução de problemas em detalhe. - Apelidos:
actual-computer,actualcomputer,aci.
StepFun
Modelos da série Step pela StepFun — API compatível com a OpenAI, autenticação por chave de API.
# StepFun
hermes chat --provider stepfun --model step-3.5-flash
# Exige: STEPFUN_API_KEY em ~/.hermes/.env
Ou defina de forma permanente no config.yaml:
model:
provider: "stepfun"
default: "step-3.5-flash"
A URL base pode ser sobrescrita com STEPFUN_BASE_URL (padrão: https://api.stepfun.com/v1).
Hugging Face Inference Providers
Os Hugging Face Inference Providers roteiam para mais de 20 modelos abertos por um endpoint unificado compatível com a OpenAI (router.huggingface.co/v1). Os pedidos são roteados automaticamente para o backend disponível mais rápido (Groq, Together, SambaNova etc.), com failover automático.
# Use qualquer modelo disponível
hermes chat --provider huggingface --model Qwen/Qwen3.5-397B-A17B
# Exige: HF_TOKEN em ~/.hermes/.env
# Apelido curto
hermes chat --provider hf --model deepseek-ai/DeepSeek-V3.2
Ou defina de forma permanente no config.yaml:
model:
provider: "huggingface"
default: "Qwen/Qwen3.5-397B-A17B"
Pegue o seu token em huggingface.co/settings/tokens — não esqueça de habilitar a permissão "Make calls to Inference Providers". O nível gratuito está incluído (US$ 0,10 de crédito por mês, sem margem sobre os preços dos provedores).
Você pode acrescentar sufixos de roteamento aos nomes de modelo: :fastest (padrão), :cheapest ou :provider_name para forçar um backend específico.
A URL base pode ser sobrescrita com HF_BASE_URL.
Provedores de LLM personalizados e auto-hospedados
O Hermes Agent funciona com qualquer endpoint de API compatível com a da OpenAI. Se um servidor implementa /v1/chat/completions, você pode apontar o Hermes para ele. Isso significa que você pode usar modelos locais, servidores de inferência em GPU, roteadores multiprovedor ou qualquer API de terceiros.
Configuração geral
Três formas de configurar um endpoint personalizado:
Configuração interativa (recomendada):
hermes model
# Selecione "Custom endpoint (self-hosted / VLLM / etc.)"
# Informe: URL base da API, chave de API, nome do modelo
Configuração manual (config.yaml):
# Em ~/.hermes/config.yaml
model:
default: nome-do-seu-modelo
provider: custom
base_url: http://localhost:8000/v1
api_key: sua-chave-ou-deixe-vazio-para-local
O LLM_MODEL no .env foi removido — o config.yaml é a única fonte de verdade para a configuração de modelo e endpoint. O OPENAI_BASE_URL ainda é respeitado, mas apenas para o provedor openai-api (ele sobrescreve o endpoint da OpenAI no acesso direto por chave de API). Para outros provedores e endpoints personalizados, use hermes model ou defina model.base_url direto no config.yaml. Se você tem entradas velhas no seu .env, elas são limpas automaticamente no próximo hermes setup ou na próxima migração de configuração.
As duas abordagens persistem no config.yaml, que é a fonte de verdade para modelo, provedor e URL base.
Trocar de modelo com /model
O hermes model (rodado no seu terminal, fora de qualquer sessão de chat) é o assistente completo de configuração de provedores. Use-o para adicionar provedores novos, rodar fluxos OAuth, informar chaves de API e configurar endpoints personalizados.
O /model (digitado dentro de uma sessão ativa do Hermes) só consegue alternar entre provedores e modelos que você já configurou. Ele não adiciona provedores novos, não roda OAuth e não pede chaves de API. Se você configurou só um provedor (por exemplo, o OpenRouter), o /model vai mostrar apenas os modelos daquele provedor.
Para adicionar um provedor novo: saia da sessão (Ctrl+C ou /quit), rode hermes model, configure o provedor novo e então comece uma sessão nova.
Com pelo menos um endpoint personalizado configurado, você pode trocar de modelo no meio da sessão:
/model custom:qwen-2.5 # Muda para um modelo no seu endpoint personalizado
/model custom # Detecta o modelo automaticamente pelo endpoint
/model openrouter:claude-sonnet-4 # Volta para um provedor de nuvem
Se você tem provedores personalizados nomeados configurados (veja abaixo), use a sintaxe tripla:
/model custom:local:qwen-2.5 # Usa o provedor personalizado "local" com o modelo qwen-2.5
/model custom:work:llama3 # Usa o provedor personalizado "work" com o llama3
Ao trocar de provedor, o Hermes persiste a URL base e o provedor na configuração, então a mudança sobrevive a reinícios. Ao sair de um endpoint personalizado para um provedor embutido, a URL base velha é limpa automaticamente.
O /model custom (puro, sem nome de modelo) consulta a API /models do seu endpoint e seleciona o modelo automaticamente se houver exatamente um carregado. Útil para servidores locais rodando um único modelo.
Tudo o que vem abaixo segue esse mesmo padrão — basta trocar a URL, a chave e o nome do modelo.
Ollama — modelos locais, zero configuração
O Ollama roda modelos de pesos abertos localmente com um comando. Melhor para: experimentação local rápida, trabalho sensível à privacidade, uso offline. Suporta chamada de ferramentas pela API compatível com a da OpenAI.
# Instale e rode um modelo
ollama pull qwen2.5-coder:32b
ollama serve # Sobe na porta 11434
Depois configure o Hermes:
hermes model
# Selecione "Custom endpoint (self-hosted / VLLM / etc.)"
# Informe a URL: http://localhost:11434/v1
# Pule a chave de API (o Ollama não precisa de uma)
# Informe o nome do modelo (por exemplo, qwen2.5-coder:32b)
Ou configure o config.yaml diretamente:
model:
default: qwen2.5-coder:32b
provider: custom
base_url: http://localhost:11434/v1
context_length: 64000 # Veja o aviso abaixo
O Ollama não usa a janela de contexto completa do seu modelo por padrão. Dependendo da sua VRAM, o padrão é:
| VRAM disponível | Contexto padrão |
|---|---|
| Menos de 24 GB | 4.096 tokens |
| 24 a 48 GB | 32.768 tokens |
| 48 GB ou mais | 256.000 tokens |
O Hermes Agent exige pelo menos 64.000 tokens de contexto para uso como agente com ferramentas. Janelas menores são rejeitadas na inicialização, porque o prompt de sistema, os esquemas de ferramentas e o estado de trabalho da conversa precisam de espaço suficiente para fluxos de vários passos confiáveis.
Como aumentar (escolha uma):
# Opção 1: definir para todo o servidor por variável de ambiente (recomendado)
OLLAMA_CONTEXT_LENGTH=64000 ollama serve
# Opção 2: para um Ollama gerenciado pelo systemd
sudo systemctl edit ollama.service
# Acrescente: Environment="OLLAMA_CONTEXT_LENGTH=64000"
# Depois: sudo systemctl daemon-reload && sudo systemctl restart ollama
# Opção 3: embutir em um modelo personalizado (persistente por modelo)
echo -e "FROM qwen2.5-coder:32b\nPARAMETER num_ctx 64000" > Modelfile
ollama create qwen2.5-coder-64k -f Modelfile
Você não consegue definir o tamanho do contexto pela API compatível com a da OpenAI (/v1/chat/completions). Isso precisa ser configurado no servidor ou por um Modelfile. Essa é a fonte de confusão número 1 ao integrar o Ollama com ferramentas como o Hermes.
Confirme que o seu contexto está certo:
ollama ps
# Olhe a coluna CONTEXT — ela deve mostrar o valor que você configurou
Liste os modelos disponíveis com ollama list. Baixe qualquer modelo da biblioteca do Ollama com ollama pull <modelo>. O Ollama cuida do descarregamento para a GPU automaticamente — na maioria das configurações, não é preciso ajustar nada.
vLLM — inferência em GPU de alto desempenho
O vLLM é o padrão para servir LLMs em produção. Melhor para: vazão máxima em hardware de GPU, servir modelos grandes, batching contínuo.
pip install vllm
vllm serve meta-llama/Llama-3.1-70B-Instruct \
--port 8000 \
--max-model-len 65536 \
--tensor-parallel-size 2 \
--enable-auto-tool-choice \
--tool-call-parser hermes
Depois configure o Hermes:
hermes model
# Selecione "Custom endpoint (self-hosted / VLLM / etc.)"
# Informe a URL: http://localhost:8000/v1
# Pule a chave de API (ou informe uma, se você configurou o vLLM com --api-key)
# Informe o nome do modelo: meta-llama/Llama-3.1-70B-Instruct
Tamanho do contexto: por padrão, o vLLM lê o max_position_embeddings do modelo. Se isso passar da memória da sua GPU, ele dá erro e pede que você reduza o --max-model-len. Você também pode usar --max-model-len auto para achar automaticamente o máximo que cabe. Defina --gpu-memory-utilization 0.95 (padrão 0.9) para espremer mais contexto na VRAM.
A chamada de ferramentas exige flags explícitas:
| Flag | Para que serve |
|---|---|
--enable-auto-tool-choice | Obrigatória para tool_choice: "auto" (o padrão no Hermes) |
--tool-call-parser <nome> | Parser para o formato de chamada de ferramenta do modelo |
Parsers suportados: hermes (Qwen 2.5, Hermes 2/3), llama3_json (Llama 3.x), mistral, deepseek_v3, deepseek_v31, xlam, pythonic. Sem essas flags, as chamadas de ferramenta não funcionam — o modelo vai imprimir as chamadas como texto.
Parsers de raciocínio do Qwen: o Hermes preserva metadados estruturados de raciocínio, como reasoning, reasoning_content e deltas de raciocínio em streaming, quando servidores compatíveis com a OpenAI os devolvem. Esses metadados são tratados como traço de raciocínio/pensamento, não como substituto da resposta visível do assistente. Para modelos de raciocínio Qwen servidos pelo vLLM, garanta que a resposta final visível ao usuário continue aparecendo em content. Se o --reasoning-parser qwen3 deixar o content vazio na sua implantação, desligue esse parser ou passe uma opção de pedido suportada pelo servidor, como chat_template_kwargs.enable_thinking: false, pelo extra_body.
O vLLM aceita tamanhos legíveis por humanos: --max-model-len 64k (k minúsculo = 1000, K maiúsculo = 1024).
SGLang — serviço rápido com RadixAttention
O SGLang é uma alternativa ao vLLM, com RadixAttention para reaproveitar o cache KV. Melhor para: conversas de vários turnos (cache de prefixo), decodificação restrita, saída estruturada.
pip install "sglang[all]"
python -m sglang.launch_server \
--model meta-llama/Llama-3.1-70B-Instruct \
--port 30000 \
--context-length 65536 \
--tp 2 \
--tool-call-parser qwen
Depois configure o Hermes:
hermes model
# Selecione "Custom endpoint (self-hosted / VLLM / etc.)"
# Informe a URL: http://localhost:30000/v1
# Informe o nome do modelo: meta-llama/Llama-3.1-70B-Instruct
Tamanho do contexto: por padrão, o SGLang lê da configuração do modelo. Use --context-length para sobrescrever. Se você precisa passar do máximo declarado do modelo, defina SGLANG_ALLOW_OVERWRITE_LONGER_CONTEXT_LEN=1.
Chamada de ferramentas: use --tool-call-parser com o parser adequado à família do seu modelo: qwen (Qwen 2.5), llama3, llama4, deepseekv3, mistral, glm. Sem essa flag, as chamadas de ferramenta voltam como texto puro.
Se as respostas parecerem truncadas, acrescente max_tokens aos seus pedidos ou defina --default-max-tokens no servidor. O padrão do SGLang é de apenas 128 tokens por resposta, quando nada é especificado no pedido.
llama.cpp / llama-server — inferência em CPU e Metal
O llama.cpp roda modelos quantizados em CPU, Apple Silicon (Metal) e GPUs de consumidor. Melhor para: rodar modelos sem uma GPU de datacenter, usuários de Mac, implantação na borda.
# Compile e suba o llama-server
cmake -B build && cmake --build build --config Release
./build/bin/llama-server \
--jinja -fa \
-c 64000 \
-ngl 99 \
-m models/qwen2.5-coder-32b-instruct-Q4_K_M.gguf \
--port 8080 --host 0.0.0.0
Tamanho do contexto (-c): as versões recentes usam 0 por padrão, o que lê o contexto de treino do modelo dos metadados do GGUF. Em modelos com 128k ou mais de contexto de treino, isso pode estourar a memória ao tentar alocar o cache KV completo. Defina -c explicitamente com pelo menos 64.000 tokens para o Hermes. Se você usar slots paralelos (-np), o contexto total é dividido entre os slots — com -c 64000 -np 4, cada slot fica com só 16k, abaixo do mínimo do Hermes por sessão ativa.
Depois configure o Hermes para apontar para ele:
hermes model
# Selecione "Custom endpoint (self-hosted / VLLM / etc.)"
# Informe a URL: http://localhost:8080/v1
# Pule a chave de API (servidores locais não precisam de uma)
# Informe o nome do modelo — ou deixe em branco para detectar automaticamente, se só um modelo estiver carregado
Isso salva o endpoint no config.yaml, então ele persiste entre sessões.
--jinja é obrigatório para chamada de ferramentasSem o --jinja, o llama-server ignora o parâmetro tools por completo. O modelo vai tentar chamar ferramentas escrevendo JSON no texto da resposta, mas o Hermes não vai reconhecer isso como chamada de ferramenta — você verá um JSON cru, como {"name": "web_search", ...}, impresso como mensagem em vez de uma busca de verdade.
Suporte nativo a chamada de ferramentas (melhor desempenho): Llama 3.x, Qwen 2.5 (inclusive Coder), Hermes 2/3, Mistral, DeepSeek, Functionary. Todos os outros modelos usam um handler genérico que funciona, mas pode ser menos eficiente. Veja a documentação de function calling do llama.cpp para a lista completa.
Você pode verificar se o suporte a ferramentas está ativo consultando http://localhost:8080/props — o campo chat_template deve estar presente.
Baixe modelos GGUF no Hugging Face. A quantização Q4_K_M oferece o melhor equilíbrio entre qualidade e uso de memória.
LM Studio — aplicativo de desktop com modelos locais
O LM Studio é um aplicativo de desktop para rodar modelos locais com interface gráfica. Melhor para: quem prefere uma interface visual, teste rápido de modelos, quem desenvolve em macOS/Windows/Linux.
Suba o servidor pelo aplicativo do LM Studio (aba Developer → Start Server), ou use a CLI:
lms server start # Sobe na porta 1234
lms load qwen2.5-coder --context-length 64000
Depois configure o Hermes:
hermes model
# Selecione "LM Studio"
# Pressione Enter para usar http://localhost:1234/v1
# Escolha um dos modelos descobertos
# Se a autenticação do servidor do LM Studio estiver habilitada, informe a LM_API_KEY quando for pedida
O Hermes preserva o contexto de uma instância do LM Studio já carregada. Para um modelo não carregado no modo explícito padrão, o Hermes omite o context_length, a menos que você tenha configurado um no Hermes, para o LM Studio poder aplicar o ajuste do próprio modelo. Depois disso, o Hermes usa apenas o tamanho de contexto que o LM Studio reporta após o carregamento.
Para mudar o tamanho do contexto no LM Studio:
- Clique no ícone de engrenagem ao lado do seletor de modelo
- Defina o "Context Length" com pelo menos 64000, para uma experiência tranquila
- Recarregue o modelo para a mudança valer
- Se a sua máquina não comporta 64000, considere usar um modelo menor com tamanhos de contexto maiores.
Como alternativa, use a CLI: lms load nome-do-modelo --context-length 64000
Você pode usar a CLI para estimar se o modelo vai caber: lms load nome-do-modelo --context-length 64000 --estimate-only
Para definir padrões persistentes por modelo: aba My Models → ícone de engrenagem no modelo → defina o tamanho do contexto. :::
Se você usa o carregamento sob demanda / Auto-Evict do LM Studio e quer que ele administre o carregamento e a remoção de modelos a partir dos pedidos normais de chat, pule o passo de pré-carregamento explícito do Hermes:
hermes config set model.lmstudio_load_mode jit
Volte ao comportamento padrão de pré-carregamento explícito com:
hermes config set model.lmstudio_load_mode explicit
Chamada de ferramentas: suportada desde o LM Studio 0.3.6. Modelos com treinamento nativo de chamada de ferramentas (Qwen 2.5, Llama 3.x, Mistral, Hermes) são detectados automaticamente e exibidos com um selo de ferramenta. Outros modelos usam um recuo genérico que pode ser menos confiável.
Rede no WSL2 (usuários de Windows)
Como o Hermes Agent exige um ambiente Unix, usuários de Windows o rodam dentro do WSL2. Se o seu servidor de modelo (Ollama, LM Studio etc.) roda no hospedeiro Windows, você precisa fazer a ponte de rede — o WSL2 usa um adaptador de rede virtual com sub-rede própria, então o localhost dentro do WSL2 se refere à VM Linux, não ao hospedeiro Windows.
Se o seu servidor de modelo também roda dentro do WSL2 (comum com vLLM, SGLang e llama-server), o localhost funciona como esperado — eles compartilham o mesmo espaço de nomes de rede. Pule esta seção.
Opção 1: modo de rede espelhada (recomendado)
Disponível no Windows 11 22H2+, o modo espelhado faz o localhost funcionar nos dois sentidos entre o Windows e o WSL2 — a solução mais simples.
-
Crie ou edite o
%USERPROFILE%\.wslconfig(por exemplo,C:\Users\SeuNome\.wslconfig):[wsl2]networkingMode=mirrored -
Reinicie o WSL pelo PowerShell:
wsl --shutdown -
Reabra o seu terminal do WSL2. O
localhostagora alcança os serviços do Windows:curl http://localhost:11434/v1/models # Ollama no Windows — funciona
Em algumas versões do Windows 11, o firewall do Hyper-V bloqueia conexões espelhadas por padrão. Se o localhost ainda não funcionar depois de habilitar o modo espelhado, rode isto em um PowerShell como administrador:
Set-NetFirewallHyperVVMSetting -Name '{40E0AC32-46A5-438A-A0B2-2B479E8F2E90}' -DefaultInboundAction Allow
Opção 2: use o IP do hospedeiro Windows (Windows 10 / versões antigas)
Se você não pode usar o modo espelhado, descubra o IP do hospedeiro Windows de dentro do WSL2 e use-o no lugar do localhost:
# Pegue o IP do hospedeiro Windows (o gateway padrão da rede virtual do WSL2)
ip route show | grep -i default | awk '{ print $3 }'
# Exemplo de saída: 172.29.192.1
Use esse IP na sua configuração do Hermes:
model:
default: qwen2.5-coder:32b
provider: custom
base_url: http://172.29.192.1:11434/v1 # IP do hospedeiro Windows, não localhost
O IP do hospedeiro pode mudar quando o WSL2 reinicia. Você pode pegá-lo dinamicamente no seu shell:
export WSL_HOST=$(ip route show | grep -i default | awk '{ print $3 }')
echo "Hospedeiro Windows em: $WSL_HOST"
curl http://$WSL_HOST:11434/v1/models # Testa o Ollama
Ou use o nome mDNS da sua máquina (exige libnss-mdns no WSL2):
sudo apt install libnss-mdns
curl http://$(hostname).local:11434/v1/models
Endereço de escuta do servidor (obrigatório no modo NAT)
Se você está usando a Opção 2 (modo NAT com o IP do hospedeiro), o servidor de modelo no Windows precisa aceitar conexões de fora do 127.0.0.1. Por padrão, a maioria dos servidores só escuta no localhost — no modo NAT, as conexões do WSL2 vêm de uma sub-rede virtual diferente e serão recusadas. No modo espelhado, o localhost é mapeado diretamente, então a escuta padrão em 127.0.0.1 funciona bem.
| Servidor | Escuta padrão | Como resolver |
|---|---|---|
| Ollama | 127.0.0.1 | Defina a variável de ambiente OLLAMA_HOST=0.0.0.0 antes de subir o Ollama (Configurações do Sistema → Variáveis de Ambiente no Windows, ou edite o serviço do Ollama) |
| LM Studio | 127.0.0.1 | Habilite "Serve on Network" na aba Developer → configurações do servidor |
| llama-server | 127.0.0.1 | Acrescente --host 0.0.0.0 ao comando de inicialização |
| vLLM | 0.0.0.0 | Já escuta em todas as interfaces por padrão |
| SGLang | 127.0.0.1 | Acrescente --host 0.0.0.0 ao comando de inicialização |
Ollama no Windows (detalhado): o Ollama roda como serviço do Windows. Para definir o OLLAMA_HOST:
- Abra Propriedades do Sistema → Variáveis de Ambiente
- Acrescente uma nova variável do sistema:
OLLAMA_HOST=0.0.0.0 - Reinicie o serviço do Ollama (ou reinicie a máquina)
Firewall do Windows
O Firewall do Windows trata o WSL2 como uma rede separada (tanto no modo NAT quanto no espelhado). Se as conexões continuarem falhando depois dos passos acima, adicione uma regra de firewall para a porta do seu servidor de modelo:
# Rode em um PowerShell como administrador — troque PORT pela porta do seu servidor
New-NetFirewallRule -DisplayName "Allow WSL2 to Model Server" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 11434
Portas comuns: Ollama 11434, vLLM 8000, SGLang 30000, llama-server 8080, LM Studio 1234.
Verificação rápida
De dentro do WSL2, teste se você alcança o seu servidor de modelo:
# Troque a URL pelo endereço e porta do seu servidor
curl http://localhost:11434/v1/models # Modo espelhado
curl http://172.29.192.1:11434/v1/models # Modo NAT (use o IP real do seu hospedeiro)
Se você receber uma resposta JSON listando os seus modelos, está tudo certo. Use essa mesma URL como base_url na sua configuração do Hermes.
Solução de problemas de modelos locais
Estes problemas afetam todos os servidores locais de inferência usados com o Hermes.
"Connection refused" do WSL2 para um servidor de modelo hospedado no Windows
Se você roda o Hermes dentro do WSL2 e o seu servidor de modelo no hospedeiro Windows, o http://localhost:<porta> não funciona no modo NAT padrão de rede do WSL2. Veja Rede no WSL2 acima para a solução.
As chamadas de ferramenta aparecem como texto em vez de executar
O modelo imprime algo como {"name": "web_search", "arguments": {...}} como mensagem, em vez de chamar a ferramenta de verdade.
Causa: o seu servidor não está com chamada de ferramentas habilitada, ou o modelo não a suporta pela implementação de chamada de ferramentas do servidor.
| Servidor | Solução |
|---|---|
| llama.cpp | Acrescente --jinja ao comando de inicialização |
| vLLM | Acrescente --enable-auto-tool-choice --tool-call-parser hermes |
| SGLang | Acrescente --tool-call-parser qwen (ou o parser adequado) |
| Ollama | A chamada de ferramentas vem habilitada por padrão — confirme que o seu modelo a suporta (confira com ollama show nome-do-modelo) |
| LM Studio | Atualize para a 0.3.6 ou superior e use um modelo com suporte nativo a ferramentas |
O modelo parece esquecer o contexto ou dá respostas incoerentes
Causa: a janela de contexto é pequena demais. Quando a conversa passa do limite de contexto, a maioria dos servidores descarta silenciosamente as mensagens mais antigas. Só o prompt de sistema + os esquemas de ferramentas do Hermes já podem consumir de 4k a 8k tokens.
Diagnóstico:
# Veja qual contexto o Hermes acha que tem
# Olhe a linha de inicialização: "Context limit: X tokens"
# Veja o contexto real do seu servidor
# Ollama: ollama ps (coluna CONTEXT)
# llama.cpp: curl http://localhost:8080/props | jq '.default_generation_settings.n_ctx'
# vLLM: confira o --max-model-len nos argumentos de inicialização
Solução: defina o contexto com pelo menos 64.000 tokens para uso como agente. Veja a seção de cada servidor acima para a flag específica.
"Context limit: 2048 tokens" na inicialização
O Hermes detecta automaticamente o tamanho do contexto pelo endpoint /v1/models do seu servidor. Se o servidor reporta um valor baixo (ou não reporta nada), o Hermes usa o limite declarado do modelo, que pode estar errado.
Solução: defina explicitamente no config.yaml:
model:
default: seu-modelo
provider: custom
base_url: http://localhost:11434/v1
context_length: 64000
As respostas são cortadas no meio da frase
Causas possíveis:
- Teto baixo de saída (
max_tokens) no servidor — o SGLang usa 128 tokens por resposta por padrão. Defina--default-max-tokensno servidor ou configure o Hermes commodel.max_tokensno config.yaml. Atenção: omax_tokenscontrola só o tamanho da resposta — não tem relação com o tamanho que o seu histórico de conversa pode ter (isso é ocontext_length). - Esgotamento do contexto — o modelo encheu a janela de contexto. Aumente o
model.context_lengthou habilite a compressão de contexto no Hermes.
Proxy LiteLLM — gateway multiprovedor
O LiteLLM é um proxy compatível com a OpenAI que unifica mais de 100 provedores de LLM atrás de uma única API. Melhor para: alternar entre provedores sem mudanças de configuração, balanceamento de carga, cadeias de recuo, controle de orçamento.
# Instale e suba
pip install "litellm[proxy]"
litellm --model anthropic/claude-sonnet-4 --port 4000
# Ou com um arquivo de configuração, para vários modelos:
litellm --config litellm_config.yaml --port 4000
Depois configure o Hermes com hermes model → Custom endpoint → http://localhost:4000/v1.
Exemplo de litellm_config.yaml com recuo:
model_list:
- model_name: "best"
litellm_params:
model: anthropic/claude-sonnet-4
api_key: sk-ant-...
- model_name: "best"
litellm_params:
model: openai/gpt-4o
api_key: sk-...
router_settings:
routing_strategy: "latency-based-routing"
ClawRouter — roteamento otimizado por custo
O ClawRouter, da BlockRunAI, é um proxy local de roteamento que escolhe modelos automaticamente conforme a complexidade da pergunta. Ele classifica os pedidos em 14 dimensões e roteia para o modelo mais barato capaz de dar conta da tarefa. O pagamento é em criptomoeda USDC (sem chaves de API).
# Instale e suba
npx @blockrun/clawrouter # Sobe na porta 8402
Depois configure o Hermes com hermes model → Custom endpoint → http://localhost:8402/v1 → nome do modelo blockrun/auto.
Perfis de roteamento:
| Perfil | Estratégia | Economia |
|---|---|---|
blockrun/auto | Equilíbrio entre qualidade e custo | 74-100% |
blockrun/eco | O mais barato possível | 95-100% |
blockrun/premium | Os modelos de melhor qualidade | 0% |
blockrun/free | Só modelos gratuitos | 100% |
blockrun/agentic | Otimizado para uso de ferramentas | varia |
O ClawRouter exige uma carteira com fundos em USDC na Base ou na Solana para pagamento. Todos os pedidos passam pela API de backend da BlockRun. Rode npx @blockrun/clawrouter doctor para conferir o estado da carteira.
Outros provedores compatíveis
Qualquer serviço com API compatível com a da OpenAI funciona. Algumas opções populares:
| Provedor | URL base | Observações |
|---|---|---|
| Together AI | https://api.together.xyz/v1 | Modelos abertos hospedados na nuvem |
| Groq | https://api.groq.com/openai/v1 | Inferência ultrarrápida |
| DeepSeek | https://api.deepseek.com/v1 | Modelos DeepSeek |
| Fireworks AI | https://api.fireworks.ai/inference/v1 | Hospedagem rápida de modelos abertos |
| GMI Cloud | https://api.gmi-serving.com/v1 | Inferência gerenciada compatível com a OpenAI |
| Actual Computer | https://api.actual.inc/v1 | Relay privado para o seu próprio cluster; daemon local em http://127.0.0.1:8080/v1 |
| Cerebras | https://api.cerebras.ai/v1 | Inferência em chip de escala de bolacha |
| Mistral AI | https://api.mistral.ai/v1 | Modelos Mistral |
| OpenAI | https://api.openai.com/v1 | Acesso direto à OpenAI |
| Azure OpenAI | https://YOUR.openai.azure.com/ | OpenAI corporativa |
| LocalAI | http://localhost:8080/v1 | Auto-hospedado, multimodelo |
| Jan | http://localhost:1337/v1 | Aplicativo de desktop com modelos locais |
Configure qualquer um deles com hermes model → Custom endpoint, ou no config.yaml:
model:
default: meta-llama/Llama-3.1-70B-Instruct-Turbo
provider: custom
base_url: https://api.together.xyz/v1
api_key: sua-chave-together
Detecção do tamanho do contexto
O context_length é a janela total de contexto — o orçamento combinado de tokens de entrada e de saída (por exemplo, 200.000 no Claude Opus 4.6). O Hermes usa isso para decidir quando comprimir o histórico e para validar os pedidos à API.
O model.max_tokens é o teto de saída — o número máximo de tokens que o modelo pode gerar em uma única resposta. Não tem nada a ver com o tamanho que o seu histórico de conversa pode ter. O nome padrão do setor, max_tokens, é uma fonte comum de confusão; a API nativa da Anthropic já o renomeou para max_output_tokens, para ficar claro.
Defina o context_length quando a detecção automática errar o tamanho da janela.
Defina o model.max_tokens só quando você precisar limitar o tamanho das respostas individuais.
O Hermes usa uma cadeia de resolução com várias fontes para detectar a janela de contexto correta do seu modelo e provedor:
- Sobrescrita na configuração —
model.context_lengthno config.yaml (maior prioridade) - Provedor personalizado, por modelo —
providers.<nome>.models.<id>.context_length - Cache persistente — valores descobertos antes (sobrevive a reinícios)
/modelsdo endpoint — consulta a API do seu servidor (endpoints locais/personalizados)/v1/modelsda Anthropic — consulta a API da Anthropic pelomax_input_tokens(só para quem usa chave de API)- API do OpenRouter — metadados de modelo ao vivo do OpenRouter
- Nous Portal — casa por sufixo os IDs de modelo da Nous com os metadados do OpenRouter
- models.dev — registro mantido pela comunidade, com tamanhos de contexto por provedor para mais de 3800 modelos em mais de 100 provedores
- Padrões de recuo — padrões amplos por família de modelo (128K por padrão)
Na maioria das configurações, isso funciona sem ajuste. O sistema leva o provedor em conta — o mesmo modelo pode ter limites de contexto diferentes conforme quem o serve (por exemplo, o claude-opus-4.6 tem 1M direto na Anthropic, mas 128K no GitHub Copilot).
Para definir o tamanho do contexto explicitamente, acrescente context_length à configuração do seu modelo:
model:
default: "qwen3.5:9b"
base_url: "http://localhost:8080/v1"
context_length: 131072 # tokens
Em endpoints personalizados, você também pode definir o tamanho do contexto por modelo:
providers:
my-local-llm:
api: "http://localhost:11434/v1"
models:
qwen3.5:27b:
context_length: 64000
deepseek-r1:70b:
context_length: 65536
O hermes model pergunta o tamanho do contexto ao configurar um endpoint personalizado. Deixe em branco para detecção automática.
- Você usa o Ollama com um
num_ctxpersonalizado menor que o máximo do modelo - Você quer limitar o contexto abaixo do máximo do modelo (por exemplo, 8k em um modelo de 128k, para economizar VRAM)
- Você roda atrás de um proxy que não expõe
/v1/models
Provedores personalizados nomeados
Se você trabalha com vários endpoints personalizados (por exemplo, um servidor local de desenvolvimento e um servidor de GPU remoto), pode defini-los como provedores personalizados nomeados no dicionário providers: do config.yaml, indexados pelo nome do provedor:
providers:
local:
api: http://localhost:8080/v1
# api_key omitido — o Hermes usa "no-key-required" em servidores locais sem chave
work:
api: https://gpu-server.internal.corp/v1
key_env: CORP_API_KEY
transport: chat_completions # definido explicitamente pelo assistente `hermes model` → Custom Endpoint; a detecção automática continua como recuo
anthropic-proxy:
api: https://proxy.example.com/anthropic
key_env: ANTHROPIC_PROXY_KEY
transport: anthropic_messages # para proxies compatíveis com a Anthropic
Cada entrada aceita: api (a URL base do endpoint — base_url/url são apelidos aceitos), name (nome de exibição opcional; por padrão, a chave do dicionário), key_env ou api_key inline ou key_cmd (veja abaixo), transport (chat_completions / anthropic_messages / codex_responses), default_model, models, context_length, discover_models, extra_body, extra_headers, ssl_ca_cert / ssl_verify e enabled: false, para esconder uma entrada sem apagá-la.
Credenciais cunhadas por comando (key_cmd)
Gateways corporativos costumam emitir bearer tokens de curta duração (intermediários SSO/OIDC, IAM de nuvem, proxies internos de autenticação) em vez de chaves de API estáticas, então um token copiado para o .env envelhece no meio da sessão e os pedidos começam a devolver 401. O key_cmd nomeia um comando que imprime um token; o Hermes o roda e guarda o resultado em cache até pouco antes da expiração, então sessões longas continuam funcionando sem reiniciar:
providers:
my-gateway:
base_url: "https://gateway.internal.example.com/v1"
api_mode: chat_completions
key_cmd: "my-auth-cli print-token --profile prod"
Funciona com qualquer auxiliar que imprima um token — databricks auth token, gcloud auth print-access-token, az account get-access-token, vault read ou scripts no estilo apiKeyHelper do Claude Code.
O comando precisa imprimir apenas o token na saída padrão: seja puro, seja como JSON com um campo access_token (o expires_in é respeitado; carimbos ISO absolutos de expiry/expiresOn também). Saída de várias linhas é rejeitada, não adivinhada. Se nenhuma expiração for anunciada, o token é recunhado em uma janela limitada.
Precedência: uma flag --api-key explícita ainda vence; caso contrário, o key_cmd ganha de um api_key/key_env estático na mesma entrada. A credencial cunhada vale tanto para o turno principal do agente quanto para as tarefas auxiliares (geração de título, compressão, visão, embedding).
Não confunda com secrets.command, que roda um auxiliar uma vez na inicialização para preencher variáveis de ambiente em todo o processo. Use aquele para um auxiliar de cofre/chaveiro que devolve muitos segredos; use o key_cmd quando a credencial de um provedor precisa ser recunhada durante uma sessão.
Configurações mais antigas usavam uma lista custom_providers: de nível superior. Ela ainda funciona — o Hermes lê as duas — e o hermes update a migra automaticamente para o dicionário providers: (configuração v12). Os nomes de campo diferem um pouco no formato de dicionário: o model legado virou default_model, e o api_mode legado virou transport.
Alguns endpoints compatíveis com a OpenAI precisam de campos específicos no corpo do pedido. Acrescente um mapa extra_body ao provedor personalizado correspondente e o Hermes vai mesclá-lo em cada pedido de chat-completions daquele endpoint:
providers:
gemma-local:
api: http://localhost:8080/v1
default_model: google/gemma-4-31b-it
extra_body:
enable_thinking: true
reasoning_effort: high
Use o formato que o seu servidor documenta. Por exemplo, implantações de Gemma no vLLM e alguns endpoints NIM da NVIDIA esperam o enable_thinking dentro de chat_template_kwargs, em vez de como campo de nível superior do extra_body:
extra_body:
chat_template_kwargs:
enable_thinking: true
Para modelos de raciocínio Qwen servidos pelo vLLM, esse mesmo formato pode ser usado para desligar o pensamento quando um parser de raciocínio separa todo o texto gerado em campos de raciocínio e deixa o content do assistente vazio:
extra_body:
chat_template_kwargs:
enable_thinking: false
O assistente hermes model → Custom Endpoint agora pergunta o modo de API explicitamente e persiste a sua resposta no config.yaml (como transport na entrada do provedor). A detecção automática pela URL (por exemplo, caminhos /anthropic → anthropic_messages) continua como recuo quando o campo é deixado em branco.
Visão nativa em modelos de provedor personalizado. Se o seu endpoint personalizado serve um modelo com capacidade de visão que não está no models.dev, defina model.supports_vision: true para o Hermes rotear as imagens anexadas de forma nativa (como partes image_url), em vez de pré-processá-las pelo vision_analyze. Um botão só — não é preciso definir também agent.image_input_mode: native.
model:
provider: custom
base_url: http://localhost:8080/v1
default: qwen3.6-35b-a3b
supports_vision: true # envia as imagens nativamente; caso contrário, o vision_analyze as descreve antes
A mesma chave é respeitada em modelos de provedores nomeados (providers.<nome>.models.<id>.supports_vision) e aceita os booleanos padrão do YAML (true/false/yes/no/on/off/1/0).
Alterne entre eles no meio da sessão com a sintaxe tripla:
/model custom:local:qwen-2.5 # Usa o endpoint "local" com o qwen-2.5
/model custom:work:llama3-70b # Usa o endpoint "work" com o llama3-70b
/model custom:anthropic-proxy:claude-sonnet-4 # Usa o proxy
Você também pode selecionar provedores personalizados nomeados pelo menu interativo do hermes model.
Livro de receitas: Together AI, Groq, Perplexity
Os provedores de nuvem listados em Outros provedores compatíveis falam o dialeto REST da OpenAI, então todos se configuram do mesmo jeito no dicionário providers:. Seguem três receitas prontas. Cada uma entra no ~/.hermes/config.yaml, e a chave de API correspondente vai no ~/.hermes/.env.
Together AI
Hospeda modelos de pesos abertos (Llama, MiniMax, Gemma, DeepSeek, Qwen) a preços bem abaixo das APIs de primeira parte. Bom padrão para frotas de vários modelos.
# ~/.hermes/config.yaml
providers:
together:
api: https://api.together.xyz/v1
key_env: TOGETHER_API_KEY
# transport: chat_completions # padrão — não precisa definir
model:
default: MiniMaxAI/MiniMax-M2.7 # ou qualquer modelo de together.ai/models
provider: custom:together
# ~/.hermes/.env
TOGETHER_API_KEY=sua-chave-together
Troque de modelo no meio da sessão:
/model custom:together:meta-llama/Llama-3.3-70B-Instruct-Turbo
/model custom:together:google/gemma-4-31b-it
/model custom:together:deepseek-ai/DeepSeek-V3
O endpoint /v1/models da Together funciona, então o hermes model consegue descobrir automaticamente os modelos disponíveis.
Groq
Inferência ultrarrápida (cerca de 500 tok/s no Llama-3.3-70B). Catálogo pequeno, mas forte para uso interativo sensível à latência.
# ~/.hermes/config.yaml
providers:
groq:
api: https://api.groq.com/openai/v1
key_env: GROQ_API_KEY
model:
default: llama-3.3-70b-versatile
provider: custom:groq
# ~/.hermes/.env
GROQ_API_KEY=sua-chave-groq
Perplexity
Útil quando você quer um modelo que faz busca na web ao vivo e cita fontes automaticamente. É rigoroso quanto aos modelos disponíveis — confira perplexity.ai/settings/api para a lista atual.
# ~/.hermes/config.yaml
providers:
perplexity:
api: https://api.perplexity.ai
key_env: PERPLEXITY_API_KEY
model:
default: sonar
provider: custom:perplexity
# ~/.hermes/.env
PERPLEXITY_API_KEY=sua-chave-perplexity
Vários provedores em uma configuração
As três receitas se combinam — use todas juntas e troque por turno com /model custom:<nome>:<modelo>:
providers:
together:
api: https://api.together.xyz/v1
key_env: TOGETHER_API_KEY
groq:
api: https://api.groq.com/openai/v1
key_env: GROQ_API_KEY
perplexity:
api: https://api.perplexity.ai
key_env: PERPLEXITY_API_KEY
model:
default: MiniMaxAI/MiniMax-M2.7
provider: custom:together # inicia na Together; troque à vontade depois
- O
hermes doctornão deve imprimir nenhum aviso deUnknown providerpara nenhum desses nomes, depois das correções no validador da CLI em #15083. - Se o endpoint
/v1/modelsde um provedor estiver inacessível (a Perplexity é o caso comum), ohermes modelpersiste o modelo com um aviso, em vez de rejeitar de vez — veja #15136. - Para pular os provedores nomeados por completo e usar o
provider: custompuro com a variável de ambienteCUSTOM_BASE_URL, veja #15103.
Escolhendo a configuração certa
| Caso de uso | Recomendado |
|---|---|
| Só quero que funcione | OpenRouter (padrão) ou Nous Portal |
| Modelos locais, configuração fácil | Ollama |
| Servir em GPU em produção | vLLM ou SGLang |
| Mac / sem GPU | Ollama ou llama.cpp |
| Roteamento multiprovedor | Proxy LiteLLM ou OpenRouter |
| Otimização de custo | ClawRouter ou OpenRouter com sort: "price" |
| Privacidade máxima | Ollama, vLLM ou llama.cpp (totalmente local) |
| Corporativo / Azure | Azure OpenAI com endpoint personalizado |
| Modelos de IA chineses | z.ai (GLM), Kimi/Moonshot (kimi-coding ou kimi-coding-cn), MiniMax, Xiaomi MiMo ou Tencent TokenHub (provedores de primeira classe) |
Você pode trocar de provedor a qualquer momento com hermes model — sem precisar reiniciar. O seu histórico de conversa, a memória e as skills seguem com você, independente do provedor que usar.
Chaves de API opcionais
| Recurso | Provedor | Variável de ambiente |
|---|---|---|
| Raspagem web | Firecrawl | FIRECRAWL_API_KEY, FIRECRAWL_API_URL |
| Automação de navegador | Browserbase | BROWSERBASE_API_KEY, BROWSERBASE_PROJECT_ID |
| Geração de imagem | FAL | FAL_KEY |
| Vozes premium de TTS | ElevenLabs | ELEVENLABS_API_KEY |
| TTS da OpenAI + transcrição de voz | OpenAI | VOICE_TOOLS_OPENAI_KEY |
| TTS da Mistral + transcrição de voz | Mistral | MISTRAL_API_KEY |
| Modelagem de usuário entre sessões | Honcho | HONCHO_API_KEY |
| Memória semântica de longo prazo | Supermemory | SUPERMEMORY_API_KEY |
Auto-hospedar o Firecrawl
Por padrão, o Hermes usa a API na nuvem do Firecrawl para busca e raspagem web. Se você prefere rodar o Firecrawl localmente, pode apontar o Hermes para uma instância auto-hospedada. Veja o SELF_HOST.md do Firecrawl para as instruções completas de configuração.
O que você ganha: nenhuma chave de API necessária, nenhum limite de taxa, nenhum custo por página, soberania total dos dados.
O que você perde: a versão na nuvem usa o "Fire-engine" proprietário do Firecrawl para contornar proteções antibot avançadas (Cloudflare, CAPTCHAs, rodízio de IP). A versão auto-hospedada usa fetch básico + Playwright, então alguns sites protegidos podem falhar. A busca usa o DuckDuckGo em vez do Google.
Configuração:
-
Clone e suba a pilha Docker do Firecrawl (5 contêineres: API, Playwright, Redis, RabbitMQ, PostgreSQL — exige de 4 a 8 GB de RAM):
git clone https://github.com/firecrawl/firecrawlcd firecrawl# No .env, defina: USE_DB_AUTHENTICATION=false, HOST=0.0.0.0, PORT=3002docker compose up -d -
Aponte o Hermes para a sua instância (nenhuma chave de API necessária):
hermes config set FIRECRAWL_API_URL http://localhost:3002
Você também pode definir tanto FIRECRAWL_API_KEY quanto FIRECRAWL_API_URL, se a sua instância auto-hospedada tem autenticação habilitada.
Roteamento de provedores do OpenRouter
Ao usar o OpenRouter, você pode controlar como os pedidos são roteados entre os provedores. Acrescente uma seção provider_routing ao ~/.hermes/config.yaml:
provider_routing:
sort: "throughput" # "price" (padrão), "throughput" ou "latency"
# only: ["anthropic"] # Usar somente estes provedores
# ignore: ["deepinfra"] # Pular estes provedores
# order: ["anthropic", "google"] # Tentar os provedores nesta ordem
# require_parameters: true # Usar só provedores que suportam todos os parâmetros do pedido
# data_collection: "deny" # Excluir provedores que podem guardar/treinar com os dados
Atalhos: acrescente :nitro a qualquer nome de modelo para ordenar por vazão (por exemplo, anthropic/claude-sonnet-4:nitro), ou :floor para ordenar por preço.
Roteador Pareto Code do OpenRouter
O OpenRouter oferece um roteador experimental de modelos de programação em openrouter/pareto-code, que roteia automaticamente os pedidos para o modelo mais barato que atinge uma nota mínima de qualidade em código (ranqueada pela Artificial Analysis). Escolha esse modelo e ajuste o botão min_coding_score no ~/.hermes/config.yaml:
model:
provider: openrouter
model: openrouter/pareto-code
openrouter:
min_coding_score: 0.65 # 0.0–1.0; mais alto = programadores mais fortes (e mais caros). Padrão 0.65.
Observações:
- O
min_coding_scoreé enviado somente quandomodel.modeléopenrouter/pareto-code. Em qualquer outro modelo, o valor não faz nada. - Deixe como string vazia (ou remova a linha) para o OpenRouter escolher o programador mais forte disponível — é o comportamento documentado quando o bloco de plugins é omitido.
- A seleção é determinística por nota em um dado dia, mas o modelo escolhido de fato pode mudar conforme a fronteira de Pareto se move (novos modelos, atualizações de benchmark).
- Veja a documentação do Pareto Router do OpenRouter para o comportamento completo do roteador.
- Para usar o roteador Pareto Code em uma tarefa auxiliar específica (compressão, visão etc.) em vez do agente principal, defina
extra_body.pluginsnaquela tarefa — veja Modelos auxiliares → Roteamento do OpenRouter e Pareto Code em tarefas auxiliares.
Provedores de reserva
Configure uma cadeia de provedores de reserva que o Hermes tenta em ordem quando o modelo principal falha (limite de taxa, erros de servidor, falhas de autenticação). O formato canônico é uma lista fallback_providers: de nível superior:
fallback_providers:
- provider: openrouter
model: anthropic/claude-sonnet-4
- provider: anthropic
model: claude-sonnet-4
# base_url: http://localhost:8000/v1 # opcional, para endpoints personalizados
# api_mode: chat_completions # sobrescrita opcional
O dicionário legado fallback_model:, de par único, continua aceito por compatibilidade:
fallback_model:
provider: openrouter
model: anthropic/claude-sonnet-4
Quando ativado, o recuo troca o modelo e o provedor no meio da sessão, sem perder a sua conversa. A cadeia é tentada entrada por entrada; a ativação acontece uma vez por sessão.
Provedores suportados: openrouter, nous, novita, openai-codex, copilot, copilot-acp, anthropic, gemini, qwen-oauth, huggingface, zai, kimi-coding, kimi-coding-cn, minimax, minimax-cn, minimax-oauth, deepseek, nvidia, xai, xai-oauth, ollama-cloud, bedrock, ai-gateway, azure-foundry, opencode-zen, opencode-go, commandcode, commandcode-anthropic, kilocode, xiaomi, arcee, gmi, actual, stepfun, lmstudio, alibaba, alibaba-coding-plan, tencent-tokenhub, custom.
O recuo é configurado exclusivamente pelo config.yaml — ou de forma interativa, pelo hermes fallback. Para todos os detalhes sobre quando ele dispara, como a cadeia avança e como interage com tarefas auxiliares e delegação, veja Provedores de reserva.
Veja também
- Configuração — Configuração geral (estrutura de diretórios, precedência de configuração, backends de terminal, memória, compressão e mais)
- Variáveis de ambiente — Referência completa de todas as variáveis de ambiente