Início / Aprenda / Hermes Agent com Claude por meio de um gateway: configuração de provedor personalizado, controles de custo e correções
Hermes Agent. Uma mensagem de papel dobrado em forma de asa atravessando um pequeno arco de gateway em direção a um espaço de trabalho com código organizado, uma metáfora para o roteamento de agentes.

Hermes Agent com Claude por meio de um gateway: configuração de provedor personalizado, controles de custos e correções

O Hermes Agent mantém os segredos em ~/.hermes/.env e todo o restante em ~/.hermes/config.yaml. A maneira confiável de executá-lo com o Claude por meio de um gateway é usar um provedor personalizado nomeado que utilize o formato Anthropic Messages. O atalho, provider: anthropic com uma URL base diferente, parece correto, mas envia solicitações para a Anthropic quando o host não é reconhecido.

Instalação

Linux / macOS / WSL2
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
Windows
iex (irm https://hermes-agent.nousresearch.com/install.ps1)

hermes setup executa o assistente completo; hermes model configura apenas o provedor e o modelo; hermes doctor verifica uma instalação existente.

Adicione o gateway como provedor personalizado

~/.hermes/.env
AIPRIME_API_KEY=your_gateway_key
~/.hermes/config.yaml
providers:
  aiprime:
    api: https://aiprimetech.io/v1
    key_env: AIPRIME_API_KEY
    transport: anthropic_messages
    catalog_provider: anthropic

model:
  provider: custom:aiprime
  default: claude-sonnet-5
Chave Por quê
transport: anthropic_messagesUse o formato Messages da Anthropic. Sem isso, o Hermes passa a usar o formato Chat Completions da OpenAI
key_envO nome da variável em .env que contém a chave
catalog_provider: anthropicOs modelos Claude do gateway herdam os metadados de contexto e visão da Anthropic
provider: custom:aiprimeSeleciona o provedor nomeado; /model custom:aiprime:<model> alterna dentro de um chat

O assistente faz o mesmo: hermes model, depois **Endpoint personalizado** e, em seguida, o modo de API **Anthropic Messages**. Se escolher Chat Completions, mantenha /v1 na URL.

Por que provider: anthropic com uma URL base não funciona

Definir provider: anthropic e base_url: https://aiprimetech.io parece correto, mas não tem efeito: no código-fonte atual do Hermes, a substituição da URL base no provedor Anthropic integrado só é aceita para hosts da Anthropic, do Claude e do Azure, portanto as solicitações continuam sendo enviadas à Anthropic. Use o provedor personalizado nomeado acima.

ANTHROPIC_BASE_URL é documentado como uma substituição da URL base da Anthropic, mas um bug em aberto no Hermes faz com que o seletor de modelos o ignore. O provedor personalizado evita ambos os problemas.

O que determina o uso de tokens e quais configurações o limitam

O Hermes executa tarefas além da conversa que você vê, e todas elas são cobradas na mesma chave, a menos que você as encaminhe para outro destino.

Origem do uso Definir
Subagents (delegation)delegation.max_concurrent_children (padrão 10), delegation.max_iterations (padrão 250), delegation.max_spawn_depth (padrão 1); um mais barato delegation.model
Revisão de memória e habilidades em segundo plano após cada turnoauxiliary.background_review.enabled: false, ou um menor max_input_tokens
Tarefas auxiliares (compressão, títulos, visão)auxiliary.<task>.provider e .model para enviá-las a um modelo mais barato
Tarefas agendadascron.model para todas as tarefas; hermes cron pause <id> ou hermes pause
Gateway de mensagens (Telegram, Discord e outros)Listas de permissões como TELEGRAM_ALLOWED_USERS; evite GATEWAY_ALLOW_ALL_USERS=true
~/.hermes/config.yaml (adições)
delegation:
  max_concurrent_children: 3
  model: claude-haiku-4-5
auxiliary:
  background_review:
    enabled: false
cron:
  model: claude-haiku-4-5

hermes prompt-size mostra o custo fixo de cada chamada; /usage e /compress ajudam durante uma sessão longa.

Login no Claude Pro ou Max em vez de uma chave

O Hermes pode fazer login em uma conta Claude, mas sua documentação informa que essa opção funciona apenas em um plano Max com créditos de uso adicional comprados e que assinantes Pro não podem usá-la. Com uma chave de API de um gateway, não há janela de uso da assinatura; o uso é cobrado por token e descontado do seu saldo.

Modelos

ID do modelo Use para
claude-sonnet-5Padrão para programação e trabalho com agentes: rápido, eficiente e de preço intermediário.
claude-opus-5-5Raciocínio mais complexo, grandes refatorações e execuções longas de agentes.
claude-fable-5-1O mais capaz e mais caro; reserve-o para as tarefas mais difíceis.
claude-haiku-4-5Barato e rápido: títulos, resumos, classificação e pequenas etapas.

O Hermes precisa de uma janela de contexto de pelo menos 64K tokens; todos os modelos da tabela atendem a esse requisito.

Solução de problemas

O que você vê Causa Correção
HTTP 400 na primeira execuçãoO nome do modelo não corresponde a um ID de modelo do gatewayUse um ID da tabela acima
As solicitações são enviadas à Anthropic ou falham com um erro de autenticação da Anthropicprovider: anthropic com uma URL base de terceirosUse o provedor personalizado nomeado
Respostas sem sentido ou vaziasTransporte incorreto para a URLtransport: anthropic_messages para Claude
Limite de tamanho do contexto excedidoSessão maior que a janela configuradaDefina model.context_length; /compress
403 Your request was blockedUm firewall na frente do endpoint rejeita o clienteAdicionar extra_headers com um User-Agent semelhante ao de um navegador
Configurações ausentes após uma atualizaçãoO esquema de configuração mudouhermes config check, depois hermes config migrate
Bot sem responder no Telegram ou DiscordGateway não está em execução ou remetente não autorizadohermes gateway status; verifique ~/.hermes/logs/gateway.log

Comparando frameworks de agentes? Consulte o guia de configuração do OpenClaw.

Perguntas frequentes

Como usar o Hermes Agent com um endpoint personalizado do Claude?
Adicione um provedor nomeado em ~/.hermes/config.yaml com api definido como a URL do gateway, key_env apontando para uma variável em ~/.hermes/.env e transport: anthropic_messages; depois, defina model.provider: custom:<name>.
Por que o Hermes ignora meu base_url da Anthropic?
Com provider: anthropic, o Hermes aceita uma substituição da URL base apenas para hosts da Anthropic, Claude e Azure, portanto uma URL de terceiros é descartada. Use um provedor personalizado nomeado.
Como reduzir o uso de tokens do Hermes Agent?
Limite os subagentes (configurações de delegação), encaminhe tarefas auxiliares e tarefas cron para um modelo mais barato, desative a revisão em segundo plano e verifique hermes prompt-size.
O Hermes Agent pode usar uma assinatura Claude Pro?
Segundo a documentação do Hermes, não: o método de login do Claude funciona apenas no Max com créditos de uso extra. Uma chave de API evita por completo os limites da assinatura.
Comece a usar o Claude em minutos

Obtenha uma chave de API — sem precisar de conta na Anthropic nem de lista de espera.

Obtenha sua chave de API

AI Prime Tech é um gateway de API independente. Não tem afiliação com a Anthropic, não é endossado por ela e não é seu revendedor. Claude e os nomes dos modelos relacionados são marcas comerciais de seus respectivos proprietários.

Mais guias da API do Claude

Como obter uma chave de API do ClaudePreços da API Claude explicadosA maneira mais barata de usar a API do ClaudeCursor ilimitado com a API do ClaudeAcesso ilimitado ao Claude CodeGateway da API do Claude vs. acesso direto à AnthropicUse Claude com o SDK da OpenAI: endpoint compatível com OpenAI, streaming, ferramentas e limitesModelos Claude explicados: uma comparação entre Claude Opus, Sonnet, Haiku e Fable — todos os modelos da API Claude, nomes e preços dos modelos Anthropic (2026)Pagamento da API do Claude com criptomoedasAcesso à API do Claude sem lista de esperaComo reduzir o uso de tokens do ClaudeCline ilimitado com a API do ClaudeRoo Code ilimitado com a API do ClaudeClaude ilimitado nas IDEs da JetBrainsAider com Claude por meio de um gateway: ANTHROPIC_API_BASE, arquivos de configuração, modo arquiteto e correçõesClaude ilimitado no VS CodeConfiguração do OpenCode para Claude: configuração do opencode.json, modelos e erros comunsExecutando OpenClaw ilimitado com ClaudeO que significa uma API compatível com a AnthropicChave de API do Claude Code — ANTHROPIC_API_KEY: como obtê-la, configurá-la e quando usar claude setup-token em seu lugarCustos da API do Claude Code — Preços e como reduzi-losErros da API Claude explicados: erro de servidor 500, sobrecarga 529, limite de requisições 429, requisição inválida 400 — e a correção para cada umComo comprar créditos da API do Claude — e por que um crédito do Claude é melhor do que qualquer oferta de "comprar conta do Claude"API Claude gratuita: existe uma chave de API Claude gratuita e o que realmente é gratuito em 2026?API do Claude vs assinatura Claude Pro/Max — Qual escolherCodex CLI com um provedor personalizado: config.toml, modelos GPT e Claude, extensão para IDE e correçõesConectando Claude ao n8nRoteando LiteLLM para ClaudeUsando Claude no Kilo CodeGitHub Copilot Chat com Claude por meio de um gateway: configuração de Custom Endpoint, modo agente e correçõesConecte o Zed ao Claude por meio do gatewayConecte o Cherry Studio ao ClaudeChatAnthropic no LangChain: importação, base_url, streaming, ferramentas e errosSDK de Python da Anthropic: instale, defina base_url, use streaming e trate errosClaude com o Vercel AI SDK: baseURL de createAnthropic, streaming e correçõesExecute o Factory Droid com o ClaudeA API do Claude Code, explicadaComo integrar a API do Claude à sua aplicaçãoComo obter uso ilimitado do Claude — e por que não existe "Claude Code crackeado"