Hermes Agent: referência prática (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 o Hermes funciona: o modelo mental

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

1. Monta o prompt do sistema 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 provider em tempo de execução via runtime_provider.py — esta é a etapa que escolhe sua autenticação, URL base e modo API³
3. Chama o provider usando um dos três modos API: chat_completions, codex_responses ou anthropic_messages³
4. Encaminha quaisquer chamadas de ferramenta retornadas por model_tools.py e pelo registro central de ferramentas (tools/registry.py)³
5. Repete até que o modelo produza 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ê estiver lendo uma chave de configuração e se perguntando o que ela faz, a resposta geralmente é “é um ajuste na etapa 1, 2, 3 ou 4 do loop acima.”

Núcleo independente de plataforma. Uma única classe AIAgent atende à CLI, ao gateway, ao ACP, ao lote e ao servidor API. As diferenças de plataforma ficam no ponto de entrada, não no próprio agente.³ É por isso que os mesmos slash commands 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. O 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 o Hermes armazena X”, está em um desses lugares.

O que há de novo na v0.18.0 (The Judgment Release)

Hermes Agent v0.18.0 (tag v2026.7.1, 1 de julho de 2026) recebe seu nome por causa de judgment: o agente verificando o próprio trabalho em vez de afirmar sucesso, e raciocínio em ensemble que você pode realmente inspecionar. Ela também fecha todo o backlog P0/P1 — cerca de 692 itens de maior prioridade resolvidos em doze dias.²²

• Mixture-of-Agents como modelo de primeira classe. MoA agora pode ser selecionado como qualquer outro modelo em todas as interfaces, e o raciocínio em ensemble é visível: a saída completa de cada modelo de referência aparece como seu próprio bloco rotulado, com streaming ao vivo da resposta — você pode ver o ensemble pensar em vez de receber uma resposta mesclada opaca.²²
• Contratos de conclusão para /goal. O agente verifica o próprio trabalho executando as verificações do projeto antes de relatar que uma meta foi concluída, em vez de afirmar sucesso — judgment aplicado a si mesmo.²²
• /learn — descreva qualquer coisa para virar uma skill. Transforme um fluxo de trabalho em uma skill reutilizável descrevendo-o; as skills geradas seguem automaticamente as convenções do CONTRIBUTING.md do repo.²²
• Linha do tempo /journey. Um histórico visual de memória e skills ao longo do tempo, com edição, além de um grafo de memória no desktop.²²
• Fan-out de subagentes em background. Delegue várias tarefas que rodam simultaneamente sem bloquear a conversa — o único subagente em background da v0.17.0 vira uma frota.²²
• Projetos no desktop. Projects de coding de primeira classe com um modelo de organização por projeto/repo/lane.²²
• Gateway scale-to-zero. Gateways podem ficar dormentes quando ociosos e coordenar drains para deploys sem interrupção — algo relevante para qualquer pessoa que execute o Hermes como serviço sempre ativo.²²
• Suporte ao Google Vertex AI. Acesso ao Gemini por meio de contas de serviço do GCP com atualização automática de token OAuth2, entrando no catálogo de providers.²²
• Comando de editor /prompt. Abre $EDITOR para compor prompts de várias linhas em vez de brigar com a linha de entrada.²²

Se você está fazendo upgrade a partir da v0.17.x, nada aqui quebra a CLI. Os principais motivos para atualizar são contratos de conclusão (metas que se verificam), MoA de primeira classe com ensembles inspecionáveis e /learn para capturar skills.

O que há de novo na v0.17.0 (The Reach Release)

Hermes Agent v0.17.0 (tag v2026.6.19, 19 de junho de 2026) recebe seu nome por causa do alcance que o agente agora tem — novos canais de mensagens, novos providers de modelos e controle mais profundo no desktop e no dashboard. Ela é aditiva em relação à v0.16.x; a superfície da CLI permanece inalterada.²¹

• Novos canais de mensagens. iMessage agora funciona sem um relay no Mac via Photon Spectrum (OAuth por código de dispositivo, hermes photon login); a API do WhatsApp Business Cloud é um adaptador oficial da Meta que substitui a exigência de um processo de bridge; SimpleX ganha grupos, anexos nativos, agrupamento de texto e aceite automático; e Raft entra como um plugin de plataforma incluído, com um design de wake-channel baseado em privacy-by-contract.²¹
• Novos modelos e providers. O catálogo adiciona z-ai/glm-5.2 (contexto de 1M), anthropic/claude-fable-5, laguna-m.1, nemotron-3-ultra e grok-composer-2.5-fast (modelo do Cursor via OAuth da xAI, contexto de 200k). O padrão da xAI mudou para grok-build-0.1, e os modelos adaptativos Anthropic agora seguem o contrato moderno de thinking (eles nunca enviam um campo reasoning).²¹
• Desktop e dashboard. O desktop adiciona subagentes em background com streaming ao vivo de “watch-windows” mostrando atividade delegada (delegate_task(background=true)), um seletor de modelo Composer, atalhos de teclado reconfiguráveis, notificações nativas do sistema operacional, rascunhos de composer por thread, temas do VS Code Marketplace e UI em japonês + chinês tradicional. O dashboard adiciona um construtor completo de profiles (modelos/skills/MCPs sem editar config.yaml), um seletor global de profile, um Skills Hub refeito com verificação de segurança, Automation Blueprints (templates parametrizados para formulário, slash command, conversa e docs) e um login seguro que retorna 401 atrás do gate OAuth.²¹
• Skills e ferramentas. image_generate agora pode editar e transformar uma imagem de origem, não apenas criar uma do zero, em todos os providers de imagem compatíveis; a ferramenta memory ganhou um array operations para adicionar/substituir/remover em lote de forma atômica em uma única chamada; uma nova skill simplify-code executa uma revisão paralela com três agentes e uma passada de limpeza controlada por um nível de risco Chesterton’s-Fence; e um booleano write_approval substitui o write_mode de três estados.²¹
• Arquitetura. Subagentes em background retornam um handle imediatamente e reinserem seu resultado como um novo turno; um handler de elicitação MCP permite confirmação no meio de uma chamada de ferramenta, e ferramentas MCP que se conectam tarde são expostas entre turnos (cache-safe); cron vira um CronScheduler plugável com um provider de managed-cron Chronos; e um novo Managed scope (/etc/hermes) permite que um administrador fixe configurações imutáveis para o usuário, junto com um relay Gateway-Gateway para topologias com múltiplos gateways.²¹
• Novos comandos. /version, /billing (billing interativo no terminal), hermes photon login (autenticação do iMessage) e hermes curator run --consolidate — a consolidação agora é opt-in, então a curadoria rotineira em background custa zero tokens.²¹
• Segurança. A v0.17.0 fecha um bypass da lista de bloqueio de shell-escape, falha fechada quando módulos de aprovação e adaptadores de gateway own-policy estão ausentes, sanitiza o ambiente para subprocessos de job-scripts do cron, redige secrets em dumps de debug de requests, verifica configs stdio MCP contra padrões de exfiltração e atualiza urllib3 e PyJWT para eliminar CVEs.²¹

Se você está fazendo upgrade a partir da v0.16.x, nada aqui quebra a CLI; são novos canais, modelos e superfícies ao redor do mesmo agente. O iMessage sem relay, os adaptadores oficiais do WhatsApp e o Managed scope para administradores são os principais motivos para atualizar.

Novidades na v0.16.0 (The Surface Release)

Hermes Agent v0.16.0 (tag v2026.6.5, 5 de junho de 2026) recebe esse nome por causa das novas superfícies que coloca diante do agente priorizado para CLI. O destaque é que Hermes não é mais limitado ao terminal.²⁰

• Aplicativo desktop nativo. Hermes Desktop é um novo app Electron para macOS, Linux e Windows, com instalação em um clique e autoatualização dentro do app. Ele oferece uma janela de chat com streaming, arquivos por arrastar e soltar, colagem de imagens da área de transferência, uma paleta Cmd+K, uma lista de sessões com arquivamento e busca, e um seletor de modelo na barra de status. Ele pode se conectar a um gateway Hermes remoto por uma WebSocket segura, autenticando via OAuth ou nome de usuário/senha, com hosts remotos por profile e sessões simultâneas em múltiplos profiles vinculadas por referências @session entre profiles. A UI desktop também traz uma tradução completa para chinês simplificado (简体中文) por uma camada i18n tipada (display.language; inglês continua sendo o padrão).²⁰
• Painel de administração no navegador. O dashboard web local evoluiu de uma visualização de status para um painel completo de administração: um catálogo MCP com toggles para ativar/desativar, gerenciamento de credenciais, criação de webhooks e hooks, configuração de memória, controles de gateway e uma página System com verificação antes de atualizar e Debug Share em um clique. Uma nova página Channels configura todas as plataformas de mensagens do gateway (Telegram, Discord, Slack e as demais) pelo navegador. A autenticação agora é plugável: login com nome de usuário/senha, um provedor OIDC genérico auto-hospedado, hermes dashboard register para um cliente OAuth auto-hospedado e rotação de sessão por refresh-token.²⁰
• Novos CLI e slash commands. /undo [N] faz backup dos últimos N turnos do usuário com prefill e exclusão reversível, e funciona no CLI, na TUI e em plataformas de mensagens. Uma interface padrão configurável (cli vs tui) chega com override --cli; a TUI ganha um comando /model unificado e uma sobreposição Sessions. hermes portal é um alias legível para humanos para o fluxo de onboarding do Nous Portal, com novos caminhos de primeira execução Quick Setup vs Full Setup, e chegam dois diagnósticos: hermes prompt-size e hermes sessions optimize.²⁰
• Novos modelos e providers. O seletor adiciona deepseek-v4-flash, MiniMax-M3 (contexto de 1M, providers nativos MiniMax), qwen3.7-plus (Nous + OpenRouter) e gemini-3.5-flash (Gemini OAuth + chave API). Um provider xAI Grok OAuth de primeira classe entra no launcher desktop, o seletor de modelos passou a ter busca fuzzy em todas as superfícies, providers com múltiplos endpoints são agrupados em uma única linha, e a atualização do catálogo passou de diária para horária.²⁰
• Skills mais enxutas e divulgação progressiva. O conjunto padrão de skills removeu skills redundantes e mortas (Spotify passou para um plugin nativo, Linear para hermes mcp install linear, e várias entradas desatualizadas foram removidas), moveu mais itens para opcionais e adicionou um gate de relevância no frontmatter environments: (kanban/docker/s6) que mantém skills específicas de contexto fora do índice até serem solicitadas. NVIDIA/skills agora é um tap padrão confiável do Skills Hub ao lado de OpenAI, Anthropic e HuggingFace. Ferramentas MCP e de plugins ganharam divulgação progressiva (com escopo), e um bug de MCP que informava sucesso falso de OAuth quando nenhum token era obtido foi corrigido.²⁰
• Segurança. v0.16.0 fixa uma versão corrigida do Starlette (≥1.0.1) para CVE-2026-48710 (BadHost), move verificações de URL contra SSRF para fora do event loop em caminhos async, remove o token bearer de inferência do Bedrock do env de subprocessos, adiciona bws_cache.json à proteção de leitura de segurança de arquivos, adiciona docker restart/stop/kill à lista de padrões perigosos e sanitiza unicode invisível em conteúdo de skills verificadas. A release fechou 2 problemas P0 e 62 P1, 16 deles marcados como segurança.²⁰

Se você está atualizando a partir da v0.15.x, nada disso é uma breaking change para o próprio CLI; são superfícies e providers adicionais ao redor do mesmo agente. O app desktop e o painel de administração são o motivo para atualizar se você quer executar Hermes para usuários que não usam terminal ou administrar um gateway remoto pelo navegador.

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, clone do repo, ambiente virtual e 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 troca para um bundle Android testado).⁷ A v0.14.0 adiciona suporte nativo ao Windows em beta inicial via 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 ponte 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 mostra exatamente o que está faltando e como corrigir.⁷ hermes dump é o comando de diagnóstico para colar em uma issue GitHub ou thread no 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 customizada 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 pelo extra voice, que depende de wheels ctranslate2 que não são publicados para Android.⁷

Autenticação e provedores

Hermes oferece suporte a ~19 provedores de primeira classe, além de endpoints personalizados, e 3 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 3 caminhos de autenticação

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

Caminho 1 — chave API em .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 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 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 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 para cada um.²

Anthropic: 3 métodos de autenticação

Anthropic tem sua própria seção porque o Hermes oferece suporte a 3 caminhos distintos para entrar no Claude, e escolher o caminho 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 Anthropic OAuth por meio de hermes model, o 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: 2 modos

Copilot é compatível em 2 modos: API direto do Copilot (recomendado) e Copilot ACP (que inicia o CLI local do Copilot 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, segundo 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 compatíveis são tokens OAuth (gho_*), PATs refinados (github_pat_* com permissão Copilot Requests) e tokens de GitHub App (ghu_*). Se o 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

As URLs base podem ser substituídas pelas 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 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, o Hermes envia o header x-grok-conv-id em toda solicitação para rotear ao 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ê rotaciona 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 personalizados e self-hosted

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

Ambas as abordagens persistem em config.yaml, que é a única fonte de verdade para modelo principal, provedor e URL base.² As env vars 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 às cegas se você as usa ali.)⁴

Alternar endpoints personalizados 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 (puro, sem nome de modelo) consulta o API /v1/models do seu endpoint e seleciona automaticamente o modelo se exatamente 1 estiver carregado — útil para servidores locais que executam um único modelo.²

Servidores LLM locais (templates 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 projetado para produzir um endpoint funcional ao qual o Hermes pode se conectar.²

Ollama — caminho local mais fácil, zero 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 comprimentos de contexto muito baixos (4.096 tokens com menos de 24 GB de VRAM). Você precisa aumentá-lo via OLLAMA_CONTEXT_LENGTH ou um Modelfile — o API compatível com OpenAI não aceita comprimento de contexto do cliente, então o Hermes não pode 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 ferramenta 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, chamadas de ferramenta voltarão como texto simples.²

SGLang — serving rápido com RadixAttention para reutilização 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 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 ferramenta. Sem ele, o llama-server ignora totalmente o parâmetro tools e o modelo tenta chamar ferramentas escrevendo JSON no texto da resposta — o que o Hermes não consegue interpretar como chamadas reais de ferramenta.²

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 comprimento de contexto dos metadados do modelo, mas muitos modelos GGUF informam padrões de 2048 ou 4096. Sempre defina explicitamente o comprimento de contexto nas configurações de modelo do LM Studio — clique no ícone de engrenagem ao lado do seletor de modelo, defina “Context Length” para pelo menos 16384 (de preferência 32768) e recarregue o modelo.²

Provedores personalizados nomeados

Se você trabalha com vários endpoints personalizados (um servidor de desenvolvimento local e um servidor GPU remoto, 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 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 personalizados nomeados no 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 em modo API compatível com OpenAI, Anthropic ou Codex, você pode implementar uma subclasse de ProviderProfile que declare o caminho de autenticação, a URL base, o catálogo de modelos e os headers de cache; o 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 o Hermes já está autenticado — Claude Pro, ChatGPT Pro, SuperGrok ou outro provedor compatível configurado.¹⁹ Isso significa que ferramentas que esperam um API no estilo OpenAI, incluindo Codex CLI, Aider, Cline, Continue ou scripts personalizados, podem reutilizar sua autenticação do Hermes baseada em assinatura sem uma chave API separada. Trate o proxy como infraestrutura local de desenvolvimento: vincule-o intencionalmente, não o exponha de forma ampla e mantenha os termos específicos de cada provedor em mente.

Detecção de comprimento 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). O 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 comprimento 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: substituição por config → modelo específico de provedor personalizado → cache persistente → /models do endpoint → /v1/models do Anthropic → API do 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 tem 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 reserva para o qual o Hermes alterna automaticamente quando seu modelo primário falha (limites de taxa, erros de 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 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

Hermes usa modelos “auxiliares” leves para tarefas secundárias: análise de imagem, 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 via detecção automática (OpenRouter → Nous → Codex).

Você pode configurar qual modelo e provedor cada tarefa auxiliar usa. Todo slot auxiliar usa os mesmos 3 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 somente dentro das configurações 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 personalizado compatível com OpenAI como modelo principal, defina provider: custom na seção model:.⁴

Por que isso importa: se você configurou apenas Anthropic OAuth (sem chave OpenRouter), sua 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 silenciosamente 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.

Estrutura dos arquivos de configuração

Segundo 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 vence para configurações que não são secretas.⁴ A regra é: - Secrets (chaves API, tokens de bot, senhas) → .env - Todo o resto (modelo, backend do terminal, configurações de compressão, limites de memória, toolsets) → config.yaml

Secrets podem ser referenciados a partir de 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 para executar depois de cada hermes update — eles detectam novas opções de configuração que ainda não existem no seu arquivo.⁶

Precedência da configuração

Hermes carrega a configuração de várias fontes. Quando várias fontes definem o mesmo valor, a fonte de 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 — apenas secrets
5. Padrões integrados — aplicados quando nada mais define um valor

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

Localização (v0.13.0+)

A v0.13.0 adicionou 7 locales para mensagens de CLI e do gateway: chinês (simplificado), japonês, alemão, espanhol, francês, ucraniano e turco.¹⁸ A v0.14.0 localiza todos os comandos do gateway e o dashboard web, adiciona mais 8 locales e leva o total para 16.¹⁹ 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 explícita locale: 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 cubra.

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, sessões, skills, memória e PID do gateway. É assim que você executa “Hermes de 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), então vários profiles podem executar o gateway simultaneamente sem interferir uns nos outros.⁶³

Comandos CLI

Esta seção é a referência prática para comandos CLI de nível superior. Para a referência autoritativa derivada do código, consulte a Referência de comandos CLI.⁶

Opções globais

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

Comandos de nível superior

hermes chat — O ponto de entrada principal

hermes sem argumentos coloca você no 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 entra direto em uma seção:⁶

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 que tail -f nos arquivos de log porque oferece suporte a filtros 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 tools, ciclo de vida da sessão, INFO+) - errors.log — apenas avisos e erros (um subconjunto filtrado de agent.log) - gateway.log — atividade do gateway de mensagens (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 dá errado. Ele verifica a validade da configuração, a presença de dependências, a disponibilidade de chave API, o status do serviço 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 simples com chaves API ocultadas, pronto para colar em uma issue do GitHub ou thread no Discord.⁶

Comandos slash

Os comandos slash rodam 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, 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 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

Tools, skills e informações

Comandos slash dinâmicos de skill

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 comandos rápidos em config.yaml, que criam um alias de 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"

Então 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 registro vence. Nomes completos de comandos 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 ferramentas integrado que cobre busca na web, automação de navegador, execução no terminal, edição de arquivos, memória, delegação, treinamento de RL, entrega de mensagens, integração com Home Assistant e mais.¹⁰ As ferramentas 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.¹⁰

Gerenciamento de 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 alternadas no meio da sessão via /tools disable <name> e /tools enable <name>, o que redefine a sessão para que o novo conjunto de ferramentas entre em vigor.⁹

Backends de terminal

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

Troque de backend 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 do 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ção sobrevivem entre sessões.¹⁰

Todos os backends de contêiner são executados com reforço 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 namespace, workspace persistente via volumes.¹⁰

Processos em segundo plano

A ferramenta 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 ferramentas interativas CLI como Codex e Claude Code.¹⁰

Sudo

Se um comando precisar de sudo, o Hermes pedirá 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 um primitivo de primeira classe: um quadro Kanban durável que acompanha tarefas, status e identidade do worker entre agentes e reinicializações.¹⁸ O quadro é o que faz um enxame de workers do Hermes realmente concluir trabalho em vez de travar em passagens de bastão mortas.

O quadro Kanban combina naturalmente com /goal (loop Ralph de alvo bloqueado) no lado do alvo e com a ferramenta delegate_task existente para semântica de spawn. O resultado é um padrão de enxame em que todos os agentes compartilham uma única fonte da 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 agent pode carregar quando necessário. Elas 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 a fonte da verdade. Em uma instalação nova, as skills incluídas são copiadas do repo. Skills instaladas pelo Hub e criadas pelo agent 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 agent só carrega o conteúdo completo da skill quando realmente precisa dele.¹¹

Formato de 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 está indisponível:¹¹

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

Skills gerenciadas pelo agent

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

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

Ações:¹¹

Skill Hub

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.¹¹

Varredura de segurança

Todas as skills instaladas pelo 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 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 agent cria ou edita uma skill, ele sempre grava em ~/.hermes/skills/. A precedência local vence se o nome de uma 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 por meio da 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 no disco imediatamente, mas só aparecem no prompt do sistema na próxima sessão.¹²

O que salvar

Salve estes itens (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 e docstrings no estilo Google” → memory - Trabalho concluído: “Migrou o banco de dados de MySQL para PostgreSQL em 2026-01-15” → memory

Ignore estes itens:¹² - Informações triviais/óbvias - Fatos fáceis de redescobrir - Despejos 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 pesquisar conversas anteriores 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 anteriores relevantes com sumarização do Gemini Flash.¹²

Provedores externos de memória

Para uma 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 capacidades 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 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 da atuação do agente recuperáveis. 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; 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 no gateway e tarefas acionadas por cron não redefinem 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 poda real, limites de disco e nenhum repositório sombra órfão.¹⁸ O sistema de checkpoint anterior acumulava estado em disco em profiles de longa duração; o armazenamento v2 coloca um limite rígido no armazenamento local de checkpoints e remove a escrituração duplicada que causava esse crescimento. Nenhuma mudança de configuração voltada ao usuário é necessária; a próxima gravação de checkpoint usa o caminho v2.

personalidade e SOUL.md

SOUL.md é a identidade principal 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 personalidade previsível entre projetos.¹³

O que pertence ao SOUL.md

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

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

Esses itens 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 no nível da personalidade.

AGENTS.md — arquitetura do projeto, convenções de código, preferências de ferramentas, workflows específicos do repositório, 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.¹³

Personalidades integradas

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

Personalidades 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 de sobreposição no nível da 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 usando as credenciais do Portal que já têm — 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 do 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 de um 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 serão roteadas pelo Portal. Caso contrário, sua chave API direta (se presente) será 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 pelo 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ç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 dos lançamentos do Hermes. Cadastre-se em https://portal.nousresearch.com/ e confira a página de preços para ver os planos 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 pelo campo de configuração use_gateway por ferramenta e controladas pelo estado da sua assinatura do Portal.²⁶

Enquadramento: o que este lançamento não é

O CLI do Hermes Agent não fica bloqueado atrás de uma assinatura. O projeto continua licenciado sob MIT; todos os recursos principais (CLI, skills, memória, messaging gateway, 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 de conveniência para usuários que já pagam pelo Nous Portal — ela não remove nada do caminho gratuito.

Messaging Gateway

Hermes pode ser executado 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 genérico de Webhook.^325171819 A v0.9.0 adicionou iMessage via BlueBubbles (registro automático de webhook, assistente de configuração, resiliência a falhas) e suporte nativo a WeChat via iLink Bot API, com modo de callback do 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 adaptadores, 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 auth via Graph, listener de webhook, runtime de pipeline e entrega de saída.¹⁹ A v0.17.0 (19 de junho de 2026) adiciona iMessage sem relay via Photon Spectrum (OAuth com código de dispositivo usando hermes photon login — sem exigir Mac/relay do BlueBubbles), o adaptador oficial da WhatsApp Business Cloud API (substituindo a exigência de processo bridge), grupos do SimpleX e anexos nativos, e Raft como plugin de plataforma incluído.²¹

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 orienta você na conexão de cada plataforma: tokens API, IDs de bot, mapeamentos de canal, allowlists.⁶

Como as mensagens fluem

Dos documentos 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 comandos slash funcionam de forma idêntica nos dois lugares e por que um cron job agendado no Telegram pode entregar sua 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 jobs são tarefas de agente, não comandos de shell. Cada job agendado passa por um AIAgent novo com o prompt configurado, skills anexadas opcionais, e entrega 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 vai configurar o cron job por meio das próprias 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 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

Hermes comprime automaticamente conversas longas para permanecer dentro da janela de contexto do seu modelo. O resumidor 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 precisa oferecer uma extensão de contexto pelo menos tão grande quanto a do seu modelo principal, já que ele recebe toda a seção intermediária 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 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 provedores locais (localhost, IPs de LAN):⁴

O timeout de leitura de socket é aumentado para 30 minutos em endpoints locais porque LLMs locais podem levar minutos no prefill de 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 segundo plano (v0.9.0+)

watch_patterns permite definir padrões para monitorar a saída de processos em segundo plano e receber notificações em tempo real quando houver correspondência.¹⁶ Monitore erros, espere 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 quando uma tarefa em segundo plano termina), Hermes agora tem uma camada completa de observabilidade para processos em segundo plano.¹⁵

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 do 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 config, 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 grandes mudanças ou compartilhar uma configuração conhecida como boa 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 de TUI para telas mobile, 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 fechou 8 problemas de segurança P0 e alterou um padrão a favor do usuário.¹⁸ A v0.14.0 vem em seguida com o fechamento de mais 12 P0 e 50 P1, incluindo reforço contra força bruta de sudo / sudo-stdin, correções de bypass de comandos perigosos, sanitização de erros de ferramentas antes da reinjeção no modelo, autenticação API de plugins 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 a v0.13.0 e a v0.14.0 como upgrades relevantes para segurança, não apenas como entregas de recursos. A v0.13.0 fecha o bypass entre guilds do Discord e duas janelas TOCTOU; a v0.14.0 adiciona mais uma rodada de reforço no 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 poder depurar, estender ou raciocinar sobre performance. É 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” versus “28 tools” no seu banner. A contagem de “47 tools” é o total do registro de ferramentas do repositório upstream — todas as ferramentas para as quais o Hermes inclui código-fonte, em todos os toolsets. O seu CLI em execução real 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 de scraping mais pesadas etc. O total do registro é “o que está disponível”; o número no banner é “o que está ativado no seu profile atual”. Verifique 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 um reset da sessão para que o agente reconstrua seu manifesto de ferramentas).

Os três modos API

O Hermes abstrai diferenças entre providers em três modos 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 OAuth, pools de credenciais e resolução de aliases.³

Fluxo de dados em uma sessão 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 prompt inclui:¹³

1. SOUL.md (identidade do agente — ou fallback integrado se indisponível)
2. Orientação de comportamento sensível a 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 resto é 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 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 CLI por meio de um contexto API. Memory providers 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 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 mensagens (Telegram, Discord, Slack, WhatsApp, Signal, Matrix, Mattermost), padrões do agente (esforço de raciocínio, compressão, atraso humano, fuso horário, sandbox), políticas de reset de sessão, regras de aprovação, configuração de TTS, configurações de navegador, configurações de ferramentas, timeout de exec, allowlist de comandos, configuração de gateway e chaves API de 3 fontes.⁶

Arquivados para revisão manual: cron jobs, plugins, hooks/webhooks, backend de memória (QMD), configuração do registry de skills, UI/identidade, logging, configuração multiagente, vínculos de canal, IDENTITY.md, TOOLS.md, HEARTBEAT.md, BOOTSTRAP.md.⁶

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

Solução de problemas

“chave API não definida”

Execute hermes model para configurar seu provider interativamente, ou hermes config set OPENROUTER_API_KEY your_key. O comando hermes doctor vai dizer exatamente quais chaves estão faltando.⁷

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

Hermes detecta automaticamente o tamanho do contexto pelo endpoint /v1/models do seu servidor, mas muitos servidores locais informam padrões baixos. Defina isso explicitamente em config.yaml:²

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

Chamadas de ferramenta aparecem como texto em vez de executar

Seu servidor não está com tool calling habilitado, ou o modelo não oferece suporte a isso pela implementação do servidor.²

As respostas são cortadas no meio da frase

Há 2 causas possíveis:²

1. Limite baixo de saída (max_tokens) no servidor — SGLang usa 128 tokens por resposta por padrão. Defina --default-max-tokens no servidor ou configure model.max_tokens em config.yaml.
2. Esgotamento do contexto — O modelo preencheu a 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. Há 2 opções:²

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

[wsl2]
networkingMode=mirrored

Depois execute wsl --shutdown e reinicie. Agora localhost funciona nos dois sentidos.

Fallback para IP do host (Windows mais antigo): obtenha o IP do host Windows de dentro do WSL2 e use-o no lugar 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 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 o local do arquivo de configuração. hermes config env-path imprime o local do .env.⁶

FAQ

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

Claude Code é o CLI oficial da Anthropic, limitado aos modelos da Anthropic. Hermes Agent é um framework de agente open-source da Nous Research que funciona com qualquer provider 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.¹² Hermes também inclui um gateway de mensagens para Telegram/Discord/Slack/WhatsApp/Signal que Claude Code não tem.

Posso usar Hermes com uma chave API da Anthropic?

Sim. Há 3 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 — Hermes vai usar o armazenamento de credenciais do Claude Code quando disponível
3. Defina manualmente um ANTHROPIC_TOKEN (setup-token ou token OAuth) como fallback

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

Como alterno providers 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 preservados:⁹

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

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

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

Correção: adicione uma OPENROUTER_API_KEY para tarefas auxiliares ou reconfigure os slots auxiliares para usar seu provider principal. Observe que a compressão de contexto fica no próprio bloco de nível superior compression: e recebe summary_provider, não auxiliary.compression.provider — o slot auxiliary.compression expõe apenas 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 e padrões de comunicação. Ele fica em ~/.hermes/SOUL.md e acompanha você em todos os lugares. AGENTS.md é específico do projeto — arquitetura, convenções, comandos, caminhos — e fica no diretório do seu projeto.¹³ Se deve acompanhar você em todos os lugares, SOUL.md. Se pertence a um projeto, AGENTS.md.

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

Profiles. Cada profile tem seu próprio HERMES_HOME, configuração, 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

Hermes oferece suporte a LLMs locais?

Sim, pelo caminho de endpoint personalizado. 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 Endpoints personalizados e auto-hospedados para a configuração por servidor.

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

O guia cita 47 tools / 20 toolsets do registro de arquitetura upstream — esse é o total completo de tools para as quais o Hermes inclui 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 neste guia informa 28 tools) porque Hermes habilita apenas o conjunto de toolsets padrão na inicialização. Muitos toolsets são opcionais: adaptadores de gateway de mensagens, automação de navegador, stacks de scraping mais pesadas e várias integrações especializadas precisam ser listadas explicitamente em toolsets: em ~/.hermes/config.yaml antes de serem carregadas. Total do registro = “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. Ative ou desative toolsets individuais em runtime com /tools enable <name> e /tools disable <name> (desabilitar dispara um reset da sessão para que o agente reconstrua seu manifesto de tools com o novo formato).

Como Hermes lida com fallback de modelo quando meu provider principal falha?

Configure um bloco fallback_model em config.yaml:²

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

Quando o principal falha (limite de taxa, erro do servidor, falha de autenticação), Hermes troca para o fallback no meio da sessão sem perder o histórico da conversa. Dispara no máximo 1 vez por sessão.

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

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

Existe integração com IDE?

Sim — 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