Hermes Agent: referência do profissional (2026)

Resumo: Hermes Agent é um agente de IA open-source e autoaprimorável da Nous Research. Ele roda como 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 LLM compatível com OpenAI — Nous Portal, OpenRouter, Anthropic, GitHub Copilot, z.ai, Kimi, MiniMax, DeepSeek, Qwen Cloud, Hugging Face, Google, xAI/SuperGrok ou seu próprio endpoint auto-hospedado.¹²¹⁹ A partir da v0.14.0 (16 de maio de 2026), Hermes adiciona SuperGrok OAuth com contexto de 1M do grok-4.3, um proxy local compatível com OpenAI para provedores OAuth (hermes proxy), x_search de primeira classe, suporte a instalação via PyPI, instalação preguiçosa de dependências, 22 plataformas de mensagens com LINE e SimpleX Chat, /handoff, diagnósticos semânticos LSP após escritas, video_generate unificado, computer_use via cua-driver para provedores que não são Anthropic, beta nativo para Windows e fechamento de 12 P0 / 50 P1.¹⁹ A parte mais difícil para a maioria dos novos usuários é a autenticação de provedores: Hermes oferece suporte a cerca de 20 provedores de primeira classe, além de endpoints personalizados, e três caminhos distintos de autenticação (chave API em .env, OAuth via hermes model ou endpoint personalizado em config.yaml). O modelo de autenticação é a primeira coisa que você deve aprender — todo o resto depende de qual provedor é resolvido.

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

A diferença entre o uso casual e especialista do Hermes se resume a cinco sistemas. Domine estes pontos e o Hermes vira um multiplicador de força:

1. Resolução de provedores: como os fluxos de autenticação mapeiam para chamadas API
2. Hierarquia de configuração: config.yaml + .env + auth.json + SOUL.md + AGENTS.md
3. Sistema de tools + 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 Hermes onde você vive, não só onde você está

Principais conclusões

• A autenticação de provedores tem três caminhos, não um. Chave API em .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 mais familiar.
• Trocar de provedor é um único comando. hermes model guia você interativamente por todos os provedores compatíveis, incluindo logins OAuth, e /model provider:model troca 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 guarda configurações e ~/.hermes/.env guarda segredos. auth.json, SOUL.md, MEMORY.md e skills/ são gerenciados diretamente pelo Hermes — você pode editar SOUL.md manualmente, mas o restante é alterado pelo próprio agente.⁴
• Hermes é o sucessor do OpenClaw. Se você está migrando, hermes claw migrate importa automaticamente mais de 30 categorias de estado.⁵
• A qualidade do serviço depende do seu modelo auxiliar. Visão, resumo da web, compressão e flush de memória usam um LLM auxiliar separado. Por padrão, ele é Gemini Flash via autodetecção (OpenRouter → Nous → Codex) — se nenhum deles estiver configurado, esses recursos degradam silenciosamente até você apontar os slots auxiliares para seu provedor principal.⁴

O que muda na v0.14

A v0.14.0 tem menos a ver com um recurso principal e mais com reduzir o atrito de configuração enquanto amplia onde o Hermes pode rodar.¹⁹ As principais mudanças operacionais:

• Instalação e inicialização estão mais leves. pip install hermes-agent funciona pelo PyPI, adaptadores pesados são instalados de forma preguiçosa no primeiro uso, e o caminho de inicialização adia trabalho suficiente para reduzir a partida a frio em cerca de 19 segundos.
• Assinaturas podem virar endpoints API locais. hermes proxy transforma provedores apoiados por OAuth, como Claude Pro, ChatGPT Pro e SuperGrok, em um endpoint local compatível com OpenAI para ferramentas como Codex, Aider, Cline e Continue.
• O alcance do gateway aumenta. LINE e SimpleX Chat elevam a contagem de plataformas para 22, Microsoft Teams está conectado de ponta a ponta, o backfill de histórico do Discord vem ativado por padrão, e prompts clarify no Telegram/Discord agora usam botões nativos.
• A verificação no momento da escrita melhora. Após edições, Hermes pode mostrar resumos de mutações de arquivos por turno e diagnósticos semânticos de language-server antes do próximo turno, aproximando-o de um trabalho de agente orientado por evidências.
• Ferramentas de desktop e mídia ficam mais amplas. computer_use funciona por meio do cua-driver para provedores que não são Anthropic, video_generate é unificado por trás de backends plugáveis, e vision_analyze envia pixels brutos para modelos que realmente conseguem enxergar.

Cada seção abaixo se baseia 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 veio.

Escolha seu caminho

Como Hermes funciona: o modelo mental

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

1. Monta 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 em runtime via runtime_provider.py — esta é a etapa que escolhe 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. Encaminha qualquer chamada de ferramenta retornada por meio de model_tools.py e do registro central de ferramentas (tools/registry.py)³
5. Continua o loop até o modelo produzir uma resposta final e então persiste a sessão no SQLite com FTS5³

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

Núcleo independente de plataforma. Uma classe AIAgent atende ao 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 que os mesmos comandos slash funcionam no terminal e 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. Hermes armazena tudo em ~/.hermes/ (ou $HERMES_HOME para profiles não padrão):⁴

~/.hermes/
├── config.yaml        # Settings (model, terminal, TTS, compression, etc.)
├── .env               # API keys and secrets
├── 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)

Cada arquivo acima tem uma função específica; nenhum deles se sobrepõe. Se você está procurando “onde Hermes armazena X”, está em um deles.

Instalação

O instalador de uma linha continua sendo o caminho guiado para a maioria 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.⁷ A v0.14.0 também traz um pacote PyPI real, então pip install hermes-agent agora é uma instalação direta viável quando você já controla o ambiente Python.¹⁹

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

pip install hermes-agent
hermes

Funciona em Linux, macOS, WSL2 e Android/Termux (o instalador detecta Termux automaticamente e muda para um bundle Android testado).⁷ A v0.14.0 adiciona suporte nativo ao Windows em beta inicial por meio de um instalador PowerShell, mas WSL2 continua sendo a recomendação mais segura para uso em produção até o caminho do Windows amadurecer.¹⁹

Depois que terminar:

source ~/.bashrc    # or ~/.zshrc
hermes              # Start chatting

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

Verifique a instalação

hermes version      # Check version
hermes doctor       # Diagnose config/dependency issues
hermes status       # Show current configuration + auth state
hermes dump         # Copy-pasteable setup summary for debugging

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 thread do Discord ao pedir ajuda — é um resumo em texto simples de toda a sua configuração, com segredos ocultados.⁸

Instalação manual

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

O comando de instalação do 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 faster-whisper via o extra voice, que depende de wheels ctranslate2 que não são publicados para Android.⁷

autenticação e provedores

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

os três caminhos de autenticação

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

Caminho 1 — chave API no .env. Coloque sua chave em ~/.hermes/.env e 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 código de dispositivo, 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 customizado 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 auto-hospedado. Configurado uma vez via hermes model → Custom endpoint e 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 de cada um.²

Anthropic: três métodos de autenticação

Anthropic recebe sua própria seção porque Hermes oferece suporte a três caminhos distintos para Claude, e escolher o certo faz diferença. Da 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 pelo hermes model, Hermes prefere o armazenamento de credenciais do próprio Claude Code em vez de copiar o token para ~/.hermes/.env. Isso mantém as credenciais Claude renováveis como renová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

Copilot é compatível em dois modos: API direto do Copilot (recomendado) e Copilot ACP (que inicia o CLI local do Copilot como um 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, de acordo com 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 do CLI gh auth token 5. login por código de dispositivo OAuth via hermes model

O tipo de token importa. O API do Copilot não oferece suporte a Personal Access Tokens clássicos (ghp_*). Os tipos aceitos são tokens OAuth (gho_*), PATs refinados (github_pat_* com permissão Copilot Requests) e tokens de GitHub App (ghu_*). Se seu gh auth token retornar um token ghp_*, use hermes model para autenticar via OAuth.²

provedores chineses de AI (suporte de primeira classe)

Hermes tem suporte integrado para z.ai/GLM, Kimi/Moonshot, MiniMax (endpoints globais + 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, Hermes testa vários endpoints (global, China, variantes de coding) para encontrar um que aceite sua chave API. O endpoint funcional é armazenado em cache automaticamente — GLM_BASE_URL não é necessário para a maioria dos usuários.²

xAI (Grok) habilita cache de prompt automaticamente. Quando a URL base contém x.ai, Hermes envia o cabeçalho x-grok-conv-id em todas as solicitações para rotear para o mesmo servidor dentro de uma sessão de conversa, reutilizando prompts de sistema e histórico em cache.² É automático; nenhuma 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ê alterna várias chaves 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 customizados e auto-hospedados

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

Configuração interativa (recomendada):

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

As duas abordagens persistem em config.yaml, que é a fonte única de verdade para modelo principal, provedor e URL base.² As variáveis de ambiente legadas OPENAI_BASE_URL e LLM_MODEL não são mais lidas para configuração do modelo principal — use hermes model ou edite config.yaml diretamente.² (OPENAI_BASE_URL + OPENAI_API_KEY ainda são respeitadas como fallback para o caminho auxiliar de roteamento provider: "main", então não as exclua sem pensar se você as usa ali.)⁴

Trocar endpoints customizados no meio da 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 (simples, sem nome de modelo) consulta o API /v1/models do seu endpoint e seleciona automaticamente o modelo se exatamente um estiver carregado — útil para servidores locais rodando um único modelo.²

servidores LLM locais (modelos de configuração)

A documentação upstream tem guias completos de configuração para Ollama, vLLM, SGLang, llama.cpp e LM Studio. Aqui estão os comandos principais que você realmente vai executar. Cada um foi pensado para produzir um endpoint funcional ao qual Hermes possa apontar.²

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

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 usa por padrão contextos muito baixos (4.096 tokens abaixo de 24GB de VRAM). Você precisa aumentá-lo via OLLAMA_CONTEXT_LENGTH ou um Modelfile — o API compatível com OpenAI não aceita tamanho de contexto do cliente, então Hermes não consegue defini-lo para você.² Para uso com agentes, 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

Chamadas de ferramentas exigem --enable-auto-tool-choice e --tool-call-parser <name>. Parsers compatíveis: hermes (Qwen 2.5, Hermes 2/3), llama3_json, mistral, deepseek_v3, deepseek_v31, xlam, pythonic. Sem essas flags, as chamadas de ferramentas voltarão como texto simples.²

SGLang — serving rápido com RadixAttention para reutilização do 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 forem 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 é obrigatório para chamadas de ferramentas. Sem ele, llama-server ignora totalmente o parâmetro tools e o modelo tenta chamar ferramentas escrevendo JSON no texto da resposta — o que Hermes não consegue analisar como chamadas de ferramenta 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 hermes model para http://localhost:1234/v1.

Pegadinha crítica do LM Studio: o LM Studio lê o tamanho de contexto dos metadados do modelo, mas muitos modelos GGUF informam 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” como pelo menos 16384 (de preferência 32768) e recarregue o modelo.²

provedores customizados nomeados

Se você trabalha com vários endpoints customizados (um servidor local de desenvolvimento e um servidor GPU remoto, por exemplo), defina-os como provedores customizados 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 no meio da 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 customizados nomeados pelo menu interativo hermes model.²

arquitetura de provedores plugável (v0.13.0+)

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

proxy local compatível com OpenAI (v0.14.0+)

hermes proxy expõe um endpoint local compatível com OpenAI apoiado pelo provedor OAuth no qual Hermes já está conectado — Claude Pro, ChatGPT Pro, SuperGrok ou outro provedor compatível configurado.¹⁹ Isso significa que ferramentas que esperam um API no estilo OpenAI, incluindo CLI Codex, Aider, Cline, Continue ou scripts customizados, podem reutilizar sua autenticação Hermes baseada em assinatura sem uma chave API separada. Trate o proxy como infraestrutura local de desenvolvimento: vincule-o intencionalmente, não o exponha amplamente e leve em conta os termos específicos de cada provedor.

detecção de tamanho de contexto

Duas configurações são confundidas o tempo todo, segundo a documentação upstream:²

• context_length — a janela total de contexto (orçamento combinado de tokens de entrada + saída, por exemplo, 1.000.000 para Claude Opus 4.7 ou 200.000 para Sonnet 4.6). Hermes usa isso para decidir quando comprimir o histórico.
• model.max_tokens — o limite de saída (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 detecção automática errar o tamanho da janela:

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

Hermes usa uma cadeia de resolução com várias fontes para detectar janelas de contexto: sobrescrita de configuração → provedor customizado por modelo → cache persistente → endpoint /models → /v1/models do Anthropic → API OpenRouter → Nous Portal → models.dev (registro mantido pela comunidade para mais de 3800 modelos) → padrões de fallback (128K).² O sistema é ciente do provedor, então o mesmo modelo pode ter limites de contexto diferentes dependendo de quem o serve (por exemplo, claude-opus-4.6 é 1M no Anthropic direto, mas 128K no GitHub Copilot).²

rotação e fallback de provedores

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

Modelo de fallback. Configure um provider:model de backup para o qual Hermes alterna automaticamente quando seu modelo principal falha (limites de taxa, erros do servidor, falhas de autenticação):²

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 modelo e provedor no meio da sessão sem perder sua conversa. Ele dispara no máximo uma vez por sessão.² Provedores compatíveis com 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

Hermes usa modelos “auxiliares” leves para tarefas paralelas: análise de imagens, resumo de páginas web, análise de screenshots do navegador, classificação de aprovação de comandos perigosos, compressão de contexto, resumo de busca de sessão, correspondência de skill, despacho de ferramenta MCP e flush de memória.⁴ Por padrão, eles usam Gemini Flash por detecção automática (OpenRouter → Nous → Codex).

Você pode configurar qual modelo e provedor cada tarefa auxiliar usa. Todo slot auxiliar usa os mesmos três controles: 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 provedor "main" significa “use qualquer provedor que meu agente principal usa” — válida apenas dentro das configs auxiliary:, compression: e fallback_model:. Ela não é válida para sua configuração de nível superior model.provider. Se você usa um endpoint customizado compatível com OpenAI como modelo principal, defina provider: custom na seção model:.⁴

Por que isso importa: se você configurou apenas OAuth do Anthropic (sem chave OpenRouter), visão, resumo web e compressão vão degradar ou falhar porque a cadeia padrão de fallback auxiliar tenta OpenRouter primeiro. Adicione uma 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 mais comum de “meus recursos simplesmente não funcionam” para novos usuários do Hermes.

Sistema de configuração

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

Layout dos arquivos de configuração

De acordo com a documentação upstream, 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, config.yaml tem prioridade para configurações que não são secretas.⁴ A regra é: - Secrets (chaves API, tokens de bots, senhas) → .env - Todo o resto (model, backend do terminal, configurações de compactação, limites de memory, toolsets) → config.yaml

Secrets podem ser referenciados em 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}

Gerenciamento da 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 para executar depois de cada hermes update — eles identificam novas opções de configuração adicionadas que o seu arquivo ainda não tem.⁶

Precedência da configuração

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

1. Argumentos CLI — hermes chat --model anthropic/claude-sonnet-4 (substituição 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 — somente secrets
5. Padrões integrados — aplicados quando nada mais define um valor

Flags CLI sempre vencem para aquela única invocação. config.yaml é a fonte da verdade de longo prazo.

Localização (v0.13.0+)

v0.13.0 adicionou 7 locales para mensagens de CLI e gateway: chinês (simplificado), japonês, alemão, espanhol, francês, ucraniano e turco.¹⁸ v0.14.0 localiza todos os comandos de gateway e o dashboard web, adiciona mais 8 locales e eleva o total para 16.¹⁹ No momento, a documentação está localizada apenas em zh-Hans. O locale é resolvido pelas variáveis de ambiente LC_ALL / LANG ou por uma chave locale: explícita em config.yaml. O inglês continua sendo o padrão e a fonte da verdade para qualquer string que uma tradução ainda não cobre.

Profiles — várias instâncias isoladas do Hermes

Profiles permitem que você tenha várias instâncias isoladas do Hermes, cada uma com sua própria configuração, sessions, skills, memory e PID de gateway. É assim que você executa “Hermes de trabalho” e “Hermes pessoal” lado a lado sem que uma instância veja o estado da outra.⁶

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), então vários profiles podem executar o gateway ao mesmo tempo sem interferir uns nos 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

Comandos slash são executados dentro de uma sessão de chat ativa (CLI ou plataforma de mensagens). Eles são despachados de um COMMAND_REGISTRY compartilhado em hermes_cli/commands.py, por isso 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 principal recurso para trocar de provider 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

Tools, skills e informações

Comandos slash dinâmicos de skill

Todo skill instalado é exposto automaticamente 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 comandos rápidos em config.yaml, criando um alias de 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, digite /review, /deploy ou /morning no CLI.

Correspondência por prefixo

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

Comandos específicos de mensagens

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

• /status — mostrar informações da sessão
• /sethome (alias /set-home) — marcar o chat atual como home da plataforma
• /approve [session|always] — aprovar um comando perigoso pendente
• /deny — rejeitar um comando perigoso pendente
• /update — atualizar o Hermes Agent para a versão mais recente
• /commands [page] — navegar 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.⁹

Tools e toolsets

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

Categorias de alto nível

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

Gerenciando tools

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

As tools também podem ser alternadas 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 tools entre em vigor.⁹

Backends de terminal

A tool de terminal pode executar comandos em 6 ambientes diferentes:¹⁰

Alterne backends com hermes config set terminal.backend <name> ou em config.yaml:

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

Backend SSH (recomendado para segurança — o agente não consegue 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 contêiner (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 contêiner rodam com reforço de segurança: sistema de arquivos raiz somente leitura (Docker), todas as capacidades Linux removidas exceto DAC_OVERRIDE, CHOWN e FOWNER, sem escalonamento de privilégios, limites de PID (256 processos), isolamento completo de namespace, workspace persistente via volumes.¹⁰

Processos em segundo plano

A tool de terminal oferece suporte à execução em segundo plano 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 tools interativas CLI como Codex e Claude Code.¹⁰

Sudo

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

Kanban multiagente (v0.13.0+)

A v0.13.0 transforma a colaboração multiagente em uma primitiva de primeira classe: um quadro Kanban durável que acompanha tarefas, status e identidade dos workers entre agentes e reinicializações.¹⁸ O quadro é o que faz um swarm de workers Hermes realmente concluir o trabalho, em vez de travar em handoffs mortos.

O quadro Kanban combina naturalmente com /goal (loop Ralph de alvo travado) para o lado do alvo e com a tool delegate_task existente para a semântica de spawn. O resultado é um padrão de swarm em que todos os agentes compartilham 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.¹¹

Todos os skills ficam em ~/.hermes/skills/ — o diretório principal e a fonte da verdade. Em uma instalação nova, os skills incluídos são copiados do repositório. Skills instalados pelo hub e criados pelo agente também vão para cá.¹¹

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 do skill quando realmente precisa dele.¹¹

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

## Verification
How to confirm it worked.

Ativação condicional

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

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

Skills gerenciados pelo agente

O agente pode criar, atualizar e excluir seus próprios skills por meio da ferramenta skill_manage. Esta é a memória procedural do agente — quando ele descobre um workflow não trivial, salva a abordagem como um skill para reutilização futura.¹¹

Quando o agente cria skills:¹¹ - Depois de concluir uma tarefa complexa (5+ chamadas de ferramentas) 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:¹¹

Hub de skills

Navegue, pesquise, instale e gerencie skills 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 de hub integradas:¹¹

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

Verificação de segurança

Todos os skills instalados pelo hub passam por um scanner de segurança que verifica exfiltração de dados, prompt injection, comandos destrutivos, sinais de cadeia de suprimentos e outras ameaças.¹¹

Níveis de confiança:¹¹

--force pode substituir bloqueios de política não perigosos para skills da comunidade. Ele não substitui um veredito de varredura dangerous.¹¹

Diretórios externos de skills

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

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

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

Memória persistente

Hermes tem uma 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 prompt do sistema como um snapshot congelado no início da sessão. O agente gerencia a própria memória pela ferramenta memory — add, replace ou remove.¹²

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

O que salvar

Salve isto (o agente faz isso proativamente):¹² - Preferências do usuário: “Prefiro TypeScript em vez de 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: “Migrou o banco de dados de MySQL para PostgreSQL em 2026-01-15” → memory

Ignore isto:¹² - Informações triviais/óbvias - Fatos fáceis de redescobrir - Dumps de dados brutos (grandes demais para a memória) - Efêmeros específicos da sessão - Informações que já estão em arquivos de contexto

Busca de sessões

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

Provedores externos de memória

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

Provedores externos rodam junto com a memória integrada (nunca a substituem) e adicionam recursos como grafos de conhecimento, busca semântica, extração automática de fatos e modelagem de usuários 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 por vez. A memória integrada está sempre ativa.⁶

Retomada automática de sessão (v0.13.0+)

A v0.13.0 torna interrupções no meio do agente recuperáveis. O gateway retoma automaticamente sessões interrompidas após uma reinicialização; reinicializações por /update preservam o estado da sessão durante a atualização; recarregamentos de arquivos-fonte durante o desenvolvimento mantêm a sessão ativa viva em vez de forçar uma nova.¹⁸ Efeito prático: trabalhos longos de gateway e jobs acionados por cron não reiniciam mais a 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, proteções de disco e nenhum repo sombra órfão.¹⁸ O sistema anterior de checkpoint acumulava estado em disco ao longo de profiles de longa duração; o armazenamento v2 impõe um teto rígido ao armazenamento local de checkpoints e remove a escrituração duplicada que causava esse crescimento. Nenhuma alteração de configuração voltada ao usuário é necessária; a próxima gravação de checkpoint usa o caminho v2.

Personality e SOUL.md

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

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. Hermes só carrega SOUL.md de HERMES_HOME — ele não procura no diretório de trabalho atual. Isso torna a personality previsível entre projetos.¹³

O que pertence ao SOUL.md

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

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

Isso pertence 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 personality.

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 acompanhar você em todos os lugares, pertence ao SOUL.md. Se pertence a um projeto, pertence ao AGENTS.md.¹³

Personalities integradas

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

Personalities personalizadas 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

SOUL.md é a voz de base. /personality é uma camada por 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 por meio das credenciais existentes do Portal — sem chaves API extras para gerenciar.²¹ O CLI do Hermes em si continua licenciado sob MIT e totalmente open source. O que mudou é que sua autenticação no Portal agora desbloqueia mais do que inferência de modelos.

O que há no gateway

Como funciona

O gateway é opt-in por ferramenta por meio do novo campo de configuração 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 houver) é 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, Hermes prefere o gateway mesmo que você também tenha uma chave API direta configurada. Isso importa para cobrança — chamadas do gateway consomem sua assinatura do Portal, não o saldo da sua chave API direta.

Habilitar 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 existe 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ços e acesso

Preços e nomes de planos são publicados na página de preços do Nous Portal (https://portal.nousresearch.com/pricing). Este guia não enumera os planos porque eles são responsabilidade do produto Portal, não do CLI do Hermes, e mudam independentemente das releases do Hermes. Cadastre-se em https://portal.nousresearch.com/ e consulte a página de preços para ver os planos atuais.

Aviso de depreciação

• A variável de ambiente HERMES_ENABLE_NOUS_MANAGED_TOOLS foi removida na v0.10.0. Ferramentas gerenciadas agora são habilitadas pelo campo de configuração use_gateway por ferramenta e ficam condicionadas ao estado da sua assinatura do Portal.²¹

Enquadramento: o que esta release não é

O CLI do Hermes Agent não fica bloqueado atrás de uma assinatura. O projeto ainda é licenciado sob MIT, todos os recursos principais (CLI, skills, memória, gateway de mensagens, cron, MCP, dashboard local, BYOK para todos os provedores) funcionam de ponta a ponta sem pagar ninguém. A v0.10.0 adiciona um caminho conveniente para usuários que já pagam pelo Nous Portal — ela não remove nada do caminho gratuito.

Gateway de mensagens

Hermes pode rodar como um processo de gateway de longa duração que se conecta a 22 plataformas de mensagens a partir de um único processo de 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, LINE, SimpleX Chat e um adaptador Webhook genérico.^320171819 A v0.9.0 adicionou iMessage via BlueBubbles (registro automático de webhook, assistente de configuração, resiliência a falhas) e suporte nativo ao WeChat via iLink Bot API, com modo de callback WeCom para apps empresariais.¹⁶ 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, usando a mesma arquitetura de adaptadores plugáveis; 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.¹⁸ A v0.14.0 adiciona LINE e SimpleX Chat e completa a stack do Microsoft Teams de ponta a ponta com autenticação Graph, listener de webhook, runtime de pipeline e entrega outbound.¹⁹

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 guia você pela conexão de cada plataforma: tokens API, IDs de bot, mapeamentos de canal, 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 mensagens passa pelo mesmo loop de conversa AIAgent que o CLI. É por isso que os slash commands funcionam do mesmo jeito nos dois lugares e por isso um cron job agendado no Telegram pode entregar a saída no Discord — a diferença entre plataformas fica só 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 desconhecidos aleatórios conversem com o seu gateway. Um usuário envia um código de pareamento pela plataforma de mensagens; você aprova com hermes pairing approve; a partir daí, ele fica autorizado.⁶

Tarefas agendadas (cron)

Hermes tem um sistema de cron de primeira classe em que os jobs são tarefas de agente, não comandos shell. Cada job agendado roda por meio de um AIAgent novo com o prompt configurado, skills opcionais anexadas, e entrega os resultados para 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 de forma conversacional dentro de um chat de mensagens:

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

O agente configurará o cron job por meio de suas tools. 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 Hermes a servidores MCP externos para ampliar sua superfície de tools:

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

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 provider 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 provider:⁴

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

Alertas de pressão de orçamento

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

Timeouts de stream

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

O timeout de leitura do socket é aumentado para 30 minutos em endpoints locais porque LLMs locais podem levar minutos para fazer 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 mexer em arquivos de configuração nem 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 definir padrões para monitorar a saída de processos em background e receber notificações em tempo real quando eles correspondem.¹⁶ Monitore erros, aguarde eventos específicos (“listening on port”) ou acompanhe logs de build — tudo sem polling. Combinado com notify_on_complete da v0.8.0 (que notifica ao concluir tarefas em background), Hermes agora tem uma camada completa de observabilidade para processos em background.¹⁵

Context engine plugável (v0.9.0+)

O gerenciamento de contexto agora é um slot plugável via hermes plugins. Troque por 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 central do agente, permitindo customização de contexto por projeto ou por domínio.

Backup e restore (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 grandes ou compartilhar uma configuração testada e confiável com colegas de equipe.

Suporte a Termux / Android (v0.9.0+)

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

Reforço de segurança (v0.13.0+)

A v0.13.0 corrigiu 8 problemas de segurança P0 e mudou um padrão a favor do usuário.¹⁸ A v0.14.0 vem em seguida com mais 12 correções P0 e 50 P1, incluindo reforço contra força bruta em sudo / sudo-stdin, correções de bypass de comandos perigosos, sanitização de erros de ferramentas antes da reinjeção no modelo, autenticação de API do plugin do dashboard, cobertura de SSRF no skills-hub e varredura de avisos de supply chain durante a instalação.¹⁹

Se você mantém uma implantação do Hermes, trate as versões v0.13.0 e v0.14.0 como upgrades relevantes para segurança, não apenas como lançamentos de recursos. A v0.13.0 corrige o bypass entre guilds no Discord e duas janelas TOCTOU; a v0.14.0 adiciona outra rodada de reforço em tratamento de sudo, reinjeção de erros de ferramentas, APIs de plugins, SSRF no skills-hub e avisos de dependências.

Arquitetura para profissionais

Esta seção é para quem quer entender o que acontece por baixo dos panos para conseguir 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 ferramentas / 20 toolsets” vs. “28 ferramentas” no seu banner. A contagem de “47 ferramentas” é o total do registro de ferramentas do repositório upstream — todas as ferramentas que o Hermes inclui no 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 que verifiquei para este guia informa 28 tools / 89 skills). Isso não é um bug. Muitos toolsets são opt-in e precisam ser ativados explicitamente em config.yaml em toolsets: — adaptadores de plataformas de mensagens, automação de navegador, ferramentas mais pesadas de scraping etc. O total do registro é “o que está disponível”; o número no banner é “o que está ativado no seu profile atual.” Veja quais toolsets estão ativos com hermes tools --list e ative ou desative 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 aciona uma redefinição da 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 runtime:³

O resolvedor 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 integrado 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. Sobreposições opcionais de system prompt, como /personality

SOUL.md é a base — todo o restante é construído sobre ele.¹³

Armazenamento de sessões

Armazenamento de sessões baseado em SQLite com busca de texto completo FTS5. As sessões têm rastreamento de linhagem (pai/filho entre compressões), isolamento por plataforma e gravações 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 um contexto de API. 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

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 grava 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 personalizados, servidores MCP, tokens e allowlists de plataformas de mensagens (Telegram, Discord, Slack, WhatsApp, Signal, Matrix, Mattermost), padrões do agente (reasoning effort, compressão, atraso humano, fuso horário, sandbox), políticas de redefinição de sessão, regras de aprovação, config de TTS, configurações de navegador, configurações de ferramentas, timeout de exec, allowlist de comandos, config de gateway e chaves de API de 3 fontes.⁶

Arquivados para revisão manual: cron jobs, plugins, hooks/webhooks, backend de memória (QMD), config do registro de skills, UI/identidade, logging, configuração multiagente, 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