Configuração de Coding Agents

Configurar Hermes Agent: API Key, Base URL e modelos

Instale o Hermes Agent, configure a Base URL e a API Key da BetterToken, escolha um modelo disponível e corrija erros comuns. Para seu projeto.

Para conectar o Hermes Agent à BetterToken, prepare uma API Key, informe a Base URL abaixo e escolha um ID de modelo atual na model plaza.

Configurações principais

Campo	Valor
API Key	BetterToken API Key
Base URL	`https://bettertoken.ai/v1`
Modelo	Um ID de modelo atual da model plaza

Pré-requisitos

A versão atual da ferramenta está instalada
Uma BetterToken API Key: cadastre-se e crie uma
Um ID de modelo da model plaza

Cadastre-se e obtenha uma BetterToken API Key

Já tem uma conta? Entre, recarregue o saldo e crie uma chave no console.

Requisitos adicionais

Copie o Model ID exato da model plaza.
macOS, Linux, Windows 10/11 ou WSL2
Um modelo com janela de contexto mínima de 64K para uso de ferramentas

Instalação

Instalar o Hermes Agent

Desktop (macOS / Windows)

A Hermes recomenda o instalador Desktop no macOS e no Windows. Baixe o Hermes Desktop e execute o instalador do seu sistema.

Linux / macOS / WSL2

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

Ao terminar, abra um novo terminal ou recarregue o shell antes de executar hermes.

Windows PowerShell

O Hermes Agent oferece suporte nativo ao Windows 10 e 11. Abra o PowerShell ou Windows Terminal e execute:

iex (irm https://hermes-agent.nousresearch.com/install.ps1)

Não são necessários privilégios de administrador. Abra uma nova janela do PowerShell após a instalação para carregar o User PATH atualizado.

hermes --version
hermes doctor

Referência rápida de recursos

Recurso	Finalidade
Terminal UI	Converse com o agente diretamente no terminal
Skills	Salve fluxos reutilizáveis para tarefas recorrentes
MCP	Conecte recursos de ferramentas locais ou remotas
Scheduled tasks	Execute tarefas agendadas e fluxos recorrentes
Subagents	Divida trabalhos complexos entre agentes especializados
Message gateway	Conecte o agente a mais pontos de entrada de mensagens

Configuração manual

Use a configuração interativa de modelo do Hermes Agent como caminho principal. Edite os arquivos de configuração diretamente apenas quando precisar de uma configuração manual.

Campo	Valor
API Key	BetterToken API Key
Base URL	`https://bettertoken.ai/v1`
Modelo	Um ID de modelo atual da model plaza

Configuração

Configuração interativa

Execute o seletor de modelos

Saia de qualquer chat Hermes ativo e execute:

hermes model

Escolha Custom endpoint

Selecione Custom endpoint (self-hosted / VLLM / etc.) na lista de provedores.

Preencha a configuração da BetterToken

Informe:

Base URL: https://bettertoken.ai/v1
API Key: sua BetterToken API Key
Model: um ID de modelo disponível copiado da model plaza

Se o Hermes pedir o API mode, escolha OpenAI-compatible Chat Completions. Use o context length publicado para o modelo e confirme pelo menos 64K.

Inicie o Hermes Agent

hermes --tui

Execute hermes para usar a interface de terminal clássica.

Arquivos de configuração

A configuração interativa valida e salva o endpoint. Para configurar manualmente, adicione os ajustes a ~/.hermes/config.yaml:

model:
  default: YOUR_MODEL_ID
  provider: custom
  base_url: "https://bettertoken.ai/v1"

Guarde a API Key em ~/.hermes/.env:

OPENAI_API_KEY=YOUR_API_KEY

No Windows nativo, esses arquivos ficam em %LOCALAPPDATA%\hermes\. Substitua os valores e execute hermes doctor.

Migre do OpenClaw

Se você já usa OpenClaw, primeiro verifique se a versão atual do Hermes Agent oferece o comando de migração. Execute uma simulação antes de alterar algo.

hermes claw migrate --dry-run

Depois de confirmar a saída, execute a migração:

hermes claw migrate

Após a migração, revise a Base URL, a API Key e o ID de modelo do Hermes Agent. Eles devem corresponder a https://bettertoken.ai/v1, à sua BetterToken API Key e a um ID de modelo disponível.

Verifique a conexão

Inicie hermes --tui ou hermes e envie:

Reply with HERMES_OK only. Do not use tools.

A conexão funciona quando o Hermes retorna HERMES_OK sem erro de autenticação, endpoint ou ID de modelo.

Alterne entre modelos

Execute hermes model fora do chat para adicionar ou reconfigurar um provedor. No chat, use /model para alternar entre provedores e modelos já configurados.

Erros comuns

Erro	O que verificar
`401` ou `Unauthorized`	Verifique a BetterToken API Key e remova espaços no início ou no fim.
`404`	Verifique a Base URL e não acrescente um caminho de endpoint específico.
`model not found`	Copie um ID de modelo atual da model plaza.
As alterações não são aplicadas	Salve a configuração e reinicie completamente a ferramenta.

Solução de problemas

Se as solicitações falharem ou não retornarem resposta, confirme que Base URL é exatamente https://bettertoken.ai/v1. Não acrescente /chat/completions nesse campo.
Se o Hermes informar que o modelo não existe, confirme que Model é um ID de modelo disponível da model plaza.
Copie o Model ID exato da model plaza.
Se o Hermes continuar usando o modelo antigo após uma alteração, encerre a sessão atual do Hermes Agent e execute hermes novamente.
A BetterToken geralmente não exige User-Agent adicional nem cabeçalhos personalizados. Adicione cabeçalhos somente quando o gateway personalizado, roteamento de tenant, observabilidade ou camada de cache exigir explicitamente.

Para um gateway que exige cabeçalhos de autenticação extras, o Hermes aceita extra_headers em providers.<provider-name> no config.yaml. Siga a configuração de provedores nomeados para conferir os nomes de cabeçalho exigidos e mantenha os valores das credenciais privados.

FAQ relacionada

Detalhes técnicos

Protocolo, endpoint e campos internos do provedor

Esta configuração usa https://bettertoken.ai/v1. A ferramenta acrescenta o caminho de endpoint compatível com OpenAI. Não adicione /chat/completions ou /responses, exceto quando um campo específico exigir isso.