API personalizada do Hermes Agent: provedores, transportes e verificações da primeira chamada

Um endpoint personalizado do Hermes Agent é configurado para saída, como uma entrada nomeada em providers: dentro de ~/.hermes/config.yaml, onde api é a URL base e transport é o protocolo de transporte. Isso é diferente do próprio servidor de API do Hermes, que aponta na direção oposta. Ambos são chamados de “API personalizada do Hermes” nos resultados de busca, e as páginas oficiais de documentação de cada um aparecem para as mesmas consultas — portanto, corrija primeiro a direção.

Esta página trata do Hermes Agent, o agente de código aberto da Nous Research. Uma verificação da API do GitHub em 21 de setembro de 2026 retornou archived: false, disabled: false, uma licença MIT e uma atualização no mesmo dia; a versão publicada mais recente é Hermes Agent v0.21.3, marcada com v2026.9.14 em 14 de setembro de 2026, não uma prévia. As superfícies das quais esta página obtém configuração são esse repositório e hermes-agent.nousresearch.com. hermes-agent.org abrange o mesmo projeto a partir de um domínio externo a nousresearch.com e carrega análises do Microsoft Clarity (verificado em 21 de setembro de 2026); não é uma superfície própria do projeto, portanto não extraia configuração dela. Isto também não é o Hermes 3 nem o Hermes 4, a família de modelos de pesos abertos da Nous, nem o mecanismo JavaScript de mesmo nome.

Duas coisas opostas chamadas de API personalizada do Hermes

As duas linhas são citadas das próprias páginas do Hermes, lidas em 21 de setembro de 2026: a referência do provedor e a página do servidor de API. Há uma particularidade de nomenclatura que vale conferir na sua própria instalação: a página do servidor de API documenta hermes gateway como o comando que o executa, enquanto a referência da CLI descreve hermes gateway como o gerenciador do serviço de mensagens, com os subcomandos run, start, stop e status. Execute hermes gateway --help em vez de tentar adivinhar. Tudo abaixo é a metade de saída.

A configuração mínima de saída

# ~/.hermes/config.yaml
providers:
  kunavo:
    api: https://api.kunavo.com/v1   # aliases accepted: base_url, url
    key_env: KUNAVO_API_KEY          # or inline api_key:, or key_cmd:
    transport: chat_completions      # set it by hand; see the transport section
    models:
      claude-sonnet-5:
        prompt_caching: true

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

KUNAVO_API_KEY=your-key

Campo a campo, conforme a referência do provedor: a chave de configuração é providers.<name>, o campo da URL base é api (com base_url e url aceitos como aliases), a credencial é key_env, uma api_key embutida ou uma key_cmd, e o protocolo é transport. A mesma entrada também aceita name, default_model, models, context_length, discover_models, extra_body, extra_headers, session_affinity_header, ssl_ca_cert / ssl_verify, catalog_provider e enabled: false. Selecione a entrada com model.provider: custom:kunavo ou, no meio da sessão, com /model custom:kunavo:<model-id>.

Dois comandos não são intercambiáveis. hermes model, executado fora de uma sessão de chat, é o assistente completo de configuração do provedor e a única coisa que pode adicionar um provedor ou aceitar uma chave. /model, dentro de uma sessão, apenas alterna entre o que já existe. Para endpoints empresariais que emitem tokens de curta duração, key_cmd nomeia um comando que imprime um token em stdout — puro ou como JSON com um campo access_token — que o Hermes executa e armazena em cache até pouco antes da expiração, sendo preferível a um api_key ou key_env estático na mesma entrada.

Escolha o transporte manualmente em vez de deixar o campo em branco

A referência do provedor lista três valores aceitos para transport em uma entrada personalizada. Ela também diz que o assistente hermes model Custom Endpoint agora solicita explicitamente o protocolo e persiste a resposta em config.yaml, e que a detecção automática baseada na URL “ainda ocorre como fallback quando o campo é deixado em branco”. A única regra de detecção detalhada na documentação é um caminho /anthropic mapeado para anthropic_messages, que uma URL base do Kunavo não corresponde; o restante da heurística não é enumerado em nenhuma página lida aqui, razão para escrever o campo em vez de inferir o que ele faria. O Kunavo fornece /v1/chat/completions, /v1/messages e /v1/responses, portanto cada transporte tem uma rota correspondente no papel.

A linha Anthropic merece a ressalva, não uma resposta confiante. O guia do Azure Foundry do Hermes afirma que /v1 é removido da URL base porque o SDK da Anthropic acrescenta /v1/messages a toda solicitação — mas essa frase aparece sob um título do Azure, e o próprio exemplo da referência do provedor (api: https://proxy.example.com/anthropic) nunca diz qual sufixo o Hermes acrescenta para um proxy genérico. Portanto, ambos os candidatos acima são plausíveis e um deles pode produzir um 404 com /v1 duplicado. Verifique o caminho da solicitação que sua primeira chamada realmente registra; o documento da URL base aborda a armadilha entre origem e /v1 por trás da maioria dos 404 neste transporte. A autenticação é uma preocupação menor: a rota Messages do Kunavo aceita tanto Authorization: Bearer quanto x-api-key, portanto qualquer cabeçalho que o SDK da Anthropic envie para um proxy genérico deveria ser aceito — mas o Hermes não documenta essa escolha, então “deveria” é o termo honesto.

Uma questão em aberto que esta página também não responderá. O Hermes documenta uma atualização silenciosa de nomes de modelos da família GPT-5.x para codex_responses mesmo quando config.yaml ainda diz chat_completions — mas essa frase aparece sob provider: azure-foundry enquanto é formulada como detecção de nome de modelo. Não está documentado se um slug GPT em provider: custom aciona o mesmo movimento. Se escolher um modelo da classe GPT, registre para qual rota a primeira chamada foi enviada.

O que um endpoint personalizado não recebe gratuitamente, por transporte

Nenhum destes é um bloqueio de plano. O Hermes Agent é “gratuito e de código aberto sob a licença MIT”, segundo a própria perguntas frequentes da página inicial do projeto, e o dicionário providers: é documentado como configuração comum, não como recurso de um nível. Eles são bloqueios de capacidade e diferem conforme o transporte.

Duas saídas de emergência para um gateway especificamente. catalog_provider aceita um ID de provedor do Hermes ou um ID do models.dev e faz com que os modelos da entrada herdem os metadados desse catálogo — apenas consultas; as solicitações continuam indo para sua URL api com sua chave. E discover_models: false ignora completamente a sondagem /models e usa apenas os modelos listados na entrada, sendo a correção quando a descoberta é ruidosa ou lenta. Não foi testado aqui se a resposta /v1/models do Kunavo satisfaz a sondagem do Hermes; se não satisfizer, a detecção de contexto recai no padrão de 128K. O raciocínio de custos por trás dessas configurações — slots auxiliares, workers de delegação e continuidade do cache — está em preços do Hermes Agent, em vez de ser repetido aqui.

Uma sequência de verificação para executar antes de mover trabalho real

Estas são etapas para você executar, com a observação esperada, não resultados obtidos pelo Kunavo. Nenhuma execução do Hermes contra o Kunavo foi realizada, não há um guia de configuração do Kunavo para o Hermes e nada nesta página deve ser interpretado como uma integração testada. Mantenha sua rota de trabalho disponível durante todo o processo.

1. Adicione o provedor e depois faça o diagnóstico. hermes model o adiciona; hermes doctor é documentado como diagnóstico de problemas de configuração e dependências, e a referência da CLI registra duas verificações de configuração de endpoint personalizado que ele executa — uma chave custom_providers que não é uma lista YAML e uma entrada de lista legada sem uma entrada providers: correspondente. Ambas apenas geram avisos e --fix não as reescreve.
2. Confirme que a chave foi carregada antes de gastar qualquer coisa. hermes dump imprime um resumo de configuração pronto para copiar e colar — versão, provedor, modelo e se uma chave de API está presente. Espere seu ID de modelo e uma chave presente. hermes prompt-size é executado offline e informa uma divisão em bytes do prompt do sistema e dos esquemas de ferramentas, que é a parte fixa carregada em todos os turnos antes de qualquer conteúdo da conversa.
3. Um turno de texto sem streaming. Espere uma resposta e espere que a solicitação tenha seguido pelo caminho pretendido. Um endpoint personalizado que “funciona”, mas retorna lixo, é uma linha da tabela de solução de problemas do guia de início rápido do Hermes, que cita URL base incorreta, nome de modelo incorreto ou endpoint que não é realmente compatível com OpenAI, e orienta verificar primeiro o endpoint em um cliente separado.
4. Um turno com streaming. Espere saída incremental, em vez de um único bloco no final. Não foi testado nesta página se o enquadramento de streaming de um determinado endpoint satisfaz a análise de progresso do Hermes.
5. Uma rodada de ferramenta. Espere que a ferramenta seja executada. Se a chamada for impressa como texto, isso é o suporte à chamada de ferramentas no lado do servidor, não o transporte.
6. Leia o medidor. /usage é o painel de tokens, custos e contexto dentro da sessão. Compare-o com a cobrança que sua conta do provedor realmente registrou — a própria aritmética de um agente sobre os tokens informados é uma estimativa, não um livro contábil. Consulte o documento de uso.

Quanto custa a sequência e quanto custa uma alternância no meio da sessão

Suponha que as seis etapas acima enviem 26.000 tokens de entrada e recebam 1.150 tokens de saída no total — um prompt do sistema e um esquema de ferramentas fixos em cada uma de três chamadas, mais um resultado de ferramenta reenviado uma vez. Essa suposição é apenas ilustrativa; hermes prompt-size informa seu próprio prompt fixo como uma divisão em bytes, o que é mais próximo da verdade do que um número que esta página poderia estimar. As tarifas são preços atuais do catálogo do Kunavo por milhão de tokens.

Esta é uma aritmética ilustrativa de tokens às tarifas do catálogo, não uma tarefa Hermes medida nem um teto de cobrança. Ela exclui gravações de cache, ferramentas externas e impostos. O objetivo do número é mostrar sua pequenez: verificar uma rota custa muito menos do que descobrir uma configuração incorreta depois de uma semana de trabalho agendado.

O segundo número é o que o comando /model oculta. Os caches de prompts são associados ao modelo que atende à solicitação, portanto qualquer mudança de modelo no meio da conversa faz a mensagem seguinte reler toda a conversa ao preço integral de entrada, em vez da tarifa de leitura do cache, que o Hermes descreve como aproximadamente 75 a 90 por cento mais barata. Em uma conversa de 120.000 tokens com Claude Sonnet 5, a diferença entre $1.40 por milhão e a tarifa de leitura do cache $0.14 é de cerca de $0.151 para esse único turno — trivial uma vez, mas não trivial como hábito. O valor do catálogo do Kunavo é um piso de cobrança, não um teto: quando o upstream informa sua cobrança, a fatura é o maior entre o custo do catálogo e o custo do upstream multiplicado pelo markup aplicável. O mínimo é uma recarga pré-paga de $10 sem assinatura. Consulte cobrança.

Revertendo a configuração novamente

O Hermes documenta um caminho de desfazer, razão pela qual um teste é de baixo risco. enabled: false na entrada a oculta sem excluí-la. Cópias pontuais de config.yaml são gravadas em backups/config/config.yaml.<reason>.<timestamp> antes que hermes setup ou hermes migrate a reescrevam e sempre que ela for analisada, com repetições idênticas ignoradas e apenas as cinco mais recentes por motivo mantidas; se o arquivo posteriormente não puder ser analisado, o Hermes serve a cópia válida mais recente em vez dos padrões integrados. A referência de configuração também anota model.base_url como “limpo ao trocar de provedor”, portanto voltar para um provedor integrado é documentado como remoção da URL base obsoleta, em vez de deixá-la no arquivo — verifique o valor gravado depois, em vez de presumir.

Três armadilhas vêm de tutoriais antigos. A lista legada de nível superior custom_providers: ainda funciona e hermes update a migra automaticamente para o dicionário providers:, onde model legado se torna default_model e api_mode legado se torna transport. LLM_MODEL em .env foi removido por completo — config.yaml é a única fonte de verdade. E OPENAI_BASE_URL é documentado de duas formas por duas páginas oficiais atuais: a referência do provedor diz que ele é respeitado apenas para o provedor openai-api, enquanto a referência de variáveis de ambiente o lista como a URL base de um endpoint personalizado. Essa divergência não foi resolvida; portanto, configure o endpoint em config.yaml e não dependa dessa variável de ambiente como rota.

Se você está escolhendo um provedor em vez de conectar um, a API compatível com OpenAI aborda o que a superfície compatível inclui e não inclui, e Hermes vs OpenClaw compara os dois agentes. Quando estiver pronto para testar esta rota com uma chave financiada, crie uma conta no Kunavo.

Perguntas frequentes

Documentação do Hermes Agent — a referência do provedor, a página do servidor de API, a página de configuração de modelos, a página de configuração, a referência da CLI, a referência de comandos de barra, o guia de início rápido e a página inicial do projeto — lida em 21 de setembro de 2026. O estado do repositório e a versão mais recente foram verificados na API do GitHub no mesmo dia. As três rotas de API do Kunavo foram confirmadas no próprio código-fonte. Todos os valores em dólares são aritmética ilustrativa de tokens com base em tarifas atuais do catálogo, não um custo de tarefa medido. A configuração do Hermes foi reportada a partir de documentos-fonte; nenhuma execução do Hermes contra o Kunavo foi realizada.