Tutorial 7: Arquivos de Configuração

Bem-vindos de volta, domadores de agentes! Neste tutorial, vamos mergulhar no coração do Hermes: os arquivos de configuração. Se você já se sentiu perdido em um mar de YAML e variáveis de ambiente, não tema — vamos tornar isso o mais indolor possível.

A Base do Hermes

Tudo vive em ~/.hermes/. Pense nisso como o apartamento do seu agente. Aqui está o que tem dentro:

~/.hermes/
├── config.yaml     # Configurações (modelo, terminal, TTS, compressão, etc.)
├── .env            # Chaves de API e segredos
├── auth.json       # Credenciais do provedor OAuth (Nous Portal, etc.)
├── SOUL.md         # Identidade primária do agente (slot #1 no prompt do sistema)
├── memories/       # Memória persistente (MEMORY.md, USER.md)
├── skills/         # Habilidades criadas pelo agente (gerenciadas via ferramenta skill_manage)
├── cron/           # Tarefas agendadas
├── sessions/       # Sessões do gateway
└── logs/           # Logs (errors.log, gateway.log — segredos são automaticamente mascarados)

O Caminho Mais Fácil: Configuração com Um Comando

Antes de entrarmos nos detalhes, aqui vai uma dica de profissional: execute hermes setup --portal. Um único OAuth te dá um provedor de modelo e todas as quatro ferramentas do Tool Gateway sem tocar em um único arquivo YAML. Assinantes do Portal também ganham 10% de desconto em provedores cobrados por token. É o jeito preguiçoso de começar, e a gente ama isso.

Gerenciando Sua Configuração

O Hermes te dá um kit completo de ferramentas para gerenciar configurações. Aqui estão os comandos que você usará no dia a dia:

hermes config              # Ver a configuração atual
hermes config edit         # Abrir o config.yaml no seu editor
hermes config get KEY      # Exibir um valor resolvido
hermes config set KEY VAL  # Definir um valor específico
hermes config unset KEY    # Remover um valor definido pelo usuário
hermes config check        # Verificar opções ausentes (após atualizações)
hermes config migrate      # Adicionar opções ausentes interativamente

Aqui estão alguns exemplos práticos:

hermes config get model
hermes config set model anthropic/claude-opus-4
hermes config set terminal.backend docker
hermes config unset terminal.backend
hermes config set OPENROUTER_API_KEY sk-or-...  # Salva no .env

O truque de mágica: hermes config set roteia automaticamente os valores para o arquivo certo. Chaves de API vão para o .env, todo o resto vai para o config.yaml. Chega de adivinhar!

O Que Vence Quando Há Conflito?

O Hermes resolve as configurações nesta ordem (prioridade mais alta primeiro):

Argumentos de CLI — como hermes chat --model anthropic/claude-sonnet-4
~/.hermes/config.yaml — seu arquivo de configuração principal
~/.hermes/.env — para segredos (chaves de API, tokens, senhas)
Padrões embutidos — valores hardcoded seguros

Regra de ouro: Segredos vão no .env. Todo o resto vai no config.yaml. Quando ambos estão definidos, o config.yaml vence para configurações não secretas.

Substituição de Variáveis de Ambiente

Você pode referenciar variáveis de ambiente no config.yaml usando a sintaxe ${VAR_NAME}:

auxiliary:
  vision:
    api_key: ${GOOGLE_API_KEY}
    base_url: ${CUSTOM_VISION_URL}

delegation:
  api_key: ${DELEGATION_KEY}

Referências múltiplas também funcionam: url: "${HOST}:${PORT}". Se uma variável não estiver definida, o placeholder permanece como está e um aviso é registrado no log. A sintaxe estilo Cursor ${env:VAR_NAME} também funciona, então você pode copiar trechos de configurações do Cursor ou do Claude sem alterações.

Timeouts de Provedores

Você pode definir timeouts por provedor e por modelo:

providers:
  some-provider:
    request_timeout_seconds: 600
    models:
      some-model:
        timeout_seconds: 300

Também existe o stale_timeout_seconds para detectar chamadas não-streaming obsoletas. Essas configurações substituem as variáveis de ambiente legadas HERMES_API_TIMEOUT e HERMES_API_CALL_STALE_TIMEOUT.

Limites de Runtime

Para superfícies de servidor de longa duração (gateway, hermes serve --isolated), você pode definir limites de descritores de arquivo:

runtime:
  nofile_soft_limit: 4096

O padrão é 4096. Defina como 0, false ou null para desativar o ajuste.

Comportamento de Atualizações

As configurações de atualização ficam em updates no config.yaml:

updates:
  pre_update_backup: quick

Concluindo

Esse foi o tour pela configuração! Lembre-se: hermes setup --portal para o caminho fácil, hermes config set para mudanças rápidas, e mantenha os segredos no .env. Seu agente vai agradecer.

A seguir: vamos explorar os provedores de IA e como conectar seus modelos favoritos. Fique ligado!