Hermes Agent: guia de referência para profissionais (2026)

TL;DR: Hermes Agent é um agente de IA open source e autoaperfeiçoável da Nous Research. Ele funciona como uma CLI e como um gateway de mensagens multiplataforma, armazena em disco uma identidade durável e memória persistente, reúne skills que melhoram com o uso e funciona com qualquer provedor de LLM compatível com OpenAI — Nous Portal, OpenRouter, Anthropic, GitHub Copilot, z.ai, Kimi, MiniMax, DeepSeek, Qwen Cloud, Hugging Face, Google, xAI/SuperGrok ou seu próprio endpoint auto-hospedado.¹²¹⁹ A versão atual é a v0.21.5 (tag v2026.9.24, de 24 de setembro de 2026), um patch cumulativo da linha v0.21; Novidades da v0.21.5 explica o que mudou, e as seções de versões seguintes estão ordenadas da mais recente para a mais antiga.⁵² Para a maioria dos novos usuários, a parte mais difícil é a autenticação com provedores: na tag v2026.9.24, o Hermes inclui 39 provedores em sua lista estática de seleção e amplia essa lista automaticamente com 38 plugins de provedores integrados, além de endpoints personalizados e três caminhos distintos de autenticação (chave API no .env, OAuth por meio de hermes model ou endpoint personalizado no config.yaml).⁵³ O modelo de autenticação é a primeira coisa que você deve aprender — todo o restante depende de qual provedor é resolvido.

O Hermes Agent funciona como um runtime completo de agente, não como uma simples camada de chat. Ele lê seu sistema de arquivos, executa comandos em backends isolados por sandbox, extrai conteúdo da web, cria subagentes, executa tarefas cron agendadas, 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.¹ A CLI é uma interface de terminal construída sobre um loop de conversa em run_agent.py; o gateway é um processo de longa duração que encaminha mensagens das plataformas de mensagens pelo mesmo loop de conversa.³

A diferença entre o uso casual e avançado do Hermes se resume a cinco sistemas. Domine-os e o Hermes se tornará um multiplicador de produtividade:

1. Resolução de provedores: como os fluxos de autenticação são convertidos em chamadas de API
2. Hierarquia de configuração: config.yaml + .env + auth.json + SOUL.md + AGENTS.md
3. Sistema de ferramentas + toolsets: o que o agente pode fazer, com permissões definidas por plataforma
4. Sistema de skills: memória procedural que o agente cria e aprimora
5. Gateway + cron + profiles: execução do Hermes onde você atua, não apenas onde você está

Principais conclusões

• A autenticação com provedores tem três caminhos, não apenas um. Chave API no .env, OAuth por meio de hermes model/hermes auth ou endpoint personalizado no config.yaml. Escolha o caminho adequado ao seu provedor, não aquele que parece mais familiar.
• Para trocar de provedor, basta um único comando. hermes model orienta você interativamente por todos os provedores compatíveis, incluindo logins com OAuth, e /model provider:model permite trocar durante a sessão sem perder o histórico.²
• Dois arquivos formam a superfície de configuração editável pelo usuário. ~/.hermes/config.yaml armazena as configurações e ~/.hermes/.env armazena os segredos. auth.json, SOUL.md, MEMORY.md e skills/ são gerenciados diretamente pelo Hermes — você pode editar SOUL.md manualmente, mas os demais são modificados pelo próprio agente.⁴
• O Hermes é o sucessor do OpenClaw. Se você estiver migrando, hermes claw migrate importa automaticamente mais de 30 categorias de estado.⁵
• Por padrão, as tarefas auxiliares usam seu modelo principal. Visão, classificação de aprovações, compactação e títulos de sessões são executados como chamadas “auxiliares” separadas de LLM e, nessa tag, auto encaminha todas elas ao seu modelo principal de chat — não há nada para configurar, mas, em modelos de raciocínio caros, essas tarefas secundárias acrescentam um custo considerável. Quando isso for importante, configure cada slot auxiliary.<task> para usar modelos rápidos e baratos.⁴³⁴

Todas as seções abaixo se baseiam na documentação oficial 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é que aponta para a página oficial específica da qual ela foi extraída.

Escolha seu caminho

Como o Hermes funciona: o modelo mental

O Hermes é estruturado em torno de um único loop de conversa que pode ser invocado por qualquer ponto de entrada. 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 por meio de agent/prompt_builder.py (a reorganização de setembro de 2026 o moveu para o novo pacote agent/)³
2. Resolve o provedor de execução por meio de runtime_provider.py — é nessa etapa que são escolhidos seu método de autenticação, a URL base e o modo API³
3. Chama o provedor usando um dos três modos API: chat_completions, codex_responses ou anthropic_messages³
4. Encaminha todas as chamadas de ferramentas retornadas por meio de model_tools.py e do registro central de ferramentas (tools/registry.py)³
5. Repete o loop até que o modelo produza uma resposta final e, em seguida, salva a sessão no SQLite com FTS5³

Entender esse loop é importante porque todos os recursos — personalidades, memória, skills, compressão e fallback — se conectam a uma dessas etapas. Quando você estiver lendo uma chave de configuração e se perguntando o que ela faz, a resposta geralmente será: “é um controle da 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 processamento em lote e ao servidor API. As diferenças entre plataformas ficam no ponto de entrada, não no próprio agente.³ É por isso que os mesmos comandos slash funcionam no terminal e no Telegram — eles são encaminhados por um COMMAND_REGISTRY compartilhado em hermes_cli/commands.py.⁶

A estrutura de diretórios é o sistema. O Hermes armazena tudo em ~/.hermes/ (ou em $HERMES_HOME para profiles que não sejam 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 aos demais. Se você quer saber “onde o Hermes armazena X”, a resposta está entre eles.

Novidades da v0.21.5 (o pacote de atualizações de 24 de setembro)

O Hermes Agent v0.21.5 (tag v2026.9.24, de 24 de setembro de 2026) é a versão atual, o terceiro pacote enxuto de atualizações da linha v0.21.x: “Esta tag reúne os cerca de 460 PRs integrados desde a v0.21.4 em uma versão estável com tag para consumidores downstream”. As notas selecionadas foram novamente adiadas para a v0.22.0. Estas são as mudanças voltadas aos operadores, verificadas no código-fonte correspondente à tag:⁵²⁵³

• A memória Hindsight deixa a árvore principal. O provedor Hindsight incluído e o extra hermes-agent[hindsight] do pip foram removidos; agora o Hindsight é instalado pelo catálogo de plugins e mantido pela Vectorize; as notas da versão não mencionam essa mudança. Se sua configuração definir memory.provider: hindsight, hermes update instalará o plugin do catálogo em todos os diretórios iniciais de profiles que o mencionarem. Se ele ainda estiver ausente, a primeira inicialização do agente também o instalará, a menos que security.allow_lazy_installs seja false (nesse caso, execute hermes plugins install hindsight). As configurações, as chaves do .env e os dados da memória permanecem intactos. Consulte Provedores externos de memória.
• gateway.multiplex_profiles: false foi descontinuado. O gateway altera esse valor para true no próprio arquivo e exibe uma única vez um aviso dentro de uma caixa. Um profile nomeado que precise manter seu próprio gateway deve definir gateway.standalone: true em seu config.yaml; para colocar offline um dos profiles atendidos, hermes -p <name> gateway stop agora o suspende sem interromper o host. Consulte Gateway de mensagens.
• Novos modelos nos seletores da Nous e do OpenRouter: GPT-6 Sol e GPT-6 Luna (cada um com uma variante -pro) e Claude Opus 5.5.
• A compatibilidade com plugins não mudou: plugins.allow_deprecated_imports: true continua funcionando.

Para atualizar: hermes update ou o comando de uma linha do instalador; as imagens do Docker e do Hermes Cloud são criadas a partir de nousresearch/hermes-agent:v2026.9.24.⁵²

Novidades da v0.21.4 (o segundo patch cumulativo)

O Hermes Agent v0.21.4 (tag v2026.9.21, 21 de setembro de 2026) é o segundo rollup deliberadamente enxuto da linha v0.21.x. Nas palavras da própria versão: “Versão de patch. Esta tag reúne os cerca de 1.800 PRs incorporados desde a v0.21.3 em uma versão estável com tag para consumidores downstream (imagens Docker, Hermes Cloud, implantações hospedadas).” O período desde a v0.21.3 abrange “5.071 commits sem merge” em “5.169 arquivos alterados”, “1.812 PRs incorporados” e “2.116 issues encerradas”. Pela quantidade de commits, esse é o segundo maior intervalo entre tags na história do projeto, atrás apenas dos 5.139 da v0.21.1; pela quantidade de PRs incorporados, é o maior. A narrativa organizada foi adiada novamente, literalmente: “As notas de versão completas e organizadas para este período serão publicadas com a v0.22.0, que documentará tudo a partir da v0.21.0” e “Nada deste período será ignorado.” As notas listam o que deixam sem documentar, e cada item abaixo foi conferido no código-fonte da tag; quando um item altera uma seção permanente deste guia, o link correspondente aparece no próprio texto.⁵⁰⁵¹

• Um gateway por host, e o Desktop se conecta em vez de iniciar outro processo. A regra é um hermes serve e um hermes gateway run por host e por usuário do sistema operacional, cada um multiplexando todos os profiles — imposta por uma nova camada singleton para todo o host: um bloqueio do host mantido durante toda a vida útil do processo vencedor, além de um registro de rendezvous contendo (pid, createTime), para que uma segunda invocação possa comprovar que o proprietário é o mesmo processo ainda ativo e se conectar a ele em vez de vincular uma segunda porta. O estado obsoleto é comprovado, nunca presumido, e o aplicativo Desktop aplica a mesma ideia do seu lado, conectando-se ao backend do host em execução em vez de iniciar outro. Gateway de mensagens apresenta os detalhes do funcionamento.⁵¹
• Os conectores se tornam uma única operação controlada pelo backend, com um único cartão de configuração. Uma chamada da ferramenta manage_connections aciona no backend uma máquina de estados de conexão baseada apenas em dados, e Desktop, TUI e CLI exibem o mesmo cartão de configuração: um campo para cada credencial ausente, com a ação do cartão indisponível até que todos os campos obrigatórios tenham texto. Consulte a subseção sobre o nível gratuito do Nous.⁵¹
• --format stream-json: execuções únicas legíveis por máquina. hermes chat -q ... --format stream-json emite um objeto JSON por linha no stdout para executores de CI e orquestradores: um evento system/init, seguido por deltas de text / eventos tool_use / tool_result e, por fim, um envelope terminal result contendo o código de saída, o texto final e as estatísticas de tokens. Os diagnósticos e o ID da sessão permanecem no stderr, a saída das ferramentas é limitada a 5.000 caracteres por evento, a flag implica --quiet, exige -q ou --query-file (código de saída 2 sem uma dessas opções) e não pode ser combinada com --tui. A tabela de opções de hermes chat inclui essa flag.⁵¹
• skills.auto_load fixa skills em todas as sessões. Os nomes listados em skills.auto_load no config.yaml são carregados integralmente em cada nova sessão — seja CLI, TUI, gateway, cron ou API — e resolvidos uma única vez quando o prompt é criado pela primeira vez. O sistema de skills ganha uma subseção sobre skills fixadas.⁵¹
• Uma opção decline para DMs não autorizadas. unauthorized_dm_behavior ganha um terceiro valor além de pair e ignore: decline envia uma única recusa educada e depois permanece em silêncio para esse remetente por 24 horas. Consulte Autorização e pareamento de usuários.⁵¹
• mcp.discovery_concurrency limita as conexões de descoberta do MCP. O padrão é 4, e 0 = ilimitado; todos os servidores configurados continuam se conectando, mas deixam de fazer isso de uma só vez. Consulte Integração com o MCP.⁵¹
• session_search ganha limites de tempo e uma nova tentativa para melhorar a recuperação. O formato de descoberta aceita limites after/before (ISO ou durações relativas, como 7d), e uma consulta com várias palavras que não retorna resultados é repetida buscando QUALQUER termo, em vez do AND implícito entre todos os termos do FTS5. Consulte Busca de sessões.⁵¹
• hermes sessions set-journal-mode delete|wal: o conversor offline do modo de journal. Este é o caminho de autoatendimento para um state.db preso no modo incorreto de journal do SQLite — algo que antes exigia executar manualmente PRAGMA journal_mode=DELETE. Primeiro, interrompa o gateway, o dashboard e todas as instâncias de CLI: o comando se recusa a prosseguir enquanto qualquer processo externo mantiver o banco de dados aberto, faz a alteração sem aguardar o encerramento desses processos e depois verifica os bytes do cabeçalho do SQLite. O Windows não conta com uma verificação dos processos que mantêm o arquivo aberto; portanto, nesse sistema, o comando se recusa a prosseguir até que você use --force, depois de encerrar por conta própria todos os processos do Hermes. Agora, hermes doctor orienta você a usá-lo. A linha de hermes sessions em Comandos de nível superior inclui esse recurso.⁵¹
• Desktop: uma configuração de fonte, atualizações do mecanismo com um clique e desinstalação de plugins. As configurações ganham um campo para a família de fontes, persistido por profile em desktop.font_family — ele substitui a fonte sem serifa do tema em todo o chat e na interface, a lista de sugestões começa com fontes voltadas à acessibilidade (OpenDyslexic, Atkinson Hyperlegible, Lexend) e, se o campo estiver vazio, o tema decide. O runtime gerenciado de modelos locais exibe um botão “Atualizar mecanismo” quando há uma atualização disponível, e uma atualização malsucedida permanece visível para que você possa tentar novamente diretamente. Além disso, o hub de Plugins permite desinstalar um plugin após uma caixa de diálogo de confirmação.⁵¹
• Catálogos de vídeo: LTX 2.5 e Kling O3. O plugin de vídeo FAL adiciona ltx-2.5 (o modelo de áudio e vídeo de código aberto da Lightricks: áudio nativo, conversão de imagem em vídeo de até 20 s / 4K, predefinições de movimento de câmera e nível econômico — o fal rejeita clipes acima de 10 s em 1440p/2160p) e kling-o3 (a família de ponta da Kuaishou, no nível premium: narrativa nativa com várias tomadas, áudio opcional e duração de 3 a 15 s).⁵¹
• O catálogo de plugins se torna um diretório distribuído e um site. O diretório plugin-catalog/ do repositório cresceu de 9 entradas em v2026.9.14 para 228 nesta tag — um YAML revisado por plugin, fixado em um SHA de commit exato — e o site da documentação agora gera uma página para cada plugin e cada autor, exibindo em cada uma o README do plugin proveniente do commit fixado. Os dez plugins da comunidade mencionados na versão estão todos presentes no catálogo dessa tag. O sistema de plugins apresenta os detalhes.⁵¹
• E uma grande rodada de correções envolvendo isolamento de profiles/multiplexação, cron, kanban, Desktop e state.db, mencionada pela versão apenas como uma categoria; caberá à v0.22.0 registrar essas correções de forma organizada.⁵⁰

A reversão da compatibilidade de plugins ainda não entrou neste período. COMPAT_MANIFEST.md, compat_manifest.json e os shims de compatibilidade estão todos presentes em v2026.9.21; as únicas alterações em hermes_cli/plugin_compat.py durante o período são um cache de varredura compartilhado por todo o processo (um gateway multiplexado descobre os plugins uma vez para cada profile servido, e reanalisar o código-fonte de cada plugin custava cerca de 0,4 s por profile durante a inicialização) e caminhos de resultados no formato POSIX no Windows (#112576) — o bloqueio por data e a válvula de escape com booleano literal permanecem inalterados, portanto plugins.allow_deprecated_imports: true ainda mantém os plugins afetados em funcionamento. O quadro de compatibilidade em Sistema de plugins apresenta o estado atual.⁴²

O processo de atualização não mudou: hermes update (para instalações via git) ou o instalador de shell para novas instalações; as imagens Docker e do Hermes Cloud são criadas a partir desta tag (nousresearch/hermes-agent:v2026.9.21).⁵⁰

Novidades da v0.21.3 (o patch de 14 de setembro)

O Hermes Agent v0.21.3 (tag v2026.9.14, 14 de setembro de 2026) representa mais três dias da branch main resumidos em uma nota de dois itens. A versão foi lançada porque os agentes do Cloud são atualizados automaticamente para a tag de versão mais recente e precisavam das correções de login do gateway remoto para continuar acessíveis. (1) As sessões remotas do dashboard não são mais revogadas por rajadas de atualizações: os dois fluxos de atualização no gateway (a verificação por cookie e a rota bearer nativa do Desktop) agora agrupam solicitações simultâneas que carregam o mesmo refresh token rotativo em uma única operação. Assim, uma rajada ao despertar o Desktop não pode mais reutilizar no Portal um token já rotacionado, acionar a detecção de reutilização e revogar toda a sessão — além disso, a atualização é executada fora do event loop, de modo que um provedor de identidade lento não congela mais /api/status. (2) Os processos de longa duração deixam de criar identificadores de gravação duplicados para o state.db: gateway, backend do dashboard/Desktop, ACP e leitores do CLI se conectam no modo somente leitura, enquanto os gravadores no mesmo processo compartilham o identificador do registro. Estatísticas do período: “1.036 commits sem merge” em “2.642 arquivos alterados” e “338 PRs incorporados”. Todo o restante foi adiado de propósito: a versão informa o que não está documentando (seletores de esforço de raciocínio em todos os seletores de modelo, PKCE do OAuth do OpenRouter, decodificação de HEIF/HEIC/AVIF, uma onda de adições ao catálogo FAL, tabelas coladas no Slack e o API de Sessões do Agente, a recusa do WAL do state.db em sistemas de arquivos entre VMs e outros itens) e se compromete com o registro organizado, literalmente: “As notas de versão completas e organizadas para este período serão publicadas com a v0.22.0, que documentará tudo a partir da v0.21.0” e “Nada deste período será ignorado.”⁴⁹

E o prazo da compatibilidade de plugins chegou conforme programado. A remoção em 14 de setembro de 2026 anunciada pela v0.21.1 entrou em vigor como um bloqueio por data no código distribuído, não como uma reversão do código: na tag v2026.9.14, hermes_cli/plugin_compat.py contém COMPAT_REMOVAL_DATE = 2026-09-14, e removal_in_effect() retorna true a partir dessa data (ou assim que o arquivo de manifesto desaparecer). Com isso, um plugin externo afetado passa a ser desativado durante o carregamento e exibe o aviso em vermelho. O que ainda NÃO aconteceu: a reversão que realmente exclui os caminhos antigos de importação. COMPAT_MANIFEST.md, compat_manifest.json e os shims de compatibilidade ainda estão presentes na tag — e continuam presentes em v2026.9.21 e na main em 22 de setembro — por isso plugins.allow_deprecated_imports: true ainda funciona como válvula de escape: os caminhos antigos continuam sendo resolvidos quando o carregador recebe permissão para prosseguir. Há duas ressalvas importantes: a chave precisa ser um booleano YAML literal (o código aceita apenas o booleano True; uma string entre aspas, como "true" ou "false", é tratada como não definida, conforme o comentário no código “Literal boolean only”), e essa válvula de escape deixa de funcionar assim que a reversão entrar, pois os próprios caminhos desaparecerão. O quadro de compatibilidade em Sistema de plugins apresenta o estado atual.⁴²⁴⁹

Novidades na v0.21.2 (a versão de correção do state.db)

O Hermes Agent v0.21.2 (tag v2026.9.11, 11 de setembro de 2026) existe, antes de tudo, para corrigir o que a v0.21.0 quebrou. A versão diz isso claramente: “A v0.21.0 trouxe uma grande reformulação do gerenciamento de conexões do armazenamento de sessões e, em algumas instalações, tornou o state.db frágil: segundos processos de escrita cancelavam os bloqueios uns dos outros, bancos de dados íntegros eram identificados como corrompidos e uma única linha inválida interrompia o sessions list. Esta versão elimina essa categoria de problemas e reúne tudo o que chegou à main nos quatro dias desde a v0.21.1.” Ao contrário das notas deliberadamente sucintas da v0.21.1, esta versão documenta seus próprios destaques; as estatísticas do período são “947 commits sem merge” em “1.869 arquivos alterados” e “312 PRs mesclados” de “140 colaboradores”, enquanto o registro selecionado de todo o ciclo v0.21.x ainda ficará a cargo da v0.22.0.⁴⁸

• A campanha de confiabilidade do state.db: seis PRs e 44 problemas resolvidos. A recomendação da versão para operadores vem primeiro — e você também deve segui-la: se o seu state.db apresentou problemas na 0.21.0 ou 0.21.1, execute hermes doctor — agora ele distingue danos estruturais de danos no índice de pesquisa de texto completo, em vez de chamar tudo de “corrupção de escrita no FTS”, e indica hermes sessions recover --inspect-only (offline, não destrutivo e fixado ao profile; informa se a tabela canônica pode ser lida sem criar um banco de dados de saída) quando uma reconstrução não basta. O trabalho na causa raiz elimina todos os processos secundários de escrita no armazenamento: os gateways dos profiles gravavam o estado das salas hospedadas no state.db raiz a cada 5 segundos, e agora essa coordenação fica em um shared-state.db dedicado, de modo que os gateways dos profiles nunca abrem o armazenamento principal de sessões para escrita; o dashboard tenta primeiro abri-lo como somente leitura; a proteção do ciclo de vida do cron passa pelo registro de conexões monitoradas, em vez de usar um open() bruto em um banco de dados ativo (o que cancela os bloqueios POSIX do gateway — a receita clássica para corromper seu SQLite); e doctor --fix recusa um checkpoint quando não consegue comprovar que ele é seguro. Além dos processos de escrita: agora, danos ao índice FTS apenas limitam a pesquisa e fazem com que o índice seja reconstruído depois, em vez de encerrar todo o turno com falha; uma linha corrompida não interrompe mais sessions list, a exportação ou os insights (linhas inválidas são exibidas como ?, com um aviso que identifica a sessão); as sessões nunca se vinculam ao banco de dados de outro profile nem o leem; e a abertura no modo somente leitura não adquire mais o bloqueio de escrita, fazendo com que uma execução pontual do hermes por trás de um gateway ocupado passe de uma espera seguida de falha de 4 a 20 segundos para 0,01 segundo.⁴⁸
• Reforço do isolamento entre vários profiles. Desde a v0.19.0, este guia repete a afirmação do projeto de que o roteamento por profile oferece a cada profile “configurações, skills, memória e segredos totalmente isolados”. Na v0.21.2, essa promessa ainda tinha brechas, que agora foram fechadas: bots de profiles secundários herdavam as listas de permissões do profile padrão, adaptadores podiam enviar credenciais ao host do profile padrão, servidores MCP via stdio recebiam os segredos do cofre do profile padrão, a entrega por MEDIA: podia anexar o .env, auth.json ou state.db de outro profile, callbacks de webhook e do Feishu podiam sair do profile para o qual foram roteados, e profiles secundários podiam receber o bearer do Nous de outro profile por meio de memos por processo (#107609-#107630). Se você executa vários profiles em um único gateway multiplexado, esta é a versão em que a promessa de isolamento realmente se concretiza.⁴⁸
• O cofre de credenciais invisível a senhas. Agora, o agente pode fazer login, pagar e preencher endereços no navegador usando o 1Password, o Bitwarden ou o cofre local do Hermes sem jamais ver um segredo, e os códigos de autenticação de dois fatores vêm de uma chave de autenticador salva (TOTP: uma semente em base32 ou um URI otpauth://totp; HOTP baseado em contador não é aceito) ou são solicitados na sua interface. Todos os backends fornecem ao agente o mesmo formato — metadados de login e um identificador opaco com namespace (vault_ local, op:, bw:), enquanto a senha só é obtida no momento do preenchimento; gerenciadores externos permanecem bloqueados até que você os desbloqueie para a sessão, e a senha mestra “nunca é um argumento de ferramenta, nunca aparece em argv e nunca é persistida”. Isso amplia o trabalho com SecretSource da v0.19.0, que retirou as chaves API dos provedores do .env em texto simples; agora, o cofre faz o mesmo pelas credenciais de navegação do agente.⁴⁸
• Um catálogo selecionado de plugins fixados por SHA. hermes plugins browse lista “todas as entradas selecionadas do catálogo de plugins”, hermes plugins search pesquisa no catálogo e hermes plugins install resolve nomes do catálogo, além de URLs do Git e owner/repo. hermes plugins pack completa o conjunto com “coleções de plugins declarativas e compartilháveis”: um único hermes-pack.yaml fixa um conjunto de plugins em SHAs de commits exatos, pack install distribui a execução entre instalações fixadas comuns, mantendo o consentimento de recursos individual para cada plugin, pack export gera um pack da instalação atual e pack show funciona como uma simulação. O bloco de comandos do sistema de plugins inclui os novos subcomandos.⁴⁸
• Plano gratuito do Nous e primeira inicialização guiada. Instalações novas recebem inferência gratuita e conectores prontos para uso com um único comando de login, /login funciona dentro de um chat e as ferramentas dos conectores (Gmail, Linear, Notion e outras) podem ser pesquisadas por meio de tool_search. A primeira inicialização guiada do aplicativo para desktop fica condicionada a HERMES_GUEST_ONBOARDING=1, e somente o valor literal 1 a ativa: o teste do próprio aplicativo confirma que 'true', '0' e um valor vazio a mantêm desativada, e a decisão tomada na inicialização é registrada no ambiente do backend iniciado, impedindo que um valor herdado seja propagado. Consulte Nous Tool Gateway.⁴⁸
• As tempestades de inicialização do backend no aplicativo para desktop acabaram. Antes, o Bot Mode iniciava ou se conectava a um backend por profile na inicialização e a cada atualização da lista, passar o cursor sobre a lista de Bots iniciava um backend por linha, e trocar de profile podia iniciar uma cópia duplicada do backend principal. Tudo isso foi corrigido nesta versão.⁴⁸

A atualização continua igual: hermes update em uma instalação existente ou o instalador via shell em uma instalação nova.⁴⁸

O que há de novo na v0.21.1 (o patch cumulativo)

O Hermes Agent v0.21.1 (tag v2026.9.7, 7 de setembro de 2026) é deliberadamente enxuto: uma “versão de correção” que “reúne o estado atual da main desde a v0.21.0 para implantações com tag e consumidores downstream”. O texto apresenta as estatísticas do período — “5.139 commits sem merge em 4.364 arquivos alterados (+601.014 / -768.419)” e “632 PRs mesclados” — e então adia a história: “As notas de versão completas e selecionadas para este período serão publicadas com a v0.22.0”. Isso faz deste o maior intervalo entre tags da história do projeto (nenhum intervalo anterior entre tags adjacentes supera os 2.790 commits sem merge de v2026.7.20..v2026.7.30), publicado com as menores notas de versão. Até que a v0.22.0 apresente o registro selecionado, os seis grupos abaixo são o que muda na forma como você opera o Hermes nessa tag, cada um verificado no código-fonte.⁴¹

• A base de código foi decomposta, e o prazo de compatibilidade dos plugins terminou em 14 de setembro. A decomposição de setembro de 2026 (PR nº 102117) dividiu os grandes módulos do repositório em arquivos focados: um novo pacote agent/ contém os componentes internos do loop de conversação (214 módulos no nível superior, além de sete subpacotes; prompt_builder.py agora fica em agent/prompt_builder.py, enquanto run_agent.py continua sendo o local de AIAgent), os parsers de subcomandos da CLI foram movidos para um pacote hermes_cli/subcommands/ (61 módulos), a lista estática CANONICAL_PROVIDERS foi movida de hermes_cli/models.py para hermes_cli/models_catalog_static.py (a lista em si não mudou: 39 entradas estáticas, ainda estendidas automaticamente a partir dos 39 diretórios de plugins de provedores incluídos), e delegate_task foi dividido em aproximadamente uma dúzia de módulos tools/delegate_tool_*. Caminhos de importação internos não são uma API estável, então um novo COMPAT_MANIFEST.md na raiz do repositório reexporta 1.148 nomes públicos “moved-lazy” dos caminhos de módulo antigos, cada um emitindo um HermesPluginCompatWarning uma vez por nome, por processo, quando resolvido. A camada de compatibilidade era temporária, e sua remoção entrou em vigor conforme programado em 14 de setembro de 2026, seis dias após a tag — não como uma reversão de código, mas como uma condição baseada em data já presente no código publicado. Desde essa data, um plugin de terceiros afetado não é carregado: o banner da CLI, hermes doctor e hermes update mostram um aviso vermelho com o nome do plugin desativado, o desktop exibe uma caixa de diálogo uma única vez, e hermes plugins list mostra o motivo. Se você usa plugins externos, verifique-os: hermes plugins compat <path> exibe cada file:line com caminho antigo -> caminho novo e retorna o código 1 enquanto ainda houver algo pendente (--json para uma saída legível por máquina; execute sem argumentos para verificar todo o conjunto instalado). A saída de emergência para um plugin cujo autor ainda não se atualizou é plugins.allow_deprecated_imports: true em config.yaml, e ela ainda funciona: a reversão que realmente exclui os caminhos de importação antigos ainda não foi incorporada até 22 de setembro (verificado até a tag v2026.9.21 e na main), portanto os caminhos antigos ainda são resolvidos quando o carregador recebe permissão para prosseguir. Os detalhes das consequências estão em O que há de novo na v0.21.2 acima; a seção Sistema de plugins contém o quadro com o estado atual.⁴²
• As conversas do gateway não são mais alternadas por temporizadores, em nenhuma circunstância. A documentação do ciclo de vida da sessão agora declara o contrato explicitamente: “A inatividade e o tempo decorrido nunca alternam uma conversa. /new e /reset criam um limite explícito; a compactação do contexto continua gerenciando históricos longos. A configuração legada de temporizadores é ignorada. O tipo de dado SessionResetPolicy existente é um dado de compatibilidade inerte, não uma política de runtime.” Os limites são explícitos e definidos pelo usuário; se você trouxe temporizadores de redefinição de sessão da era do OpenClaw por meio de hermes claw migrate, agora eles são dados inertes. Consulte Gateway de mensagens.⁴³
• A autorização da MCP ganha um fluxo por código de dispositivo. hermes mcp login <name> ganha --flow {browser,device}: browser é o fluxo PKCE existente, device é um login por código de dispositivo conforme a RFC 8628 para máquinas nas quais um callback do navegador não é prático, e a flag substitui a configuração oauth.flow do servidor. O período também reforçou o restante da superfície de autenticação da MCP: a propriedade do profile é aplicada em todas as sessões da OAuth, caches de metadados malformados da OAuth são ignorados em vez de travar um servidor, e o desktop retransmite a OAuth da MCP por callbacks locais do cliente. Além disso, -t/--toolsets agora também filtra quais servidores da MCP configurados chegam a ser iniciados, portanto uma execução pontual de hermes -z -t <toolsets> evita iniciar a frio servidores desnecessários. O bloco de comandos de Integração da MCP agora inclui login e reauth [--all], ambos anteriores a este período, mas que ainda não haviam sido documentados aqui.⁴⁴
• A delegação passa a tratar o trabalho em segundo plano com transparência. Seis mudanças de confiabilidade em delegate_task, todas extraídas do código-fonte da ferramenta de delegação nessa tag. (1) Por padrão, um lote em segundo plano retorna como UMA conclusão; habilitar delegation.independent_completions divide a chamada em unidades de conclusão: tarefas que compartilham um valor de group são agrupadas e reportadas juntas, enquanto cada tarefa sem grupo é reportada individualmente quando termina. Esse padrão é intencional — o código-fonte observa que uma enxurrada de conclusões por tarefa “fragmentava orquestradores que não tinham um plano para isso”. (2) Os processos em segundo plano de um filho são encerrados durante sua desmontagem, a menos que o filho os transfira ao pai com process_manage(action="handoff"); processos restantes que não foram transferidos são identificados no resultado como orphaned_processes, e processos filhos que terminaram sem nunca terem sido lidos aparecem como unread_completions, acompanhados do trecho final da saída. A posição do projeto, conforme a docstring no código-fonte: o pai “precisa ouvir isso do runtime”, em vez de confiar na afirmação de um filho de que há um “watcher em execução”. (3) delegation.fallback_providers torna-se uma configuração real: null herda a cadeia do pai para filhos sem fixação, [] desativa o fallback, e um filho fixado por provedor, endpoint ou modelo não recebe fallback, a menos que essa configuração declare um. (4) A cadeia de fallback do filho é resolvida pelo normalizador canônico, portanto entradas malformadas são descartadas em vez de impedir a criação. (5) Uma falha no meio de uma unidade não perde mais os filhos concluídos: cada filho concluído de uma unidade com vários filhos é registrado de forma durável na própria linha da unidade e permanece no resultado recuperado como parcial. (6) Subagentes nunca herdam o nível de cache de prompt de 1 hora: um filho delegado passa para o nível de 5 minutos, porque o nível de 1 hora tem preço voltado para uma pessoa que se afasta, não para uma sequência de filhos paralelos.⁴⁵
• Provedores e modelos. Os catálogos passam a incluir GPT-6 Astra e Astra Pro da OpenAI, com variantes de velocidade -fast/-flex (“preço 2x, nível prioritário” / “preço 0,5x, nível flex”) nos catálogos do Nous Portal e OpenRouter. Na rota da OAuth do ChatGPT/Codex, o Astra é restrito por conta (somente a descoberta ativa no escopo da conta pode anunciá-lo) e ganha uma variante opcional -900k no seletor, que eleva a janela anunciada de 272K para cerca de 900K, verificados ao vivo; o sufixo nunca é enviado pela rede. Também chegam: anthropic/claude-fable-5.1, google/gemini-3.7-flash e gemini-3.8-flash, qwen/qwen3.8-max-0902 e qwen3.8-flash, além da família Muse Spark 1.3 da Meta (contexto de 1M, incluindo variantes de colaboradores) e um plugin de provedor de geração de imagens muse-image da Meta. O Tavily chega como backend de pesquisa e extração na web (TAVILY_API_KEY; funciona sem chave quando o Tavily é selecionado por meio de hermes tools). Um runtime gerenciado do llama.cpp transforma modelos locais em uma opção de primeira classe (binários oficiais, um único llama-server supervisionado e configuração com um clique pelo desktop), enquanto provedores de processos externos fora do repositório ganham uma ramificação própria de resolução. Em termos operacionais, os catálogos remotos do seletor agora são atualizados a cada 20 minutos (model_catalog.ttl_minutes, padrão 20; a chave legada ttl_hours só é respeitada quando um usuário a definiu explicitamente).⁴⁶
• Desktop: faça anotações na página e controle a sessão. O navegador integrado ganha o modo de comentários: clique em Anotar, depois clique em qualquer elemento (ou arraste para desenhar uma caixa) na página ativa e digite uma observação; os comentários salvos permanecem como marcadores numerados e nunca enviam um turno por conta própria. Quando terminar, “Adicionar N comentários” transfere o lote para o compositor com uma captura de tela recortada por marcador, e cada comentário de elemento inclui seu seletor da CSS, sua marcação e os estilos computados relevantes para o layout, permitindo que o agente encontre o elemento no seu código-fonte em vez de tentar adivinhar pela imagem (senhas, valores ocultos e atributos que parecem conter chaves são removidos antes que a marcação saia da página). Lotes maiores chegam agrupados por região da página, de modo que cerca de vinte comentários se transformam em algumas unidades de trabalho que normalmente afetam arquivos distintos — o que torna seguro distribuí-las entre workers paralelos. Ao redor desse recurso: controles estruturados de sessão e controles de automação de sessão, criação de sessões por arrastar, uma visualização de importação de sessões para transcrições de agentes de programação externos, display.resume_last_session (padrão true: uma inicialização a frio reabre o último chat ou página), uma solicitação de consentimento na primeira abertura oferecendo browser.use_real_profile quando um painel do Browser é aberto com essa opção desativada, um catálogo integrado de skills opcionais em Recursos -> Skills com instalação em um clique e um novo idioma russo para a interface do desktop (os 17 catálogos de idiomas da CLI permanecem inalterados).⁴⁷

A atualização não mudou: hermes update para uma instalação existente ou o instalador shell para instalações novas. Cabe à v0.22.0 registrar esse período de forma organizada; os grupos acima são o que muda nessa tag.⁴¹

Novidades da v0.21.0 (The Pantheon Release)

Hermes Agent v0.21.0 (tag v2026.8.31, 31 de agosto de 2026) é a versão atual com novos recursos e o registro consolidado para o qual toda a sequência de atualizações v0.20.x vinha apontando: “Esta versão reúne tudo o que foi lançado nos patches de infraestrutura v0.20.1 a v0.20.6 — esses períodos estão totalmente documentados aqui.” A proposta é uma continuação do Herald: “A v0.20.0 transformou Hermes no mensageiro — ele falou e levou a mensagem a outros agentes. Na v0.21.0, os deuses se reúnem.” Os números, literalmente: “Desde a v0.20.0: cerca de 5.800 commits · cerca de 2.475 PRs mesclados · cerca de 5.680 arquivos alterados · cerca de 869.000 inserções · cerca de 135.000 exclusões · cerca de 2.100 issues fechadas · mais de 760 colaboradores”.³⁵

A versão está organizada por área de recurso, assim como este resumo. Quando um recurso altera uma seção permanente deste guia, o link aparece no próprio item.

• Bot Mode: seus agentes se tornam uma sociedade integrada. O Bot Mode deixa de ser o plugin hermes-bots incluído na versão v0.20.3 e passa a ser uma parte do aplicativo para desktop ativada por padrão. Cada profile de agente recebe um nome, um rosto de avatar determinístico com controles para gerar outro ou bloqueá-lo e um lugar em uma lista compartilhada; você cria conversas em grupo no estilo do Discord, nas quais vários bots e você conversam na mesma sala, menciona qualquer bot com @ no campo de mensagem e dá nomes e imagens às salas. O conjunto de recursos inclui cartões de mensagens entre agentes com identificação do remetente, avisos de entrega para quem enviou, hidratação com prioridade para a renderização para ativações instantâneas, um painel Routines e uma reconstrução baseada no sistema de design do aplicativo. Nas palavras da própria versão: “Antes, ‘multi-agent’ significava infraestrutura; agora, parece um aplicativo de chat cheio de colegas de trabalho.”³⁵
• hermes peer: mensagens diretas entre seus agentes. Qualquer agente Hermes pode enviar mensagens a qualquer outro usando seu identificador, entre diferentes profiles e gateways, por meio da CLI ou de dentro de uma conversa — peça ao seu bot de pesquisa que envie as descobertas ao seu bot de programação e leia a resposta onde você estiver. “As respostas chegam ao Bot Chat canônico de cada agente, então as conversas entre agentes são duráveis e podem ser inspecionadas, em vez de serem enviadas e esquecidas.” O comando hermes peer (adicionar/listar/remover peers, dm) está na tabela de comandos de nível superior.³⁵
• Cron jobs que se lembram. As tarefas agendadas deixam de ter memória curta: agentes de cron carregam e atualizam memória persistente como qualquer outro agente, continuity=true leva a saída de cada execução para a seguinte para que um monitor possa eliminar duplicatas com base no que já informou, cada tarefa recebe um bloco de notas durável, tarefas no modo monitor ignoram totalmente a LLM quando nada mudou, o nível de esforço de raciocínio pode ser fixado por tarefa e a saída do cron pode chegar ao Bot Chat canônico de um bot, onde ele realmente responde. A seção Tarefas agendadas (Cron) agora documenta os mecanismos disponíveis no tag para cada um desses recursos.³⁵³⁷
• Orquestração de subagentes em tempo real. delegate_task ganha ações de controle: listar filhos em execução, redirecionar um deles durante a execução com uma correção de rumo ou interrompê-lo antecipadamente e preservar o resultado parcial. As saídas dos filhos podem ser validadas em relação a um schema JSON, o custo de cada delegação aparece nos resultados e os padrões aumentam para 250 iterações por subagente e 10 filhos simultâneos (os limites unificados que substituíram max_async_children na v0.19.0).³⁵³⁸
• A central de comando de MCP. Os servidores MCP e o catálogo são reunidos em uma única página do aplicativo para desktop, com importação por arrastar e soltar no estilo “cole qualquer coisa”, verificações de integridade em segundo plano que avisam você para refazer a autenticação antes que uma chamada de ferramenta falhe, uma sobreposição de custos e uso da frota (estimativas de tokens do schema e uso de 30 dias por servidor) e deep links hermes:// que instalam um servidor MCP mediante confirmação explícita. Consulte Integração com MCP.³⁵
• Uma onda de recursos avançados na CLI. Ctrl+P abre uma paleta de comandos com busca aproximada (também disponível como /palette), o seletor /model filtra conforme você digita, /status mostra o modo de raciocínio, as aprovações pendentes e o uso do contexto, e a barra de status pode exibir em tempo real a porcentagem de acertos do cache, a latência e os tokens por segundo, com controles individuais para cada campo. Há também uma parada de emergência global, a opção de fixar ou desafixar sessões, placeholders rotativos no campo de mensagem e mascotes no terminal. Uma observação sobre nomenclatura: a versão anuncia um verificador de aprovações em modo de simulação como hermes approval-check; nesse tag, essa funcionalidade é hermes approvals test — não existe o subcomando approval-check.³⁵⁴⁰
• O agente controla o navegador do aplicativo para desktop. O navegador integrado deixa de ser uma janela que o agente só consegue observar: Hermes navega, clica e lê diretamente, e as páginas podem ser abertas no navegador do sistema com menus de contexto completos para links.³⁵
• Seis novos providers e uma onda de novidades no catálogo de modelos. Meta Model API (Muse Spark), CommandCode, Tencent TokenPlan, Nebius Token Factory, Ramp Router e Actual Computer. Três deles (Meta AI, CommandCode e Actual Computer) chegaram durante períodos anteriores da consolidação e já estavam na matriz de providers; agora, a matriz inclui Tencent TokenPlan, Nebius Token Factory e Ramp Router, além do novo SKU Alibaba Token Plan apresentado na documentação. Os catálogos recebem GLM-5.3-Flash, qwen3.8-max/flash, Gemini 3.7 Flash, MiniMax M3 free, Nemotron 3.5 Lightning e Muse Spark 1.2. Duas mudanças estruturais acompanham as novidades: model_overrides em config.yaml permite ajustar a janela de contexto ou o preço de qualquer modelo sem esperar por uma nova versão, e agora os providers podem ser distribuídos como pacotes instalados pelo pip e descobertos por meio de entry points; um registro unificado de verificações de seleção também emite alertas em todos os seletores quando um modelo é treinado com seus dados.³⁵³⁶
• Reforço de segurança em todas as frentes. Gravações em arquivos protegidos de instruções do agente (AGENTS.md, skills e repositórios de memória) agora sempre exigem aprovação, impedindo que um agente afetado por prompt injection reescreva silenciosamente suas próprias instruções permanentes; uma ampla revisão de redação fecha brechas de vazamento de segredos em erros do terminal, leituras de .env, checkpoints e logs do ACP; o sistema de aprovação passa a reconhecer comandos destrutivos do Windows; as permissões concedidas no macOS sobrevivem às atualizações graças a uma identidade estável de assinatura TCC (hermes desktop --setup-tcc-identity); e a entrada do Blender no catálogo de MCP e sua skill foram removidas após o comprometimento do projeto upstream. Consulte Reforço de segurança para ver os detalhes disponíveis no tag.³⁵³⁹
• Amadurecimento do gateway. O Slack recebe cartões dinâmicos nativos (respostas transmitidas em tempo real e cartões opcionais de planos e tarefas), além da supressão de prévias de links enviados; o Telegram ganha um seletor inline que permite pesquisar todos os comandos e skills por meio de @botname, contornando o limite do menu de comandos do Telegram; o canal de retransmissão amadurece (inicialização nativa de plugins, operações de cartões dinâmicos com streaming de rascunhos, segmentação por intervalos da sessão e restauração da conversão de mensagens de voz em texto); um socket de controle do gateway permite que consumidores da frota consultem o gateway e que atualizadores o pausem de forma controlada, em vez de encerrar toda a árvore de processos; e o mecanismo de encerramento de turnos captura as pilhas de workers travados quando o watchdog é acionado.³⁵
• Uma onda de skills. Oito skills de produtividade recuperadas (document-to-action-items, meeting-action-items, email-inbox-triage, github-issue-to-pr, weekly-review-planning, competitor-news-monitor, product-price-monitor, social-media-content-calendar), clientes de API derivados de HAR (“observe um site uma vez e depois chame diretamente a API oculta dele, sem navegador”), publish-site, session-librarian, blocked-page-recovery, merge-reconciler, plan-interrogation e um linter consultivo de SKILL.md durante a criação.³⁵

Revertidos neste período (não incluídos na versão): tanto o modo Model Council (/council) quanto o context engine DCP chegaram a ser implementados e depois revertidos; o servidor de gateway exclusivo para WS (#94245) foi mesclado e depois revertido (#96118), portanto FastAPI continua no fluxo de inicialização do aplicativo para desktop — mas a repetição de eventos com números de sequência (#94219) e a reconexão sem perdas do aplicativo para desktop por WebSocket FORAM incluídas. O Electron voltou para a versão 40.10.2. Caso a cobertura da comunidade sobre as versões v0.20.x tenha mencionado algum desses recursos, eles não fazem parte desta versão.³⁵

O processo de atualização não mudou: use hermes update em uma instalação existente ou o instalador via shell para instalações novas. A subseção de consolidação dentro da versão Herald abaixo continua sendo o registro por tag do que foi incluído em cada período.³⁵

Novidades da v0.20.0 (The Herald Release)

O Hermes Agent v0.20.0 (tag v2026.8.3, 3 de agosto de 2026) foi a versão de recursos lançada antes de a v0.21.0 consolidar tudo; a v0.20.1 (13 de agosto) e a v0.20.2 (16 de agosto) são tags de estabilização criadas sobre ela, e a v0.20.3 (tag v2026.8.16.2, publicada em 17 de agosto), a v0.20.4 (tag v2026.8.18, 18 de agosto), a v0.20.5 (tag v2026.8.19, publicada em 21 de agosto) e a v0.20.6 (tag v2026.8.27, 27 de agosto) mantêm a sequência de consolidações com janelas que também trazem recursos próprios — veja a subseção abaixo. A janela desde a v0.19.0 abrange aproximadamente 3.650 commits, 1.400 PRs mesclados e 1.200 issues encerradas, com mais de 650 colaboradores.⁵⁵

Três mudanças invalidam as instruções que as versões anteriores deste guia deram a você. Leia-as antes de qualquer outra coisa:

• Agora, o Node 26 é obrigatório. O instalador fixa NODE_VERSION="26" e recusa runtimes mais antigos com a mensagem “Node.js … is too old (Hermes requires Node >=26).” Os instaladores, heal e upgrade aplicam essa exigência. Observe que a página de instalação do site da documentação ainda informa Node v22 — o script do instalador e as notas da versão são as fontes mais recentes e confiáveis.⁵⁵
• pip e Homebrew foram descontinuados, não apenas depreciados. Nas palavras da própria nota: “brew + pip/PyPI wheel channels retired (shell installer / Docker / Nix are the supported channels).” Se você ainda usa uma instalação via pip ou brew, esse canal não recebe mais versões.⁵⁵
• O limite padrão de iterações para chamadas de ferramentas passou de 90 para 500. Execuções autônomas longas deixaram de atingir uma barreira artificial, e todos os limites de pressão do orçamento abaixo são calculados com base nesse novo teto. O padrão de read_file também passou de 500 para 2.000 linhas.⁵⁵

O restante da versão:

• Voz conversacional. TTS por streaming com interrupção por voz e palavras de ativação processadas no dispositivo.⁵⁵
• A2A v1.0. Um plugin de protocolo entre agentes que atende à antiga solicitação da issue nº 514.⁵⁵
• Webhooks de saída assinados. Antes, hermes webhook aceitava apenas entradas; a v0.20.0 adiciona webhooks de ciclo de vida de saída, assinados com HMAC, para eventos de sessão, turno e ferramenta.⁵⁵
• Citações fundamentadas. Uma nova skill com um modo de verificação de fatos.⁵⁵
• Uma onda de recursos para usuários avançados no CLI. !command executa instantaneamente um comando do shell sem gastar um turno do modelo; /init examina o projeto e cria ou atualiza um AGENTS.md; /diff mostra alterações preparadas, todas as alterações ou as alterações da sessão em qualquer interface; /context detalha o que está preenchendo a janela de contexto; /focus oferece uma visualização com menos saída e permite recuperar linhas ocultas; Ctrl+S guarda temporariamente um prompt escrito pela metade. hermes import-agent migra uma configuração do Claude Code ou do CLI do Codex com um único comando.⁵⁵
• Novidades na interface de gerenciamento de segredos. Uma fonte de segredos baseada em comandos auxiliares que pode ser combinada com qualquer cofre, rotação de tokens com um único comando e erros de inicialização que indicam como agir, um cache emergencial criptografado e opcional para o Bitwarden, chaves injetadas pelo cofre com escopo definido por diretório inicial de profile e paridade de SecretRef ${env:VAR} entre config.yaml e a configuração do MCP. O modelo de autenticação com três caminhos descrito abaixo permanece inalterado.⁵⁵
• Inicialização mais rápida. A inicialização a frio de hermes -w caiu de aproximadamente 14s para 1,8s.⁵⁵
• O desktop se tornou uma plataforma. Artifacts com cards versionados e visualização dinâmica em sandbox, um SDK de plugins com Kanban como plugin fundador do desktop, um atalho global para entrada rápida, várias janelas da GUI, modo de backend remoto do SSH e login nativo segundo o RFC 8252.⁵⁵

As consolidações v0.20.3, v0.20.4, v0.20.5 e v0.20.6 (17 a 27 de agosto)

Após a v0.20.0, o projeto adotou um ritmo de consolidações frequentes com tags, que trouxeram mais do que apenas estabilização. As quatro adiaram as notas selecionadas da mesma forma — cada uma declarou que “full curated release notes for this window will ship with v0.21.0” — e a v0.21.0 já as entregou: Novidades da v0.21.0, acima, é o registro selecionado de todo esse período (a versão confirma que as janelas “are fully documented here”). Os blocos abaixo permanecem como o registro contemporâneo de cada tag — eles preservam o que foi incluído em cada uma, enquanto as notas selecionadas agrupam essas mudanças.^54233035

v0.20.3 (cerca de 250 commits e 125 PRs desde a v0.20.2):

• Migração do SDK do MCP 2.x, com suporte ao protocolo sem estado de 28 de julho de 2026. O Hermes passa a usar a geração atual do SDK do MCP e oferece suporte à revisão sem estado do protocolo.⁵⁴
• O Bot Mode é lançado como um plugin incluído (hermes-bots) que contém o protocolo principal de colaboração em equipe.⁵⁴
• Um plugin do provedor CommandCode passa a integrar o catálogo de provedores.⁵⁴
• Contratos de runtime do Cua Driver 0.20 para uso do computador, além do reforço da propriedade do runtime do Python em subprocessos (isolamento de PYTHONHOME/PYTHONPATH).⁵⁴
• Confiabilidade: recuperação automática do agendador cron (recuperação de EMFILE, reconciliação de reivindicações obsoletas e reativação de tarefas travadas), correções para perda de dados na transferência de sessões, recuperação automática da conexão com o gateway remoto do desktop e uma onda de melhorias no ecossistema (verificação de segurança na instalação de plugins, /worktree, preservação de edições manuais pelo /rollback e leitura de arquivos UTF-16).⁵⁴

v0.20.4 (cerca de 146 commits e 74 PRs desde a v0.20.3):

• A superfície de vidro do desktop: efeitos de vidro fosco e translucidez, com um seletor de desfoque e pré-seleção para macOS.⁵⁴
• Uma barra lateral com abas SESSIONS|BOTS, incluindo opções para ocultar e exibir cada bot, além de correções para conversas em grupo no Bot Mode (turnos longos de participantes, renderização de Markdown e roteamento entre máquinas).⁵⁴
• Verificação consultiva NVIDIA SkillEvaluator Tier 1 durante a instalação de skills — verificações de licença e segurança são executadas quando você instala uma skill.⁵⁴
• Reforço do envio de mídia pelo cron (timeout configurável, anexos em execuções manuais e exibição de acionamentos perdidos), correções de thread do loop de eventos e contenção no SessionDB, transparência do hermes update em branches estacionadas e notificações nativas do sistema operacional para o Kanban.⁵⁴

v0.20.5 (cerca de 746 commits e 323 PRs desde a v0.20.4):

• A camada web sem chaves: a busca na web funciona em instalações novas sem nenhuma chave de API — com rotação gratuita entre 5 fornecedores e failover em anel.²³
• Uma onda de refinamentos no CLI: seletor difuso de /model, uma paleta de comandos aberta com Ctrl+P e um /status mais completo.²³
• O Bot Mode amadurece: threads em salas de grupo, resumos recolhíveis de conversas, avatares blob-face e anexos de PDF/arquivos com recurso de arrastar e soltar.²³
• Ferramentas para frotas e worktrees: recibos do hermes update, hermes update --plan (as notas da versão chamam isso de “fleet --plan verification”; a flag pertence a hermes update, não a um comando fleet, e, segundo a ajuda do parser, ela irá “Show the update plan and exit without changing anything”) e hermes worktree list/prune.²³²⁷
• As tarefas cron ganham memória persistente e esforço de raciocínio por tarefa, além de disciplina de execução e proteções contra travamentos do runtime orientadas pelas descobertas da avaliação do Composio, esclarecimento com várias perguntas, o provedor sem opencode e sem autenticação e melhorias no desempenho do desktop (hidratação do Bot Mode com prioridade para a primeira renderização e React Compiler nos dois renderizadores).²³

v0.20.6 (tag v2026.8.27, 27 de agosto — cerca de 1.313 commits e 525 PRs desde a v0.20.5):

A versão se descreve explicitamente como uma “Patch release. This tag rolls up the ~525 PRs merged since v0.20.5 into a stable tagged release for downstream consumers”, e sua própria descrição contabiliza cerca de 1.313 commits em aproximadamente 1.557 arquivos (+177.113 / −21.682) — cerca de 525 PRs mesclados.³⁰ Estes são os destaques dessa descrição:

• Navegação com perfis reais sujeita a consentimento — a navegação local pode usar seu profile padrão do Chromium, com um fluxo no Windows para fechar o navegador após aprovação.³⁰
• O Browser do desktop ganha sua própria janela do sistema operacional, além de um mecanismo gerenciado de atualização remota do SSH e uma barra de profiles da frota.³⁰
• Expansão do catálogo remoto do MCP: mais de 50 servidores hospedados por fornecedores e verificados em operação, incluindo Cloudflare, Grafana Cloud, Better Stack e Railway.³⁰
• Criptografia opcional dos segredos armazenados usando o chaveiro do sistema operacional — sem mais solicitações do Keychain do macOS a cada inicialização.³⁰
• Novos modelos nos seletores: GLM-5.3-Flash, MiniMax M3 gratuito e MiniMax H3 Max video.³⁰
• Cache de resultados com TTL para web_search/web_extract e tool_search com várias consultas e stemming.³⁰
• A compressão lean-tail agora é o padrão — a seção Compressão de contexto abaixo documenta a configuração dessa tag.³⁰³¹
• Os backends de terminal passaram a aceitar plugins — veja Backends de terminal.³⁰³²
• Transparência do atualizador e da frota: os atualizadores pausam os gateways pelo socket de controle em vez de encerrar suas árvores de processos, e instalações gerenciadas por imagens ou pacotes recusam atualizações inseguras no próprio local.³⁰
• Confirmações persistentes de incidentes do cron, com falhas por divergência de código mais claras, controles de expansão de links no Slack e identidades de contêiner compartilhadas do Docker.³⁰

O processo de atualização não mudou: use hermes update em uma instalação existente ou o instalador via shell em instalações novas.⁵⁴²³³⁰

Novidades da v0.19.0 (The Quicksilver Release)

Hermes Agent v0.19.0 (tag v2026.7.20, 20 de julho de 2026) recebe esse nome em referência à velocidade do próprio deus mensageiro: o eixo central da versão é a capacidade de resposta bruta, com uma redução de cerca de 80% no tempo até o primeiro token da primeira interação em todas as plataformas. Ao redor desse eixo estão o faturamento pelo terminal, fontes de segredos de gerenciadores de senhas, aprovações inteligentes por padrão, subagentes observáveis e entrega de respostas resistente a falhas. O período desde a v0.18.0 é o maior da história do projeto: cerca de 2.245 commits, 1.065 PRs mesclados, 3.300 issues encerradas e mais de 450 colaboradores da comunidade.⁵⁶

• Cerca de 80% mais rápido até o primeiro token, em todos os lugares. O envio a frio→despacho caiu de cerca de 4,3 s para 0,9 s tanto no CLI quanto no gateway, na TUI, no desktop e no cron — a detecção de recursos do Discord saiu do caminho crítico, a verificação do Ollama é ignorada para provedores reconhecidamente não Ollama e tarefas bloqueantes foram removidas da inicialização do agente. A latência percebida também recebeu atenção: agora, os modelos de raciocínio transmitem seus pensamentos ao vivo por padrão (display.show_reasoning fica ATIVADO), e a caixa de resposta é renderizada a cada token, em vez de a cada linha.⁵⁶
• Ondas de melhorias na renderização do desktop e da TUI. O aplicativo para desktop recebeu uma reformulação de desempenho com cerca de 20 PRs: consumo de CPU 14 vezes menor no divisor de Markdown em streaming graças à análise léxica incremental por blocos, diffs virtualizados no painel de revisão, alternância ágil entre sessões com transcrições grandes e o fim das novas renderizações da barra lateral e das linhas de ferramentas a cada token. Agora, a TUI renderiza o Markdown transmitido incrementalmente por bloco.⁵⁶
• Instalações via pip e Homebrew foram descontinuadas. Os dois métodos foram marcados como instalações “legadas e sem suporte”, com remoção prevista. Essa remoção já ocorreu na v0.20.0 — os canais brew e pip/PyPI wheel foram desativados, deixando o instalador via shell, Docker e Nix como canais compatíveis.⁵⁶⁵⁵
• Os segredos podem vir do seu gerenciador de senhas. Uma nova interface conectável SecretSource busca segredos do Bitwarden e do 1Password (referências op://) durante o carregamento, com vários cofres ativados simultaneamente, precedência determinística, avisos de conflito e proveniência por variável — as chaves de API não precisam mais ficar em um arquivo .env de texto simples. Futuros provedores de cofres poderão ser adicionados como plugins.⁵⁶
• As aprovações inteligentes agora são o padrão. Quando Hermes quer executar um comando sinalizado, um revisor LLM independente o avalia, em vez de solicitar sua autorização para cada comando — e cada veredito se aplica somente àquele comando específico. Regras de negação definidas pelo usuário bloqueiam comandos correspondentes mesmo no modo YOLO, /deny <reason> transmite o motivo da sua recusa para que o agente corrija o rumo, e a ação de aprovação pre_tool_call do plugin (reintroduzida com chaves de regras) encaminha uma chamada de ferramenta para aprovação humana.⁵⁶
• Faturamento pelo terminal: /subscription e /topup. Gerencie seu plano do Nous Portal sem sair do terminal — consulte seu plano e o saldo restante, veja exatamente quanto custa um upgrade ou quando um downgrade entra em vigor e aplique a alteração com a opção de desfazer. O aplicativo para desktop ganha uma aba correspondente de configurações de faturamento.⁵⁶
• Acompanhe o trabalho dos subagentes e nunca perca uma resposta concluída. Os despachos de delegate_task retornam arquivos de transcrição ao vivo que você pode acompanhar com tail -f assim que os subagentes são iniciados — cada chamada de ferramenta, resultado e resposta transmitida, com um log legível para cada agente filho. As conclusões de delegações em segundo plano persistem entre reinicializações, e as respostas finais do gateway são registradas em um livro-razão de obrigações de entrega no state.db e reenviadas na próxima inicialização caso o gateway falhe durante o envio. A opção de configuração max_async_children foi descontinuada em favor de limites unificados de concorrência para delegações.⁵⁶
• Um gateway, vários profiles. Um único gateway multiplexado que compartilha um token de bot pode encaminhar guildas, canais ou threads específicos para diferentes profiles — cada um com configurações, skills, memória e segredos totalmente isolados — com uma substituição GATEWAY_MULTIPLEX_PROFILES. O índice de roteamento foi movido para state.db; sessions.json agora é um espelho legado opcional.⁵⁶
• Onda de provedores e modelos. Fireworks AI ganha suporte nativo (estimativa de custos e 2ª posição no seletor de provedores), junto com DeepInfra e Upstage Solar. Os catálogos adicionam GPT-5.6 (Sol/Terra/Luna + Pro, integrado de ponta a ponta), grok-4.5 (GA), kimi-k3 (kimi-k2.x descontinuado) e Claude Sonnet 5 totalmente integrado. Uma flag enabled: false por provedor e a configuração excluded_providers removem provedores não utilizados dos seletores e da resolução de /model.⁵⁶
• O nível de esforço de raciocínio vira um controle ajustável. Os novos níveis de esforço max e ultra chegam a todas as interfaces, com substituições por modelo nas configurações, esforço por slot nas predefinições de MoA (os consultores pensam profundamente, enquanto o sintetizador permanece rápido), esforço por tarefa para modelos auxiliares e um /reasoning com escopo de sessão no CLI.⁵⁶
• Recursos de CLI e MCP. hermes sessions export gera arquivos nos formatos Markdown, Quarto, HTML, somente prompt e rastreamento do Hugging Face, com uma limpeza opcional via --redact; /model --once permite substituir o modelo por uma única interação; invocações de slash-skills podem ser encadeadas (/skill-a /skill-b do XYZ); --safe-mode ajuda na solução de problemas; hermes config get/unset completam o gerenciamento de configurações; hermes serve se torna um verdadeiro backend headless; e as ferramentas de MCP adotam a convenção de nomenclatura mcp__server__tool.⁵⁶

Se você estiver atualizando da v0.18.x, duas mudanças merecem atenção antes de qualquer outra coisa: uma instalação via pip ou Homebrew agora gera um aviso de que é legada e não tem suporte (migre para o instalador de uma linha), e max_async_children foi descontinuado em favor dos limites unificados de concorrência para delegações. Todo o restante é aditivo — os principais motivos para atualizar são a redução de cerca de 80% na latência da primeira interação, as aprovações inteligentes e o livro-razão de entregas que torna as respostas concluídas resistentes a falhas.

Novidades da v0.18.0 (The Judgment Release)

Hermes Agent v0.18.0 (tag v2026.7.1, 1º de julho de 2026) recebe esse nome em referência ao julgamento: o agente verifica o próprio trabalho em vez de simplesmente afirmar que teve sucesso, com um raciocínio em conjunto que você realmente pode inspecionar. A versão também elimina todo o backlog P0/P1 — cerca de 692 itens de prioridade máxima resolvidos em 12 dias.²²

• Mixture-of-Agents como modelo nativo. Agora, o MoA pode ser selecionado como qualquer outro modelo em todas as interfaces, e o raciocínio em conjunto fica visível: a saída completa de cada modelo de referência é renderizada em um bloco próprio e identificado, com transmissão da resposta ao vivo — você pode acompanhar o conjunto pensando, em vez de receber uma resposta mesclada e opaca.²²
• Contratos de conclusão para /goal. O agente verifica o próprio trabalho executando as verificações do projeto antes de informar que um objetivo foi concluído, em vez de simplesmente afirmar que teve sucesso — aplicando julgamento a si mesmo.²²
• /learn — transforme qualquer descrição em uma skill. Converta um fluxo de trabalho em uma skill reutilizável descrevendo-o; as skills geradas seguem automaticamente as convenções do CONTRIBUTING.md do repositório.²²
• Linha do tempo de /journey. Um histórico visual da memória e das skills ao longo do tempo, com edição, além de um grafo de memória no desktop.²²
• Distribuição de subagentes em segundo plano. Delegue várias tarefas que são executadas simultaneamente sem bloquear a conversa — o único subagente em segundo plano da v0.17.0 se transforma em uma frota.²²
• Projects no desktop. Projects de programação nativos com um modelo de organização por projeto/repositório/lane.²²
• Gateway com scale-to-zero. Gateways podem entrar em estado inativo quando não estão em uso e coordenar o encerramento de tarefas para implantações sem interrupção — algo relevante para quem executa Hermes como um serviço sempre ativo.²²
• Suporte ao Google Vertex AI. Acesso ao Gemini por meio de contas de serviço do GCP com renovação automática de token OAuth2, passando a fazer parte do catálogo de provedores.²²
• Comando de edição /prompt. Abre $EDITOR para você compor prompts em várias linhas, em vez de ter que lutar com a linha de entrada.²²

Se você estiver atualizando da v0.17.x, nada aqui quebra o CLI. Os principais motivos para atualizar são os contratos de conclusão (objetivos que verificam a si mesmos), o MoA nativo com conjuntos inspecionáveis e /learn para capturar skills.

Novidades da v0.17.0 (The Reach Release)

O Hermes Agent v0.17.0 (tag v2026.6.19, 19 de junho de 2026) recebeu esse nome devido ao alcance que o agente passou a ter — novos canais de mensagens, novos provedores de modelos e um controle mais profundo do desktop e do dashboard. Ele adiciona recursos à v0.16.x; a interface CLI permanece inalterada.²¹

• Novos canais de mensagens. Agora, o iMessage funciona sem um Mac como relay por meio do Photon Spectrum (OAuth com código do dispositivo, hermes photon login); a API do WhatsApp Business Cloud é um adaptador oficial da Meta que elimina a necessidade de um processo de bridge; o SimpleX ganha grupos, anexos nativos, agrupamento de texto e aceitação automática; e o Raft passa a fazer parte dos plugins de plataforma incluídos, com um design de canal de ativação cuja privacidade é garantida por contrato.²¹
• Novos modelos e provedores. O catálogo agora inclui 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, com contexto de 200k). O padrão da xAI mudou para grok-build-0.1, e os modelos adaptativos da Anthropic agora seguem o contrato moderno de raciocínio (eles nunca enviam um campo reasoning).²¹
• Desktop e dashboard. O desktop adiciona subagentes em segundo plano, com “watch-windows” que transmitem a atividade delegada em tempo real (delegate_task(background=true)), um seletor de modelos no Composer, atalhos de teclado reconfiguráveis, notificações nativas do sistema operacional, rascunhos do Composer por thread, temas do VS Code Marketplace e interface em japonês e chinês tradicional. O dashboard adiciona um construtor completo de profiles (modelos/skills/MCPs sem editar o config.yaml), um seletor global de profile, um Skills Hub reformulado com verificação de segurança, Automation Blueprints (templates parametrizados para formulários, comandos slash, conversas e documentação) e um login seguro que retorna 401 quando está atrás da camada de proteção OAuth.²¹
• Skills e ferramentas. Agora, image_generate pode editar e transformar uma imagem de origem, não apenas criar uma do zero, em todos os provedores de imagem compatíveis; a ferramenta memory ganhou um array operations para adicionar, substituir ou remover itens em lote de forma atômica em uma única chamada; uma nova skill simplify-code executa uma etapa paralela de revisão e limpeza com três agentes, controlada por um nível de risco baseado no princípio da Cerca de Chesterton; e um write_approval booleano substitui o write_mode de três estados.²¹
• Arquitetura. Subagentes em segundo plano retornam imediatamente um identificador e reinserem seus resultados como um novo turno; um handler de elicitação de MCP permite solicitar confirmação durante uma chamada de ferramenta, e as ferramentas MCP que se conectam mais tarde são disponibilizadas entre os turnos (sem invalidar o cache); o cron se torna um CronScheduler conectável, com um provedor Chronos de cron gerenciado; e um novo escopo Managed (/etc/hermes) permite que um administrador fixe configurações que o usuário não pode alterar, além de um relay Gateway-Gateway para topologias com vários gateways.²¹
• Novos comandos. /version, /billing (faturamento interativo no terminal), hermes photon login (autenticação do iMessage) e hermes curator run --consolidate — agora, a consolidação precisa ser ativada explicitamente, portanto a curadoria rotineira em segundo plano não consome tokens.²¹
• Segurança. A v0.17.0 corrige uma forma de contornar a lista de bloqueio de escapes do shell, aplica bloqueio seguro quando módulos de aprovação ou adaptadores de gateway com políticas próprias estão ausentes, sanitiza o ambiente dos subprocessos de scripts de tarefas cron, oculta segredos nos dumps de depuração de requisições, verifica configurações stdio de MCP em busca de padrões de exfiltração e atualiza urllib3 e PyJWT para corrigir CVEs.²¹

Se você estiver atualizando da v0.16.x, nada disso causa incompatibilidade com a CLI; são novos canais, modelos e interfaces em torno do mesmo agente. O iMessage sem relay, os adaptadores oficiais do WhatsApp e o escopo Managed para administradores são os principais motivos para atualizar.

Novidades da v0.16.0 (The Surface Release)

O Hermes Agent v0.16.0 (tag v2026.6.5, 5 de junho de 2026) recebeu esse nome devido às novas interfaces que oferece ao agente centrado na CLI. A principal novidade é que o Hermes não se limita mais ao terminal.²⁰

• Aplicativo desktop nativo. O Hermes Desktop é um novo aplicativo Electron para macOS, Linux e Windows, com instalação em um clique e atualização automática dentro do próprio aplicativo. 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 modelos na barra de status. Ele pode se conectar a um Hermes gateway remoto por meio de uma WebSocket segura, com autenticação via OAuth ou nome de usuário e senha, hosts remotos específicos para cada profile e sessões simultâneas em vários profiles vinculadas por referências @session entre profiles. A interface desktop também inclui uma tradução completa para chinês simplificado (简体中文) por meio de uma camada i18n tipada (display.language; o inglês continua sendo o idioma padrão).²⁰
• Painel administrativo no navegador. O dashboard web local deixou de ser apenas uma visualização de status e se tornou um painel administrativo completo: um catálogo de MCP com controles para ativar e desativar itens, gerenciamento de credenciais, criação de webhooks e hooks, configuração de memória, controles do gateway e uma página System com verificação antes da atualização e Debug Share em um clique. Uma nova página Channels permite configurar todas as plataformas de mensagens do gateway (Telegram, Discord, Slack e as demais) pelo navegador. Agora, a autenticação é conectável: login com nome de usuário e senha, um provedor OIDC genérico auto-hospedado, hermes dashboard register para um cliente OAuth auto-hospedado e rotação de sessões por refresh token.²⁰
• Novos comandos de CLI e slash. /undo [N] desfaz os últimos N turnos do usuário com preenchimento prévio e exclusão reversível, e funciona na CLI, na TUI e nas plataformas de mensagens. Uma interface padrão configurável (cli ou tui) chega com a opção --cli; a TUI ganha um comando /model unificado e uma sobreposição Sessions. hermes portal é um alias fácil de entender para o fluxo de integração do Nous Portal, com novos caminhos de primeira execução Quick Setup e Full Setup, além de dois novos diagnósticos: hermes prompt-size e hermes sessions optimize.²⁰
• Novos modelos e provedores. O seletor agora inclui deepseek-v4-flash, MiniMax-M3 (contexto de 1M, provedores nativos da MiniMax), qwen3.7-plus (Nous + OpenRouter) e gemini-3.5-flash (OAuth do Gemini + chave de API). Um provedor OAuth oficial para o Grok da xAI passa a fazer parte do inicializador desktop, o seletor de modelos agora oferece busca aproximada em todas as interfaces, provedores com vários endpoints são agrupados em uma única linha e a atualização do catálogo passou de diária para horária.²⁰ (Desde então, a v0.21.1 alterou novamente a frequência: os catálogos remotos do seletor são atualizados a cada 20 minutos, model_catalog.ttl_minutes.⁴⁶)
• Skills mais enxutas e divulgação progressiva. O conjunto padrão de skills deixou de incluir skills redundantes e inativas (o Spotify migrou para um plugin nativo, o Linear para hermes mcp install linear e várias entradas desatualizadas foram removidas), moveu outras para o conjunto opcional e adicionou um filtro de relevância environments: no frontmatter (kanban/docker/s6), que mantém as skills específicas de determinado contexto fora do índice até que sejam solicitadas. NVIDIA/skills agora é uma fonte confiável padrão do Skills Hub, ao lado de OpenAI, Anthropic e HuggingFace. As ferramentas de MCP e de plugins ganharam divulgação progressiva (com escopo), e foi corrigido um bug de MCP que indicava falsamente o sucesso da OAuth quando nenhum token era obtido.²⁰
• Segurança. A v0.16.0 fixa a versão corrigida do Starlette (≥1.0.1) para a CVE-2026-48710 (BadHost), retira as verificações de URLs contra SSRF do event loop em caminhos assíncronos, remove o bearer token de inferência do Bedrock do ambiente dos subprocessos, adiciona bws_cache.json à proteção de segurança de leitura de arquivos, inclui docker restart/stop/kill na lista de padrões perigosos e sanitiza caracteres Unicode invisíveis no conteúdo de skills verificadas. A versão corrigiu 2 problemas P0 e 62 problemas P1, dos quais 16 estavam relacionados à segurança.²⁰

Se você estiver atualizando da v0.15.x, nada disso representa uma mudança incompatível na própria CLI; são interfaces e provedores adicionais em torno do mesmo agente. O aplicativo desktop e o painel administrativo são os motivos para atualizar se você quiser disponibilizar o Hermes a usuários que não utilizam o terminal ou administrar um gateway remoto pelo navegador.

Novidades da v0.14.0 (The Foundation Release)

A v0.14.0 não gira tanto em torno de um único recurso de destaque, mas de reduzir o atrito da configuração e ampliar os ambientes em que o Hermes pode ser executado.¹⁹ As principais mudanças operacionais:

• A instalação e a inicialização estão mais leves. pip install hermes-agent funciona pelo PyPI, adaptadores pesados são instalados sob demanda no primeiro uso, e o fluxo de inicialização posterga trabalho suficiente para reduzir a inicialização a frio em cerca de 19 segundos. (Desde então, a v0.19.0 descontinuou as instalações via pip — consulte Instalação.)
• Assinaturas podem se transformar em endpoints API locais. hermes proxy transforma provedores baseados em 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 passam a integrar o gateway (a tabela de comparação de plataformas da documentação lista 28 plataformas na tag v2026.8.31; a seção Gateway de mensagens explica o que esse número inclui), o Microsoft Teams recebe integração de ponta a ponta, o preenchimento retroativo do histórico do Discord vem ativado por padrão e as solicitações clarify do Telegram/Discord agora usam botões nativos.
• A verificação após a gravação melhora. Depois das edições, o Hermes pode exibir resumos das alterações em arquivos por turno e diagnósticos semânticos do servidor de linguagem antes do próximo turno, aproximando-se de um trabalho de agente baseado em evidências.
• As ferramentas de desktop e mídia foram ampliadas. computer_use funciona por meio do cua-driver para provedores que não são da Anthropic, video_generate foi unificado por trás de backends conectáveis e vision_analyze envia os pixels brutos aos modelos que realmente têm recursos de visão.

Instalação

O instalador de uma linha é o método de instalação oficial. Ele cuida do Python, uv, Node.js, ripgrep, ffmpeg, da clonagem do repositório, do ambiente virtual e do comando global hermes.⁷

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

As instalações via pip e Homebrew estão obsoletas desde a v0.19.0. O pacote PyPI introduzido pela v0.14.0 (pip install hermes-agent) e a fórmula do Homebrew agora são classificados como instalações “legadas sem suporte” — todas as interfaces exibem um aviso (sem bloquear a execução) quando o Hermes detecta uma delas, e está prevista a descontinuação da publicação no PyPI/Homebrew. Se você instalou via pip ou brew, migre para o instalador acima.⁵⁶

Funciona no Linux, macOS, WSL2 e Android/Termux (o instalador detecta o Termux automaticamente e usa um pacote testado para Android).⁷ O Windows nativo agora é uma plataforma de Tier 1, e não mais a versão beta inicial lançada na v0.14.0 — instale-o com iex (irm https://hermes-agent.nousresearch.com/install.ps1). Uma ressalva que a documentação deixa clara: o suporte ao macOS é exclusivo para Apple Silicon, e Macs com processadores Intel não são compatíveis.⁵⁵ Historicamente, a v0.14.0 adicionou suporte nativo ao Windows em versão beta inicial por meio de um instalador PowerShell, mas o WSL2 continua sendo a recomendação mais segura para uso em produção até que a opção para Windows amadureça.¹⁹

Após a conclusão:

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

O único pré-requisito é o git. O instalador provisiona automaticamente o Python 3.11 por meio do uv (sem exigir sudo), o Node.js 26 (para automação de navegador e a ponte do WhatsApp), o ripgrep e o ffmpeg. O Node 26 é a versão mínima obrigatória desde a v0.20.0 — o instalador rejeita qualquer versão anterior e instala uma versão do Node gerenciada pelo Hermes.⁵⁵⁷

Verifique a instalação

hermes --version    # Check version (global flag; there is no `version` subcommand)
hermes doctor       # Diagnose config/dependency issues
hermes status       # Show current configuration + auth state
hermes dump         # Copy-pasteable setup summary for debugging

O hermes doctor informa exatamente o que está faltando e como corrigir o problema.⁷ O hermes dump é o comando de diagnóstico que você deve colar em uma issue do GitHub ou em uma conversa no Discord ao pedir ajuda — ele gera um resumo em texto simples de toda a sua configuração, com os dados secretos ocultados.⁸

Instalação manual

Se você precisar de controle total — uma versão personalizada do Python, extras específicos ou integração com Nix/NixOS —, o processo manual está documentado passo a passo no guia de instalação oficial.⁷ Estes são os principais extras opcionais que você pode combinar com uv pip install -e ".[<extras>]":

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

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

Isso ocorre porque .[all] no Android instala o faster-whisper por meio do extra voice, que depende de wheels do ctranslate2 que não são publicados para Android.⁷

Autenticação e provedores

Na tag v2026.9.7, hermes_cli/models_catalog_static.py contém 39 entradas estáticas de CANONICAL_PROVIDERS na linha 311 (a reorganização de setembro de 2026 moveu a lista para fora de hermes_cli/models.py; as entradas em si não mudaram, incluindo tencent-tokenplan da v0.21.0) e amplia automaticamente essa lista com base em plugins/model-providers/ (39 diretórios incluídos; nove deles — actual, alibaba-coding-plan, commandcode, deepinfra, meta-ai, nebius-token-factory, opencode-free, router, upstage — não têm uma entrada estática e são incorporados pela extensão automática porque usam o tipo de autenticação padrão api_key). As tabelas da página de documentação sobre provedores incluem 45 provedores de nuvem e assinatura, além de uma linha para endpoints personalizados, e apresentam separadamente os servidores locais e auto-hospedados (Ollama, vLLM, SGLang, llama.cpp, LM Studio, LiteLLM, ClawRouter e qualquer endpoint compatível com OpenAI).²⁶ Na tag v2026.9.24, a lista estática ainda contém 39 entradas, mas plugins/model-providers/ contém 38 diretórios: o provedor sem chave opencode-free foi removido em 18 de setembro porque o nível gratuito do OpenCode passou a rejeitar tráfego anônimo vindo de fora do próprio cliente.⁵³ Além disso, há endpoints personalizados e três caminhos distintos de autenticação. A seguir está toda a superfície de autenticação, organizada por caminho para que você encontre aquele que corresponde ao que tem disponível.

Os três caminhos de autenticação

Todos os provedores do Hermes se encaixam em um destes três padrões de autenticação:

Caminho 1 — chave de API no .env. Coloque sua chave em ~/.hermes/.env, e o Hermes a lerá na inicialização. Esse caminho é 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 pela maioria dos provedores de terceiros.² Desde a v0.19.0, a chave não precisa mais ficar em um arquivo de texto simples: uma interface conectável SecretSource pode buscar segredos no Bitwarden ou 1Password (referências op://) durante o carregamento, com vários cofres ativados simultaneamente, precedência determinística, avisos de conflito e rastreabilidade da origem de cada variável — o .env continua sendo a alternativa. (Isso é diferente do token de bootstrap do Bitwarden Secrets Manager introduzido na v0.15.0, que consolidava as chaves dos provedores por trás de um único token; o SecretSource substitui o próprio arquivo de texto simples, e futuros provedores de cofres podem ser adicionados como plugins.)⁵⁶

Caminho 2 — OAuth via hermes model ou hermes auth. Inicia um fluxo de código de dispositivo, abre um navegador, armazena as 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 do ChatGPT), GitHub Copilot e Anthropic (Claude Pro/Max).²

Caminho 3 — endpoint personalizado no 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. Configure uma vez em hermes model → Custom endpoint; depois, a configuração será salva no config.yaml.²

A matriz completa de provedores

Esta matriz abrange os provedores presentes nas tabelas da página de documentação, com o fluxo exato de configuração de cada um; o seletor da tag lista mais provedores do que a documentação (consulte a contagem acima), e qualquer serviço compatível com OpenAI pode usar a linha de endpoint personalizado.²²⁶

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

A Anthropic tem uma seção própria porque o Hermes oferece três caminhos distintos para acessar a Claude, e escolher o correto faz diferença. Segundo a documentação upstream:²

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

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

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

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

Quando você escolhe a OAuth da Anthropic pelo hermes model, o Hermes prioriza o armazenamento de credenciais do próprio Claude Code em vez de copiar o token para ~/.hermes/.env. Assim, as credenciais atualizáveis da Claude continuam podendo ser renovadas.² Se você já usa o Claude Code na mesma máquina, esse é o caminho mais simples.

Para fixar permanentemente a Anthropic no config.yaml:

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

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

Copilot da GitHub: dois modos

O Copilot é compatível com dois modos: API direta do Copilot (recomendado) e Copilot ACP (que inicia a 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

Segundo a documentação upstream, a autenticação é verificada nesta ordem:² 1. Variável de ambiente COPILOT_GITHUB_TOKEN 2. Variável de ambiente GH_TOKEN 3. Variável de ambiente GITHUB_TOKEN 4. Fallback para gh auth token na CLI 5. Login por código de dispositivo da OAuth via hermes model

O tipo de token é importante. A API do Copilot não aceita Personal Access Tokens clássicos (ghp_*). Os tipos compatíveis são tokens da OAuth (gho_*), PATs refinados (github_pat_* com a permissão Copilot Requests) e tokens de App da GitHub (ghu_*). Se o comando gh auth token retornar um token ghp_*, use hermes model para se autenticar pela OAuth.²

Providers chineses de IA (suporte nativo)

O Hermes oferece suporte integrado a z.ai/GLM, Kimi/Moonshot, MiniMax (endpoints globais e da China) e Alibaba Cloud, com IDs de provider 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.²

O Z.AI detecta o endpoint automaticamente. Ao usar o provider z.ai/GLM, o Hermes testa vários endpoints (globais, da China e variantes para programação) para encontrar um que aceite a sua chave de API. O endpoint funcional é armazenado em cache automaticamente — a maioria dos usuários não precisa definir GLM_BASE_URL.²

A xAI (Grok) ativa automaticamente o cache de prompts. Quando a URL-base contém x.ai, o Hermes envia o cabeçalho x-grok-conv-id em todas as solicitações para encaminhá-las ao mesmo servidor durante uma sessão de conversa, reutilizando os prompts de sistema e o histórico armazenados 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 da 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

Os pools de credenciais permitem alternar entre várias chaves de API ou tokens da OAuth para o mesmo provider — algo útil para distribuir os limites de uso entre várias chaves sem alterar o código.⁶ Os comandos legados hermes login / hermes logout foram removidos; use hermes auth no lugar deles.⁶

Endpoints personalizados e auto-hospedados

O Hermes funciona com qualquer endpoint de API compatível com OpenAI. Se um servidor implementar /v1/chat/completions, você poderá direcionar 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

Configuração manual no config.yaml:

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 salvam as configurações no config.yaml, que é a única fonte da verdade para o modelo principal, o provider e a URL-base.² As variáveis de ambiente legadas OPENAI_BASE_URL e LLM_MODEL não são mais lidas para configurar o modelo principal — use hermes model ou edite o config.yaml diretamente.² (OPENAI_BASE_URL + OPENAI_API_KEY ainda são aceitas como fallback para o caminho de roteamento auxiliar provider: "main", portanto, não as exclua sem verificar se você as usa nesse contexto.)⁴

Como alternar endpoints personalizados durante uma sessão:

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

/model custom (sem o nome do modelo) consulta o API /v1/models do seu endpoint e seleciona automaticamente o modelo caso apenas um esteja carregado — útil para servidores locais que executam um único modelo.²

Servidores LLM locais (modelos de configuração)

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

Ollama — o caminho local mais fácil, sem nenhuma 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

Armadilha crítica do Ollama: por padrão, o Ollama usa janelas de contexto muito pequenas (4.096 tokens com menos de 24 GB de VRAM). Você precisa aumentá-las por meio de OLLAMA_CONTEXT_LENGTH ou de um Modelfile — o API compatível com OpenAI não aceita o tamanho do contexto enviado pelo cliente, portanto o Hermes não pode configurá-lo para você.² Para usar com agentes, defina pelo menos 16k–32k.

vLLM — servidor GPU de alto desempenho:

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

As 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 serão retornadas como texto simples.²

SGLang — servidor 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

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

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

./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 essa opção, o llama-server ignora completamente o parâmetro tools, e o modelo tenta chamar ferramentas escrevendo JSON no texto da resposta — algo que o Hermes não consegue interpretar como chamadas de ferramentas reais.²

LM Studio — aplicativo para desktop com interface gráfica:

Inicie o servidor pelo aplicativo LM Studio (aba Developer → Start Server) ou pelo 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.

Armadilha crítica do LM Studio: o LM Studio lê o tamanho do contexto nos metadados do modelo, mas muitos modelos GGUF informam valores padrão de 2048 ou 4096. Sempre defina explicitamente o tamanho do contexto nas configurações de modelo do LM Studio — clique no ícone de engrenagem ao lado do seletor de modelos, defina “Context Length” como pelo menos 16384 (de preferência 32768) e recarregue o modelo.²

Provedores personalizados nomeados

Se você trabalha com vários endpoints personalizados (por exemplo, um servidor local de desenvolvimento e um servidor GPU remoto), defina-os como provedores personalizados nomeados no config.yaml:²

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

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

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

Você também pode selecionar provedores personalizados nomeados no menu interativo de hermes model.²

Arquitetura de provedores extensível (v0.13.0+)

A v0.13.0 inclui uma ABC ProviderProfile e uma pasta plugins/model-providers/, permitindo adicionar provedores de inferência de terceiros sem modificar o núcleo.¹⁸ Se um provedor oferece um modo de API compatível com OpenAI, Anthropic ou Codex, você pode implementar uma subclasse de ProviderProfile que declare o fluxo de autenticação, a URL base, o catálogo de modelos e os cabeçalhos de cache; o Hermes faz a resolução pelo mesmo fluxo de runtime_provider.py usado pelos provedores integrados. Essa é a mudança arquitetural por trás da expansão de provedores na v0.13.0: em vez de editar o código principal para adicionar um provedor, você distribui um plugin.

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

hermes proxy disponibiliza 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 vinculada à assinatura sem precisar de uma chave API separada. Trate o proxy como infraestrutura local de desenvolvimento: vincule-o a uma interface de rede de forma intencional, não o exponha amplamente e considere os termos específicos do provedor.

Detecção do tamanho do contexto

Segundo a documentação upstream, duas configurações são confundidas constantemente:²

• context_length — a janela de contexto total (orçamento combinado de tokens de entrada e saída, por exemplo, 1.000.000 para Claude Opus 4.7 ou 200.000 para Sonnet 4.6). O Hermes usa esse valor para decidir quando comprimir o histórico.
• model.max_tokens — o limite de saída (número máximo de tokens que o modelo pode gerar em uma única resposta). Não está relacionado ao tamanho do histórico.

Defina context_length quando a detecção automática identificar incorretamente o tamanho da janela:

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

O Hermes usa uma cadeia de resolução com várias fontes para detectar janelas de contexto: substituição na configuração → configuração por modelo do provedor personalizado → cache persistente → /models do endpoint → /v1/models do Anthropic → API do OpenRouter → Nous Portal → models.dev (registro mantido pela comunidade com mais de 3.800 modelos) → valores padrão de fallback (128K).² O sistema considera o provedor, portanto o mesmo modelo pode ter limites de contexto diferentes dependendo de quem o fornece (por exemplo, claude-opus-4.6 tem 1M diretamente no Anthropic, mas 128K no GitHub Copilot).²

Roteamento inteligente de modelos: rotação de provedores e fallback

O Hermes não limita você a um modelo em um único provedor. Roteamento inteligente de modelos é o conjunto de mecanismos que decide qual provedor e modelo realmente atende a uma determinada solicitação: pools de credenciais distribuem a carga entre as chaves, um fallback configurado assume quando o provedor principal falha e os slots auxiliares abaixo encaminham tarefas secundárias para modelos mais baratos, independentemente do seu modelo principal.²⁶ Configure esses três recursos em conjunto – eles fazem a diferença entre um agente que para ao atingir um limite de requisições e outro que continua trabalhando.

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

Modelo de fallback. Configure um provider:model alternativo, para o qual o Hermes muda automaticamente quando o modelo principal falha (limites de requisições, erros do servidor ou 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 o modelo e o provedor durante a sessão sem perder sua conversa. Ele é acionado 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

O Hermes usa modelos “auxiliares” para tarefas secundárias: análise de imagens (visão), classificação de aprovação de comandos perigosos, compressão de contexto, geração de títulos de sessões, inserção de tags de áudio TTS, correspondência de skills, encaminhamento de ferramentas MCP e a família de especificadores/decompositores do Kanban.⁴³⁴ Por padrão (auxiliary.*.provider: "auto"), todas as tarefas auxiliares são executadas pelo seu modelo principal de chat – o mesmo provedor/modelo que você escolheu em hermes model. A documentação deixa claro que isso substituiu a antiga detecção automática de provedores baratos: “Versões anteriores direcionavam usuários de agregadores (OpenRouter, Nous Portal) para uma opção padrão barata do provedor. Isso era inesperado … agora, auto usa o modelo principal para todos, e as substituições por tarefa no config.yaml continuam prevalecendo.”³⁴ Você não precisa configurar nada para começar; a desvantagem é o custo – em modelos de raciocínio caros, as tarefas auxiliares geram gastos consideráveis, portanto direcione tarefas específicas para modelos rápidos e baratos quando isso for importante. Duas antigas tarefas auxiliares deixaram de usar qualquer LLM: a extração da web (“web_extract e os snapshots do navegador truncam conteúdos longos de forma determinística e armazenam o texto completo para paginação com read_file – sem envolver LLM”) e a busca de sessões (a ferramenta de formato único retorna o conteúdo do banco de dados diretamente). Os antigos blocos auxiliary.web_extract.* e auxiliary.session_search.* foram removidos das configurações padrão – valores remanescentes em um config.yaml existente são “resíduos inofensivos e ignorados” – e o slot flush_memories também não está presente nas configurações padrão dessa tag.³⁴

Você pode configurar o modelo e o provedor usados por cada tarefa auxiliar. Todos os slots auxiliares usam as mesmas opções: provider, model, base_url (além de api_key, timeout, extra_body e um reasoning_effort específico para cada tarefa).⁴³⁴

auxiliary:
  vision:                          # vision_analyze + browser screenshots
    provider: "auto"               # "auto" (= main model), "openrouter", "nous", "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: 120
    download_timeout: 30
  approval:                        # dangerous-command approval classifier
    provider: "auto"
    model: ""
    timeout: 30
  compression:                     # summarizer -- legacy compression.summary_* keys migrate here (config v17)
    provider: "auto"
    model: ""
    base_url: ""
    timeout: 120
  title_generation:                # auto-generated session titles after the first exchange
    enabled: true                  # set false to disable auto-titles
    provider: "auto"
    model: ""
    language: ""                   # empty follows the conversation; e.g. "English" pins titles to one language
  tts_audio_tags:    { provider: "auto", model: "" }  # Gemini 3.1 TTS hidden audio-tag insertion
  skills_hub:        { provider: "auto", model: "" }  # skill matching and search
  mcp:               { provider: "auto", model: "" }  # MCP tool dispatch
  triage_specifier:  { provider: "auto", model: "" }  # hermes kanban specify: rough one-liner into a concrete spec, promoted to todo
  kanban_decomposer: { provider: "auto", model: "" }  # hermes kanban decompose: triage task into a graph of child tasks routed to specialist profiles
  profile_describer: { provider: "auto", model: "" }  # hermes profile describe --auto: 1-2 sentence profile descriptions

Outros slots especializados seguem o mesmo formato – goal_judge (avalia se o contrato de /goal foi cumprido), curator (o fork de revisão do uso de skills), background_review (o fork de autoaperfeiçoamento executado após o turno), review (o subagente revisor de /review), moa_reference e moa_aggregator (Mixture-of-Agents), memory_query_rewrite e monitor – e você não precisa editar YAML manualmente: execute hermes model e escolha “Configure auxiliary models” para abrir um seletor interativo por tarefa.³⁴

A opção de provedor "main" significa “usar o mesmo provedor que o meu agente principal usa” – válida somente em auxiliary:, compression: e nas entradas principais de fallback (fallback_providers: ou o antigo fallback_model:). Ela não é válida na configuração de nível superior model.provider. Se você usar um endpoint personalizado compatível com OpenAI como modelo principal, defina provider: custom na seção model:.⁴

Por que isso importa: como auto já usa o seu modelo principal, a antiga armadilha de “configure o OpenRouter ou as tarefas auxiliares perderão recursos silenciosamente” deixou de existir – agora, o ponto de atenção é o custo. Se o seu modelo principal for um modelo de raciocínio caro, encaminhe as tarefas secundárias mais frequentes para algo barato e rápido:

auxiliary:
  vision:
    provider: "openrouter"
    model: "google/gemini-2.5-flash"
  compression:
    provider: "openrouter"
    model: "google/gemini-2.5-flash"

Sistema de configuração

O Hermes tem um sistema de configuração em camadas. Entender a ordem de precedência é essencial, pois as camadas superiores substituem as inferiores, e uma delas é um registro global de provedores que você não pode ver no config.yaml.

Estrutura dos arquivos de configuração

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

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

config.yaml vs .env — quando ambos estão definidos, config.yaml prevalece para configurações que não são secretas.⁴ A regra é: - Segredos (chaves API, tokens de bots, senhas) → .env - Todo o restante (modelo, backend do terminal, configurações de compactação, limites de memória, toolsets) → config.yaml

Os segredos podem ser referenciados no 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 get KEY        # Print a single value (v0.19.0+)
hermes config unset KEY      # Remove a key so the default applies again (v0.19.0+)
hermes config path           # Print the config file path
hermes config env-path       # Print the .env file path
hermes config check          # Check for missing options (after updates)
hermes config migrate        # Interactively add missing options

Exemplos:⁴

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

hermes config check e hermes config migrate são os comandos que você deve executar após cada hermes update — eles detectam novas opções de configuração que ainda não estão no seu arquivo.⁶

Precedência da configuração

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

1. Argumentos de CLI — hermes chat --model anthropic/claude-sonnet-4 (substituição para uma única execução)
2. Variáveis de ambiente — aplicadas na inicialização do processo
3. config.yaml — o arquivo principal de configurações
4. .env — apenas segredos
5. Valores padrão integrados — aplicados quando nenhuma outra fonte define um valor

As flags de CLI sempre prevalecem naquela execução específica. O config.yaml é a fonte da verdade de longo prazo.

Localização (v0.13.0+)

A v0.13.0 adicionou 7 idiomas às mensagens de CLI e do gateway: chinês (simplificado), japonês, alemão, espanhol, francês, ucraniano e turco.¹⁸ A v0.14.0 traduz todos os comandos do gateway e o painel web, adiciona mais 8 idiomas e eleva o total para 16.¹⁹ Na tag v2026.8.31, a árvore locales/ contém 17 catálogos de mensagens – inglês e 16 traduções (af, ar, de, es, fr, ga, hu, it, ja, ko, pt, ru, tr, uk, zh-hant, zh).³³ No momento, a documentação está disponível apenas em zh-Hans, além do inglês. O idioma é determinado pelas variáveis de ambiente LC_ALL / LANG ou por uma chave locale: explícita no config.yaml. O inglês continua sendo o padrão e a fonte da verdade para qualquer texto que uma tradução ainda não cubra.

Profiles — várias instâncias isoladas do Hermes

Os profiles oferecem 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 um “Hermes de trabalho” e um “Hermes pessoal” lado a lado, sem que um tenha acesso ao 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), permitindo que vários profiles executem o gateway simultaneamente sem interferir uns nos outros.⁶³

O limite de isolamento passou a ser aplicado com mais rigor a partir da v0.21.2: um conjunto de correções eliminou vazamentos reais entre profiles em configurações com gateways multiplexados, nas quais profiles secundários podiam herdar as listas de permissões do profile padrão, enviar credenciais ao host dele, fornecer os segredos do cofre dele a servidores MCP via stdio ou anexar o .env/auth.json/state.db de outro profile à entrega por MEDIA: (#107609-#107630). Se você multiplexa profiles, a v0.21.2 é a tag em que a alegação de isolamento realmente passa a valer – consulte Novidades da v0.21.2.⁴⁸

Comandos do CLI

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

Opções globais

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

Comandos de nível superior

hermes chat — O principal ponto de entrada

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

hermes chat -q "Summarize the latest PRs" --oneshot # Answer and exit (without --oneshot, a TTY seeds an interactive session)
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"

Principais opções:

hermes setup — Assistente completo

Executa o assistente completo de configuração ou abre diretamente 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 do que tail -f nos arquivos de log porque permite filtrar simultaneamente por nível, ID da sessão e intervalo de tempo.⁶

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 — todas as atividades do agente (chamadas do API, despacho de ferramentas, ciclo de vida da sessão, INFO+) - errors.log — apenas avisos e erros (um subconjunto filtrado de agent.log) - gateway.log — atividades do gateway de mensagens (conexões com plataformas, despachos e webhooks)

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

hermes doctor — Diagnósticos

hermes doctor [--fix] é o primeiro comando que você deve executar quando algo dá errado. Ele verifica a validade da configuração, a presença de dependências, a disponibilidade da chave do API e o status dos serviços, além de poder tentar correções automáticas com --fix.⁶

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

Comandos slash

Os comandos slash são executados dentro de uma sessão de chat ativa (CLI ou plataforma de mensagens). Eles são despachados de um COMMAND_REGISTRY compartilhado em hermes_cli/commands.py, por isso a maioria dos comandos funciona da mesma forma em todas as interfaces.⁹

Controle da sessão

Configuração e modelo

O comando /model é o principal recurso para trocar de provedor durante uma 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

A v0.19.0 adiciona /model --once — uma substituição do modelo por um único turno que retorna automaticamente ao modelo anterior após a resposta.⁵⁶ Desde a janela da v0.20.5, o seletor de /model também usa busca aproximada: ele filtra à medida que você digita.²³³⁵

Ferramentas, skills e informações

Comandos slash dinâmicos de skills

Cada skill instalada é exposta 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

Desde a v0.19.0, as invocações de skills por comando slash podem ser encadeadas: /skill-a /skill-b do XYZ carrega as duas skills em ordem, em um único turno, com preenchimento automático e texto fantasma para os nomes encadeados.⁵⁶

Você também pode definir comandos rápidos no config.yaml que associam um nome curto a 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 permitem correspondência por prefixo: digitar /h resulta em /help, enquanto /mod resulta em /model. Quando um prefixo é ambíguo, prevalece o primeiro registro na ordem do registro. Nomes completos de comandos e aliases registrados sempre têm prioridade sobre correspondências por prefixo.⁹

Comandos específicos para plataformas de mensagens

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

• /status — mostra informações da sessão (não é mais exclusivo das plataformas de mensagens; consulte Controle da sessão)
• /sethome (alias /set-home) — define o chat atual como a página inicial da plataforma
• /approve [session|always] — aprova um comando perigoso pendente
• /deny [reason] — rejeita um comando perigoso pendente. Desde a v0.19.0, /deny <reason> informa ao agente o motivo da recusa para que ele corrija o rumo em vez de tentar novamente sem saber o motivo⁵⁶
• /update — atualiza o Hermes Agent para a versão mais recente
• /commands [page] — permite navegar por todos os comandos e skills (com paginação)

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

Tools e Toolsets

O Hermes vem com um amplo registro de tools integradas que abrange pesquisa na web, automação de navegador, execução no terminal, edição de arquivos, memória, delegação, treinamento por RL, envio de mensagens, integração com o 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

Entre os nomes comuns de toolsets estão web, terminal, file, browser, vision, image_gen, moa, skills, tts, todo, memory, session_search, cronjob, code_execution, delegation, clarify, homeassistant e rl.¹⁰

Gerenciamento de tools

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

Também é possível ativar ou desativar tools durante uma sessão usando /tools disable <name> e /tools enable <name>. Isso reinicia a sessão para que o novo conjunto de tools entre em vigor.⁹

Backends de terminal

A tool de terminal inclui 7 backends de execução integrados — e, desde a v0.20.6, esse conjunto pode ser ampliado por plugins, assim como o seletor de provedores (veja abaixo):¹⁰²⁴

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

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

Backends de plugins (v0.20.6+). Os fornecedores terceirizados de sandbox não precisam mais ser incorporados ao repositório principal: um plugin registra um TerminalEnvironmentProvider durante o carregamento por meio de PluginContext.register_terminal_environment_provider, e o nome registrado passa a ser selecionável em terminal.backend exatamente como um backend integrado. Os nomes integrados são reservados — o registro rejeita provedores cujos nomes entrem em conflito com um backend do próprio repositório — e um backend registrado participa automaticamente de todas as interfaces principais (o seletor de backends do hermes setup, o status das verificações no dashboard, as verificações do hermes doctor, o tratamento de caminhos e cwd dos contêineres e a remoção de segredos), pois o núcleo consulta o registro em cada ponto de classificação, em vez de usar uma lista de nomes fixa no código.³²

Backend SSH (recomendado por 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 dos contêineres (aplicável a docker, singularity, modal e 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, os pacotes instalados, arquivos e configurações são preservados entre as 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 namespaces e workspace persistente por meio de 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) permite usar tools interativas do CLI, como Codex e Claude Code.¹⁰

Sudo

Se um comando precisar de sudo, o Hermes solicitará sua senha, que ficará armazenada em cache durante a sessão. Outra opção é definir SUDO_PASSWORD em ~/.hermes/.env.¹⁰

Kanban multiagente (v0.13.0+)

A v0.13.0 transforma a colaboração multiagente em um recurso fundamental: um quadro Kanban persistente que acompanha tarefas, status e a identidade dos workers entre agentes e reinicializações.¹⁸ É o quadro que permite que um swarm de workers do Hermes realmente conclua o trabalho, em vez de ficar parado por causa de transferências interrompidas.

O quadro Kanban combina naturalmente o /goal (loop Ralph com objetivo bloqueado) para definir o objetivo e a tool delegate_task existente para a semântica de criação de agentes. O resultado é um padrão de swarm no qual todos os agentes compartilham uma única fonte da verdade sobre o que fazer a seguir, quem está fazendo o quê e onde há bloqueios.

O que é um swarm do Hermes?

Um swarm é formado por vários workers do Hermes executados em paralelo com um único quadro Kanban compartilhado. Não é um subsistema separado que você precisa ativar — é o que o quadro torna possível. O quadro fornece o único elemento que agentes paralelos não conseguem fornecer por conta própria: uma resposta única e definitiva para o que devo assumir agora e alguém já está trabalhando nisso?

A v0.15.0 elevou esse padrão a uma topologia com suporte oficial, adicionando a topologia de swarm para a coordenação de workers paralelos, a decomposição automática de um objetivo de alto nível em subtarefas, substituições de modelo por tarefa, tarefas agendadas e gerenciamento de worktrees, para que workers paralelos não entrem em conflito no mesmo checkout.⁵⁹

Na prática: forneça um objetivo ao swarm, deixe a decomposição automática dividi-lo em tarefas no quadro e permita que os workers assumam, executem e retornem resultados. O limite de novas tentativas é definido por tarefa (max_retries), para que uma única subtarefa frágil não consuma toda a tolerância da execução. Como o quadro é persistente, um swarm sobrevive a reinicializações — os workers se reconectam e retomam o trabalho usando o mesmo estado.

Um swarm só é tão bom quanto sua decomposição. O quadro coordena os workers, mas não transforma um objetivo mal dividido em um bom objetivo. Tarefas que compartilham um estado oculto ainda entrarão em conflito, com ou sem worktrees.

Sistema de skills

Skills são documentos de conhecimento sob demanda que o agente 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 repositório. As skills instaladas pelo Hub e criadas pelo agente também ficam aqui.¹¹

Divulgação progressiva

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

O agente só carrega o conteúdo completo da skill quando realmente precisa 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

As skills podem se exibir ou se ocultar conforme as ferramentas disponíveis. Isso é especialmente útil para skills de fallback — alternativas gratuitas ou locais que só devem aparecer quando uma ferramenta premium não estiver disponí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 agente usa web_search — a skill do DuckDuckGo permanece oculta. Sem a chave API, a skill do DuckDuckGo aparece automaticamente como fallback.¹¹

Skills gerenciadas pelo agente

O agente pode criar, atualizar e excluir as próprias skills por meio da ferramenta skill_manage. Essa é a memória procedural do agente — quando ele descobre um fluxo de trabalho não trivial, salva a abordagem como uma skill para reutilizá-la no futuro.¹¹

Quando o agente cria skills:¹¹ - Depois de concluir com sucesso uma tarefa complexa (mais de 5 chamadas de ferramentas) - Quando encontrou erros ou becos sem saída e descobriu o caminho que funciona - Quando o usuário corrigiu sua abordagem - Quando descobriu um fluxo de trabalho 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 integradas do Hub:¹¹

Taps padrão do GitHub (navegáveis sem configuração): openai/skills, anthropics/skills, huggingface/skills, NVIDIA/skills, garrytan/gstack. A fonte claude-marketplace foi removida na v0.20.0; browse-sh a substituiu na lista de fontes.¹¹⁵⁵

Verificação de segurança

Todas as skills instaladas pelo Hub passam por um verificador de segurança que procura exfiltração de dados, injeção de prompts, comandos destrutivos, sinais de ataques à cadeia de suprimentos e outras ameaças.¹¹

Níveis de confiança:¹¹

--force pode ignorar bloqueios de política não perigosos para skills da comunidade. Ele não ignora um veredicto dangerous da verificação.¹¹

Diretórios externos de skills

Você pode indicar ao Hermes outros diretórios de skills que serão verificados junto com o diretório local:¹¹

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

Os caminhos oferecem suporte à expansão de ~ e à substituição de variáveis de ambiente ${VAR}. Os diretórios externos são somente leitura — quando o agente cria ou edita uma skill, ele sempre grava em ~/.hermes/skills/. A versão local tem precedência quando existe uma skill com o mesmo nome nos dois lugares.¹¹

Skills fixadas: skills.auto_load (período da v0.21.4)

Os nomes de skills listados em skills.auto_load no config.yaml são fixados e carregados integralmente em cada nova sessão – CLI, TUI, gateway, cron e API:⁵¹

skills:
  auto_load:
    - team-conventions
    - deploy-checklist

A lista é resolvida uma única vez, quando o prompt do agente é criado pela primeira vez; um nome ausente ou desabilitado gera um aviso e é ignorado, em vez de provocar uma falha na sessão, e HERMES_IGNORE_RULES (o mecanismo por trás de --ignore-rules) suprime a lista, assim como o restante do contexto injetado automaticamente. Esse é o complemento de instruções permanentes para -s/--skills, que pré-carrega skills somente para uma sessão.⁵¹

Memória persistente

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

Ambos são inseridos no prompt do sistema como um snapshot congelado no início da sessão. O agent gerencia a própria memória por meio da ferramenta memory — add, replace ou remove.¹²

Padrão de snapshot congelado: a inserção no prompt do sistema é capturada uma única vez no início da sessão e nunca muda durante a sessão. Isso é intencional — preserva o cache de prefixo do LLM para melhorar o desempenho. As alterações feitas durante uma sessão são salvas imediatamente em disco, mas só aparecem no prompt do sistema na sessão seguinte.¹²

O que salvar

Salve estas informações (o agent faz isso proativamente):¹² - Preferências do usuário: “Prefiro TypeScript a JavaScript” → user - Informações sobre o ambiente: “Este servidor executa Debian 12 com PostgreSQL 16” → memory - Correções: “Não use sudo em comandos Docker, o usuário está no grupo docker” → memory - Convenções: “O projeto usa tabulações, linhas de até 120 caracteres e docstrings no estilo do Google” → memory - Trabalho concluído: “Migração do banco de dados do MySQL para o PostgreSQL concluída em 15 de janeiro de 2026” → memory

Não salve estas informações:¹² - Informações triviais ou óbvias - Fatos que podem ser redescobertos facilmente - Dumps de dados brutos (grandes demais para a memória) - Informações efêmeras específicas da sessão - Informações que já estão nos arquivos de contexto

Busca em sessões

Além de MEMORY.md e USER.md, o agent pode pesquisar conversas anteriores usando a ferramenta session_search. Todas as sessões de CLI e de mensagens são armazenadas no SQLite (~/.hermes/state.db) com busca de texto completo FTS5. Desde a reformulação da v0.15.0, a ferramenta não envolve nenhum LLM – ela retorna diretamente o conteúdo armazenado das conversas (nas palavras da fonte: a “ferramenta de formato único retorna o conteúdo do banco de dados diretamente”), o que a tornou 4.500 vezes mais rápida e eliminou seu custo de API.¹²⁵⁹³⁴

Duas adições da janela da v0.21.4, ambas verificadas na tag v2026.9.21. Primeiro, limites de tempo: o formato de descoberta aceita after (um limite inferior inclusivo para o horário de início da sessão) e before (um limite superior exclusivo), cada um como uma data/data e hora ISO – um valor contendo apenas a data significa meia-noite UTC daquele dia – ou uma duração relativa (7d, 24h, 2w), destinados apenas a consultas que realmente especificam um período; sort continua sendo um viés de classificação, não um limite. Segundo, uma nova tentativa de recuperação quando não há resultados: o AND implícito do FTS5 entre os termos significa que uma consulta parafraseada com várias palavras pode não encontrar uma frase armazenada que não contenha sequer uma delas. Por isso, quando a consulta exata e todos os fallbacks por substring não retornam resultados, a busca tenta novamente no índice, procurando correspondências com QUALQUER termo e priorizando na classificação as linhas que abrangem mais termos. Os resultados mantêm a semântica de correspondência exata (a nova tentativa só ocorre quando não há nenhum resultado), enquanto consultas com OR/NOT explícito, de termo único e encaminhadas para CJK não são alteradas.⁵¹

Provedores externos de memória

Para uma memória persistente mais profunda, além de MEMORY.md e USER.md, Hermes inclui sete plugins externos de provedor de memória: Honcho, OpenViking, Mem0, Holographic, RetainDB, ByteRover e Supermemory. Outros, como Hindsight, podem ser instalados pelo catálogo de plugins.¹²

Hindsight fez parte da árvore principal até a v0.21.4 e foi transferido para o catálogo na v0.21.5, sob manutenção da Vectorize. As configurações existentes migram automaticamente: se memory.provider: hindsight estiver definido, hermes update instalará o plugin do catálogo em cada diretório inicial de profile que o mencionar, e a primeira inicialização do agent o instalará se ele ainda estiver ausente. Com security.allow_lazy_installs: false, o fluxo de inicialização do agent apenas registra uma mensagem, então execute você mesmo hermes plugins install hindsight. O plugin é instalado em ~/.hermes/plugins/hindsight/ e adicionado a plugins.enabled; memory.provider, memory.hindsight.*, HINDSIGHT_API_KEY e seus dados de memória permanecem como estavam. Verifique com hermes memory status e hermes plugins list. O extra hermes-agent[hindsight] do pip foi removido.⁵³

Os provedores externos funcionam em conjunto 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 do 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 permite retomar o trabalho após uma interrupção no meio da execução do agent. O gateway retoma automaticamente as sessões interrompidas depois de uma reinicialização; as reinicializações feitas por /update preservam o estado da sessão durante a atualização; e o recarregamento de arquivos-fonte durante o desenvolvimento mantém a sessão ativa em vez de forçar uma nova.¹⁸ Na prática, trabalhos de longa duração no gateway e tarefas acionadas por cron não perdem mais a janela de contexto quando o processo é reiniciado.

Checkpoints v2 (v0.13.0+)

A persistência de estado foi reescrita na v0.13.0 como um design de armazenamento único, com limpeza real, proteções para o disco e sem repositórios-sombra órfãos.¹⁸ O sistema de checkpoint anterior acumulava estados no disco em profiles de longa duração; o armazenamento v2 impõe um limite rígido ao armazenamento local de checkpoints e elimina os registros duplicados que provocavam esse crescimento. Nenhuma alteração de configuração é necessária para o usuário; a próxima gravação de checkpoint usará o caminho v2.

Personalidade e SOUL.md

SOUL.md é a identidade principal de uma instância do Hermes. Ele ocupa a posição nº 1 no prompt do sistema, substituindo a identidade padrão definida diretamente no código.¹³

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

O que deve ficar no SOUL.md

Use-o para orientações duradouras sobre voz e personalidade:¹³ - tom - estilo de comunicação - nível de franqueza - estilo padrão de interação - o que evitar em termos de estilo - como Hermes deve lidar com incertezas, discordâncias e ambiguidades

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

Essas informações devem ficar em AGENTS.md, não em 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 e comportamento relacionado à personalidade.

AGENTS.md — arquitetura do projeto, convenções de código, preferências de ferramentas, fluxos de trabalho específicos do repositório, comandos, portas, caminhos e notas de implantação.

Uma regra útil: se algo deve acompanhar você em todo lugar, deve ficar em SOUL.md. Se pertence a um projeto, deve ficar em AGENTS.md.¹³

Personalidades integradas

Hermes inclui personalidades integradas que você pode ativar 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, ative-a com /personality codereviewer.

SOUL.md vs. /personality

SOUL.md é a voz de base. /personality é uma camada aplicada no nível da sessão.¹³ Mantenha um SOUL.md padrão e pragmático; depois, use /personality teacher para uma conversa didática ou /personality creative para um brainstorming.

Nous Tool Gateway (v0.10.0+)

A partir do Hermes Agent v0.10.0 (16 de abril de 2026), os assinantes pagos do Nous Portal passam a ter acesso gerenciado a um conjunto selecionado de ferramentas usando suas credenciais existentes do Portal — sem precisar gerenciar chaves API adicionais.⁶¹ O CLI do Hermes continua sob a licença MIT e totalmente open source. A mudança é que agora sua autenticação no Portal libera mais do que apenas a inferência de modelos.

O caminho mais rápido é hermes setup --portal, que o README apresenta como “Um comando a partir de uma instalação nova”: ele faz login via OAuth, define a Nous como seu provedor e ativa o Tool Gateway. A partir daí, hermes portal gerencia essa integração. hermes portal login (o padrão quando nenhum subcomando é informado) executa o mesmo onboarding em uma única etapa; hermes portal info exibe o “resumo da autenticação do Portal + roteamento do Tool Gateway”; hermes portal open abre a página de assinatura no seu navegador padrão; hermes portal tools lista as ferramentas do gateway e indica quais são roteadas pela Nous. hermes portal status permanece como um alias oculto de compatibilidade retroativa para info, e a referência do CLI na documentação dessa tag ainda apresenta o subcomando como status, portanto ambos funcionam.²⁸

O que há no gateway

Como funciona

O gateway é ativado individualmente para cada ferramenta por meio de um novo campo de configuração use_gateway. Se você tiver credenciais do Portal em hermes auth e ativar o gateway para uma ferramenta, as chamadas dela serão roteadas pelo Portal. Caso contrário, será usada sua chave API direta (se houver).

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

Precedência em runtime: quando o gateway está disponível e uma ferramenta tem use_gateway: true, o Hermes dá preferência ao gateway, mesmo que você também tenha configurado uma chave API direta. Isso afeta a cobrança — as chamadas pelo gateway consomem sua assinatura do Portal, não o saldo da sua chave API direta.

Como ativar o gateway

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

A assinatura é detectada automaticamente pelas credenciais de OAuth do Portal que você já tem em hermes auth — não há uma etapa separada de login. Desde a v0.19.0, você também pode gerenciar a própria assinatura durante uma sessão: /subscription mostra seu plano e o saldo restante, apresenta exatamente quanto custa um upgrade ou quando um downgrade entra em vigor e aplica a alteração com avisos de mudança agendada e opção para desfazer; /topup adiciona créditos. O aplicativo para desktop tem uma aba correspondente de configurações de cobrança.⁵⁶

Preços e acesso

Os preços e nomes dos 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 versões do Hermes. Cadastre-se em https://portal.nousresearch.com/ e consulte a página de preços para ver os planos atuais.

Plano gratuito da Nous e primeira inicialização guiada (v0.21.2+)

Desde a v0.21.2, uma instalação nova não precisa de um plano pago nem de uma chave API para oferecer um agente funcional: a inferência gratuita e os conectores já vêm incluídos, com um único comando para fazer login, e /login inicia o login dentro de um chat. As ferramentas dos conectores (Gmail, Linear, Notion e as demais) podem ser pesquisadas por meio de tool_search, como qualquer outra ferramenta. O aplicativo para desktop adiciona uma primeira inicialização guiada controlada por HERMES_GUEST_ONBOARDING=1; somente o valor literal 1 a ativa – o próprio teste do aplicativo para desktop confirma que 'true', '0' e um valor vazio a mantêm desativada, e a decisão de inicialização é registrada no ambiente do backend iniciado para impedir que um valor herdado seja propagado.⁴⁸

Desde o período da v0.21.4, conectar esses conectores passou a ser uma única operação controlada pelo backend, em vez de uma lógica fragmentada entre diferentes frontends: uma chamada à ferramenta manage_connections aciona uma máquina de estados de conexão baseada apenas em dados no backend (com um prazo fixo de 300 segundos para a operação – deliberadamente não configurável), e Desktop, TUI e CLI apresentam o mesmo cartão de configuração. O cartão exibe um campo para cada credencial ausente (nome, instrução, obrigatoriedade) e mantém sua ação desativada até que todos os campos obrigatórios tenham conteúdo, enquanto o backend aplica a mesma separação exclusiva para dados secretos em todos os frontends.⁵¹

Aviso de descontinuação

• A variável de ambiente HERMES_ENABLE_NOUS_MANAGED_TOOLS foi removida na v0.10.0. Agora, as ferramentas gerenciadas são ativadas pelo campo de configuração use_gateway de cada ferramenta e dependem do estado da sua assinatura do Portal.⁶¹

Contexto: o que esta versão não é

O CLI do Hermes Agent não exige uma assinatura. O projeto continua sob a licença MIT, e todos os recursos principais (CLI, skills, memória, gateway de mensagens, cron, MCP, dashboard local e BYOK para todos os provedores) funcionam de ponta a ponta sem que você precise pagar nada. A v0.10.0 adiciona uma opção conveniente para usuários que já assinam o Nous Portal — ela não remove nada da opção gratuita.

Gateway de mensagens

O Hermes pode ser executado como um processo gateway de longa duração que se conecta a 28 plataformas de mensagens por meio de um único processo gateway: Telegram, Discord, Slack, WhatsApp, Signal, SMS, e-mail, Home Assistant, Mattermost, Matrix, DingTalk, Feishu/Lark, WeCom, Weixin (WeChat), BlueBubbles (iMessage), QQBot, Microsoft Teams, Tencent Yuanbao, Google Chat, LINE, SimpleX Chat, Photon (iMessage), WhatsApp Cloud API, WeCom Callback, Raft, IRC, ntfy, Buzz e um adaptador Webhook genérico.^360171819 Esse total de 28 vem da tabela Platform Comparison da documentação na tag v2026.8.31; por baixo dos panos, gateway/config.py define 24 membros integrados do enum Platform (incluindo entradas que não são de chat, como local, api_server, webhook, msgraph_webhook e relay) e resolve sob demanda qualquer outro nome para um dos 22 diretórios de adaptadores incluídos em plugins/platforms/. Por isso, uma simples contagem do enum ou dos diretórios não corresponderá ao número da documentação.²⁵ A v0.9.0 adicionou suporte ao iMessage via BlueBubbles (registro automático de webhook, assistente de configuração e resiliência a falhas) e suporte nativo ao WeChat via iLink Bot API, com o modo de callback do WeCom para aplicativos empresariais.¹⁶ A v0.11.0 adicionou o QQBot.⁶⁰ A v0.12.0 adicionou o Microsoft Teams e o Tencent Yuanbao.¹⁷ A v0.13.0 adicionou o Google Chat como a 20ª plataforma, usando a mesma arquitetura de adaptadores conectáveis; o IRC e o Microsoft Teams também foram migrados para o novo padrão de adaptadores, com hooks genéricos de plugin env_enablement_fn / cron_deliver_env_var.¹⁸ A v0.14.0 adiciona LINE e SimpleX Chat e completa a integração do Microsoft Teams de ponta a ponta, com autenticação do Graph, listener de webhook, runtime do pipeline e entrega de saída.¹⁹ A v0.17.0 (19 de junho de 2026) adiciona iMessage sem relay via Photon Spectrum (OAuth por código de dispositivo com hermes photon login — sem necessidade de um Mac ou de relay do BlueBubbles), o adaptador oficial do WhatsApp Business Cloud API (substituindo a exigência de um processo bridge), grupos do SimpleX e anexos nativos, além do Raft como plugin de plataforma incluído.²¹ Outras duas plataformas aparecem na tabela da documentação sem destaque nas notas de versão: ntfy é um canal leve de push pub-sub via HTTP (assine um tópico pelo aplicativo móvel do ntfy, envie uma mensagem ao tópico para conversar com o agente e receba a resposta no celular; funciona com o servidor público ntfy.sh ou com uma instância auto-hospedada, sem exigir SDK nem daemon), enquanto o Buzz conecta o Hermes a uma comunidade Buzz, a plataforma open source da Block para colaboração entre pessoas e agentes baseada no protocolo Nostr, invocando o buzz CLI para mensagens de saída e usando uma assinatura Nostr WebSocket nativa para mensagens de entrada. Ambos são configurados por meio de hermes gateway setup.²⁵

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 bots, mapeamentos de canais e listas de permissões.⁶

Como as mensagens fluem

Segundo a documentação de arquitetura do projeto original:³

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

Todas as plataformas de mensagens passam pelo mesmo loop de conversa AIAgent usado pela CLI. É por isso que os comandos de barra funcionam da mesma forma nos dois ambientes e que um cron job agendado no Telegram pode entregar sua saída ao Discord — a diferença entre as plataformas existe apenas nas extremidades.³

A v0.19.0 adiciona roteamento de mensagens por profile e entrega durável. Um único gateway multiplexado compartilhando um token de bot pode encaminhar guilds, canais ou threads específicos para profiles diferentes — cada um com configurações, skills, memória e segredos totalmente isolados —, com uma substituição por GATEWAY_MULTIPLEX_PROFILES. Além disso, uma série de melhorias de robustez impede que um profile configurado incorretamente derrube todo o gateway. Nos bastidores, o índice de roteamento foi transferido para state.db (sessions.json agora é apenas um espelho legado opcional), e as respostas finais são registradas em um ledger durável de obrigações de entrega antes e depois do envio pela plataforma — se uma resposta concluída coincidir com uma falha do gateway, ela será reenviada na próxima inicialização, em vez de ser perdida silenciosamente.⁵⁶ O isolamento entre profiles roteados foi reforçado na v0.21.2, que eliminou um conjunto de vazamentos entre profiles justamente nessa configuração multiplexada: listas de permissões herdadas, credenciais enviadas ao host do profile padrão, segredos do vault do profile padrão chegando a servidores stdio MCP, anexos MEDIA: cruzando profiles e o bearer do Nous de um profile irmão persistindo em memos por processo (#107609-#107630).⁴⁸

A v0.21.1 faz com que os limites das conversas sejam exclusivamente explícitos. O documento sobre o ciclo de vida das sessões na tag v2026.9.7 define o contrato em quatro frases: “A inatividade e o tempo transcorrido nunca alternam uma conversa. /new e /reset criam um limite explícito; a compactação de contexto continua gerenciando históricos longos. As configurações legadas de temporizador são ignoradas. O tipo de dados SessionResetPolicy existente é apenas um dado inerte de compatibilidade, não uma política de runtime.” A suspensão explícita ainda cria um limite no próximo turno de entrada, a recuperação respeita os limites finalizados em vez de reabri-los e a remoção causada exclusivamente por recursos mantém as conversas retomáveis. Se uma sessão no seu gateway parecer “nunca expirar”, agora isso é intencional; alterne-a você mesmo com /new.⁴³

Desde a janela da v0.21.4, uma segunda execução de hermes gateway run se conecta ao processo existente ou recusa a inicialização, em vez de tentar usar a mesma porta duas vezes. A regra é ter um hermes serve e um hermes gateway run por host e por usuário do sistema operacional, com cada um multiplexando todos os profiles. Iniciar um gateway para um profile que o multiplexador em execução já atende apenas conecta o comando ao processo existente e o encerra com código 0; se ele ainda não atender esse profile, o Hermes solicita que ele verifique novamente profiles/ e se conecta assim que o profile for atendido; se não for possível fazer com que o processo atenda esse profile, o comando recusa a operação em vez de iniciar silenciosamente um segundo gateway. Agora, --replace atua sobre esse processo do host, independentemente de qual profile o iniciou, e --force pula completamente a pergunta quando o processo proprietário está travado. Gateways independentes ainda podem coexistir: se o gateway em execução for o gateway standalone (não multiplexado) de outro profile, o seu profile iniciará o próprio gateway ao lado dele, como antes, até que essa migração seja forçada (#109417). Se dois gateways forem iniciados ao mesmo tempo, aquele que não conseguir obter o lock do host será encerrado com código 75, que todos os supervisores gerados pelo Hermes tentam executar novamente; nesse momento, o registro do vencedor já existirá, portanto a nova tentativa se conectará ou recusará a operação de acordo com as regras acima. Os locks e o registro de rendezvous ficam em $HERMES_GATEWAY_LOCK_DIR ou, se essa variável não estiver definida, em $XDG_STATE_HOME/hermes/gateway-locks (por padrão, ~/.local/state/hermes/gateway-locks), com escopo limitado ao usuário do sistema operacional; um registro cujo PID não esteja mais ativo ou tenha sido reutilizado por outro processo é considerado obsoleto e ignorado, portanto uma falha do gateway não impede a próxima inicialização. O aplicativo Desktop segue a mesma regra, conectando-se ao backend do host em execução em vez de iniciar outro.⁵¹

Desde a v0.21.5, a multiplexação não é mais opcional. gateway.multiplex_profiles tem apenas um valor válido, true: uma chave ausente é interpretada como ativada e gravada no config.yaml do profile padrão, enquanto um valor false explícito é reescrito como true no próprio arquivo, acompanhado de um aviso em caixa exibido uma vez ao iniciar esse gateway e novamente no resumo da próxima execução de hermes update. Dois controles substituem a antiga opção de desativação. Para deixar um profile offline sem interromper os bots de todos os outros, execute hermes -p <name> gateway stop: o host o estaciona (usando um marcador profiles/<name>/gateway.parked), enquanto hermes -p <name> gateway start o reativa; os botões Stop/Start do dashboard e do Desktop fazem o mesmo. Um profile nomeado que ainda precise de um gateway próprio deve definir gateway.standalone: true no seu próprio config.yaml; o host nunca o atenderá, e seus comandos stop/start atuarão sobre o processo exclusivo dele. A documentação chama essa chave de “uma solução temporária de compatibilidade”, não de uma topologia compatível, e ela é ignorada com um aviso no profile padrão. Uma divisão entre usuários do sistema operacional ou um HERMES_HOME localizado fora de profiles/ no diretório pessoal padrão ainda exige --force.⁵³

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

Os códigos de pareamento impedem que desconhecidos conversem com o seu gateway. Um usuário envia um código de pareamento pela plataforma de mensagens; você o aprova com hermes pairing approve e, a partir daí, ele fica autorizado.⁶

unauthorized_dm_behavior determina o que a DM de um desconhecido recebe antes do pareamento: pair envia um código de pareamento por DM, ignore descarta a mensagem silenciosamente e decline, valor adicionado na janela da v0.21.4, envia uma única recusa educada e depois permanece em silêncio para aquele remetente por 24 horas (#88028). A recusa é desduplicada por plataforma e remetente, inclusive entre aliases, e seu texto vem de unauthorized_dm_decline_message (uma chave global; um valor vazio usa a resposta integrada: “Olá! Sou um assistente pessoal e só posso conversar com meu proprietário, então não posso ajudar você diretamente. Desculpe!”). Defina o comportamento globalmente ou por plataforma, no local em que o assistente de configuração o grava:

# ~/.hermes/config.yaml
unauthorized_dm_behavior: decline      # global; gateway.unauthorized_dm_behavior also works
unauthorized_dm_decline_message: ""    # empty = built-in reply
platforms:
  telegram:
    unauthorized_dm_behavior: pair     # per-platform value always wins

Quando nenhuma opção está definida, o padrão efetivo depende das suas listas de permissões. Sem nenhuma configurada, ele é pair; assim que qualquer lista de permissões é definida (GATEWAY_ALLOWED_USERS ou uma variável de usuários permitidos, usuários de grupos permitidos ou chats de grupos permitidos de uma plataforma), ele passa a ser ignore, pois a lista sinaliza um gateway deliberadamente restrito, e enviar códigos a contatos desconhecidos gera ruído e representa um possível vazamento de informações (#9337). Um valor global ignore ou decline substitui essa regra, mas um valor global pair não pode fazer isso, pois é interpretado da mesma forma que o padrão; para manter o pareamento junto de uma lista de permissões, defina pair por plataforma. (O dm_policy próprio de um adaptador de plataforma, quando definido, é consultado antes da regra da lista de permissões.) Como o e-mail funciona como uma caixa de entrada, seu padrão é ignore, a menos que sua própria chave específica da plataforma ative outra opção; um valor global não se aplica a ele. Ao configurar uma plataforma sem lista de permissões, hermes gateway setup oferece decline como uma das opções.⁵¹

Tarefas agendadas (Cron)

O Hermes tem um sistema cron nativo no qual os jobs são tarefas do agente, não comandos do shell. Cada job agendado é executado por meio de um novo AIAgent com o prompt configurado e skills opcionais anexadas, e entrega os resultados a qualquer plataforma:³⁶

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

Ou crie um conversando 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 job cron por meio de suas ferramentas. Os jobs são persistidos em JSON e continuam existindo após reinicializações.³

A v0.21.0 deu memória e capacidade de julgamento aos jobs agendados. Quatro mecanismos, todos verificados na tag v2026.8.31:³⁵³⁷

• Continuidade. continuity=true injeta em cada execução a saída mais recente do próprio job, para que um agente de reconhecimento ou monitoramento “acorde vendo o que relatou da última vez e possa eliminar duplicações e continuar de onde parou” — a instrução injetada é “evite repetir o que já foi relatado”, a primeira execução não muda e, internamente, a opção é armazenada como a entrada reservada self em context_from. Ative ou desative com hermes cron create ... --continuity e hermes cron edit <job_id> --continuity / --no-continuity.³⁷
• Blocos de notas persistentes. Cada job recebe um pequeno espaço de rascunho KV para cursores, marcas d’água e listas de monitoramento (16 KB por valor, 64 KB por job — ele é injetado no prompt a cada execução, por isso os limites são intencionais), gravado por meio de hermes cron notepad <job_id> set <key> <value>, que o agente em execução invoca usando sua ferramenta de terminal.³⁷
• Modo de monitoramento. Um job pode anexar uma fonte econômica monitor_script/monitor_url, executada primeiro a cada ciclo: uma saída inalterada (comparada como bytes exatos) suprime completamente a execução do agente — nenhuma chamada a LLM, nenhuma entrega, apenas uma execução silenciosa no_change — enquanto uma alteração injeta um bloco de diff e executa o agente normalmente. Faça os scripts de monitoramento emitirem uma saída estável; caso contrário, cada ciclo parecerá uma alteração.³⁷
• Esforço de raciocínio por job e entrega ao Bot Chat. --reasoning-effort fixa o nível de raciocínio de um job (de none a ultra), substituindo as configurações globais e por modelo nas execuções desse job; e deliver=bot-chat envia a saída para a sessão canônica do Bot Chat de um profile como uma mensagem recebida real, na qual o bot “executa tudo o que exigir ação e responde no próprio chat”, em vez de um humano apenas ler um canal.³⁷

Integração com MCP

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

Como cliente — conecte o Hermes a servidores MCP externos para ampliar seu conjunto 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
hermes mcp login <name>       # Force re-auth for an OAuth server (--flow browser|device)
hermes mcp reauth [--all]     # Re-authenticate one OAuth server, or every one

Ou configure manualmente no config.yaml:¹⁴

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

Desde a v0.19.0, as ferramentas MCP são apresentadas ao modelo seguindo a convenção de nomenclatura mcp__server__tool — cada nome de ferramenta inclui o nome do servidor, evitando conflitos quando dois servidores disponibilizam a mesma ferramenta — e as notificações de log dos servidores MCP são exibidas no agent.log.⁵⁶

A v0.21.1 adiciona um fluxo de código de dispositivo ao OAuth do MCP: hermes mcp login <name> aceita --flow {browser,device} — browser é o fluxo PKCE já existente, enquanto device é um login por código de dispositivo conforme a RFC 8628 para máquinas headless ou remotas — e a opção substitui a configuração oauth.flow do servidor. Essa mesma versão impõe a propriedade do profile durante todas as sessões de OAuth, ignora caches malformados de metadados de OAuth em vez de travar um servidor e retransmite o OAuth do __TERM_22 no desktop por meio de callbacks locais do cliente; agora -t/--toolsets também filtra quais servidores MCP configurados são iniciados, portanto uma invocação com escopo definido não inicializa servidores desnecessários.⁴⁴

A v0.21.0 transforma a área de MCP do desktop em uma central de comando: servidores e catálogo são reunidos em uma única página com importação do tipo “cole qualquer coisa” por arrastar e soltar, verificações de integridade em segundo plano que sinalizam autenticações prestes a expirar antes que uma chamada de ferramenta falhe, uma sobreposição de custos e uso de toda a frota que mostra estimativas de tokens do esquema e o uso de cada servidor nos últimos 30 dias, além de deep links hermes:// que instalam um servidor MCP mediante confirmação explícita.³⁵

A versão v0.21.4 adiciona mcp.discovery_concurrency (padrão 4; 0 = ilimitado, #117373): um limite para quantos servidores MCP configurados o processo de descoberta conecta simultaneamente. Todos os servidores ainda são conectados — o limite apenas impede que todos se conectem ao mesmo tempo — e um valor negativo ou que não seja inteiro registra um aviso e volta ao padrão.⁵¹

Como servidor — disponibilize as conversas do Hermes para outros agentes:

hermes mcp serve
hermes mcp serve -v    # Verbose

Compressão de contexto

O Hermes compacta automaticamente conversas longas para permanecer dentro da janela de contexto do seu modelo. O sumarizador de compactação usa uma chamada separada a LLM — você pode direcioná-lo para qualquer provedor ou endpoint.⁴ Desde a v0.20.6, a política de retenção do trecho final usa lean por padrão (compression.tail_mode: lean) e, nessa tag, as opções de modelo, provedor e endpoint do sumarizador ficam em auxiliary.compression.*, em vez das antigas compression.summary_* — as chaves legadas são migradas automaticamente no primeiro carregamento (versão 17 da configuração).³⁰³¹

compression:
  enabled: true
  threshold: 0.50          # Compress at this % of context limit
  threshold_tokens: null   # Optional absolute token cap -- trigger fires at the lower of ratio vs cap
  target_ratio: 0.20       # Fraction of threshold to preserve as recent tail (legacy tail mode)
  tail_mode: lean          # Tail retention: "lean" (default) or "legacy"
  protect_last_n: 20       # Min recent messages to keep uncompressed
  protect_first_n: 3       # Non-system head messages pinned across compactions

auxiliary:
  compression:
    model: ""              # Empty = main chat model; e.g. "google/gemini-3-flash-preview"
    provider: "auto"       # "auto", "openrouter", "nous", "codex", "main", etc.
    base_url: null         # Custom OpenAI-compatible endpoint (overrides provider)

O que tail_mode determina. legacy mantém literalmente um trecho final com o tamanho definido por target_ratio — em configurações com janelas grandes ou limites elevados, isso acumula de 100 a 240 mil tokens por compactação. lean mantém literalmente um trecho final limitado a 2,5% da janela de contexto (mínimo de 10 mil e máximo de 25 mil) e transfere a continuidade para o resumo: um log detalhado da sessão que preserva identificadores da região compactada (uma chamada auxiliar ao sumarizador por tentativa), um índice de âncoras extraído mecanicamente (números de PR, SHAs, caminhos e strings de erro — por regex, nunca parafraseados), todas as mensagens reais do usuário citadas literalmente e um ponteiro de recuperação session_search para que o agente possa acessar novamente qualquer conteúdo removido pelo resumo. O resultado medido pela documentação em sessões reais de 500 mil tokens: cerca de 49 mil tokens retidos, em vez de aproximadamente 162 mil. Resultados antigos de ferramentas dentro do trecho final de lean são reduzidos a resumos de uma linha com um ponteiro de recuperação, e valores desconhecidos de tail_mode usam lean como fallback.³¹

Opções de provedor:⁴³¹

O modelo de resumo precisa oferecer uma janela de contexto pelo menos tão grande quanto a do seu modelo principal, pois recebe toda a seção intermediária da conversa em uma única chamada — se a janela dele for menor, a chamada falhará e os turnos intermediários serão descartados sem resumo.⁴³¹

Alertas de pressão sobre o orçamento

Quando o agente trabalha em uma tarefa complexa com muitas chamadas de ferramentas, ele pode esgotar seu orçamento de iterações (padrão: 500 turnos desde a v0.20.0, anteriormente 90) sem perceber. A pressão sobre o orçamento alerta o modelo automaticamente:⁴

Timeouts de streaming

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

O timeout de leitura do socket é elevado para 30 minutos em endpoints locais porque LLMs locais podem levar vários minutos para fazer o prefill de contextos grandes antes de gerar o primeiro token.⁴

Dashboard web local (v0.9.0+)

Um dashboard acessível pelo navegador para gerenciar localmente o Hermes Agent. Defina configurações, monitore sessões, navegue pelas skills e gerencie seu gateway sem precisar mexer em arquivos de configuração ou no terminal.¹⁶ Inicie com hermes dashboard. Este é o caminho de onboarding mais fácil para novos usuários que preferem uma GUI.

Monitoramento de processos em 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 uma correspondência.¹⁶ Monitore erros, aguarde eventos específicos (“listening on port”) ou acompanhe logs de build — tudo isso sem polling. Combinado com notify_on_complete da v0.8.0 (que envia uma notificação quando uma tarefa em segundo plano é concluída), o Hermes agora oferece 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 por meio de hermes plugins. Use context engines personalizados que controlam o que o agente vê a cada turno — com filtragem, sumarização ou injeção de contexto específico do domínio.¹⁶ Isso separa a estratégia de contexto do loop principal do agente, permitindo personalizar o contexto por projeto ou domínio.

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

hermes backup cria um arquivo completo com suas configurações, sessões, skills e memória. hermes import restaura os dados de um arquivo de backup.¹⁶ Use esses recursos para migrar entre máquinas, criar snapshots antes de grandes alterações ou compartilhar uma configuração validada com colegas de equipe.

Suporte a Termux / Android (v0.9.0+)

O Hermes é executado nativamente no Android por meio do Termux. Caminhos de instalação adaptados, otimizações da TUI para telas de dispositivos móveis, suporte a backend de voz e o comando /image funcionam diretamente no dispositivo.¹⁶

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

A v0.13.0 corrigiu 8 problemas de segurança P0 e alterou uma configuração padrão em benefício do usuário.¹⁸ Em seguida, a v0.14.0 corrigiu outros 12 problemas P0 e 50 P1, incluindo reforços contra força bruta no sudo e no sudo-stdin, correções de formas de contornar a detecção de comandos perigosos, sanitização de erros de ferramentas antes da reinjeção no modelo, autenticação de API de plugins do dashboard, cobertura contra SSRF no hub de skills e verificação de alertas da cadeia de suprimentos 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 atualizações relevantes para a segurança, não apenas como lançamentos de recursos. A v0.13.0 corrige a falha entre servidores do Discord e duas janelas TOCTOU; a v0.14.0 acrescenta outra rodada de reforços no tratamento do sudo, na reinjeção de erros de ferramentas, nos APIs de plugins, na proteção contra SSRF do hub de skills e nos alertas de dependências.

A v0.21.0 adiciona uma quarta rodada. Gravações em arquivos protegidos de instruções do agente – AGENTS.md, CLAUDE.md, SOUL.md, .cursorrules, skills e armazenamentos de memória – agora sempre exigem aprovação, impedindo que um agente afetado por prompt injection reescreva silenciosamente suas próprias instruções permanentes. A proteção vem ativada por padrão (security.protected_instruction_files: true, com uma lista de extensões de nomes-base em formato fnmatch em protected_instruction_extra_patterns), e o código-fonte especifica o vetor exato que ela elimina: “uma instrução injetada que edita AGENTS.md / CLAUDE.md / SOUL.md”, observando que os arquivos de instruções são carregados das árvores do cwd, portanto “qualquer AGENTS.md em um local no qual o agente possa ser executado posteriormente é um alvo ativo”.³⁵³⁹ A mesma versão corrige falhas de vazamento de segredos em erros do terminal, leituras de arquivos .env, checkpoints e logs do ACP; ensina ao sistema de aprovação quais comandos e caminhos são destrutivos no Windows; faz com que as permissões concedidas no macOS persistam após atualizações por meio de uma identidade estável de assinatura TCC (configuração única: hermes desktop --setup-tcc-identity, somente para macOS, requer openssl/security/codesign); remove a entrada do catálogo e a skill do Blender MCP após o comprometimento de um componente upstream; e adiciona verificação de segurança de Nível 1 às instalações de plugins.³⁵³⁹

Arquitetura para profissionais

Esta seção é para quem quer entender o que acontece nos bastidores para poder depurar, ampliar ou analisar o desempenho. Ela sintetiza a documentação de arquitetura upstream.³

Pontos de entrada → AIAgent

Todos os pontos de entrada do Hermes acabam 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 tools do repositório upstream — todas as tools cujo código-fonte acompanha o Hermes, considerando todos os toolsets. A CLI em execução exibirá um número menor no banner de inicialização (a instalação usada para verificar este guia informa 28 tools / 89 skills). Isso não é um bug. Muitos toolsets são opcionais e precisam ser habilitados explicitamente em config.yaml, na seção toolsets: — adaptadores de plataformas de mensagens, automação de navegador, ferramentas mais robustas de scraping etc. O total do registro representa “o que está disponível”; o número no banner representa “o que está habilitado no seu profile atual”. Confira quais toolsets estão ativos com hermes tools --list e habilite ou desabilite toolsets individuais usando 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 tool reinicia a sessão para que o agente reconstrua seu manifesto de tools).

Os três modos de API

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

O resolvedor runtime_provider.py mapeia tuplas (provider, model) para (api_mode, api_key, base_url) em mais de 18 provedores, gerenciando fluxos de OAuth, pools de credenciais e resolução de aliases.³

Fluxo de dados em uma sessão da CLI

User input → HermesCLI.process_input()
  → AIAgent.run_conversation()
    → agent.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

Extraído da página de arquitetura upstream.³

Ordem de montagem do prompt

A pilha do prompt inclui:¹³

1. SOUL.md (identidade do agente — ou fallback integrado, caso não esteja disponível)
2. Orientações de comportamento relacionadas às tools
3. Memória/contexto do usuário (MEMORY.md, USER.md)
4. Orientações sobre skills
5. Arquivos de contexto (AGENTS.md, .cursorrules)
6. Data e hora
7. Dicas de formatação específicas da plataforma
8. Sobreposições opcionais do prompt do sistema, 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 pesquisa de texto completo FTS5. As sessões têm rastreamento de linhagem (relações pai/filho entre compressões), isolamento por plataforma e gravações atômicas com tratamento de contenção.³

Se o armazenamento apresentar problemas em uma instalação v0.21.x, use a v0.21.2 ou posterior: ela corrigiu a categoria de fragilidades do state.db presente desde a v0.21.0 (segundos processos de gravação cancelando os bloqueios uns dos outros, bancos de dados íntegros sendo relatados como corrompidos e uma única linha inválida interrompendo sessions list) e transferiu a coordenação de salas hospedadas do armazenamento raiz para um shared-state.db dedicado, evitando que gateways de profiles abram o armazenamento principal de sessões para gravação. Agora, hermes doctor identifica separadamente danos estruturais e danos ao índice FTS; danos ao FTS prejudicam a pesquisa em vez de interromper o turno; e hermes sessions recover --inspect-only (offline, não destrutivo e fixado ao profile) informa se a tabela canônica pode ser lida sem criar um banco de dados de saída — o subcomando já existia antes desse período, mas ainda não havia sido documentado aqui. Consulte Novidades da v0.21.2.⁴⁸ Para um armazenamento preso no modo incorreto de journal do SQLite, o período da v0.21.4 adicionou o conversor offline hermes sessions set-journal-mode delete|wal (consulte a linha hermes sessions em Comandos de nível superior).⁵¹

Sistema de plugins

Há três fontes de descoberta: ~/.hermes/plugins/ (usuário), .hermes/plugins/ (projeto) e pontos de entrada do pip. Os plugins registram tools, hooks e comandos da CLI por meio de uma API de contexto. Provedores de memória são um tipo especializado de plugin em plugins/memory/.³ Desde a v0.21.2, também há um catálogo de plugins selecionados e fixados por SHA, que você pode explorar e usar para instalar plugins pelo nome, além de hermes plugins pack para “conjuntos de plugins declarativos e compartilháveis”: um único hermes-pack.yaml fixa um conjunto de plugins em SHAs de commits exatos, enquanto as instalações de packs se desdobram em instalações fixadas comuns e o consentimento de recursos continua sendo concedido separadamente para cada plugin.⁴⁸

O período da v0.21.4 transformou esse catálogo de uma interface de CLI em um artefato distribuído. O diretório plugin-catalog/ do repositório passou de 9 entradas em v2026.9.14 para 228 em v2026.9.21 — um YAML revisado por plugin (nome, repositório, mantenedor, nível, categoria e recursos), fixado em um SHA de commit exato com 40 caracteres, sendo que a presença no diretório constitui admissão — publicado como plugin-catalog.json para a CLI (obtido em tempo real e armazenado em cache em ~/.hermes/cache/). Agora, o site da documentação gera uma página por plugin (/docs/plugins/<name>) e por autor (/docs/plugins/by/<slug>) usando esses mesmos dados. Cada página renderiza o README do plugin obtido do commit fixado, nunca da ponta de uma branch, por meio de uma lista de permissões aplicada durante o build que descarta HTML bruto, com a ordenação por adição/atualização marcada pelas datas dos committers. Os dez plugins da comunidade citados na versão v0.21.4 estão todos presentes no catálogo da tag, com seus slugs reais: hermes-tailscale, hermes-ssh, shodan, hermes-terminal, hermes-rss (além de um rss-reader separado), hermes-resetwatch, done-bell, kiwi, cognee e web-octen. No desktop, agora é possível desinstalar um plugin pelo hub Plugins após uma caixa de diálogo de confirmação — plugins do catálogo por meio de plugins.manage remove e plugins independentes do desktop por meio do carregador do Electron.⁵¹

hermes plugins                       # Interactive enable/disable UI
hermes plugins browse                # List every curated plugin catalog entry (v0.21.2+)
hermes plugins search <query>        # Search the curated plugin catalog (v0.21.2+)
hermes plugins install <name|repo>   # Install from the curated catalog, a Git URL, or owner/repo
hermes plugins enable <name>
hermes plugins disable <name>
hermes plugins list
hermes plugins pack install <src>    # Shareable SHA-pinned plugin sets; also: pack export, pack show (v0.21.2+)

Período de compatibilidade (v0.21.1), agora encerrado: plugins externos precisavam abandonar os caminhos de importação anteriores à decomposição até 14 de setembro de 2026. A decomposição de setembro de 2026 (PR #102117) realocou os componentes internos que os plugins importavam com frequência, e uma camada temporária COMPAT_MANIFEST.md reexportou 1.148 nomes públicos movidos de seus módulos antigos, emitindo um aviso uma vez por nome em cada processo (HermesPluginCompatWarning). A remoção entrou em vigor conforme programado em 14 de setembro de 2026 por meio de uma verificação de data no código distribuído (COMPAT_REMOVAL_DATE em hermes_cli/plugin_compat.py; não foi necessário reverter código): desde essa data, um plugin afetado fica desabilitado — ele não é carregado, e um aviso vermelho aparece no banner da CLI, em hermes doctor e em hermes update, além de uma caixa de diálogo única no desktop e do motivo exibido em hermes plugins list. Para autores: hermes plugins compat <path> ainda mostra cada file:line com caminho antigo -> caminho novo e retorna o código 1 enquanto restar qualquer ocorrência (adicione --json para obter uma saída legível por máquina). Usuários presos a um plugin sem manutenção ainda podem definir plugins.allow_deprecated_imports: true em config.yaml — o valor precisa ser um booleano YAML literal, não uma string entre aspas — e isso ainda funciona porque a reversão que exclui os caminhos antigos ainda não foi incorporada: o manifesto e os shims estão presentes em v2026.9.14, em v2026.9.21, em v2026.9.24 e em main desde 24 de setembro (o período da v0.21.4 alterou o módulo de compatibilidade apenas para armazenar as varreduras de plugins em cache e normalizar caminhos do Windows; o período da v0.21.5 não alterou hermes_cli/plugin_compat.py e removeu apenas as entradas do manifesto referentes ao módulo Hindsight excluído). Essa saída de emergência deixará de funcionar assim que a reversão for incorporada, pois os próprios caminhos antigos desaparecerão. Apenas nomes públicos de nível superior foram contemplados; nomes privados e pontos de monkeypatch de testes nunca fizeram parte da interface e não foram restaurados.⁴²⁵³

Princípios de design

Da página de arquitetura upstream:³

Migração do OpenClaw

Hermes Agent é o sucessor do OpenClaw. Se você estiver migrando 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ê ~/.openclaw por padrão (e também detecta automaticamente os 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, provedores personalizados, servidores MCP, tokens e listas de permissões de plataformas de mensagens (Telegram, Discord, Slack, WhatsApp, Signal, Matrix, Mattermost), configurações padrão do agente (esforço de raciocínio, compactação, atraso humano, fuso horário, sandbox), políticas de redefinição de sessão (agora inativas: desde a v0.21.1, os temporizadores nunca alternam uma conversa⁴³), regras de aprovação, configuração de TTS, configurações do navegador, configurações de ferramentas, tempo limite de execução, lista de comandos permitidos, configuração do gateway e chaves API de 3 fontes.⁶

Arquivados para revisão manual: tarefas cron, plugins, hooks/webhooks, backend de memória (QMD), configuração do registro de skills, interface/identidade, registros, configuração multiagente, associações de canais, IDENTITY.md, TOOLS.md, HEARTBEAT.md, BOOTSTRAP.md.⁶

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

Solução de problemas

“Nenhum provedor de inferência configurado. Execute ‘hermes model’ para escolher um provedor e um modelo”

Este é o primeiro erro que toda instalação nova encontra: o Hermes ainda não tem um provedor definido. A mensagem quer dizer exatamente isso — nenhum dos três métodos de autenticação resultou em um provedor utilizável. Execute:

hermes model

O seletor interativo orienta você por todos os provedores compatíveis, inclusive os fluxos de código de dispositivo OAuth (Nous Portal, GitHub Copilot, Anthropic, OpenAI Codex) e endpoints personalizados para servidores auto-hospedados. Se você esperava que um provedor já estivesse configurado, hermes doctor mostra quais credenciais o Hermes realmente consegue acessar. As causas mais comuns são uma chave API definida no lugar errado (ela deve ficar no .env ou ser configurada com hermes config set, não no seu perfil do shell), uma credencial OAuth expirada em ~/.hermes/auth.json ou um endpoint personalizado em config.yaml que perdeu seu base_url. Os métodos de autenticação são explicados em detalhes em Autenticação e provedores.²⁷

“Chave API não definida”

Execute hermes model para configurar seu provedor interativamente ou hermes config set OPENROUTER_API_KEY your_key. O comando hermes doctor informará exatamente quais chaves estão ausentes.⁷

“Limite de contexto: 2048 tokens” na inicialização (modelos locais)

O Hermes detecta automaticamente o tamanho do contexto pelo endpoint /v1/models do seu servidor, mas muitos servidores locais informam valores padrão baixos. Defina-o explicitamente no config.yaml:²

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

As chamadas de ferramentas aparecem como texto em vez de serem executadas

Seu servidor não está com a chamada de ferramentas ativada ou o modelo não oferece suporte a ela por meio da implementação do servidor.²

As respostas são interrompidas no meio de uma frase

Há duas causas possíveis:²

1. Limite de saída baixo (max_tokens) no servidor — o padrão do SGLang é 128 tokens por resposta. Defina --default-max-tokens no servidor ou configure model.max_tokens no config.yaml.
2. Esgotamento do contexto — o modelo preencheu toda a janela de contexto. Aumente model.context_length ou ative a compactação de contexto no Hermes.

“Conexão recusada” do WSL2 para um servidor de modelos hospedado no Windows

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

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

[wsl2]
networkingMode=mirrored

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

Alternativa com o IP do host (versões anteriores do Windows): 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 configurar o servidor de modelos para usar 0.0.0.0, e não 127.0.0.1 — defina OLLAMA_HOST=0.0.0.0 para o Ollama, adicione --host 0.0.0.0 ao llama-server/SGLang ou ative “Serve on Network” no LM Studio.²

O orçamento de iterações ignora agent.max_turns

Se a linha de atividade mostrar N/90 (ou outro limite desatualizado), embora o config.yaml contenha agent.max_turns: 500, a causa provável é uma linha HERMES_MAX_ITERATIONS obsoleta em ~/.hermes/.env: anteriormente, o assistente de configuração gravava o orçamento nos dois locais e, se a integração de inicialização for interrompida devido a um erro anterior de análise da configuração, o valor residual do .env prevalecerá silenciosamente. Desde a v0.21.1, hermes doctor detecta o par conflitante, e hermes doctor --fix exclui a linha do .env, deixando o config.yaml como fonte oficial.⁴¹

Onde fica cada coisa?

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

Perguntas frequentes

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

Claude Code é o CLI oficial da Anthropic, restrito aos modelos da Anthropic. Hermes Agent é um framework de agentes 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.¹² Hermes também inclui um gateway de mensagens para Telegram/Discord/Slack/WhatsApp/Signal, recurso que Claude Code não oferece.

Posso usar Hermes com uma chave API da Anthropic?

Sim. Há três maneiras:²

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

A opção 2 é a preferida se você já usa Claude Code na mesma máquina — ela mantém atualizáveis as credenciais Claude que permitem renovação.

Como posso trocar de provedor sem perder minha conversa?

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

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

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

Nas versões atuais, isso praticamente não pode mais acontecer da forma antiga. Por padrão (auxiliary.*.provider: "auto"), todas as tarefas auxiliares — visão, classificação de aprovações, compressão e títulos de sessões — são executadas no seu modelo principal de chat. Portanto, uma configuração que usa somente a Anthropic atende a essas tarefas com o OAuth que já possui. O padrão antigo (Gemini Flash via OpenRouter → Nous → detecção automática do Codex, com degradação silenciosa quando nenhum deles estava configurado) foi removido: “auto agora usa o modelo principal para todos, e as substituições específicas por tarefa em config.yaml continuam tendo prioridade”.³⁴

Se uma tarefa auxiliar ainda falhar, procure uma substituição explícita para essa tarefa apontando para um provedor que você nunca configurou (auxiliary.<task>.provider / .model em config.yaml) ou chaves legadas obsoletas: desde a tag v2026.8.31, o sumarizador de compressão é configurado como qualquer outro slot auxiliar — auxiliary.compression.provider — e as chaves legadas compression.summary_* são migradas automaticamente para esse local (versão 17 da configuração).³¹ A extração da web deixou de ser uma tarefa do LLM (“nenhum LLM envolvido”), portanto, nas versões atuais, uma falha de sumarização da web não é um problema do modelo auxiliar.³⁴ Para vincular explicitamente uma tarefa ao seu provedor principal:

auxiliary:
  vision:      { provider: "main" }
  compression: { 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 e caminhos — e fica no diretório do seu projeto.¹³ Se algo deve acompanhar você em todos os lugares, use SOUL.md. Se pertence a um projeto, use AGENTS.md.

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

Use 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, por meio do 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.² Consulte Endpoints personalizados e auto-hospedados para ver a configuração de cada servidor.

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

O guia menciona 47 ferramentas e 20 toolsets do registro de arquitetura upstream — essa é a contagem total das ferramentas cujo código-fonte o Hermes inclui 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 ferramentas) porque o Hermes habilita apenas o conjunto padrão de toolsets na inicialização. Muitos toolsets precisam ser ativados: adaptadores do gateway de mensagens, automação de navegador, stacks de scraping mais pesados e várias integrações especializadas precisam ser listados explicitamente em toolsets: no arquivo ~/.hermes/config.yaml antes de serem carregados. 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 durante a execução com /tools enable <name> e /tools disable <name> (a desativação reinicia a sessão para que o agente reconstrua seu manifesto de ferramentas com o novo formato).

Como o Hermes gerencia o modelo alternativo quando meu provedor principal falha?

Configure um bloco fallback_model em config.yaml:²

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

Quando o provedor principal falha (limite de requisições, erro do servidor ou falha de autenticação), o Hermes muda para o modelo alternativo durante a sessão sem perder o histórico da conversa. Isso ocorre no máximo uma vez por sessão.

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

Sim — essa é a parte de “autoaperfeiçoamento” do Hermes Agent. O agente pode criar, atualizar e excluir skills por meio da ferramenta skill_manage. Quando descobre como executar um fluxo de trabalho não trivial, ele salva a abordagem como uma skill para reutilização futura.¹¹ O agente cria skills após tarefas complexas (mais de 5 chamadas de ferramentas), quando encontra erros e descobre o caminho que funciona, quando você corrige sua abordagem ou quando ele descobre um fluxo de trabalho não trivial.

Existe uma integração com IDE?

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

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

Changelog