Hermes Agent

Um provedor nomeado em ~/.hermes/config.yaml — api https://api.kunavo.com, transport anthropic_messages, selecionado com provider: custom:kunavo — coloca o Hermes Agent no Claude pela interface Messages, na qual ele envia seus próprios marcadores de cache e limite de saída.

# ~/.hermes/config.yaml
providers:
  kunavo:
    api: https://api.kunavo.com        # origin — the Anthropic SDK adds /v1/messages
    key_env: KUNAVO_API_KEY            # the variable's NAME; the key goes in ~/.hermes/.env
    transport: anthropic_messages
    models:
      claude-sonnet-5:
        context_length: 1000000
        prompt_caching: true
      claude-haiku-4-5:
        context_length: 200000
        prompt_caching: true

model:
  default: claude-sonnet-5
  provider: custom:kunavo

Passo a passo

1. Crie uma chave em /app/keys e copie-a — ela é exibida uma única vez.
2. Armazene a chave onde o Hermes guarda segredos: hermes config set KUNAVO_API_KEY sk-kn-... grava-a em ~/.hermes/.env. A linha key_env no bloco indica o nome dessa variável; a chave em si nunca é gravada em config.yaml.
3. Adicione o bloco a ~/.hermes/config.yaml — o comando hermes config edit abre esse arquivo. Se já houver uma seção model:, substitua os valores de default e provider e mantenha o restante.
4. Ou deixe o assistente de configuração gravar tudo: execute hermes model em um terminal, fora de qualquer sessão de chat, escolha Custom endpoint (self-hosted / VLLM / etc.) e responda às solicitações — URL base da API, chave, nome do modelo, modo da API e tamanho do contexto.
5. Inicie hermes e leia o banner: ele mostra o modelo e a janela de contexto, que devem corresponder aos valores do bloco.
6. Envie duas mensagens e abra /usage para ver o que os turnos usaram. Para trocar de modelo durante uma sessão, use /model custom:kunavo:claude-opus-5-5.

Verificado em Página de provedores de IA do Hermes Agent em 5 de outubro de 2026. As configurações de terceiros podem mudar; se o nome de um campo aqui já não corresponder ao que você vê, aquela página é a autoridade, não esta.

Verifique antes de depurar o cliente

Uma solicitação determina se a falha está no endpoint, na chave ou no arquivo de configuração. Se isto retornar JSON, a mesma URL base e a mesma chave funcionarão em Hermes Agent.

# Settles whether a failure is the endpoint, the key, or the client.
curl -sS https://api.kunavo.com/v1/messages \
  -H "Authorization: Bearer sk-kn-..." \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":16,"messages":[{"role":"user","content":"ping"}]}'

Qual ID de modelo inserir no campo

Todo modelo de texto pode ser acessado como um ID de modelo — a lista atual está em GET /v1/models, e o catálogo com preços está na página de modelos. As tarifas são em USD por 1 milhão de tokens, entrada / saída.

A interface compatível com OpenAI

A mesma chave dá acesso a todas as outras famílias de modelos por meio de /v1/chat/completions, e, para isso, basta usar a forma mais curta documentada pelo Hermes — um bloco model: com provider: custom e base_url, que também é o que hermes model solicita:

# ~/.hermes/config.yaml — the bare form, for an OpenAI-compatible endpoint
model:
  default: gpt-6-sol
  provider: custom
  base_url: https://api.kunavo.com/v1    # this wire keeps /v1
  key_env: KUNAVO_API_KEY
  context_length: 1050000

A URL base mantém /v1, a forma usada na documentação do Hermes nos exemplos de servidor local, e context_length define a janela para que o Hermes não precise detectá-la. Para manter as duas conexões configuradas ao mesmo tempo, dê a esta uma entrada própria, com nome — transport: chat_completions — e alterne com /model custom:<name>:<model>.

Cache de prompts em cada interface

Na conexão Anthropic, o Hermes adiciona os marcadores de cache por conta própria. Para um provedor personalizado, a página de configuração de modelos documenta a opção usada no bloco acima — prompt_caching: true no modelo — e explica que a estrutura depende do transporte: blocos nativos em anthropic_messages e a estrutura de envelope na conexão compatível com OpenAI. O /v1/messages da Kunavo encaminha o corpo tal como foi enviado e não define nenhum ponto de quebra próprio; portanto, nesta conexão, os marcadores são fornecidos pelo Hermes ou não há marcadores.

A duração é o aspecto que a documentação do Hermes deixa em aberto para um endpoint personalizado. prompt_caching.cache_ttl — 5m, 1h ou auto — é descrito para o Claude pela API Anthropic nativa, pelo OpenRouter e pelo Nous Portal, mas nada é dito sobre outros endpoints. A Kunavo encaminha o marcador recebido e cobra a gravação pela mesma tarifa. Portanto, confira seus próprios dados de uso: se um turno iniciado após uma pausa de dez minutos ainda mostrar uma leitura do cache, isso indica que a entrada tinha duração de uma hora.

Na conexão compatível com OpenAI, a Kunavo define por conta própria os pontos de quebra para modelos Claude — no prompt do sistema, nas definições das ferramentas e no fim da conversa — assim que o prompt tiver tamanho suficiente para ser armazenado em cache, independentemente de o cliente enviar ou não um marcador. Os modelos GPT são armazenados implicitamente em cache pelo fornecedor.

Não importa qual lado insere os pontos de quebra, a cobrança é a mesma. Em Claude Sonnet 5 uma leitura de cache custa $0.14 por 1M tokens, contra $1.40 para entrada nova, e uma gravação de cache custa $1.75 — o adicional cobrado pelo Claude sobre a entrada, aplicado à mesma taxa quando a entrada solicita uma duração de uma hora. Uma entrada dura cinco minutos e cada leitura renova esse prazo; por isso, o valor pago por um agente depende menos do modelo do que de a próxima solicitação chegar dentro desse intervalo. As taxas de cache de todos os modelos estão na página de cache de prompts.

Um comportamento do Hermes custa mais do que qualquer tarifa: a documentação observa que uma troca de modelo no meio de uma sessão, um fallback automático ou a rotação de credenciais reinicia o cache de prompt. Assim, a mensagem seguinte relê toda a conversa ao preço integral de entrada. Escolha o modelo antes de iniciar uma sessão longa.

Quanto custa por dia manter um agente sempre ativo

No Hermes, o que gera cobranças enquanto ninguém digita é o que você agendou, além das tarefas auxiliares acionadas por cada conversa. A documentação de cron diz que cada execução agendada inicia uma nova sessão; por isso, o prompt completo — instruções, esquemas de ferramentas e habilidades anexadas — é cobrado toda vez que a tarefa é executada. O tamanho desse prompt depende da sua configuração; por isso, a tabela parte de uma hipótese declarada explicitamente: 20.000 tokens por execução e uma execução a cada 30 minutos, totalizando 48 execuções por dia. Substitua ambos os valores pelos seus.

Três configurações alteram esse valor, todas descritas na documentação do próprio Hermes. Uma tarefa agendada usa o modelo definido para ela; caso contrário, usa cron.model e, se essa opção não estiver definida, o modelo principal. Portanto, hermes config set cron.model claude-haiku-4-5 tira todas as tarefas sem modelo definido do nível mais caro. Um script de tarefa que imprime {"wakeAgent": false} pula o modelo nessa execução, e uma tarefa sem agente não chama nenhum modelo. Já as tarefas auxiliares — compactação, títulos e visão — usam o modelo principal, a menos que auxiliary as direcione para outro modelo:

# ~/.hermes/config.yaml — what decides the cost of an unattended day
compression:
  threshold_tokens: 256000         # compact here, not at half of a 1M window

auxiliary:
  compression:
    provider: kunavo               # the named entry above
    model: claude-haiku-4-5        # summaries on the cheapest tier
  title_generation:
    provider: kunavo
    model: claude-haiku-4-5

threshold_tokens é a configuração relevante para uma janela grande. Por padrão, a compactação começa na metade do comprimento do contexto, e a documentação do Hermes apresenta essa configuração como a forma de estabelecer um limite fixo para o custo de cada chamada.

As horas em que o agente está realmente trabalhando são a outra metade da conta, e é aí que o cache faz diferença. Faça 100 solicitações consecutivas, cada uma reenviando um contexto de 100.000 tokens, acrescentando 2.000 tokens novos e retornando 800 tokens de saída. Em Claude Sonnet 5, isso custa cerca de $2.31 enquanto o contexto é lido do cache, e cerca de $14.84 quando o contexto é cobrado como entrada nova em cada solicitação. Mesmo trabalho, mesmo modelo: a diferença é se os pontos de interrupção estão presentes e se as solicitações são feitas com menos de cinco minutos de intervalo.

Para ter uma referência baseada em medições, não em suposições: entre as contas da Kunavo que mantêm um agente sempre ativo, um dia ativo mediano custou $12.67, e um dia no percentil 90 custou cerca de $163. Esses valores são os custos diários faturados até 5 de outubro de 2026, às tarifas vigentes em cada dia. Como se trata de um grupo pequeno, considere-os como a amplitude da faixa, não como uma previsão para o seu agente.

Quando o saldo acaba

O Kunavo é pré-pago: cada chamada é paga com o saldo da carteira, e um agente que trabalha enquanto você dorme esvazia esse saldo enquanto você dorme. Uma solicitação que a carteira não consegue cobrir é recusada com HTTP 402 e o código insufficient_balance, em qualquer um dos protocolos, sem cobrança. A recusa ocorre antes de o saldo chegar a zero: cada solicitação primeiro reserva seu custo máximo, que inclui o prompt e a maior resposta permitida. Assim, quanto maior o limite de saída solicitado pelo agente, mais cedo suas chamadas começam a ser recusadas. O erro informa o valor que faltou, em balance_usd e needed_usd.

A resposta do Hermes Agent à falha de um provedor é uma cadeia de fallback: fallback_providers no config.yaml, gerenciada com hermes fallback e testada turno a turno. A documentação lista limites de taxa, erros do servidor, falhas de autenticação e erros 404 como situações que a acionam para o modelo principal, e cita HTTP 402 entre os erros de capacidade que fazem uma tarefa auxiliar passar para a próxima opção da cadeia. Ela não especifica o que acontece com um turno que recebe HTTP 402 quando nenhum fallback está configurado. Considere a interpretação mais direta: o turno falha e, com ele, a tarefa agendada. Lembre-se também de que um turno que usa fallback começa com o cache de prompt vazio.

Duas configurações evitam que um agente sem supervisão chegue a essa situação, e cada uma tem uma função diferente:

• Recarga automática, em Cobrança. Salve um cartão uma vez e defina três valores: o saldo abaixo do qual será feita uma recarga, o valor a adicionar a cada recarga e um limite mensal. A carteira será recarregada em poucos segundos após uma chamada que faça o saldo ficar abaixo do limite. Uma solicitação que chegar enquanto o saldo da carteira ainda estiver insuficiente aguardará a cobrança e, em seguida, será atendida em vez de recusada. Um 402 ainda será retornado quando não for possível fazer a cobrança — por exemplo, se o cartão for recusado ou se o limite mensal tiver sido atingido — ou quando uma solicitação reservar mais do que a carteira terá após a recarga. É necessário usar um cartão ou o Link — Alipay, WeChat Pay, Pix e outros métodos de pagamento locais não podem ser cobrados automaticamente.
• Um limite mensal para a chave, em Chaves de API. Dê ao agente uma chave própria e defina o valor máximo que essa chave poderá gastar em um mês-calendário. Acima desse valor, as chamadas dessa chave serão recusadas com um 402 e nenhuma cobrança será feita, enquanto suas outras chaves continuarão funcionando. Esse é o limite necessário para conter um loop descontrolado, algo que a carteira não pode oferecer, pois todas as chaves usam a mesma carteira.

Defina o limite de recarga acima do valor reservado por uma única solicitação e escolha o valor da recarga com base em um dia de uso do agente, não no mínimo: a menor recarga é de $10, e o custo mediano de um dia com o agente sempre ativo, mencionado acima, é de $12.67. Os limites da recarga automática estão na página de cobrança, e o corpo completo do erro está na página de erros.

Guias relacionados

• API personalizada do Hermes Agent — por que o provedor de saída não é o servidor da API de entrada, uma explicação do campo transport e as verificações a fazer na primeira chamada.
• Preços do Hermes Agent — quanto custa executá-lo além das tarifas por token.
• A compactação de contexto do Hermes excedeu o tempo limite — o que significa o erro quando o sumarizador trava e como se recuperar.
• Hermes vs. OpenClaw — e a mesma configuração para o outro agente, na página do OpenClaw.