Hermes Agent: A Referência do Profissional (2026)

TL;DR: Hermes Agent é um agente de IA autoaprimorável de código aberto da Nous Research. Ele funciona como um CLI e como um gateway de mensagens multiplataforma, armazena uma identidade durável e memória persistente em disco, agrega skills que melhoram com o uso e funciona com qualquer provedor de LLM compatível com OpenAI — Nous Portal, OpenRouter, Anthropic, GitHub Copilot, z.ai, Kimi, MiniMax, DeepSeek, Alibaba, Hugging Face, Google ou seu próprio endpoint auto-hospedado.¹² A parte mais difícil para a maioria dos novos usuários é a autenticação do provedor: o Hermes suporta cerca de 19 provedores de primeira classe além de endpoints personalizados, e três caminhos de autenticação distintos (chave API no .env, OAuth via hermes model ou endpoint personalizado em config.yaml). O modelo de autenticação é o primeiro a ser aprendido — todo o resto é consequência de qual provedor é resolvido.

O Hermes Agent opera como um runtime de agente completo, não como um wrapper de chat. Ele lê seu sistema de arquivos, executa comandos em backends sandboxed, faz scraping da web, gera subagentes, executa jobs cron agendados, conversa com Telegram/Discord/Slack/WhatsApp/Signal/Email a partir de um único processo gateway e cria suas próprias skills a partir da experiência.¹ O CLI é uma interface de terminal construída sobre um loop de conversação em run_agent.py; o gateway é um processo de longa duração que roteia mensagens de plataformas de mensageria pelo mesmo loop de conversação.³

A diferença entre o uso casual e expert do Hermes se resume a cinco sistemas. Domine-os e o Hermes se torna um multiplicador de força:

1. Resolução de provedor: como os fluxos de autenticação mapeiam para chamadas de API
2. Hierarquia de configuração: config.yaml + .env + auth.json + SOUL.md + AGENTS.md
3. Sistema de tool + toolset: o que o agente pode fazer, controlado por plataforma
4. Sistema de skills: memória procedural que o agente cria e evolui
5. Gateway + cron + profiles: rodar o Hermes onde você vive, não apenas onde você está

Principais conclusões

• A autenticação do provedor são três caminhos, não um. Chave API no .env, OAuth via hermes model/hermes auth ou endpoint personalizado em config.yaml. Escolha o caminho que corresponde ao seu provedor, não o que parece familiar.
• Trocar de provedor é um único comando. hermes model guia você interativamente por cada provedor suportado, incluindo logins OAuth, e /model provider:model alterna no meio da sessão sem perder o histórico.²
• Dois arquivos são a superfície de configuração editável pelo usuário. ~/.hermes/config.yaml armazena configurações e ~/.hermes/.env armazena secrets. auth.json, SOUL.md, MEMORY.md e skills/ são gerenciados diretamente pelo Hermes — você pode editar SOUL.md manualmente, mas o resto é tocado pelo próprio agente.⁴
• O Hermes é o sucessor do OpenClaw. Se você está migrando, hermes claw migrate importa mais de 30 categorias de estado automaticamente.⁵
• A qualidade do serviço depende do seu modelo auxiliar. Visão, sumarização da web, compressão e flush de memória usam um LLM auxiliar separado. Por padrão, é o Gemini Flash via detecção automática (OpenRouter → Nous → Codex) — se nenhum desses estiver configurado, esses recursos se degradam silenciosamente até você apontar os slots auxiliares para seu provedor principal.⁴

Cada seção abaixo é fundamentada na documentação upstream em hermes-agent.nousresearch.com/docs e na árvore de código-fonte em github.com/NousResearch/hermes-agent. Cada afirmação factual tem uma nota de rodapé apontando para a página upstream específica de onde ela veio.

Escolha seu caminho

Como o Hermes funciona: o modelo mental

O Hermes é estruturado em torno de um único loop de conversação que qualquer ponto de entrada pode invocar. Os pontos de entrada são a CLI (cli.py), o messaging gateway (gateway/run.py), o adaptador ACP para integração com editores, o batch runner e um servidor API.³ Todos eles, no final, chamam AIAgent.run_conversation() em run_agent.py, que:

1. Constrói o system prompt a partir de SOUL.md, MEMORY.md, USER.md, skills, arquivos de contexto e orientações de ferramentas via prompt_builder.py³
2. Resolve o provedor de runtime via runtime_provider.py — esse é o passo que define sua autenticação, URL base e modo API³
3. Chama o provedor usando um dos três modos API: chat_completions, codex_responses ou anthropic_messages³
4. Despacha qualquer chamada de ferramenta retornada através de model_tools.py e do registro central de ferramentas (tools/registry.py)³
5. Repete o loop até o modelo produzir uma resposta final, então persiste a sessão no SQLite com FTS5³

Entender esse loop é importante porque cada recurso — personalidades, memória, skills, compressão, fallback — se conecta a um desses estágios. Quando você está lendo uma chave de configuração e se perguntando o que ela faz, a resposta geralmente é “é um controle no estágio 1, 2, 3 ou 4 do loop acima.”

Núcleo agnóstico de plataforma. Uma única classe AIAgent atende CLI, gateway, ACP, batch e servidor API. As diferenças de plataforma ficam no ponto de entrada, não no agente em si.³ Por isso os mesmos comandos slash funcionam tanto no terminal quanto no Telegram — eles são despachados a partir de um COMMAND_REGISTRY compartilhado em hermes_cli/commands.py.⁶

A estrutura de diretórios é o sistema. O Hermes armazena tudo em ~/.hermes/ (ou $HERMES_HOME para perfis não padrão):⁴

~/.hermes/
├── config.yaml        # Configurações (modelo, terminal, TTS, compressão, etc.)
├── .env               # Chaves e segredos API
├── auth.json          # Credenciais de provedor OAuth (Nous Portal, Codex, Anthropic)
├── SOUL.md            # Identidade primária do agente (slot #1 no system prompt)
├── memories/          # Memória persistente (MEMORY.md, USER.md)
├── skills/            # Skills incluídas + criadas pelo agente + instaladas do hub
├── cron/              # Tarefas agendadas
├── sessions/          # Estado de sessão do gateway
└── logs/              # agent.log, gateway.log, errors.log (segredos auto-ocultados)

Cada arquivo acima tem um papel específico; nenhum deles se sobrepõe. Se você está procurando “onde o Hermes armazena X”, é um desses.

Instalação

O instalador de uma linha é o caminho para 95% dos usuários. Ele cuida de Python, uv, Node.js, ripgrep, ffmpeg, o clone do repositório, o ambiente virtual e o comando global hermes.⁷

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

Funciona no Linux, macOS, WSL2 e Android/Termux (o instalador detecta automaticamente o Termux e alterna para um bundle testado para Android).⁷ Windows nativo não é suportado — instale o WSL2 e execute o comando acima a partir dele.⁷

Depois que terminar:

source ~/.bashrc    # ou ~/.zshrc
hermes              # Comece a conversar

O único pré-requisito é o git. O instalador provisiona automaticamente Python 3.11 via uv (sem necessidade de sudo), Node.js v22 (para automação de navegador e a bridge do WhatsApp), ripgrep e ffmpeg.⁷

Verificar a instalação

hermes version      # Verificar versão
hermes doctor       # Diagnosticar problemas de configuração/dependências
hermes status       # Mostrar configuração atual + estado de autenticação
hermes dump         # Resumo copiável da configuração para depuração

hermes doctor diz exatamente o que está faltando e como corrigir.⁷ hermes dump é o comando de diagnóstico para colar em uma issue do GitHub ou em uma thread no Discord quando pedir ajuda — é um resumo em texto puro de toda a sua configuração com segredos ocultados.⁸

Instalação manual

Se você precisa de controle total — versão personalizada do Python, extras específicos, integração com Nix/NixOS — o fluxo manual está documentado passo a passo no guia de instalação upstream.⁷ Extras opcionais que você pode combinar com uv pip install -e ".[<extras>]":

O comando de instalação no Termux é diferente — ele usa pip com um arquivo de constraints, não uv pip:

python -m pip install -e ".[termux]" -c constraints-termux.txt

Isso acontece porque .[all] no Android puxa o faster-whisper pelo extra voice, que depende de wheels do ctranslate2 que não são publicadas para Android.⁷

Autenticação e Provedores

O Hermes suporta cerca de 19 provedores de primeira classe, além de endpoints personalizados, e três caminhos distintos de autenticação. Aqui está toda a superfície de autenticação, organizada por caminho para que você encontre aquele que corresponde ao que você tem.

Os Três Caminhos de Autenticação

Cada provedor no Hermes se encaixa em um destes três padrões de autenticação:

Caminho 1 — chave de API no .env. Coloque sua chave em ~/.hermes/.env e o Hermes a lê na inicialização. Usado por OpenRouter, AI Gateway, z.ai/GLM, Kimi/Moonshot, MiniMax (e MiniMax China), Alibaba Cloud/DashScope, Kilo Code, OpenCode Zen, OpenCode Go, DeepSeek, Hugging Face, Google/Gemini e a maioria dos provedores de terceiros.²

Caminho 2 — OAuth via hermes model ou hermes auth. Inicia um fluxo de device code, abre um navegador, armazena credenciais em ~/.hermes/auth.json (e pode importar credenciais existentes de ferramentas como Claude Code ou Codex CLI). Usado por Nous Portal, OpenAI Codex (conta ChatGPT), GitHub Copilot e Anthropic (Claude Pro/Max).²

Caminho 3 — Endpoint personalizado em config.yaml. Para qualquer API compatível com OpenAI — Ollama, vLLM, SGLang, llama.cpp, LM Studio, proxy LiteLLM, Together AI, Groq, Azure OpenAI ou seu próprio servidor self-hosted. Configurado uma vez via hermes model → Custom endpoint, depois persistido em config.yaml.²

A Matriz Completa de Provedores

Esta é a lista completa de provedores de primeira classe, com o fluxo exato de configuração para cada um.²

Anthropic: Três Métodos de Autenticação

Anthropic ganha sua própria seção porque o Hermes suporta três caminhos distintos para o Claude, e escolher o certo importa. Conforme a documentação upstream:²

# Method 1: API key (pay-per-token)
export ANTHROPIC_API_KEY=***
hermes chat --provider anthropic --model claude-sonnet-4-6

# Method 2: OAuth through hermes model (preferred)
# Uses Claude Code's credential store when available
hermes model

# Method 3: Manual setup-token (fallback/legacy)
export ANTHROPIC_TOKEN=***
hermes chat --provider anthropic

# Auto-detect Claude Code credentials
hermes chat --provider anthropic   # reads Claude Code files automatically

Quando você escolhe OAuth do Anthropic via hermes model, o Hermes prefere o credential store do próprio Claude Code em vez de copiar o token para ~/.hermes/.env. Isso mantém credenciais Claude atualizáveis de fato atualizáveis.² Se você já usa Claude Code na mesma máquina, este é o caminho mais limpo.

Para fixar Anthropic permanentemente em config.yaml:

model:
  provider: "anthropic"
  default: "claude-sonnet-4-6"

--provider claude e --provider claude-code também funcionam como atalhos para --provider anthropic.²

GitHub Copilot: Dois Modos

O Copilot é suportado em dois modos: API direto do Copilot (recomendado) e Copilot ACP (que executa a CLI Copilot local como subprocesso).²

# Direct Copilot API
hermes chat --provider copilot --model gpt-5.4

# Copilot ACP (requires the Copilot CLI in PATH + an existing copilot login)
hermes chat --provider copilot-acp --model copilot-acp

A autenticação é verificada nesta ordem, conforme a documentação upstream:² 1. Variável de ambiente COPILOT_GITHUB_TOKEN 2. Variável de ambiente GH_TOKEN 3. Variável de ambiente GITHUB_TOKEN 4. Fallback para CLI gh auth token 5. Login via device code OAuth usando hermes model

O tipo de token importa. A API do Copilot não suporta Personal Access Tokens clássicos (ghp_*). Os tipos suportados são tokens OAuth (gho_*), PATs fine-grained (github_pat_* com permissão Copilot Requests) e tokens de GitHub App (ghu_*). Se seu gh auth token retorna um token ghp_*, use hermes model para autenticar via OAuth.²

Provedores Chineses de IA (Suporte de Primeira Classe)

O Hermes tem suporte embutido para z.ai/GLM, Kimi/Moonshot, MiniMax (endpoints global + China) e Alibaba Cloud com IDs de provedor dedicados.²

# z.ai / ZhipuAI GLM
hermes chat --provider zai --model glm-5                 # Requires: GLM_API_KEY

# Kimi / Moonshot AI
hermes chat --provider kimi-coding --model kimi-for-coding   # Requires: KIMI_API_KEY

# MiniMax (global)
hermes chat --provider minimax --model MiniMax-M2.7          # Requires: MINIMAX_API_KEY

# MiniMax (China)
hermes chat --provider minimax-cn --model MiniMax-M2.7       # Requires: MINIMAX_CN_API_KEY

# Alibaba Cloud / DashScope (Qwen)
hermes chat --provider alibaba --model qwen3.5-plus          # Requires: DASHSCOPE_API_KEY

URLs base podem ser sobrescritas com as variáveis de ambiente GLM_BASE_URL, KIMI_BASE_URL, MINIMAX_BASE_URL, MINIMAX_CN_BASE_URL ou DASHSCOPE_BASE_URL.²

Z.AI detecta o endpoint automaticamente. Ao usar o provedor z.ai/GLM, o Hermes sonda múltiplos endpoints (global, China, variantes de coding) para encontrar um que aceite sua chave de API. O endpoint funcional é cacheado automaticamente — não é necessário GLM_BASE_URL para a maioria dos usuários.²

xAI (Grok) habilita prompt caching automaticamente. Quando a URL base contém x.ai, o Hermes envia o header x-grok-conv-id em cada requisição para rotear ao mesmo servidor dentro de uma sessão de conversa, reusando system prompts e histórico cacheados.² Automático; sem configuração necessária.

O Comando hermes auth

hermes auth é o comando de gerenciamento de credenciais para pools e credenciais OAuth.⁶

hermes auth                              # Interactive wizard
hermes auth list                         # Show all credential pools
hermes auth list openrouter              # Show one provider's pool
hermes auth add openrouter --api-key sk-or-v1-xxx
hermes auth add anthropic --type oauth
hermes auth remove openrouter 2          # Remove by index
hermes auth reset openrouter             # Clear cooldowns

Pools de credenciais são como você rotaciona múltiplas chaves de API ou tokens OAuth para o mesmo provedor — útil para distribuir limites de taxa entre várias chaves sem alterar código.⁶ Os comandos legados hermes login / hermes logout foram removidos; use hermes auth em vez disso.⁶

Endpoints Personalizados e Self-Hosted

O Hermes funciona com qualquer endpoint API compatível com OpenAI. Se um servidor implementa /v1/chat/completions, você pode apontar o Hermes para ele.²

Setup interativo (recomendado):

hermes model
# Select "Custom endpoint (self-hosted / VLLM / etc.)"
# Enter: API base URL, API key, Model name

config.yaml manual:

model:
  default: your-model-name
  provider: custom
  base_url: http://localhost:8000/v1
  api_key: your-key-or-leave-empty-for-local

Ambas as abordagens persistem em config.yaml, que é a única fonte de verdade para main-model, provider e base URL.² As variáveis de ambiente legadas OPENAI_BASE_URL e LLM_MODEL não são mais lidas para configuração de main-model — use hermes model ou edite o config.yaml diretamente.² (OPENAI_BASE_URL + OPENAI_API_KEY ainda são honradas como fallback para o caminho de roteamento auxiliar provider: "main", então não as apague cegamente se você as estiver usando ali.)⁴

Trocando endpoints personalizados durante a sessão:

/model custom:qwen-2.5             # Custom endpoint with explicit model
/model custom                      # Auto-detect the model from the endpoint
/model custom:local:qwen-2.5       # Named custom provider "local"
/model custom:work:llama3          # Named custom provider "work"
/model openrouter:claude-sonnet-4  # Back to a cloud provider

/model custom (sem nome de modelo) consulta a API /v1/models do seu endpoint e auto-seleciona o modelo se exatamente um estiver carregado — útil para servidores locais executando um único modelo.²

Servidores LLM Locais (Templates de Setup)

A documentação upstream traz guias completos de setup para Ollama, vLLM, SGLang, llama.cpp e LM Studio. Aqui estão os comandos-chave que você realmente vai executar. Cada um foi feito para produzir um endpoint funcional ao qual o Hermes pode se conectar.²

Ollama — caminho local mais fácil, configuração zero:

ollama pull qwen2.5-coder:32b
OLLAMA_CONTEXT_LENGTH=32768 ollama serve   # Raise from 4k default
hermes model   # Custom endpoint → http://localhost:11434/v1 → qwen2.5-coder:32b

Pegadinha crítica do Ollama: O Ollama tem como padrão tamanhos de contexto muito baixos (4.096 tokens em VRAM abaixo de 24GB). Você precisa aumentar via OLLAMA_CONTEXT_LENGTH ou um Modelfile — a API compatível com OpenAI não aceita tamanho de contexto do cliente, então o Hermes não pode defini-lo por você.² Para uso de agente, defina pelo menos 16k–32k.

vLLM — serving GPU de alta performance:

pip install vllm
vllm serve meta-llama/Llama-3.1-70B-Instruct \
  --port 8000 \
  --max-model-len 65536 \
  --tensor-parallel-size 2 \
  --enable-auto-tool-choice \
  --tool-call-parser hermes

Tool calling requer --enable-auto-tool-choice e --tool-call-parser <name>. Parsers suportados: hermes (Qwen 2.5, Hermes 2/3), llama3_json, mistral, deepseek_v3, deepseek_v31, xlam, pythonic. Sem essas flags, tool calls retornarão como texto puro.²

SGLang — serving rápido com RadixAttention para reuso de cache KV:

pip install "sglang[all]"
python -m sglang.launch_server \
  --model meta-llama/Llama-3.1-70B-Instruct \
  --port 30000 \
  --context-length 65536 \
  --tp 2 \
  --tool-call-parser qwen

Pegadinha do SGLang: O max_tokens padrão é 128. Defina --default-max-tokens no servidor ou configure model.max_tokens em config.yaml se as respostas estiverem sendo cortadas.²

llama.cpp / llama-server — CPU e Apple Silicon Metal:

./build/bin/llama-server \
  --jinja -fa \
  -c 32768 \
  -ngl 99 \
  -m models/qwen2.5-coder-32b-instruct-Q4_K_M.gguf \
  --port 8080 --host 0.0.0.0

--jinja é necessário para tool calling. Sem ele, o llama-server ignora completamente o parâmetro tools e o modelo tenta chamar tools escrevendo JSON no texto da resposta — o que o Hermes não consegue interpretar como tool calls reais.²

LM Studio — app desktop com GUI:

Inicie o servidor pelo app LM Studio (aba Developer → Start Server), ou via CLI: lms server start (inicia na porta 1234) e lms load qwen2.5-coder --context-length 32768.² Depois aponte o hermes model para http://localhost:1234/v1.

Pegadinha crítica do LM Studio: O LM Studio lê o tamanho de contexto a partir dos metadados do modelo, mas muitos modelos GGUF reportam padrões de 2048 ou 4096. Sempre defina o tamanho de contexto explicitamente nas configurações do modelo no LM Studio — clique no ícone de engrenagem ao lado do seletor de modelo, defina “Context Length” para pelo menos 16384 (preferencialmente 32768) e recarregue o modelo.²

Provedores Personalizados Nomeados

Se você trabalha com múltiplos endpoints personalizados (um servidor de dev local e um servidor remoto GPU, por exemplo), defina-os como provedores personalizados nomeados em config.yaml:²

custom_providers:
  - name: local
    base_url: http://localhost:8080/v1
    # api_key omitted — Hermes uses "no-key-required" for keyless local servers
  - name: work
    base_url: https://gpu-server.internal.corp/v1
    api_key: corp-api-key
    api_mode: chat_completions      # optional, auto-detected from URL
  - name: anthropic-proxy
    base_url: https://proxy.example.com/anthropic
    api_key: proxy-key
    api_mode: anthropic_messages    # for Anthropic-compatible proxies

Depois alterne entre eles durante a sessão com a sintaxe tripla:

/model custom:local:qwen-2.5
/model custom:work:llama3-70b
/model custom:anthropic-proxy:claude-sonnet-4

Você também pode selecionar provedores personalizados nomeados a partir do menu interativo hermes model.²

Arquitetura de Provedor Plugável (v0.13.0+)

A v0.13.0 traz uma ProviderProfile ABC mais um diretório plugins/model-providers/ para que provedores de inferência de terceiros entrem sem modificações no core.¹⁸ Se um provedor falar um modo de API compatível com OpenAI, Anthropic ou Codex, você pode implementar uma subclasse ProviderProfile que declara o caminho de auth, base URL, catálogo de modelos e headers de caching; o Hermes a resolve pelo mesmo caminho runtime_provider.py que os provedores embutidos usam. Esta é a mudança arquitetural por trás da expansão de provedores na v0.13.0: em vez de editar o código core para adicionar um provedor, você ship um plugin.

Detecção de Tamanho de Contexto

Duas configurações são confundidas constantemente, conforme a documentação upstream:²

• context_length — a janela de contexto total (orçamento combinado de tokens de input + output, ex: 1.000.000 para Claude Opus 4.7 ou 200.000 para Sonnet 4.6). O Hermes usa isso para decidir quando comprimir o histórico.
• model.max_tokens — o limite de output (máximo de tokens que o modelo pode gerar em uma única resposta). Não tem relação com o tamanho do histórico.

Defina context_length quando a auto-detecção errar o tamanho da janela:

model:
  default: "qwen3.5:9b"
  base_url: "http://localhost:8080/v1"
  context_length: 131072      # tokens

O Hermes usa uma cadeia de resolução de múltiplas fontes para detectar janelas de contexto: override de config → custom provider por modelo → cache persistente → endpoint /models → Anthropic /v1/models → API OpenRouter → Nous Portal → models.dev (registro mantido pela comunidade para mais de 3800 modelos) → defaults de fallback (128K).² O sistema é provider-aware, então o mesmo modelo pode ter limites de contexto diferentes dependendo de quem o serve (ex: claude-opus-4.6 é 1M no Anthropic direto mas 128K no GitHub Copilot).²

Rotação de Provedor e Fallback

Pools de credenciais. Quando você tem múltiplas chaves de API para o mesmo provedor, configure uma estratégia de rotação via hermes auth. É assim que você distribui limites de taxa entre múltiplas chaves.⁶

Modelo de fallback. Configure um provider:model reserva para o qual o Hermes troca automaticamente quando seu modelo principal falha (limites de taxa, erros de servidor, falhas de auth):²

fallback_model:
  provider: openrouter            # required
  model: anthropic/claude-sonnet-4  # required
  # base_url: http://localhost:8000/v1    # optional, for custom endpoints
  # api_key_env: MY_CUSTOM_KEY           # optional, env var name

O fallback troca model e provider durante a sessão sem perder sua conversa. Dispara no máximo uma vez por sessão.² Provedores suportados para fallback: openrouter, nous, openai-codex, copilot, copilot-acp, anthropic, huggingface, zai, kimi-coding, minimax, minimax-cn, deepseek, ai-gateway, opencode-zen, opencode-go, kilocode, alibaba, custom.²

Modelos Auxiliares

O Hermes usa modelos “auxiliares” leves para tarefas paralelas: análise de imagem, sumarização de páginas web, análise de screenshots do navegador, classificação de aprovação de comandos perigosos, compressão de contexto, sumarização de busca em sessão, skill matching, dispatch de ferramenta MCP e flush de memória.⁴ Por padrão, eles usam Gemini Flash via auto-detecção (OpenRouter → Nous → Codex).

Você pode configurar qual modelo e provedor cada tarefa auxiliar usa. Cada slot auxiliar usa os mesmos três botões: provider, model, base_url.⁴

auxiliary:
  vision:
    provider: "auto"                # "auto", "openrouter", "nous", "codex", "main", etc.
    model: ""                       # e.g. "openai/gpt-4o", "google/gemini-2.5-flash"
    base_url: ""                    # Custom OpenAI-compatible endpoint
    api_key: ""                     # Falls back to OPENAI_API_KEY
    timeout: 30
    download_timeout: 30
  web_extract:
    provider: "auto"
    model: ""
    timeout: 360
  approval:
    provider: "auto"
    model: ""
    timeout: 30
  compression:
    timeout: 120
  session_search: { provider: "auto", model: "", timeout: 30 }
  skills_hub:    { provider: "auto", model: "", timeout: 30 }
  mcp:           { provider: "auto", model: "", timeout: 30 }
  flush_memories:{ provider: "auto", model: "", timeout: 30 }

A opção de provider "main" significa “use o provedor que meu agente principal usa” — válido apenas dentro de configs auxiliary:, compression: e fallback_model:. Não é válido para sua configuração de model.provider no nível superior. Se você usa um endpoint personalizado compatível com OpenAI como seu modelo principal, defina provider: custom na sua seção model:.⁴

Por que isso importa: se você só configurou OAuth do Anthropic (sem chave OpenRouter), sua visão, sumarização web e compressão vão degradar ou falhar porque a cadeia de fallback auxiliar padrão tenta o OpenRouter primeiro. Adicione um OPENROUTER_API_KEY para tarefas auxiliares, ou reconfigure cada slot auxiliar para usar seu provedor principal:

auxiliary:
  vision:
    provider: "main"
  web_extract:
    provider: "main"

Esta é a pegadinha “minhas funcionalidades silenciosamente não funcionam” mais comum para novos usuários do Hermes.

Sistema de configuração

O Hermes tem um sistema de configuração em camadas. Entender a precedência é essencial porque camadas superiores sobrescrevem as inferiores, e uma das camadas é um registro global de providers que você não consegue ver no config.yaml.

Layout do arquivo de configuração

De acordo com a documentação oficial, estes são os arquivos que compõem uma configuração do Hermes:⁴

~/.hermes/
├── config.yaml       # All settings (model, terminal, TTS, compression, memory, toolsets, ...)
├── .env              # Secrets (API keys, bot tokens, passwords)
├── auth.json         # OAuth provider credentials (Nous Portal, Codex, Anthropic)
├── SOUL.md           # Primary agent identity (slot #1 in system prompt)
├── memories/         # Persistent memory (MEMORY.md, USER.md)
├── skills/           # Bundled + agent-created + hub-installed skills
├── cron/             # Scheduled jobs
├── sessions/         # Gateway session state
└── logs/             # agent.log, gateway.log, errors.log (secrets auto-redacted)

config.yaml vs .env — quando ambos estão definidos, o config.yaml vence para configurações não secretas.⁴ A regra é: - Secrets (chaves de API, tokens de bot, senhas) → .env - Todo o resto (modelo, backend de terminal, configurações de compressão, limites de memória, toolsets) → config.yaml

Secrets podem ser referenciados a partir do config.yaml usando interpolação no estilo shell:⁴

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

Gerenciando a configuração

hermes config                # View current configuration
hermes config show           # Same as above
hermes config edit           # Open config.yaml in your editor
hermes config set KEY VAL    # Set a specific value
hermes config path           # Print the config file path
hermes config env-path       # Print the .env file path
hermes config check          # Check for missing options (after updates)
hermes config migrate        # Interactively add missing options

Exemplos:⁴

hermes config set model anthropic/claude-opus-4
hermes config set terminal.backend docker
hermes config set OPENROUTER_API_KEY sk-or-...   # Saves to .env

hermes config check e hermes config migrate são os comandos que você deve rodar após cada hermes update — eles capturam opções de configuração recém-adicionadas que seu arquivo ainda não tem.⁶

Precedência de configuração

O Hermes carrega configuração a partir de várias fontes. Quando múltiplas fontes definem o mesmo valor, a fonte de maior prioridade vence:⁴

1. Argumentos da CLI — hermes chat --model anthropic/claude-sonnet-4 (override por invocação)
2. Variáveis de ambiente — aplicadas na inicialização do processo
3. config.yaml — o arquivo principal de configurações
4. .env — apenas secrets
5. Padrões embutidos — aplicados quando nada mais define um valor

Flags da CLI sempre vencem para aquela invocação específica. O config.yaml é a fonte de verdade de longo prazo.

Localização (v0.13.0+)

A v0.13.0 adiciona 7 locales para mensagens da CLI e do gateway: chinês (simplificado), japonês, alemão, espanhol, francês, ucraniano e turco.¹⁸ A documentação atualmente está localizada apenas em zh-Hans. O locale é resolvido a partir das variáveis de ambiente LC_ALL / LANG ou de uma chave locale: explícita no config.yaml. O inglês permanece como padrão e fonte de verdade para qualquer string que uma tradução ainda não tenha coberto.

Profiles — múltiplas instâncias isoladas do Hermes

Profiles oferecem múltiplas instâncias isoladas do Hermes, cada uma com sua própria configuração, sessions, skills, memória e PID de gateway. É assim que você roda “Hermes do trabalho” e “Hermes pessoal” lado a lado sem que um veja o estado do outro.⁶

hermes profile list
hermes profile create work --clone                  # Clone from current profile
hermes profile use work                             # Set sticky default
hermes profile alias work --name h-work             # Create wrapper script
hermes profile export work -o work-backup.tar.gz
hermes profile import work-backup.tar.gz --name restored
hermes -p work chat -q "Hello from work profile"    # One-off without switching

Cada profile recebe seu próprio HERMES_HOME (~/.hermes-<name>/ por padrão), de modo que múltiplos profiles podem rodar o gateway simultaneamente sem atrapalhar uns aos outros.⁶³

Comandos CLI

Esta seção é a referência do praticante para os comandos de nível superior do CLI. Para a referência autoritativa derivada do código, consulte a documentação upstream CLI Commands Reference.⁶

Opções globais

hermes [global-options] <command> [subcommand/options]

Comandos de nível superior

hermes chat — O ponto de entrada principal

hermes sem argumentos abre o chat interativo. hermes chat é a forma explícita com opções:⁶

hermes chat -q "Summarize the latest PRs"           # One-shot, non-interactive
hermes chat --provider openrouter --model anthropic/claude-sonnet-4.6
hermes chat --toolsets web,terminal,skills          # Enable specific toolsets
hermes chat --quiet -q "Return only JSON"           # Programmatic mode
hermes chat --worktree -q "Review repo and open a PR"

Opções principais:

hermes setup — Assistente completo

Executa o assistente de configuração completo ou vai direto para uma seção específica:⁶

hermes setup                 # Full wizard
hermes setup model           # Provider and model only
hermes setup terminal        # Terminal backend only
hermes setup gateway         # Messaging platforms only
hermes setup tools           # Tool enable/disable per platform
hermes setup agent           # Agent behavior only
hermes setup --non-interactive
hermes setup --reset         # Reset config to defaults before setup

hermes logs — Consulta estruturada de logs

hermes logs é mais poderoso do que tail -f nos arquivos de log porque suporta filtragem por nível, ID de sessão e intervalo de tempo simultaneamente.⁶

hermes logs                          # Last 50 lines of agent.log
hermes logs -f                       # Follow in real time
hermes logs gateway -n 100           # Last 100 lines of gateway.log
hermes logs --level WARNING --since 1h   # Warnings from the last hour
hermes logs --session abc123         # Filter by session ID substring
hermes logs errors --since 30m -f    # Follow errors.log from 30m ago
hermes logs list                     # List all log files with sizes

Os arquivos de log ficam em ~/.hermes/logs/:⁶ - agent.log — toda a atividade do agente (chamadas API, despacho de ferramentas, ciclo de vida de sessões, INFO+) - errors.log — apenas avisos e erros (um subconjunto filtrado do agent.log) - gateway.log — atividade do messaging gateway (conexões de plataforma, despacho, webhooks)

A rotação é automática via RotatingFileHandler do Python — procure por agent.log.1, agent.log.2, etc.⁶

hermes doctor — Diagnósticos

hermes doctor [--fix] é o primeiro comando a executar quando algo está errado. Ele verifica validade da configuração, presença de dependências, disponibilidade de chaves API, status dos serviços, e pode tentar reparos automáticos com --fix.⁶

Para compartilhar diagnósticos com outra pessoa, use hermes dump — ele produz um resumo compacto em texto puro com chaves API ocultadas, pronto para colar em uma issue do GitHub ou em um thread no Discord.⁶

Comandos Slash

Os comandos slash são executados dentro de uma sessão de chat ativa (CLI ou plataforma de mensagens). Eles são despachados a partir de um COMMAND_REGISTRY compartilhado em hermes_cli/commands.py, e é por isso que a maioria dos comandos funciona de forma idêntica em todas as superfícies.⁹

Controle de sessão

Configuração e modelo

O comando /model é o cavalo de batalha para troca de provedor no meio da sessão:⁹

/model                              # Show current model and options
/model claude-sonnet-4              # Switch model (auto-detect provider)
/model zai:glm-5                    # Switch provider:model
/model custom:qwen-2.5              # Use model on custom endpoint
/model custom                       # Auto-detect model from custom endpoint
/model custom:local:qwen-2.5        # Named custom provider
/model openrouter:anthropic/claude-sonnet-4   # Back to cloud

Ferramentas, skills e informações

Comandos slash dinâmicos de skills

Toda skill instalada é automaticamente exposta como um comando slash:⁹

/gif-search funny cats
/axolotl help me fine-tune Llama 3 on my dataset
/github-pr-workflow create a PR for the auth refactor
/excalidraw       # Just the skill name loads it and lets the agent ask what you need

Você também pode definir quick commands no config.yaml que mapeiam um nome curto para um prompt mais longo:⁹

quick_commands:
  review: "Review my latest git diff and suggest improvements"
  deploy: "Run the deployment script at scripts/deploy.sh and verify the output"
  morning: "Check my calendar, unread emails, and summarize today's priorities"

Depois é só digitar /review, /deploy ou /morning no CLI.

Correspondência por prefixo

Os comandos suportam correspondência por prefixo: digitar /h resolve para /help, /mod resolve para /model. Quando um prefixo é ambíguo, vence o primeiro registro na ordem do registry. Nomes completos de comandos e aliases registrados sempre têm prioridade sobre correspondências por prefixo.⁹

Comandos específicos para mensagens

Alguns comandos só funcionam em plataformas de mensagens (Telegram, Discord, Slack, WhatsApp, Signal, Email, Home Assistant):⁹

• /status — mostra informações da sessão
• /sethome (alias /set-home) — marca o chat atual como home da plataforma
• /approve [session|always] — aprova um comando perigoso pendente
• /deny — rejeita um comando perigoso pendente
• /update — atualiza o Hermes Agent para a versão mais recente
• /commands [page] — navega por todos os comandos e skills (paginado)

E alguns são exclusivos do CLI: /skin, /tools, /toolsets, /browser, /config, /cron, /skills, /platforms, /paste, /statusbar, /plugins.⁹

Ferramentas e Toolsets

O Hermes vem com um amplo registro de ferramentas integradas que cobre busca na web, automação de browser, execução de terminal, edição de arquivos, memória, delegação, treinamento de RL, entrega de mensagens, integração com Home Assistant e muito mais.¹⁰ As ferramentas são organizadas em toolsets lógicos que podem ser ativados ou desativados por plataforma.

Categorias de alto nível

Nomes de toolsets comuns incluem web, terminal, file, browser, vision, image_gen, moa, skills, tts, todo, memory, session_search, cronjob, code_execution, delegation, clarify, homeassistant e rl.¹⁰

Gerenciando ferramentas

hermes chat --toolsets "web,terminal"       # Use specific toolsets
hermes tools                                # Interactive per-platform tool config
hermes tools --summary                      # Print enabled-tools summary

As ferramentas também podem ser ativadas ou desativadas no meio da sessão via /tools disable <name> e /tools enable <name>, o que reinicia a sessão para que o novo conjunto de ferramentas entre em vigor.⁹

Backends de terminal

A ferramenta de terminal pode executar comandos em seis ambientes diferentes:¹⁰

Troque de backend com hermes config set terminal.backend <name> ou no config.yaml:

terminal:
  backend: docker      # or: local, ssh, singularity, modal, daytona
  cwd: "."             # Working directory
  timeout: 180         # Command timeout in seconds

Backend SSH (recomendado por segurança — o agente não pode modificar o próprio código):¹⁰

terminal:
  backend: ssh

# In ~/.hermes/.env
TERMINAL_SSH_HOST=my-server.example.com
TERMINAL_SSH_USER=myuser
TERMINAL_SSH_KEY=~/.ssh/id_rsa

Backend Docker:

terminal:
  backend: docker
  docker_image: python:3.11-slim

Recursos de container (aplica-se a docker, singularity, modal, daytona):¹⁰

terminal:
  container_cpu: 1
  container_memory: 5120          # MB (default 5GB)
  container_disk: 51200           # MB (default 50GB)
  container_persistent: true      # Persist filesystem across sessions

Com container_persistent: true, pacotes instalados, arquivos e configurações sobrevivem entre sessões.¹⁰

Todos os backends de container rodam com hardening de segurança: sistema de arquivos raiz somente leitura (Docker), todas as capabilities do Linux removidas exceto DAC_OVERRIDE, CHOWN e FOWNER, sem escalonamento de privilégios, limites de PID (256 processos), isolamento completo de namespaces, workspace persistente via volumes.¹⁰

Processos em background

A ferramenta de terminal suporta execução em background com gerenciamento explícito de processos:¹⁰

terminal(command="pytest -v tests/", background=true)
# Returns: {"session_id": "proc_abc123", "pid": 12345}

process(action="list")                            # Show all running processes
process(action="poll", session_id="proc_abc123")  # Check status
process(action="wait", session_id="proc_abc123")  # Block until done
process(action="log", session_id="proc_abc123")   # Full output
process(action="kill", session_id="proc_abc123")  # Terminate
process(action="write", session_id="proc_abc123", data="y")  # Send input

O modo PTY (pty=true) habilita ferramentas CLI interativas como Codex e Claude Code.¹⁰

Sudo

Se um comando precisar de sudo, o Hermes solicita sua senha (em cache durante a sessão). Ou defina SUDO_PASSWORD em ~/.hermes/.env.¹⁰

Multi-Agent Kanban (v0.13.0+)

A v0.13.0 transforma a colaboração entre múltiplos agentes em uma primitiva de primeira classe: um Kanban durável que rastreia tarefas, status e identidade do worker entre agentes e entre reinicializações.¹⁸ O board é o que faz com que um swarm de workers do Hermes realmente conclua trabalho em vez de travar em handoffs mortos.

O Kanban combina naturalmente com /goal (Ralph loop com alvo travado) no lado do alvo e com a ferramenta delegate_task existente para semântica de spawn. O resultado é um padrão de swarm em que cada agente compartilha uma única fonte de verdade sobre o que fazer em seguida, quem está fazendo e o que está travado.

Sistema de skills

Skills são documentos de conhecimento sob demanda que o agente pode carregar quando necessário. Eles seguem um padrão de divulgação progressiva para minimizar o uso de tokens e são compatíveis com o padrão aberto agentskills.io.¹¹

Todas as skills ficam em ~/.hermes/skills/ — o diretório principal e fonte de verdade. Em uma instalação nova, as skills empacotadas são copiadas do repositório. Skills instaladas via hub e criadas por agentes também vão para lá.¹¹

Divulgação progressiva

Level 0: skills_list()           → [{name, description, category}, ...]   (~3k tokens)
Level 1: skill_view(name)        → Full content + metadata                 (varies)
Level 2: skill_view(name, path)  → Specific reference file                 (varies)

O agente só carrega o conteúdo completo da skill quando realmente precisa.¹¹

Formato do SKILL.md

---
name: my-skill
description: Brief description of what this skill does
version: 1.0.0
platforms: [macos, linux]      # Optional — restrict to OS platforms
metadata:
  hermes:
    tags: [python, automation]
    category: devops
    fallback_for_toolsets: [web]     # Conditional activation
    requires_toolsets: [terminal]    # Conditional activation
    config:                          # Config.yaml settings
      - key: my.setting
        description: "What this controls"
        default: "value"
        prompt: "Prompt for setup"
---

# Skill Title

## When to Use
Trigger conditions for this skill.

## Procedure
1. Step one
2. Step two

## Pitfalls
- Known failure modes and fixes

## Verificação
Como confirmar que funcionou.

Ativação condicional

Skills podem se mostrar ou se ocultar com base em quais ferramentas estão disponíveis. Isso é mais útil para skills de fallback — alternativas gratuitas ou locais que devem aparecer apenas quando uma ferramenta premium não está disponível:¹¹

Exemplo: a skill embutida duckduckgo-search usa fallback_for_toolsets: [web]. Quando você tem FIRECRAWL_API_KEY definido, o toolset web está disponível e o agente usa web_search — a skill DuckDuckGo permanece oculta. Sem a chave API, a skill DuckDuckGo aparece automaticamente como fallback.¹¹

Skills gerenciadas pelo agente

O agente pode criar, atualizar e deletar suas próprias skills via a ferramenta skill_manage. Esta é a memória procedural do agente — quando ele descobre um workflow não trivial, salva a abordagem como uma skill para reutilização futura.¹¹

Quando o agente cria skills:¹¹ - Após completar uma tarefa complexa (5+ chamadas de ferramenta) com sucesso - Quando encontrou erros ou becos sem saída e descobriu o caminho que funciona - Quando o usuário corrigiu sua abordagem - Quando descobriu um workflow não trivial

Ações:¹¹

Skill Hub

Navegue, pesquise, instale e gerencie skills a partir de registros online:⁶¹¹

hermes skills browse                          # Browse all hub skills
hermes skills browse --source official        # Browse official optional skills
hermes skills search kubernetes               # Search all sources
hermes skills search react --source skills-sh # Search skills.sh directory
hermes skills inspect openai/skills/k8s       # Preview before installing
hermes skills install openai/skills/k8s       # Install with security scan
hermes skills install skills-sh/anthropics/skills/pdf --force
hermes skills check                           # Check for upstream updates
hermes skills update                          # Reinstall changed hub skills
hermes skills audit                           # Re-scan installed hub skills
hermes skills uninstall k8s
hermes skills publish skills/my-skill --to github --repo owner/repo
hermes skills tap add myorg/skills-repo       # Add custom GitHub source

Fontes integradas do hub:¹¹

Taps GitHub padrão (navegáveis sem configuração): openai/skills, anthropics/skills, VoltAgent/awesome-agent-skills, garrytan/gstack.¹¹

Verificação de segurança

Todas as skills instaladas via hub passam por um scanner de segurança que verifica exfiltração de dados, prompt injection, comandos destrutivos, sinais de supply-chain e outras ameaças.¹¹

Níveis de confiança:¹¹

--force pode sobrescrever bloqueios de política não perigosos para skills da comunidade. Não sobrescreve um veredicto de scan dangerous.¹¹

Diretórios externos de skills

Você pode apontar o Hermes para diretórios adicionais de skills, escaneados junto com o local:¹¹

skills:
  external_dirs:
    - ~/.agents/skills
    - /home/shared/team-skills
    - ${SKILLS_REPO}/skills

Os caminhos suportam expansão ~ e substituição de variáveis de ambiente ${VAR}. Diretórios externos são somente leitura — quando o agente cria ou edita uma skill, ele sempre escreve em ~/.hermes/skills/. A precedência local vence se um nome de skill existir em ambos os locais.¹¹

Memória persistente

O Hermes tem memória limitada e curada que persiste entre sessões. Dois arquivos compõem a memória do agente, ambos armazenados em ~/.hermes/memories/:¹²

Ambos são injetados no system prompt como um snapshot congelado no início da sessão. O agente gerencia sua própria memória via a ferramenta memory — add, replace ou remove.¹²

Padrão de snapshot congelado: a injeção do system prompt é capturada uma vez no início da sessão e nunca muda durante a sessão. Isso é intencional — preserva o cache de prefixo do LLM para desempenho. Mudanças feitas durante uma sessão são persistidas em disco imediatamente, mas só aparecem no system prompt na próxima sessão.¹²

O que salvar

Salve estes (o agente faz isso proativamente):¹² - Preferências do usuário: “Prefiro TypeScript a JavaScript” → user - Fatos do ambiente: “Este servidor roda Debian 12 com PostgreSQL 16” → memory - Correções: “Não use sudo para comandos Docker, o usuário está no grupo docker” → memory - Convenções: “O projeto usa tabs, largura de linha de 120 caracteres, docstrings no estilo Google” → memory - Trabalho concluído: “Banco de dados migrado de MySQL para PostgreSQL em 2026-01-15” → memory

Pule estes:¹² - Informações triviais/óbvias - Fatos facilmente redescobertos - Despejos de dados brutos (grandes demais para a memória) - Efêmeros específicos da sessão - Informações já presentes em arquivos de contexto

Busca de sessão

Além de MEMORY.md e USER.md, o agente pode pesquisar conversas passadas usando a ferramenta session_search. Todas as sessões CLI e de mensagens são armazenadas em SQLite (~/.hermes/state.db) com busca de texto completo FTS5. As consultas retornam conversas passadas relevantes com sumarização Gemini Flash.¹²

Provedores externos de memória

Para memória persistente mais profunda além de MEMORY.md e USER.md, o Hermes vem com oito plugins de provedor externo de memória: Honcho, OpenViking, Mem0, Hindsight, Holographic, RetainDB, ByteRover e Supermemory.¹²

Provedores externos rodam junto com a memória embutida (nunca a substituindo) e adicionam recursos como grafos de conhecimento, busca semântica, extração automática de fatos e modelagem de usuário entre sessões:⁶¹²

hermes memory setup         # Pick a provider and configure it
hermes memory status        # Check what's active
hermes memory off           # Disable external provider (built-in only)

Apenas um provedor externo pode estar ativo de cada vez. A memória embutida está sempre ativa.⁶

Auto-retomada de sessão (v0.13.0+)

A v0.13.0 torna a interrupção no meio do agente sobrevivível. O gateway retoma automaticamente sessões interrompidas após uma reinicialização; reinicializações via /update preservam o estado da sessão durante a atualização; recargas de arquivo-fonte durante o desenvolvimento mantêm a sessão ativa viva em vez de forçar uma nova.¹⁸ Efeito prático: trabalhos longos no gateway e jobs disparados por cron não mais resetam sua janela de contexto quando o processo reinicia.

Checkpoints v2 (v0.13.0+)

A persistência de estado foi reescrita na v0.13.0 como um design de armazenamento único com pruning real, salvaguardas de disco e sem repositórios sombra órfãos.¹⁸ O sistema de checkpoint anterior acumulava estado em disco ao longo de profiles de longa duração; o store v2 coloca um teto rígido no armazenamento local de checkpoints e remove a contabilidade duplicada que impulsionava esse crescimento. Nenhuma mudança de configuração visível ao usuário é necessária; a próxima escrita de checkpoint usa o caminho v2.

Personalidade e SOUL.md

SOUL.md é a identidade primária de uma instância do Hermes. Ele ocupa o slot #1 no system prompt, substituindo a identidade padrão hardcoded.¹³

O Hermes cria automaticamente um SOUL.md padrão em ~/.hermes/SOUL.md (ou $HERMES_HOME/SOUL.md para profiles personalizados). Arquivos existentes do usuário nunca são sobrescritos. O Hermes carrega o SOUL.md apenas a partir de HERMES_HOME — ele não procura no diretório de trabalho atual. Isso torna a personalidade previsível entre projetos.¹³

O que pertence ao SOUL.md

Use-o para orientações duradouras de voz e personalidade:¹³ - tom - estilo de comunicação - nível de objetividade - estilo de interação padrão - o que evitar estilisticamente - como o Hermes deve lidar com incerteza, discordância e ambiguidade

Use menos para:¹³ - instruções pontuais de projeto - caminhos de arquivos - convenções de repositório - detalhes temporários de workflow

Esses pertencem ao AGENTS.md, não ao SOUL.md.

SOUL.md vs AGENTS.md

Esta é a distinção mais importante no gerenciamento de identidade do Hermes:¹³

SOUL.md — identidade, tom, estilo, padrões de comunicação, comportamento em nível de personalidade.

AGENTS.md — arquitetura do projeto, convenções de código, preferências de ferramentas, workflows específicos do repo, comandos, portas, caminhos, notas de deploy.

Uma regra útil: se deve te acompanhar em todo lugar, pertence ao SOUL.md. Se pertence a um projeto, pertence ao AGENTS.md.¹³

Personalidades integradas

O Hermes vem com personalidades integradas para as quais você pode alternar com /personality:¹³

Personalidades customizadas em config.yaml:¹³

agent:
  personalities:
    codereviewer: >
      You are a meticulous code reviewer. Identify bugs, security issues,
      performance concerns, and unclear design choices. Be precise and constructive.

Depois alterne com /personality codereviewer.

SOUL.md vs /personality

O SOUL.md é a voz de base. /personality é uma sobreposição em nível de sessão.¹³ Mantenha um SOUL.md padrão pragmático e use /personality teacher para uma conversa de tutoria ou /personality creative para brainstorming.

Nous Tool Gateway (v0.10.0+)

A partir do Hermes Agent v0.10.0 (2026-04-16), assinantes pagos do Nous Portal ganham acesso gerenciado a um conjunto curado de ferramentas através de suas credenciais existentes do Portal — sem chaves API extras para gerenciar.²⁰ O CLI do Hermes em si permanece licenciado em MIT e totalmente open source. O que mudou é que sua autenticação no Portal agora libera mais do que inferência de modelo.

O que está no gateway

Como funciona

O gateway é opt-in por ferramenta via um novo campo de config use_gateway. Se você tiver credenciais do Portal em hermes auth e habilitar o gateway para uma ferramenta, as chamadas dessa ferramenta passam pelo Portal. Caso contrário, sua chave API direta (se presente) é usada.

# config.yaml — per-tool gateway opt-in
tools:
  web_search:
    provider: firecrawl
    use_gateway: true          # route via Nous Portal subscription
  image_generation:
    provider: fal
    use_gateway: true

Precedência em runtime: quando o gateway está disponível e uma ferramenta tem use_gateway: true, o Hermes prefere o gateway mesmo que você também tenha uma chave API direta configurada. Isso importa para o billing — chamadas via gateway são debitadas da sua assinatura do Portal, não do saldo da sua chave API direta.

Habilitando o gateway

hermes model                      # select Nous Portal (OAuth flow)
hermes tools                      # per-platform tool picker integrates gateway tools
hermes status                     # confirms gateway/subscription detection

Não há um comando separado hermes subscribe ou hermes login --portal. A assinatura é detectada automaticamente a partir das credenciais OAuth do Portal que você já tem em hermes auth.

Preço e acesso

Os preços e nomes dos tiers são publicados na página de pricing do Nous Portal (https://portal.nousresearch.com/pricing). Este guia não enumera os tiers porque eles são responsabilidade do produto Portal, não do CLI Hermes, e mudam de forma independente das releases do Hermes. Inscreva-se em https://portal.nousresearch.com/ e confira a página de pricing para os tiers atuais.

Aviso de descontinuação

• A variável de ambiente HERMES_ENABLE_NOUS_MANAGED_TOOLS foi removida na v0.10.0. As ferramentas gerenciadas agora são habilitadas via o campo de config use_gateway por ferramenta e dependem do estado da sua assinatura do Portal.²⁰

Enquadramento: o que esta release não é

O CLI Hermes Agent não está restrito atrás de uma assinatura. O projeto continua licenciado em MIT, todos os recursos centrais (CLI, skills, memory, messaging gateway, cron, MCP, dashboard local, BYOK para todo provedor) funcionam de ponta a ponta sem pagar a ninguém. A v0.10.0 adiciona um caminho de conveniência para usuários que já pagam pelo Nous Portal — ela não remove nada do caminho gratuito.

Messaging Gateway

O Hermes pode rodar como um processo gateway de longa duração que se conecta a 20 plataformas de mensageria a partir de um único processo gateway: Telegram, Discord, Slack, WhatsApp, Signal, SMS, Email, Home Assistant, Mattermost, Matrix, DingTalk, Feishu/Lark, WeCom, Weixin (WeChat), BlueBubbles (iMessage), QQBot, Microsoft Teams, Tencent Yuanbao, Google Chat e um adaptador Webhook genérico.^3191718 A v0.9.0 adicionou iMessage via BlueBubbles (registro automático de webhook, assistente de configuração, resiliência a crashes) e suporte nativo ao WeChat via iLink Bot API com modo de callback WeCom para apps corporativos.¹⁶ A v0.11.0 adicionou QQBot.¹⁹ A v0.12.0 adicionou Microsoft Teams e Tencent Yuanbao.¹⁷ A v0.13.0 adicionou Google Chat como a 20ª plataforma, aproveitando a mesma arquitetura de adaptador plugável; IRC e Microsoft Teams também foram migrados para o novo padrão de adaptador com hooks de plugin genéricos env_enablement_fn / cron_deliver_env_var.¹⁸

Configuração

hermes gateway setup                # Interactive platform configuration
hermes gateway install              # Install as user service (systemd/launchd)
hermes gateway start                # Start the installed service
hermes gateway stop
hermes gateway restart
hermes gateway status
hermes gateway run                  # Run in foreground (debugging)

A configuração interativa te orienta na conexão de cada plataforma: tokens API, IDs de bots, mapeamentos de canais, allowlists.⁶

Como as mensagens fluem

Da documentação de arquitetura upstream:³

Platform event → Adapter.on_message() → MessageEvent
  → GatewayRunner._handle_message()
    → authorize user
    → resolve session key
    → create AIAgent with session history
    → AIAgent.run_conversation()
    → deliver response back through adapter

Toda plataforma de mensageria roda pelo mesmo loop de conversação AIAgent que o CLI. É por isso que slash commands funcionam identicamente nos dois lugares e por que um cron job agendado no Telegram pode entregar sua saída no Discord — a diferença de plataforma fica apenas na borda.³

Autorização e pareamento de usuários

hermes pairing list                    # Show pending and approved users
hermes pairing approve <platform> <code>
hermes pairing revoke <platform> <user-id>
hermes pairing clear-pending

Códigos de pareamento impedem que estranhos aleatórios conversem com seu gateway. Um usuário envia um código de pareamento a partir da sua plataforma de mensageria; você o aprova com hermes pairing approve; a partir daí ele está autorizado.⁶

Tarefas agendadas (Cron)

O Hermes tem um sistema de cron de primeira classe onde os jobs são tarefas de agent, não comandos shell. Cada job agendado roda por um AIAgent novo com o prompt configurado, skills opcionais anexadas, e entrega resultados a qualquer plataforma:³⁶

hermes cron list
hermes cron create --prompt "Check HN for AI news and summarize" --schedule "0 9 * * *" --deliver telegram
hermes cron edit <id>
hermes cron pause <id>
hermes cron resume <id>
hermes cron run <id>         # Trigger now on the next tick
hermes cron remove <id>
hermes cron status           # Check if scheduler is running
hermes cron tick             # Run due jobs once and exit

Ou crie um conversacionalmente dentro de um chat de mensageria:

Every morning at 9am, check Hacker News for AI news and send me a summary on Telegram.

O agent vai configurar o cron job via suas ferramentas. Os jobs persistem em JSON e sobrevivem a reinicializações.³

Integração com MCP

Hermes oferece suporte ao Model Context Protocol tanto como cliente quanto como servidor:⁶

Como cliente — conecte o Hermes a servidores MCP externos para expandir sua superfície de ferramentas:

hermes mcp add <name> --url https://example.com/mcp
hermes mcp add <name> --command npx --args "-y,@modelcontextprotocol/server-github"
hermes mcp list
hermes mcp test <name>
hermes mcp remove <name>
hermes mcp configure <name>   # Toggle individual tool selection

Ou manualmente em config.yaml:¹⁴

mcp_servers:
  github:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxx"

Como servidor — exponha conversas do Hermes para outros agentes:

hermes mcp serve
hermes mcp serve -v    # Verbose

Compressão de contexto

O Hermes comprime automaticamente conversas longas para permanecer dentro da janela de contexto do seu modelo. O sumarizador de compressão é uma chamada LLM separada — você pode apontá-lo para qualquer provedor ou endpoint.⁴

compression:
  enabled: true
  threshold: 0.50                           # Compress at this % of context limit
  target_ratio: 0.20                        # Fraction to preserve as recent tail
  protect_last_n: 20                        # Min recent messages to keep uncompressed
  summary_model: "google/gemini-3-flash-preview"
  summary_provider: "auto"                  # "auto", "openrouter", "nous", "codex", "main", etc.
  summary_base_url: null                    # Custom OpenAI-compatible endpoint

Opções de provedor:⁴

summary_model deve oferecer suporte a um comprimento de contexto pelo menos tão grande quanto o do seu modelo principal, já que ele recebe a seção intermediária completa da conversa para compressão.⁴

Avisos de pressão de orçamento

Quando o agente trabalha em uma tarefa complexa com muitas chamadas de ferramenta, ele pode esgotar seu orçamento de iterações (padrão: 90 turnos) sem perceber. A pressão de orçamento avisa o modelo automaticamente:⁴

Timeouts de stream

A conexão de streaming LLM tem duas camadas de timeout que se ajustam automaticamente para provedores locais (localhost, IPs de LAN):⁴

O timeout de leitura de socket é elevado para 30 minutos em endpoints locais porque LLMs locais podem levar minutos para prefill em contextos grandes antes de produzir o primeiro token.⁴

Dashboard web local (v0.9.0+)

Um dashboard baseado em navegador para gerenciar seu Hermes Agent localmente. Configure ajustes, monitore sessões, navegue por skills e gerencie seu gateway sem tocar em arquivos de configuração ou no terminal.¹⁶ Inicie com hermes dashboard. Este é o caminho de onboarding mais fácil para novos usuários que preferem uma GUI.

Monitoramento de processos em background (v0.9.0+)

watch_patterns permite que você defina padrões para monitorar na saída de processos em background e seja notificado em tempo real quando eles forem correspondidos.¹⁶ Monitore erros, aguarde eventos específicos (“listening on port”) ou observe logs de build — tudo sem polling. Combinado com notify_on_complete da v0.8.0 (que notifica na conclusão de tarefas em background), o Hermes agora tem uma camada completa de observabilidade de processos em background.¹⁵

Context engine plugável (v0.9.0+)

O gerenciamento de contexto agora é um slot plugável via hermes plugins. Conecte context engines customizados que controlam o que o agente vê a cada turno — filtragem, sumarização ou injeção de contexto específica de domínio.¹⁶ Isso desacopla a estratégia de contexto do loop principal do agente, permitindo customização de contexto por projeto ou por domínio.

Backup e restauração (v0.9.0+)

hermes backup cria um arquivo completo da sua configuração, sessões, skills e memória. hermes import restaura a partir de um arquivo de backup.¹⁶ Use isso para migrar entre máquinas, criar snapshots antes de mudanças importantes ou compartilhar uma configuração validada com colegas de equipe.

Suporte a Termux / Android (v0.9.0+)

O Hermes roda nativamente no Android via Termux. Caminhos de instalação adaptados, otimizações de TUI para telas móveis, suporte a backend de voz e o comando /image funcionam no dispositivo.¹⁶

Endurecimento de segurança (v0.13.0+)

A v0.13.0 fechou 8 problemas de segurança P0 e alterou um padrão a favor do usuário.¹⁸

Se você mantém uma implantação do Hermes, trate a v0.13.0 como uma atualização relevante para segurança, não apenas como um lançamento de funcionalidades. O bypass cross-guild do Discord e as duas janelas TOCTOU são exploráveis em versões anteriores.

Arquitetura para profissionais

Esta seção é para quem quer entender o que está acontecendo por baixo dos panos para poder depurar, estender ou raciocinar sobre desempenho. É uma síntese da documentação de arquitetura upstream.³

Pontos de entrada → AIAgent

Todo ponto de entrada no Hermes acaba chamando AIAgent.run_conversation():

┌──────────────────────────────────────────────────────────────────┐
│                        Entry Points                              │
│                                                                  │
│  CLI (cli.py)    Gateway (gateway/run.py)    ACP (acp_adapter/)  │
│  Batch Runner    API Server                  Python Library     │
└──────────┬──────────────┬───────────────────────┬────────────────┘
           │              │                       │
           ▼              ▼                       ▼
┌──────────────────────────────────────────────────────────────────┐
│                     AIAgent (run_agent.py)                       │
│                                                                  │
│  ┌─────────────┐  ┌──────────────┐  ┌──────────────┐             │
│  │ Prompt      │  │ Provider     │  │ Tool         │             │
│  │ Builder     │  │ Resolution   │  │ Dispatch     │             │
│  └──────┬──────┘  └──────┬───────┘  └──────┬───────┘             │
│         │                │                 │                    │
│  ┌──────┴───────┐ ┌──────┴───────┐  ┌──────┴───────┐             │
│  │ Compression  │ │ 3 API Modes  │  │ Tool Registry│             │
│  │ & Caching    │ │ chat_compl   │  │ 47 tools     │             │
│  │              │ │ codex_resp   │  │ 20 toolsets  │             │
│  │              │ │ anthropic    │  │              │             │
│  └──────────────┘ └──────────────┘  └──────────────┘             │
└──────────────────────────────────────────────────────────────────┘

Diagrama adaptado da documentação de arquitetura upstream.³

“47 tools / 20 toolsets” vs “28 tools” no seu banner. A contagem de “47 tools” é o total do registro de ferramentas do repositório upstream — toda ferramenta que o Hermes traz com código-fonte, em todos os toolsets. Seu CLI em execução vai mostrar um número menor no banner de inicialização (a instalação contra a qual verifiquei este guia reporta 28 tools / 89 skills). Isso não é um bug. Muitos toolsets são opt-in e precisam ser explicitamente habilitados em config.yaml na seção toolsets: — adaptadores de plataformas de mensageria, automação de browser, ferramentas de scraping mais pesadas, etc. O total do registro é “o que está disponível”; o número do banner é “o que está habilitado no seu profile atual.” Verifique quais toolsets estão ativos com hermes tools --list e habilite ou desabilite toolsets individuais com o bloco toolsets: em ~/.hermes/config.yaml (ou /tools list / /tools enable <name> / /tools disable <name> dentro de uma sessão em execução — remover uma ferramenta dispara um reset de sessão para que o agente reconstrua seu manifesto de ferramentas).

Os três modos de API

O Hermes abstrai diferenças entre providers em três modos de API, selecionados automaticamente em tempo de execução:³

O resolver runtime_provider.py mapeia tuplas (provider, model) para (api_mode, api_key, base_url) para mais de 18 providers, lidando com fluxos de OAuth, pools de credenciais e resolução de aliases.³

Fluxo de dados em uma sessão de CLI

User input → HermesCLI.process_input()
  → AIAgent.run_conversation()
    → prompt_builder.build_system_prompt()
    → runtime_provider.resolve_runtime_provider()
    → API call (chat_completions / codex_responses / anthropic_messages)
    → tool_calls? → model_tools.handle_function_call() → loop
    → final response → display → save to SessionDB

Da página de arquitetura upstream.³

Ordem de montagem do prompt

A pilha de prompts inclui:¹³

1. SOUL.md (identidade do agente — ou fallback embutido, se indisponível)
2. Orientação de comportamento ciente de ferramentas
3. Memória/contexto do usuário (MEMORY.md, USER.md)
4. Orientação de skills
5. Arquivos de contexto (AGENTS.md, .cursorrules)
6. Timestamp
7. Dicas de formatação específicas da plataforma
8. Overlays opcionais de system prompt, como /personality

SOUL.md é a base — todo o resto se constrói sobre ele.¹³

Armazenamento de sessões

Armazenamento de sessões baseado em SQLite com busca full-text FTS5. As sessões têm rastreamento de linhagem (pai/filho ao longo de compressões), isolamento por plataforma e escritas atômicas com tratamento de contenção.³

Sistema de plugins

Três fontes de descoberta: ~/.hermes/plugins/ (usuário), .hermes/plugins/ (projeto) e entry points do pip. Plugins registram ferramentas, hooks e comandos de CLI por meio de uma API de contexto. Provedores de memória são um tipo especializado de plugin em plugins/memory/.³

hermes plugins                       # Interactive enable/disable UI
hermes plugins install <repo>        # Install from Git URL or owner/repo
hermes plugins enable <name>
hermes plugins disable <name>
hermes plugins list

Princípios de design

Da página de arquitetura upstream:³

Migração do OpenClaw

O Hermes Agent é o sucessor do OpenClaw. Se você está migrando de uma instalação existente do OpenClaw:⁶⁵

hermes claw migrate --dry-run                    # Preview what would be migrated
hermes claw migrate --preset full                # Full migration including API keys
hermes claw migrate --preset user-data --overwrite   # User data only, no secrets
hermes claw migrate --source /custom/path        # Non-default OpenClaw location

hermes claw migrate lê de ~/.openclaw por padrão (também detecta automaticamente diretórios legados ~/.clawdbot e ~/.moldbot) e escreve em ~/.hermes.⁶

Importados diretamente (mais de 30 categorias): SOUL.md, MEMORY.md, USER.md, AGENTS.md, skills de 4 diretórios de origem, modelo padrão, providers customizados, servidores MCP, tokens e allowlists de plataformas de mensageria (Telegram, Discord, Slack, WhatsApp, Signal, Matrix, Mattermost), padrões do agente (esforço de raciocínio, compressão, atraso humano, timezone, sandbox), políticas de reset de sessão, regras de aprovação, configuração de TTS, configurações de browser, configurações de ferramentas, timeout de exec, allowlist de comandos, configuração de gateway e chaves de API de 3 fontes.⁶

Arquivados para revisão manual: jobs de cron, plugins, hooks/webhooks, backend de memória (QMD), config do registry de skills, UI/identidade, logging, setup multi-agente, vinculações de canais, IDENTITY.md, TOOLS.md, HEARTBEAT.md, BOOTSTRAP.md.⁶

A resolução de chaves de API verifica três fontes em ordem de prioridade: valores de config → ~/.openclaw/.env → auth-profiles.json.⁶

Solução de problemas

“API key not set”

Execute hermes model para configurar seu provedor de forma interativa, ou hermes config set OPENROUTER_API_KEY your_key. O comando hermes doctor informará exatamente quais chaves estão faltando.⁷

“Context limit: 2048 tokens” na inicialização (modelos locais)

O Hermes detecta automaticamente o tamanho do contexto a partir do endpoint /v1/models do seu servidor, mas muitos servidores locais reportam padrões baixos. Defina explicitamente no config.yaml:²

model:
  default: your-model
  provider: custom
  base_url: http://localhost:11434/v1
  context_length: 32768

Chamadas de ferramentas aparecem como texto em vez de serem executadas

Seu servidor não tem o tool calling habilitado, ou o modelo não oferece suporte a isso por meio da implementação do servidor.²

As respostas são cortadas no meio da frase

Duas causas possíveis:²

1. Limite baixo de saída (max_tokens) no servidor — o SGLang usa o padrão de 128 tokens por resposta. Defina --default-max-tokens no servidor ou configure model.max_tokens no config.yaml.
2. Esgotamento de contexto — o modelo encheu sua janela de contexto. Aumente model.context_length ou habilite a compressão de contexto no Hermes.

“Connection refused” do WSL2 para um servidor de modelo hospedado no Windows

O WSL2 usa um adaptador de rede virtual com sua própria sub-rede — localhost dentro do WSL2 se refere à VM Linux, não ao host Windows. Duas opções:²

Rede espelhada (Windows 11 22H2+): edite %USERPROFILE%\.wslconfig:

[wsl2]
networkingMode=mirrored

Em seguida, execute wsl --shutdown e reinicie. localhost agora funciona bidirecionalmente.

Fallback de IP do host (Windows mais antigo): obtenha o IP do host Windows de dentro do WSL2 e use-o em vez de localhost:

ip route show | grep -i default | awk '{ print $3 }'
# Use that IP as the base_url host

Você também precisa que o servidor de modelo faça bind em 0.0.0.0, não em 127.0.0.1 — defina OLLAMA_HOST=0.0.0.0 para o Ollama, adicione --host 0.0.0.0 para llama-server/SGLang ou habilite “Serve on Network” no LM Studio.²

Onde está tudo?

hermes status e hermes dump são seus aliados aqui. hermes logs list mostra todos os arquivos de log com seus tamanhos. hermes config path imprime a localização do arquivo de configuração. hermes config env-path imprime a localização do .env.⁶

FAQ

Qual é a diferença entre Hermes Agent e Claude Code?

Claude Code é o CLI oficial da Anthropic, fixado nos modelos da Anthropic. Hermes Agent é um framework de agente open-source da Nous Research que funciona com qualquer provedor compatível com OpenAI — Nous Portal, OpenRouter, Anthropic, GitHub Copilot, z.ai, Kimi, MiniMax, DeepSeek, Hugging Face, Google ou seu próprio endpoint auto-hospedado.¹² O Hermes também traz um messaging gateway para Telegram/Discord/Slack/WhatsApp/Signal que o Claude Code não tem.

Posso usar o Hermes com uma API key da Anthropic?

Sim. Três formas:²

1. Defina ANTHROPIC_API_KEY em ~/.hermes/.env e execute hermes chat --provider anthropic --model claude-sonnet-4-6
2. Execute hermes model e selecione Anthropic — o Hermes usará o credential store do Claude Code quando disponível
3. Defina um ANTHROPIC_TOKEN manual (setup-token ou token OAuth) como fallback

A opção 2 é preferível se você já usa o Claude Code na mesma máquina — ela mantém as credenciais Claude refresháveis renováveis.

Como troco de provedor sem perder minha conversa?

Use /model provider:model dentro de uma sessão. O histórico da conversa, a memória e as skills são todos preservados:⁹

/model zai:glm-5
/model openrouter:anthropic/claude-sonnet-4
/model custom:local:qwen-2.5

Configurei o Anthropic, mas vision/web/compressão não funcionam

Você está caindo no fallback do modelo auxiliar. Vision, sumarização web, compressão e outras tarefas auxiliares usam um LLM auxiliar separado — por padrão Gemini Flash via detecção automática (OpenRouter → Nous → Codex). Se nenhum desses estiver configurado e você só tiver Anthropic configurado, esses recursos degradam silenciosamente.⁴

Correção: ou adicione uma OPENROUTER_API_KEY para tarefas auxiliares, ou reconfigure os slots auxiliares para usarem seu provedor principal. Observe que a compressão de contexto fica em seu próprio bloco compression: de nível superior e aceita summary_provider, não auxiliary.compression.provider — o slot auxiliary.compression só expõe um timeout. Correção completa:

auxiliary:
  vision:      { provider: "main" }
  web_extract: { provider: "main" }

compression:
  summary_provider: "main"

Qual é a diferença entre SOUL.md e AGENTS.md?

SOUL.md é a identidade do seu agente — tom, estilo, padrões de comunicação. Ele fica em ~/.hermes/SOUL.md e te acompanha em todo lugar. AGENTS.md é específico do projeto — arquitetura, convenções, comandos, paths — e fica no diretório do seu projeto.¹³ Se deve acompanhar você em todo lugar, SOUL.md. Se pertence a um projeto, AGENTS.md.

Como executo várias instâncias do Hermes lado a lado?

Profiles. Cada profile recebe seu próprio HERMES_HOME, config, memória, sessões e PID do gateway:⁶

hermes profile create work --clone
hermes profile use work                 # Sticky default
hermes -p work chat -q "..."            # One-off without switching
hermes profile alias work --name h-work # Wrapper script

O Hermes oferece suporte a LLMs locais?

Sim, por meio do caminho de endpoint custom. O Hermes funciona com qualquer servidor compatível com OpenAI: Ollama, vLLM, SGLang, llama.cpp/llama-server, LM Studio, LocalAI, Jan ou o seu próprio.² Veja Custom & Self-Hosted Endpoints para a configuração de cada servidor.

Por que meu banner de inicialização mostra menos ferramentas do que o guia diz que o Hermes tem?

O guia cita 47 ferramentas / 20 toolsets a partir do registry de arquitetura upstream — esse é o total de ferramentas para as quais o Hermes envia código-fonte em todos os toolsets. Sua instalação em execução mostra um número menor no banner (a instalação de referência usada para este guia reporta 28 ferramentas) porque o Hermes só habilita o conjunto padrão de toolsets na inicialização. Muitos toolsets são opt-in: adaptadores do messaging gateway, automação de browser, stacks mais pesadas de scraping e várias integrações especializadas precisam ser listadas explicitamente em toolsets: em ~/.hermes/config.yaml antes de carregarem. Total do registry = “o que está disponível se você habilitar.” Total do banner = “o que seu profile atual realmente carregou.” Use hermes tools --list para ver quais toolsets estão ativos e quais estão disponíveis, mas desabilitados. Alterne toolsets individuais em runtime com /tools enable <name> e /tools disable <name> (desabilitar dispara um reset de sessão para que o agente reconstrua seu manifesto de ferramentas com o novo formato).

Como o Hermes lida com o fallback de modelo quando meu provedor primário falha?

Configure um bloco fallback_model no config.yaml:²

fallback_model:
  provider: openrouter
  model: anthropic/claude-sonnet-4

Quando o primário falha (rate limit, erro de servidor, falha de autenticação), o Hermes troca para o fallback no meio da sessão sem perder o histórico da conversa. Dispara no máximo uma vez por sessão.

O agente pode melhorar suas próprias skills ao longo do tempo?

Sim — essa é a parte “self-improving” do Hermes Agent. O agente pode criar, atualizar e excluir skills via a ferramenta skill_manage. Quando descobre um workflow não trivial, ele salva a abordagem como uma skill para reutilização futura.¹¹ O agente cria skills depois de tarefas complexas (5+ chamadas de ferramentas), quando encontra erros e descobre o caminho que funciona, quando você corrige sua abordagem ou quando descobre um workflow não trivial.

Existe uma integração com IDE?

Sim — o Hermes pode rodar como um servidor ACP (Agent Client Protocol) para VS Code, Zed e JetBrains:⁶

pip install -e '.[acp]'
hermes acp

Changelog

Referências