Hermes Agent: o 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 uma memória persistente, agrega skills que melhoram com o uso e funciona com qualquer provedor de LLM compatível com OpenAI — Nous Portal, OpenRouter, Anthropic, GitHub Copilot, z.ai, Kimi, MiniMax, DeepSeek, Qwen Cloud, Hugging Face, Google, xAI/SuperGrok ou seu próprio endpoint auto-hospedado.¹²¹⁹ A versão atual é a v0.21.7 (tag v0.21.7, 11 de outubro de 2026), o quinto patch cumulativo da linha v0.21 e o primeiro a distribuir todos os canais pelo novo pipeline de versões estáveis do projeto; Novidades da v0.21.7 explica o que mudou, e as seções de versões seguintes estão organizadas da mais recente para a mais antiga.⁵⁶ A parte mais difícil para a maioria dos novos usuários é a autenticação do provedor: o Hermes inclui 39 provedores em sua lista estática de seleção na tag v0.21.6 e amplia automaticamente essa lista com 41 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 do provedor que for resolvido.

O Hermes Agent funciona como um runtime completo de agente, não como um simples wrapper 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 pelo Telegram/Discord/Slack/WhatsApp/Signal/Email usando 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ção em run_agent.py; o gateway é um processo de longa duração que encaminha mensagens das plataformas de mensagens pelo mesmo loop de conversação.³

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 mapeados para 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 acesso controlado por plataforma
4. Sistema de skills: memória procedural que o agente cria e desenvolve
5. Gateway + cron + profiles: executar o Hermes onde você está presente, não apenas onde está fisicamente

Principais conclusões

• A autenticação do provedor 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 o que parecer mais familiar.
• Você pode trocar de provedor com um único comando. hermes model orienta você interativamente por todos os provedores compatíveis, incluindo logins com OAuth, enquanto /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 o restante é modificado pelo próprio agente.⁴
• O Hermes é o sucessor do OpenClaw. Se você estiver migrando, hermes claw migrate importará automaticamente mais de 30 categorias de estado.⁵
• Por padrão, as tarefas auxiliares usam seu modelo principal. Visão, classificação de aprovações, compressão e títulos de sessões são executados como chamadas “auxiliares” separadas de LLM e, nessa tag, auto encaminha todas elas para seu modelo principal de chat — não há nada para configurar, mas essas tarefas secundárias podem gerar custos consideráveis em modelos de raciocínio caros. Quando isso for relevante, direcione cada slot de auxiliary.<task> para modelos rápidos e econômicos.⁴³⁴

Todas as seções abaixo se baseiam na documentação upstream em hermes-agent.nousresearch.com/docs e na árvore de código-fonte em github.com/NousResearch/hermes-agent. Toda afirmação factual tem uma nota de rodapé que aponta para a página upstream específica de onde 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.³ No fim, todos eles chamam AIAgent.run_conversation() em run_agent.py, que:

1. Monta o prompt do sistema com base em SOUL.md, MEMORY.md, USER.md, skills, arquivos de contexto e orientações sobre ferramentas por meio de agent/prompt_builder.py (a reorganização de setembro de 2026 o transferiu para o novo pacote agent/)³
2. Resolve o provedor de runtime por meio de runtime_provider.py — é nesta etapa que são escolhidos sua autenticação, URL base e modo API³
3. Chama o provedor usando um dos três modos API: chat_completions, codex_responses ou anthropic_messages³
4. Encaminha todas as chamadas de ferramentas retornadas por meio de model_tools.py e do registro central de ferramentas (tools/registry.py)³
5. Repete o processo até que o modelo produza uma resposta final e, então, 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 a partir de um COMMAND_REGISTRY compartilhado em hermes_cli/commands.py.⁶

A estrutura de diretórios é o sistema. O Hermes armazena tudo em ~/.hermes/ (ou 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; não há sobreposição entre eles. Se você estiver procurando “onde o Hermes armazena X”, estará em um desses locais.

Novidades na v0.21.7 (o pacote de atualizações de 11 de outubro)

O Hermes Agent v0.21.7 (tag v0.21.7, datada de 11 de outubro de 2026 e publicada em 12 de outubro) é a versão atual, o quinto pacote incremental da linha v0.21.x. Ao contrário da v0.21.6, que disponibilizou apenas a tag e a imagem Docker, esta versão abrange todos os canais: o aplicativo para desktop (macOS com Apple silicon e Windows), as builds da Microsoft Store e MSIX, o instalador, Docker e Hermes Cloud. O período desde a v0.21.6 contém “740 commits sem merge” em “4.156 arquivos alterados”, “204 PRs mesclados” e “69 issues encerradas” (a comparação do GitHub contabiliza 777 commits com os merges). Mais uma vez, as notas selecionadas foram adiadas para a v0.22.0. Veja o que a versão documenta, conferido no código-fonte na tag:⁵⁶⁵⁷

• As instalações pelo código-fonte agora acompanham as versões publicadas com tags. hermes update em um checkout do repositório oficial avança para a versão vX.Y.Z publicada mais recente, exatamente no commit correspondente, em vez de acompanhar todos os commits da main. Uma instalação que já esteja à frente da versão mais recente permanece onde está até a próxima versão, e o resolvedor nunca retrocede um checkout com base em uma suposição: se a relação for desconhecida (histórico raso, GitHub inacessível), o HEAD será mantido. Para continuar acompanhando todos os commits, execute hermes update --set-channel main; --channel <name> substitui o canal em uma única execução (stable e canary selecionam versões publicadas, enquanto main seleciona a ponta da branch). A escolha é registrada individualmente para cada instalação em update.installs, no config.yaml, usando como chave um id derivado do caminho da instalação (hermes update --install-id o exibe), pois um único ~/.hermes pode atender simultaneamente a uma instalação no host, um gateway Docker e o aplicativo para desktop. Forks, espelhos e origens em caminhos locais continuam acompanhando a main; as instalações da Store, MSIX e do aplicativo para desktop empacotado não mudam.
• O aplicativo para desktop oferece o mesmo seletor. Em Configurações ▸ Sobre ▸ Atualizações, há uma nova linha Canal de atualização para instalações pelo código-fonte (“Versões estáveis” ou “Todos os commits”), e a caixa de diálogo de atualização informa o canal atual.
• O raciocínio é preservado ao retomar uma sessão. Blocos de pensamento assinados são reproduzidos após hermes chat --resume e no turno seguinte do gateway quando o serviço upstream os valida, e os modelos de raciocínio do Bedrock Converse não rejeitam mais sessões retomadas. Uma assinatura rejeitada pelo serviço upstream recebe uma impressão digital e é removida das requisições reconstruídas, em vez de interromper a sessão.
• As atualizações não falham mais atrás de determinados firewalls. Instalações na main não buscam mais um registro de versão ao qual firewalls regionais respondem com o código 403. A verificação do canal stable usa seu token do GitHub quando houver um configurado (GITHUB_TOKEN ou gh auth login), tenta novamente sem autenticação quando um token é rejeitado e informa um limite de requisições do GitHub como tal, em vez de indicar “nenhuma versão”.
• O Holographic deixa a árvore principal. Os únicos provedores de memória incluídos agora são ByteRover e RetainDB; o Holographic é instalado pelo catálogo de plugins (categoria da comunidade, requires_hermes: ">=0.21.5"), e a migração automática o abrange da mesma forma que os outros seis. Consulte Provedores externos de memória.
• O catálogo de plugins cresceu de 493 para 552 entradas, incluindo, segundo a versão, memory-shield, command-ledger, Memoria, Model Router, wyoming-voice-bridge, codex-account-switch e redline. Os plugins de provedores permanecem em 41 diretórios, e o seletor estático, em 39 linhas.
• Também segundo as notas da versão: os plugins podem executar ações integradas do Desktop (ctx.runAction, por exemplo, view.showBrowser) e falar pelo balão do pet (ctx.pet.say); as requisições do Codex são feitas pelo núcleo, portanto os plugins nunca têm acesso ao token; uma skill instalada durante uma sessão fica disponível para o modelo sem reconstruir o prompt; Krea 2 Medium Turbo é a opção de imagem padrão para novos assinantes pagos, com fallback para FAL quando o Krea gerenciado recusa uma requisição; as atualizações do aplicativo para desktop estão mais rápidas; instalações fixadas fazem checkout apenas da referência fixada; e os marcadores de compactação são emitidos para o Relay (agent/relay_compaction.py emite registros hermes.compaction como marcadores do NeMo Relay).

Para atualizar: o aplicativo para desktop se atualiza sozinho, e as instalações da Store são atualizadas pela Store; use hermes update ou o comando de uma linha do instalador para a CLI; Docker e Hermes Cloud obtêm nousresearch/hermes-agent:stable (ou :latest).⁵⁶

O que há de novo na v0.21.6 (compilado de 8 de outubro)

O Hermes Agent v0.21.6 (tag v0.21.6, 8 de outubro de 2026) foi a versão atual de 8 a 11 de outubro, o quarto compilado enxuto da linha v0.21.x e o primeiro criado pelo novo pipeline de versões estáveis do projeto: “uma referência de tentativa, uma imagem Docker testada e uma tag de recibo na publicação”. Ele disponibiliza apenas a tag, a versão GitHub e a imagem Docker; o aplicativo para desktop, os pacotes Termux e a compilação da Microsoft Store permanecem nas versões atuais até a próxima versão agrupada. O intervalo desde a v0.21.5 é o maior até agora: “8.867 commits sem merge” em “8.342 arquivos alterados”, “2.106 PRs mesclados” e “3.027 issues encerradas” (a comparação no GitHub contabiliza 9.180 commits incluindo merges). As notas selecionadas foram novamente adiadas para a v0.22.0. A versão lista o que deixa sem documentação; cada item abaixo foi verificado no código-fonte na tag:⁵⁴⁵⁵

• Transcrição ao vivo enquanto você fala. stt.streaming: true transmite texto parcial durante a fala no CLI, na TUI e no Desktop. O recurso vem desativado por padrão, funciona com os provedores de STT openai, xai e elevenlabs (stt.streaming_model especifica o único modelo com deltas durante a fala, gpt-live-transcribe para OpenAI) e recorre ao processamento por arquivo quando o streaming falha.
• As interações por voz ganham seu próprio slot de modelo. auxiliary.voice_chat encaminha uma interação falada (entrada de voz do CLI, uma conversa por voz no Desktop ou na TUI, uma mensagem de voz em uma plataforma de mensagens) para um modelo mais rápido que o principal da sessão, com reasoning_effort: none por padrão. A rota é vinculada depois que o prompt do sistema é criado e desfeita antes da sincronização de memória e da revisão em segundo plano. Se uma interação não couber no limite de compressão do modelo de voz, ela permanecerá no modelo principal. Consulte Modelos auxiliares.
• Plugins de terceiros podem ser executados fora do processo. plugins.isolation: host (o padrão é in_process) carrega plugins gerais em um processo host de plugins por profile e recusa qualquer outro caminho que importe código do usuário dentro do processo (provedores de categorias, profiles de provedores de modelos e APIs de plugins do dashboard); os plugins incluídos continuam sendo executados dentro do processo. Um plugin que trava ou apresenta falha derruba seu host, não o gateway. Consulte Sistema de plugins.
• Mais quatro provedores de memória saem da árvore principal. Honcho, Mem0, OpenViking e Supermemory agora são instalados pelo catálogo de plugins (nível da comunidade, mantidos por seus fornecedores), juntando-se ao Hindsight; o conjunto incluído é formado por ByteRover, Holographic e RetainDB. A migração automática introduzida na v0.21.5 abrange todos os oito nomes. Consulte Provedores externos de memória.
• A camada de compatibilidade de plugins foi removida. hermes_cli/plugin_compat.py agora é um stub inerte, COMPAT_MANIFEST.md e os shims foram excluídos, e plugins.allow_deprecated_imports deixou de existir; um plugin que ainda importa um caminho anterior à decomposição não consegue ser importado. Consulte Sistema de plugins.
• hermes status prioriza o resumo. A saída padrão exibe uma linha por componente; --full (alias --all) mostra todas as seções, e --deep executa as verificações lentas. As notas da versão também mencionam uma flag --short; o parser dessa tag não tem essa opção, pois o resumo já é o padrão.
• Pacotes de idiomas conectáveis e em camadas. display.language aceita qualquer id fornecido pelos catálogos incluídos (17 na tag), pelo diretório de sobreposição do profile ou por um pacote de idioma de plugin, e hermes config set display.language <id> detecta os plugins primeiro para aceitar um pacote recém-instalado. As strings do núcleo e da TUI são fornecidas em camadas separadas (locales/<lang>.yaml e locales/<lang>.tui.yaml, com 16 pacotes de TUI na tag). Consulte Localização.
• Três novos plugins de provedores: lmstudio, solstice e tencent-tokenhub elevam plugins/model-providers/ de 38 para 41 diretórios; a lista estática do seletor permanece com 39 linhas. Os seletores do Nous e do OpenRouter adicionam GPT-6.1 Sol (com uma variante -pro), Claude Sonnet 5.5 e Claude Haiku 5.5, enquanto as listas de openai-api e Bedrock adicionam GPT-6.1 Sol. Modelos locais: hermes model lista diretamente os modelos do Ollama, LM Studio e Ollama Cloud, e o runtime local incluído adiciona compilações CUDA do llama.cpp (llamacpp-cuda) para Linux x64 e arm64, segundo a versão.
• As regras de aprovação ganham dois detectores. Um upload com curl ou wget (-d, -F, -T) que inclua uma variável com nome relacionado a segredo ou um arquivo de credenciais, ou um arquivo de credenciais redirecionado por pipe para um desses comandos, é sinalizado como possível exfiltração; um caractere de controle Unicode invisível ou bidirecional em um comando é sinalizado como possível ofuscação, pois o que você aprova pode ser diferente do que será executado.
• O cron continua funcionando quando o armazenamento não permite gravação. Um disco cheio ou um ponto de montagem somente leitura (ENOSPC, EROFS, EACCES) coloca o armazenamento do cron em modo degradado uma única vez, em vez de emitir um aviso a cada ciclo de 60 segundos, e tenta verificá-lo novamente no máximo uma vez por minuto. hermes cron status e hermes doctor informam essa condição (a versão também adiciona um aviso no canal principal).
• A configuração do Discord verifica o token do bot e exibe o link de convite com os bits de permissão exigidos pelo adaptador, além de avisar quando o Message Content Intent continua desativado, pois o Discord recusa a conexão do bot sem ele. Consulte Gateway de mensagens.
• Também: activate.fish, equivalente para fish ao script de ambiente de desenvolvimento ./activate; uma definição unificada do fluxo de trabalho Kanban, segundo as notas da versão; e, listados pela versão, mas não incluídos na compilação para desktop desta versão, modelos favoritos e fixados no topo do seletor do Desktop, um indicador de uso antes que uma assinatura atinja seu limite, avisos sobre limites de taxa dos provedores que informam o motivo e até quando se aplicam, um seletor de escopo de diff no painel de revisão e a manutenção do dispositivo ativo durante a interação.

Correções de segurança, todas com os devidos créditos na versão: quatro problemas de autenticação do dashboard relatados pela Tenable Research (um cabeçalho X-Forwarded-For falsificado podia redefinir o limite de tentativas do login por senha e contornar o limite por IP; solicitações de login não autenticadas podiam gravar valores ilimitados no log de auditoria de autenticação; as rotas públicas /auth/ não tinham limite de tamanho do corpo; e o login nativo podia enviar códigos de acesso para um redirecionamento que não fosse de loopback, permitindo o sequestro da sessão); chamadas automáticas ao git (snapshots do workspace da sessão, worktrees de subagentes, kanban, limpeza de worktrees, hermes -w) podiam executar programas de filtro clean, smudge ou process definidos pela configuração de um repositório não confiável antes do primeiro prompt, e agora recusam a operação quando não é possível neutralizar os filtros; e um nome de exibição entre aspas no cabeçalho de e-mail From podia passar pela lista de permissões de e-mail como remetente autorizado, agora analisado com parseaddr após o desdobramento do cabeçalho (GHSA-rxqh-5572-8m77). Considere esta tag uma atualização relevante para a segurança de qualquer implantação de dashboard, gateway ou e-mail.⁵⁴⁵⁵

Atualização: hermes update ou o comando de instalação de uma linha; Docker e Hermes Cloud usam nousresearch/hermes-agent:stable (ou :latest).⁵⁴

O que há de novo na v0.21.5 (compilado de 24 de setembro)

O Hermes Agent v0.21.5 (tag v2026.9.24, 24 de setembro de 2026) foi a versão atual de 24 de setembro a 8 de outubro, o terceiro compilado enxuto da linha v0.21.x: “Esta tag reúne os cerca de 460 PRs mesclados 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. As mudanças voltadas aos operadores, verificadas no código-fonte na tag:⁵²⁵³

• A memória Hindsight sai da árvore principal. O provedor Hindsight incluído e o extra pip hermes-agent[hindsight] foram removidos; agora o Hindsight é instalado pelo catálogo de plugins e mantido pela Vectorize; as notas da versão omitem essa mudança. Se a sua configuração definir memory.provider: hindsight, hermes update instalará o plugin do catálogo na pasta inicial de cada profile que o mencionar, e a primeira inicialização do agente fará a instalação caso ele ainda esteja ausente, exceto se security.allow_lazy_installs for false (nesse caso, execute hermes plugins install hindsight). As configurações, as chaves de .env e os dados da memória permanecem intactos. Consulte Provedores externos de memória.
• gateway.multiplex_profiles: false foi descontinuado. O gateway altera essa opção para true no próprio arquivo e exibe um aviso em destaque uma única vez. Um profile nomeado que precise manter seu próprio gateway deve definir gateway.standalone: true em seu config.yaml; para tirar do ar um profile atendido sem interromper o host, hermes -p <name> gateway stop agora o coloca em espera. Consulte Gateway de mensagens.
• Novos modelos nos seletores do Nous e do OpenRouter: GPT-6 Sol e GPT-6 Luna (cada um com uma variante -pro) e Claude Opus 5.5.
• A compatibilidade de plugins permaneceu inalterada nesta tag: plugins.allow_deprecated_imports: true ainda funcionava. A v0.21.6 remove a camada e a chave (consulte O que há de novo na v0.21.6).

Atualização: hermes update ou o comando de instalação de uma linha; as imagens Docker e Hermes Cloud são compiladas a partir de nousresearch/hermes-agent:v2026.9.24.⁵²

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

O Hermes Agent v0.21.4 (tag v2026.9.21, 21 de setembro de 2026) é a segunda versão cumulativa deliberadamente enxuta 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 mesclados 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 inclui “5.071 commits sem merge” em “5.169 arquivos alterados”, “1.812 PRs mesclados” e “2.116 issues fechadas”. Pela contagem de commits, esse é o segundo maior intervalo entre tags da história do projeto, atrás apenas dos 5.139 da v0.21.1; pelo número de PRs mesclados, é o maior. O relato selecionado foi adiado novamente, nestes termos: “As notas de versão completas e selecionadas 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á omitido.” A nota apresenta o que deixa sem documentação, e cada item abaixo foi verificado no código-fonte da tag; quando um item altera uma seção permanente deste guia, o link aparece na própria linha.⁵⁰⁵¹

• 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 — algo imposto por uma nova camada singleton para todo o host: um bloqueio do host mantido durante toda a vida útil do processo vencedor e um registro de rendezvous contendo (pid, createTime), para que uma segunda invocação possa confirmar que o proprietário é o mesmo processo ativo e se conectar em vez de vincular uma segunda porta. A obsolescência é comprovada, nunca presumida, 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 controla uma máquina de estados de conexão baseada exclusivamente em dados no backend, e o Desktop, a TUI e o CLI a renderizam como o mesmo cartão de configuração: um campo para cada credencial ausente, com a ação do cartão bloqueada até que todos os campos obrigatórios contenham texto. Consulte a subseção sobre o plano gratuito da Nous.⁵¹
• --format stream-json: execuções únicas legíveis por máquina. hermes chat -q ... --format stream-json emite um objeto JSON por linha da saída padrão para executores de CI e orquestradores: um evento system/init, seguido por deltas 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 da ferramenta é 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 a 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 no CLI, na TUI, no gateway, no cron ou no 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 mensagens diretas não autorizadas. unauthorized_dm_behavior ganha um terceiro valor além de pair e ignore: decline envia uma 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; 0 = ilimitado. Todos os servidores configurados ainda se conectam, mas deixam de chegar ao mesmo tempo. Consulte Integração com MCP.⁵¹
• session_search ganha limites temporais e uma nova tentativa de recuperação. O formato de descoberta aceita limites after/before (ISO ou durações relativas como 7d), e uma consulta com várias palavras sem resultados é repetida buscando QUALQUER termo, em vez do AND implícito do FTS5 entre todos os termos. Consulte Pesquisa de sessões.⁵¹
• hermes sessions set-journal-mode delete|wal: o conversor de journal offline. Este é o caminho de autoatendimento para um state.db preso no modo de journal incorreto do SQLite — algo que antes exigia executar manualmente PRAGMA journal_mode=DELETE. Primeiro, interrompa o gateway, o dashboard e todos os CLI: o comando se recusa a prosseguir enquanto qualquer processo externo mantiver o banco de dados aberto, faz a troca sem aguardar que esses processos o liberem e depois verifica os bytes do cabeçalho do SQLite. O Windows não conta com verificação de processos que mantêm o arquivo aberto; por isso, nesse sistema, o comando se recusa a prosseguir até que você use --force, depois de interromper por conta própria todos os processos do Hermes. Agora, o hermes doctor indica esse comando. A linha de hermes sessions em Comandos de nível superior inclui essa opção.⁵¹
• Desktop: uma configuração de fonte, atualizações do engine com um clique e desinstalação de plugins. As configurações ganham um campo de família de fontes, persistido por profile em desktop.font_family — ele substitui a fonte sem serifa do tema em toda a interface e no chat, a lista de sugestões começa com fontes voltadas à acessibilidade (OpenDyslexic, Atkinson Hyperlegible, Lexend) e um campo vazio deixa a escolha por conta do tema. O runtime gerenciado do modelo local exibe um botão “Atualizar engine” 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 da FAL adiciona ltx-2.5 (o modelo de áudio e vídeo open source da Lightricks: áudio nativo, conversão de imagem em vídeo de até 20 s / 4K, predefinições de movimento de câmera e categoria econômica — a fal rejeita clipes acima de 10 s em 1440p/2160p) e kling-o3 (a família de ponta da Kuaishou, na categoria 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 passou de 9 entradas na 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 autor, cada uma renderizando o README do plugin a partir do commit fixado. Os dez plugins da comunidade mencionados pela versão fazem parte do catálogo nessa tag. Sistema de plugins apresenta os detalhes.⁵¹
• E uma grande rodada de correções em isolamento de profiles/multiplexação, cron, kanban, Desktop e state.db, mencionada pela versão apenas como uma categoria; caberá à v0.22.0 produzir o registro selecionado dessas correções.⁵⁰

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 na v2026.9.21; as únicas alterações em hermes_cli/plugin_compat.py nesse período são um cache de varredura válido para todo o processo (um gateway multiplexado descobre os plugins uma vez por profile atendido, 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 saída de emergência por booleano literal permanecem inalterados, portanto plugins.allow_deprecated_imports: true ainda permite o carregamento dos plugins afetados. O quadro de compatibilidade em Sistema de plugins apresenta o estado atual.⁴²

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

O que há de novo na 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 main reunidos em uma nota com dois itens, publicada porque os agentes do Cloud são atualizados automaticamente para a tag de versão mais recente e as correções de login no gateway remoto precisavam chegar até eles. (1) As sessões remotas do dashboard não são mais revogadas por rajadas de atualização: agora, os dois caminhos de atualização no gateway (a validação de cookies e a rota bearer nativa do Desktop) consolidam solicitações simultâneas com o mesmo refresh token rotativo em uma única operação, impedindo que uma rajada causada pela retomada do Desktop reutilize no Portal um token já rotacionado, acione a detecção de reutilização e revogue toda a sessão — além disso, a atualização é executada fora do event loop, portanto um provedor de identidade lento não bloqueia mais /api/status. (2) Processos de longa duração deixam de criar identificadores de escrita duplicados para o state.db: leitores no gateway, no backend do dashboard/Desktop, no ACP e no CLI se conectam em modo somente leitura, enquanto os escritores 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 mesclados”. Todo o restante foi adiado de propósito: a versão especifica o que não está documentando (seletores de esforço de raciocínio em todos os seletores de modelos, PKCE do OAuth do OpenRouter, decodificação de HEIF/HEIC/AVIF, uma leva de itens no catálogo da FAL, tabelas coladas no Slack e o API das sessões de agentes, a recusa do WAL do state.db em sistemas de arquivos entre VMs e outros itens) e se compromete com o registro selecionado, nestes termos: “As notas de versão completas e selecionadas 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á omitido.”⁴⁹

E o prazo da compatibilidade de plugins chegou conforme previsto. 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 desaparece), portanto um plugin externo afetado passa a ser desativado no carregamento com o aviso em vermelho. O que ainda NÃO aconteceu: a reversão que realmente exclui os caminhos de importação antigos. COMPAT_MANIFEST.md, compat_manifest.json e os shims de compatibilidade continuam presentes na tag — e também na v2026.9.21 e na main em 22 de setembro —, motivo pelo qual plugins.allow_deprecated_imports: true ainda funciona como uma saída de emergência: os caminhos antigos continuam sendo resolvidos quando o carregador recebe permissão para prosseguir. Há duas armadilhas: 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 saída de emergência 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. As notas da versão são diretas: “A v0.21.0 trouxe uma grande reformulação do gerenciamento de conexões do armazenamento de sessões e, em algumas instalações, deixou o state.db vulnerável: processos de gravação secundários cancelavam os bloqueios uns dos outros, bancos de dados íntegros eram relatados como corrompidos e uma única linha inválida derrubava o sessions list. Esta versão resolve essa classe de problemas e reúne tudo o que chegou à main nos quatro dias desde a v0.21.1.” Ao contrário das notas deliberadamente breves da v0.21.1, estas documentam seus próprios destaques; as estatísticas do período são “947 commits sem merge” em “1.869 arquivos alterados” e “312 PRs integrados” de “140 colaboradores”, enquanto o registro selecionado de todo o ciclo v0.21.x continuará sendo responsabilidade da v0.22.0.⁴⁸

• A campanha de confiabilidade do state.db: seis PRs, 44 issues encerradas. A recomendação das notas para operadores vem primeiro — e você também deve segui-la: se o seu state.db quebrou na 0.21.0 ou 0.21.1, execute hermes doctor. Agora, ele distingue danos estruturais de danos no índice de busca de texto completo, em vez de chamar tudo de “corrupção de gravação no FTS”, e indica hermes sessions recover --inspect-only (offline, não destrutivo e vinculado ao profile; relata se as tabelas canônicas podem ser lidas sem criar um banco de dados de saída) quando uma reconstrução não é suficiente. O trabalho na causa raiz elimina todos os processos de gravação secundários no armazenamento: os gateways dos profiles gravavam o estado das salas hospedadas no state.db raiz a cada 5 segundos, e essa coordenação agora fica em um shared-state.db dedicado, portanto os gateways dos profiles nunca abrem o armazenamento principal de sessões com permissão de gravação; o dashboard tenta primeiro abrir em modo somente leitura; a proteção do ciclo de vida do cron passa pelo registro de conexões rastreadas, em vez de usar um open() direto 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 cuja segurança não consiga comprovar. Além dos processos de gravação: danos no índice FTS agora apenas limitam a busca, e o índice é reconstruído posteriormente, em vez de encerrar todo o turno com falha; uma linha corrompida não derruba mais sessions list, a exportação nem os insights (linhas inválidas aparecem como ?, acompanhadas de um aviso que identifica a sessão); as sessões nunca se vinculam ao banco de dados de outro profile nem o leem; e uma abertura somente leitura não adquire mais o bloqueio de gravação, então uma execução avulsa do hermes por trás de um gateway ocupado passou de uma espera de 4 a 20 segundos seguida de falha 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 de profiles oferece a cada profile “configurações, skills, memória e segredos totalmente isolados”. Na v0.21.2, essa promessa ainda tinha brechas, agora corrigidas: 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 stdio MCP recebiam os segredos do cofre do profile padrão, a entrega via MEDIA: podia anexar o .env, auth.json ou state.db de outro profile, callbacks de webhook e do Feishu podiam se desviar do profile definido pelo roteamento, e profiles secundários podiam receber o bearer da Nous pertencente a 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 que não expõe 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, enquanto os códigos de autenticação de dois fatores vêm de uma chave de autenticador salva (TOTP: uma semente base32 ou um URI otpauth://totp; o HOTP baseado em contador é rejeitado) ou são solicitados na sua interface. Todos os backends fornecem ao agente a mesma estrutura — metadados de login e um identificador opaco com namespace (vault_ no cofre local, op:, bw:), com a senha resolvida apenas no momento do preenchimento; gerenciadores externos permanecem bloqueados até você desbloqueá-los durante a sessão, e a senha mestra “nunca é um argumento de ferramenta, nunca aparece em argv e nunca é persistida”. Isso dá continuidade ao trabalho com SecretSource da v0.19.0, que removeu as chaves API dos providers do .env em texto simples; agora, o cofre faz o mesmo com as credenciais de navegação do agente.⁴⁸
• Um catálogo selecionado de plugins fixados por SHA. hermes plugins browse lista “todas as entradas do catálogo selecionado de plugins”, hermes plugins search consulta o 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 declarativas e compartilháveis de plugins”: um único hermes-pack.yaml fixa um conjunto de plugins em SHAs exatos de commits, pack install distribui o trabalho para instalações fixadas comuns, mantendo o consentimento de recursos separado por plugin, pack export gera um pack da instalação atual e pack show funciona como uma simulação. O bloco de comandos em Sistema de plugins inclui os novos subcomandos.⁴⁸
• Plano gratuito da Nous e primeira inicialização guiada. Instalações novas já oferecem inferência e conectores gratuitos, com um único comando para fazer login; /login funciona dentro de um chat; e as ferramentas de conectores (Gmail, Linear, Notion e as demais) podem ser encontradas por meio de tool_search. A primeira inicialização guiada do aplicativo desktop fica condicionada a HERMES_GUEST_ONBOARDING=1, e somente o valor literal 1 a ativa: o próprio teste do aplicativo desktop confirma que 'true', '0' e um valor vazio mantêm o recurso desativado, enquanto a decisão de inicialização é registrada no ambiente do backend iniciado para que nenhum valor herdado seja aplicado indevidamente. Consulte Nous Tool Gateway.⁴⁸
• As tempestades de inicialização do backend no aplicativo desktop acabaram. Antes, o Bot Mode iniciava ou se conectava a um backend por profile durante a 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.⁴⁸

O processo de atualização continua o mesmo: hermes update em uma instalação existente ou o instalador via shell em uma instalação nova.⁴⁸

Novidades da 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 patch” 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 incorporados” — e deixa o restante da história para depois: “As notas de versão completas e organizadas deste 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 a menor nota de versão. Até que a v0.22.0 apresente o registro organizado, 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 termina em 14 de setembro. A decomposição de setembro de 2026 (PR nº 102117) dividiu os grandes módulos do repositório em arquivos especializados: um novo pacote agent/ contém os componentes internos do loop de conversa (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 a origem 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 ampliadas automaticamente a partir dos 39 diretórios de plugins de provedores incluídos), e delegate_task foi dividido entre cerca de uma dúzia de módulos tools/delegate_tool_*. Os caminhos internos de importação não são uma API estável, portanto um novo COMPAT_MANIFEST.md na raiz do repositório reexporta 1.148 nomes públicos “moved-lazy” a partir dos caminhos antigos de seus módulos, cada um emitindo um HermesPluginCompatWarning uma vez por nome em cada processo quando resolvido. A camada de compatibilidade era temporária, e sua remoção entrou em vigor conforme programado em 2026-09-14, seis dias após a tag — não como uma reversão de código, mas como uma restrição por data que já estava no código publicado. Desde essa data, um plugin de terceiros afetado não é carregado: o banner da CLI, hermes doctor e hermes update exibem um aviso vermelho que identifica o plugin desativado, o aplicativo para desktop mostra uma caixa de diálogo uma única vez, e hermes plugins list apresenta 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 restar qualquer ocorrência (--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 continua funcionando: a reversão que realmente exclui os caminhos de importação antigos ainda não havia sido incorporada em 22 de setembro (verificado até a tag v2026.9.21 e na main), portanto os caminhos antigos continuam sendo resolvidos quando o loader tem permissão para prosseguir. Os detalhes das consequências estão em Novidades da 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 de forma explícita: “A inatividade e o tempo decorrido nunca alternam uma conversa. /new e /reset criam um limite explícito; a compactação de contexto continua gerenciando históricos longos. Configurações antigas de temporizador são ignoradas. O tipo de dados 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ê transferiu 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> recebe --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 aplicativo para 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> não inicializa a frio servidores desnecessários. O bloco de comandos de Integração com a MCP agora inclui login e reauth [--all], ambos anteriores a este período, mas ainda não 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 verificadas no código-fonte da ferramenta de delegação na tag. (1) Por padrão, um lote em segundo plano retorna como UMA única conclusão; ativar delegation.independent_completions divide a chamada em unidades de conclusão: tarefas que compartilham um valor de group são reunidas e reportadas em conjunto, enquanto cada tarefa sem grupo é reportada separadamente conforme termina. O 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"); os 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 com o trecho final da saída. A posição adotada no projeto, segundo a docstring do código-fonte: o pai “precisa saber disso pelo 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 superfície de configuração real: null herda a cadeia do pai para filhos não fixados, [] 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, de modo que 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 uma conclusão parcial. (6) Subagentes nunca herdam a camada de cache de prompts de 1 hora: um filho delegado passa para a camada de 5 minutos, porque a camada de 1 hora tem preço voltado a uma pessoa que se afasta, não a uma rajada de filhos paralelos.⁴⁵
• Provedores e modelos. Os catálogos passam a incluir GPT-6 Astra e Astra Pro da OpenAI, com variantes de camada de velocidade -fast/-flex (“preço 2x, camada prioritária” / “preço 0,5x, camada flex”) nos catálogos do Nous Portal e do 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 recebe uma variante opcional -900k no seletor, que aumenta a janela anunciada de 272K para cerca de 900K, verificados ao vivo; o sufixo nunca é enviado na requisição. Junto com ele: 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 para colaboradores) e um plugin de provedor de geração de imagens muse-image da Meta. O Tavily chega como backend de pesquisa/extração na web (TAVILY_API_KEY; o modo sem chave funciona quando o Tavily é selecionado por meio de hermes tools). Um runtime gerenciado do llama.cpp transforma os modelos locais em uma opção de primeira classe (binários oficiais, um único llama-server supervisionado e configuração com um clique no aplicativo para desktop), e provedores de processos externos fora do repositório recebem uma ramificação própria de resolução. Na prática: os catálogos remotos do seletor agora são atualizados a cada 20 minutos (model_catalog.ttl_minutes, padrão 20; a chave antiga ttl_hours só é respeitada quando o usuário a definiu explicitamente).⁴⁶
• Aplicativo para desktop: anote a página, controle a sessão. O navegador integrado ao aplicativo recebe um modo de comentários: clique em Annotate, 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 pins numerados e nunca enviam uma interação por conta própria. Quando terminar, “Add N comments” envia o lote ao composer com uma captura de tela recortada por pin, e cada comentário de elemento inclui seu seletor da CSS, sua marcação e os estilos computados relevantes para o layout, para que o agente encontre o elemento no seu código-fonte em vez de tentar identificá-lo em uma imagem (senhas, valores ocultos e atributos com aparência de chave são ocultados 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 poucos blocos de trabalho que normalmente alteram arquivos separados — o que torna seguro distribuí-los entre workers paralelos. Ao redor disso: controles estruturados de sessão e controles de automação de sessão, criação de sessões ao arrastar, uma tela de importação de sessões para transcrições de outros agentes de programação, 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 que oferece browser.use_real_profile quando um painel Browser é aberto com essa opção desativada, um catálogo integrado de skills opcionais em Capabilities -> Skills com instalação em um clique e uma nova localidade russa para a interface do aplicativo para desktop (os 17 catálogos de localidades da CLI permanecem inalterados).⁴⁷

A atualização continua igual: hermes update em uma instalação existente ou o instalador via shell para instalações novas. Cabe à v0.22.0 apresentar o registro organizado deste período; 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 de 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 ciclos estão totalmente documentados aqui.” A proposta dá continuidade ao Herald: “A v0.20.0 transformou Hermes no arauto — ele falava e levava mensagens a outros agentes. Na v0.21.0, os deuses se reúnem.” Os números, na íntegra: “Desde a v0.20.0: cerca de 5.800 commits · cerca de 2.475 PRs incorporados · cerca de 5.680 arquivos alterados · cerca de 869.000 inserções · cerca de 135.000 exclusões · cerca de 2.100 issues encerradas · 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, a indicação aparece em linha.

• Bot Mode: seus agentes se tornam uma sociedade, integrada ao produto. O Bot Mode deixa de ser o plugin hermes-bots incluído no ciclo da 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 @ pelo 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 envia, carregamento com renderização antecipada para retomadas instantâneas, um painel de rotinas e uma reformulação baseada no sistema de design do aplicativo. Nas palavras da própria versão: “Antes, ‘multiagente’ 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, pela CLI ou de dentro de uma conversa — peça ao seu bot de pesquisa para encaminhar 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, portanto as conversas entre agentes são persistentes 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.³⁵
• Tarefas cron que se lembram. As tarefas agendadas deixam de ter memória curta: agentes cron carregam e atualizam a memória persistente como qualquer outro agente, continuity=true leva a saída de cada execução para a próxima, permitindo que um monitor elimine duplicatas com base no que já informou, cada tarefa recebe um bloco de notas persistente para rascunhos, tarefas no modo monitor ignoram totalmente a LLM quando nada mudou, o nível 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 o funcionamento de cada recurso no tag.³⁵³⁷
• Orquestração de subagentes em tempo real. delegate_task ganha ações de controle: listar filhos em execução, redirecionar um deles durante o trabalho com uma correção de curso ou interrompê-lo antecipadamente e manter o resultado parcial. As saídas dos filhos podem ser validadas com um schema JSON, o custo de cada delegação aparece nos resultados e os limites padrão 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 do 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 cada servidor nos últimos 30 dias) 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 para a CLI. Ctrl+P abre uma paleta de comandos com busca aproximada (também acessível por /palette), o seletor de /model filtra os resultados enquanto 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. Além disso, há uma parada de emergência global, fixação e desafixação de sessões, textos de exemplo 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, o comando disponível é hermes approvals test — não existe um 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 pode navegar, clicar e ler diretamente, e as páginas podem ser abertas no navegador do sistema com menus de contexto completos para links.³⁵
• Seis novos provedores 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 em ciclos anteriores do conjunto de atualizações e já estavam na matriz de provedores; agora, a matriz também inclui Tencent TokenPlan, Nebius Token Factory e Ramp Router, além do novo SKU Alibaba Token Plan mencionado na documentação. Os catálogos passam a incluir GLM-5.3-Flash, qwen3.8-max/flash, Gemini 3.7 Flash, MiniMax M3 gratuito, Nemotron 3.5 Lightning e Muse Spark 1.2. Duas mudanças estruturais também acompanham a versão: model_overrides no 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 provedores podem ser distribuídos como pacotes instalados via pip e descobertos por entry points; um registro unificado de proteções de seleção também exibe avisos em todos os seletores quando um modelo é treinado com seus dados.³⁵³⁶
• Reforço de segurança em todas as áreas. Gravações em arquivos protegidos de instruções do agente (AGENTS.md, 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; uma revisão ampla de redação de dados fecha brechas de vazamento de segredos em erros do terminal, leituras de .env, checkpoints e logs ACP; o sistema de aprovação passa a reconhecer comandos destrutivos do Windows; as permissões concedidas no macOS continuam válidas apó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 MCP e sua skill foram removidas após o comprometimento de uma dependência upstream. Consulte reforço de segurança para ver os detalhes correspondentes ao tag.³⁵³⁹
• Amadurecimento do gateway. Slack ganha cartões nativos em tempo real (respostas realmente transmitidas em streaming, além de cartões opcionais de planos e tarefas) e supressão de prévias de links enviados; Telegram recebe um seletor em linha que permite pesquisar todos os comandos e skills usando @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 em tempo real com streaming de rascunhos, segmentação por intervalo de sessão e restauração da conversão de voz em texto para mensagens de áudio); 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 encerrarem toda a árvore de processos; e o mecanismo de encerramento de turnos captura as stacks 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 API derivados de HAR (“observe um site uma vez e depois chame diretamente sua API oculta, 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 ciclo (não incluídos na versão): tanto o modo Model Council (/council) quanto o context engine DCP foram implementados e depois revertidos; o servidor de gateway exclusivo para WS (#94245) foi incorporado e posteriormente revertido (#96118), portanto FastAPI continua no fluxo de inicialização do aplicativo para desktop — porém, a repetição de eventos com marcação sequencial (#94219) e a reconexão sem perdas do aplicativo para desktop por WebSocket FORAM incluídas. Electron voltou para a versão 40.10.2. Se a cobertura da comunidade sobre os ciclos da v0.20.x mencionou algum desses recursos, eles não estão nesta versão.³⁵

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

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 com novos recursos antes que a v0.21.0 consolidasse todo o conjunto; 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 próprias que também incluem novos recursos — consulte 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 a participação de mais de 650 colaboradores.⁵⁹

Três mudanças invalidam as orientações das versões anteriores deste guia. 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. Literalmente: “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 de orçamento abaixo são calculados com base no novo teto. read_file também passa a usar 2.000 linhas por padrão, em vez de 500.⁵⁹

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, atendendo à solicitação de longa data da issue nº 514.⁵⁹
• Webhooks de saída assinados. Antes, hermes webhook aceitava apenas eventos de entrada; 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.⁵⁹
• Onda de recursos avançados para CLI. !command executa um comando shell imediatamente sem consumir 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á ocupando a janela de contexto; /focus oferece uma visualização com menos saída e permite recuperar linhas ocultas; Ctrl+S guarda um prompt parcialmente escrito. hermes import-agent migra uma configuração de Claude Code ou Codex CLI com um único comando.⁵⁹
• Novidades na área de segredos. Uma fonte de segredos baseada em comandos auxiliares que se integra a 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 pasta inicial de cada profile e paridade de SecretRef ${env:VAR} entre config.yaml e a configuração de 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. Artefatos com cartões versionados e visualização dinâmica em sandbox, um SDK de plugins com o Kanban como plugin inaugural para desktop, uma tecla de atalho global para entrada rápida, várias janelas da interface gráfica, modo de backend remoto do SSH e login nativo conforme a 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 uma cadência de alta frequência para consolidações com tags, e elas foram além da 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 agora 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 apresentam tudo em conjunto.^58233035

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

• Migração para SDK do MCP 2.x, com suporte ao protocolo sem estado de 2026-07-28. O Hermes migra para a geração atual de SDK do MCP e oferece compatibilidade com a revisão sem estado do protocolo.⁵⁸
• O Bot Mode chega como um plugin incluído (hermes-bots) que contém o protocolo central para integrantes da 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 de subprocessos do Python (isolamento de PYTHONHOME/PYTHONPATH).⁵⁸
• Confiabilidade: autorrecuperação do agendador cron (recuperação de EMFILE, reconciliação de reivindicações obsoletas e reativação de tarefas travadas), correções de perda de dados na transferência entre sessões, autorrecuperação da conexão do desktop com o gateway remoto e uma série de melhorias transferidas para o ecossistema (verificação de segurança na instalação de plugins, /worktree, preservação de edições manuais no /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: acabamento em vidro fosco e transparência, com um seletor de efeito fosco e pré-seleção no macOS.⁵⁸
• Uma barra lateral com abas SESSIONS|BOTS, com a opção de ocultar ou exibir cada bot, além de correções nos chats em grupo do Bot Mode (turnos prolongados dos participantes, renderização de Markdown e roteamento entre máquinas).⁵⁸
• Verificação consultiva de nível 1 do NVIDIA SkillEvaluator ao instalar skills — verificações de licença e segurança são executadas quando você instala uma skill.⁵⁸
• Reforço do envio de mídia por cron (timeout configurável, anexos em execuções manuais e exibição de execuções perdidas), correções na thread do loop de eventos e em contenções do SessionDB, transparência do hermes update quanto a 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 pesquisa na web funciona em instalações novas sem nenhuma chave de API — uma rotação gratuita entre 5 fornecedores com failover em anel.²³
• Uma onda de refinamentos no CLI: seletor de /model com busca aproximada, uma paleta de comandos acessível com Ctrl+P e um /status mais completo.²³
• O Bot Mode amadurece: threads em salas de grupo, resumos recolhíveis de conversas, avatares com rostos em formato de blob e anexos de PDF/arquivos com arrastar e soltar.²³
• Ferramentas para frota e worktree: 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, conforme a ajuda do parser, ela “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 controles de disciplina de execução e de travamento do runtime orientados pelas descobertas da avaliação do Composio, esclarecimento com várias perguntas, o provedor sem autenticação e independente do opencode e melhorias de desempenho no desktop (hidratação do Bot Mode com prioridade à 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 própria versão se descreve claramente 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 descrição situa a janela em cerca de 1.313 commits distribuídos por aproximadamente 1.557 arquivos (+177.113 / −21.682) — cerca de 525 PRs mesclados.³⁰ Estes são os principais destaques dessa descrição:

• Navegação com profile real condicionada ao consentimento — a navegação local pode usar seu profile padrão do Chromium, com um fluxo no Windows para fechar o navegador após sua aprovação.³⁰
• O Browser do desktop ganha sua própria janela no 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 de MCP: mais de 50 servidores hospedados por fornecedores e verificados em operação, incluindo Cloudflare, Grafana Cloud, Better Stack e Railway.³⁰
• Criptografia opcional via chaveiro do sistema operacional para segredos armazenados — sem mais solicitações do Chaves do macOS a cada inicialização.³⁰
• Novos modelos nos seletores: GLM-5.3-Flash, MiniMax M3 gratuito e MiniMax H3 Max para vídeo.³⁰
• Cache de resultados com TTL para web_search/web_extract e tool_search com várias consultas e redução de palavras aos seus radicais.³⁰
• A compactação lean-tail agora é o padrão — a seção Compactação de contexto abaixo documenta a configuração disponível nessa tag.³⁰³¹
• Os backends de terminal se tornaram extensíveis por plugins — consulte Backends de terminal.³⁰³²
• Transparência do atualizador e da frota: os atualizadores pausam os gateways por meio do socket de controle em vez de encerrar suas árvores de processos, e instalações gerenciadas por imagens ou pacotes recusam atualizações locais que não sejam seguras.³⁰
• Confirmações duráveis de incidentes do cron com erros mais claros de divergência de código, controles para a pré-visualização de links no Slack e identidades de contêiner compartilhadas do Docker.³⁰

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

Novidades da v0.19.0 (The Quicksilver Release)

O Hermes Agent v0.19.0 (tag v2026.7.20, 20 de julho de 2026) recebeu esse nome em homenagem à velocidade do próprio deus mensageiro: o eixo central da versão é a responsividade bruta, com uma redução de aproximadamente 80% no tempo até o primeiro token do primeiro turno em todas as plataformas. Em torno desse eixo estão o gerenciamento de cobranças pelo terminal, fontes de segredos em gerenciadores de senhas, aprovações inteligentes por padrão, subagentes observáveis e entrega de respostas à prova de falhas. O período desde a v0.18.0 é o maior da história do projeto: aproximadamente 2.245 commits, cerca de 1.065 PRs mesclados, aproximadamente 3.300 issues fechadas e mais de 450 colaboradores da comunidade.⁶⁰

• Primeiro token aproximadamente 80% mais rápido, em todos os lugares. O tempo entre o envio a frio e o despacho caiu de cerca de 4,3 s para aproximadamente 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 sondagem do Ollama é ignorada para provedores conhecidos que não são Ollama e as operações bloqueantes foram removidas da inicialização do agente. A latência percebida também recebeu atenção especial: agora, por padrão, os modelos de raciocínio transmitem seu processo de pensamento ao vivo (display.show_reasoning está ON), e a caixa de resposta é renderizada a cada token, não a cada linha.⁶⁰
• Ondas de melhorias na renderização do desktop e da TUI. O aplicativo para desktop passou por uma reformulação de desempenho com cerca de 20 PRs: uso 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, troca ágil de sessões em 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 de forma incremental, bloco por bloco.⁶⁰
• As instalações via pip e Homebrew estão obsoletas. Ambos os métodos foram classificados como instalações “legadas sem suporte”, com remoção planejada. Essa remoção já ocorreu na v0.20.0 — os canais brew e pip/PyPI wheel foram desativados, restando o instalador shell, o Docker e o Nix como canais compatíveis.⁶⁰⁵⁹
• Os segredos podem vir do seu gerenciador de senhas. Uma nova interface conectável SecretSource busca segredos no Bitwarden e no 1Password (referências op://) durante o carregamento, permitindo usar vários cofres simultaneamente, com precedência determinística, alertas de conflito e procedência por variável — as chaves do API não precisam mais ficar em um .env de texto simples. Outros provedores de cofres poderão ser adicionados futuramente como plugins.⁶⁰
• As aprovações inteligentes agora são o padrão. Quando o Hermes quer executar um comando sinalizado, um revisor independente do LLM o avalia em vez de pedir sua confirmação para cada comando — e cada decisão abrange apenas aquele comando específico. Regras de negação definidas pelo usuário bloqueiam comandos correspondentes até mesmo no modo YOLO, /deny <reason> transmite o motivo da sua recusa para que o agente ajuste sua abordagem, 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.⁶⁰
• Gerenciamento de cobranças 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 custará um upgrade ou quando um downgrade entrará em vigor e aplique a alteração com a opção de desfazê-la. O aplicativo para desktop recebe uma aba equivalente de configurações de cobrança.⁶⁰
• 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 após reinicializações, e as respostas finais do gateway são registradas em um registro 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 está obsoleta em favor dos 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 profiles diferentes — cada um com configurações, skills, memória e segredos totalmente isolados — com uma substituição por GATEWAY_MULTIPLEX_PROFILES. O índice de roteamento foi transferido para o state.db; agora, sessions.json é um espelho legado opcional.⁶⁰
• Onda de provedores e modelos. O Fireworks AI chega com suporte de primeira classe (estimativa de custos e 2ª posição no seletor de provedores), acompanhado pelo DeepInfra e pelo Upstage Solar. Os catálogos recebem o GPT-5.6 (Sol/Terra/Luna + Pro, integrado de ponta a ponta), o grok-4.5 (GA), o kimi-k3 (com o kimi-k2.x descontinuado) e o 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 esforço de raciocínio se torna 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 raciocinam intensamente, enquanto o sintetizador permanece rápido), esforço por tarefa para modelos auxiliares e um /reasoning limitado à sessão no CLI.⁶⁰
• Recursos do CLI e do MCP. hermes sessions export gera arquivos nos formatos Markdown, Quarto, HTML, somente prompt e rastreamento do Hugging Face, com uma opção --redact para remover dados confidenciais; /model --once permite substituir o modelo por um turno; 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 do MCP adotam a convenção de nomenclatura mcp__server__tool.⁶⁰

Se você estiver atualizando a partir da v0.18.x, duas mudanças merecem atenção antes de qualquer outra: agora, instalações via pip ou Homebrew exibem um alerta de método legado sem suporte (migre para o instalador de uma linha), e max_async_children está obsoleto em favor dos limites unificados de concorrência para delegações. Todo o restante é incremental — os principais motivos para atualizar são a redução de aproximadamente 80% na latência do primeiro turno, as aprovações inteligentes e o registro de entregas que protege as respostas concluídas contra falhas.

Novidades da v0.18.0 (The Judgment Release)

O Hermes Agent v0.18.0 (tag v2026.7.1, 1º de julho de 2026) recebeu esse nome em referência ao julgamento: o agente verifica o próprio trabalho em vez de alegar que foi bem-sucedido, e você pode realmente inspecionar o raciocínio em conjunto. 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 de primeira classe. 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 seu próprio bloco identificado, com a resposta transmitida ao vivo — você pode acompanhar o conjunto raciocinando 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 uma meta foi concluída, em vez de simplesmente alegar sucesso — o julgamento aplicado a si mesmo.²²
• /learn — transforme a descrição de qualquer coisa em uma skill. Transforme um fluxo de trabalho em uma skill reutilizável descrevendo-o; as skills geradas seguem automaticamente as convenções do CONTRIBUTING.md do 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 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 de primeira classe, com um modelo de organização por projeto/repositório/lane.²²
• Gateway com scale-to-zero. Os gateways podem entrar em estado de inatividade quando estão ociosos e coordenar o esvaziamento de tarefas para permitir implantações contínuas — algo importante para quem executa o Hermes como um serviço permanentemente ativo.²²
• Suporte ao Google Vertex AI. Acesso ao Gemini por meio de contas de serviço do GCP, com atualização automática de tokens do OAuth2, passando a integrar o catálogo de provedores.²²
• Comando de edição /prompt. Abre o $EDITOR para você escrever prompts com várias linhas, em vez de ter que lidar com as limitações da linha de entrada.²²

Se você estiver atualizando a partir da v0.17.x, nenhuma dessas mudanças afeta o CLI. Os principais motivos para atualizar são os contratos de conclusão (metas que verificam a própria execução), o MoA de primeira classe com conjuntos inspecionáveis e o /learn para registrar skills.

Novidades na 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 controles mais avançados no desktop e no dashboard. A versão 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 de 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 ser incluído como um plugin de plataforma, com um design de canal de ativação que garante privacidade por contrato.²¹
• Novos modelos e provedores. O catálogo adiciona z-ai/glm-5.2 (contexto de 1M), anthropic/claude-fable-5, laguna-m.1, nemotron-3-ultra e grok-composer-2.5-fast (modelo do Cursor via OAuth da xAI, 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” ao vivo que transmitem as atividades delegadas (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 uma 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 (modelos parametrizados disponíveis em formulários, comandos de barra, conversas e documentação) e um login seguro que retorna 401 atrás da camada de proteção OAuth.²¹
• Skills e ferramentas. Agora o image_generate pode editar e transformar uma imagem de origem, não apenas criar uma do zero, em todos os provedores de imagens compatíveis; a ferramenta memory ganhou um array operations para adicionar, substituir e remover itens em lote de forma atômica em uma única chamada; uma nova skill simplify-code executa em paralelo uma revisão e limpeza por três agentes, controlada por um nível de risco baseado na Cerca de Chesterton; e o booleano write_approval substitui o write_mode de três estados.²¹
• Arquitetura. Os subagentes em segundo plano retornam imediatamente um identificador e reinserem o resultado 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 posteriormente são disponibilizadas entre os turnos (sem comprometer o cache); o cron se torna um CronScheduler conectável, com um provedor de cron gerenciado Chronos; e um novo escopo Managed (/etc/hermes) permite que um administrador fixe configurações que o usuário não pode alterar, junto a um relay Gateway-Gateway para topologias com vários gateways.²¹
• Novos comandos. /version, /billing (faturamento interativo pelo terminal), hermes photon login (autenticação do iMessage) e hermes curator run --consolidate — agora a consolidação precisa ser ativada explicitamente, de modo que a curadoria rotineira em segundo plano não consuma tokens.²¹
• Segurança. A v0.17.0 corrige uma forma de contornar a lista de bloqueio de escapes de shell, adota o bloqueio seguro quando módulos de aprovação e adaptadores de gateway com políticas próprias estão ausentes, sanitiza o ambiente dos subprocessos de scripts executados por tarefas cron, oculta segredos nos dumps de debug das 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 aqui quebra a interface 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 na v0.16.0 (The Surface Release)

O Hermes Agent v0.16.0 (tag v2026.6.5, 5 de junho de 2026) recebeu esse nome pelas novas interfaces oferecidas ao agente centrado na CLI. O grande destaque é que o Hermes deixou de ser exclusivo do terminal.²⁰

• Aplicativo nativo para desktop. O Hermes Desktop é um novo aplicativo Electron para macOS, Linux e Windows, com instalação em um clique e atualização automática pelo 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 pesquisa e um seletor de modelos na barra de status. Ele pode se conectar a um Hermes gateway remoto por 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 para 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 padrão).²⁰
• Painel administrativo no navegador. O dashboard web local evoluiu de uma visualização de status para um painel administrativo completo: um catálogo de MCP com controles para ativar e desativar, gerenciamento de credenciais, criação de webhooks e hooks, configuração de memória, controles do gateway e uma página de sistema que verifica antes de atualizar e oferece o Debug Share em um clique. Uma nova página Channels permite configurar pelo navegador todas as plataformas de mensagens do gateway (Telegram, Discord, Slack e as demais). 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 comandos de barra. /undo [N] retrocede 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) passa a estar disponível, com --cli para substituí-la; a TUI ganha um comando /model unificado e uma sobreposição Sessions. hermes portal é um alias mais fácil de entender para o fluxo de integração do Nous Portal, que agora oferece os caminhos Quick Setup e Full Setup na primeira execução, e chegam dois diagnósticos: hermes prompt-size e hermes sessions optimize.²⁰
• Novos modelos e provedores. O seletor adiciona 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 API). Um provedor OAuth nativo para o xAI Grok chega ao inicializador para desktop, o seletor de modelos passa a oferecer pesquisa aproximada em todas as interfaces, provedores com vários endpoints são agrupados em uma única linha e a atualização do catálogo passa 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 obsoletas (o Spotify migrou para um plugin nativo, o Linear para hermes mcp install linear e várias entradas desatualizadas foram removidas), transferiu mais delas para a categoria opcional e adicionou um filtro de relevância environments: no frontmatter (kanban/docker/s6), que mantém skills específicas de determinados contextos fora do índice até que sejam solicitadas. NVIDIA/skills agora é uma fonte confiável padrão do Skills Hub, junto com OpenAI, Anthropic e HuggingFace. As ferramentas de MCP e de plugins ganharam divulgação progressiva (com escopo definido), e foi corrigido um bug de MCP que informava falsamente o sucesso da OAuth quando nenhum token era obtido.²⁰
• Segurança. A v0.16.0 fixa uma versão corrigida do Starlette (≥1.0.1) contra a CVE-2026-48710 (BadHost), retira do event loop as verificações de URL contra SSRF em fluxos assíncronos, remove do ambiente dos subprocessos o bearer token de inferência do Bedrock, adiciona bws_cache.json à proteção de leitura segura de arquivos, inclui docker restart/stop/kill na lista de padrões perigosos e sanitiza caracteres Unicode invisíveis no conteúdo verificado das skills. A versão corrigiu 2 problemas P0 e 62 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 novas interfaces e novos provedores em torno do mesmo agente. O aplicativo para desktop e o painel administrativo são os motivos para atualizar se você quiser disponibilizar o Hermes a usuários que não usam o terminal ou administrar um gateway remoto pelo navegador.

Novidades na v0.14.0 (The Foundation Release)

A v0.14.0 não gira em torno de um único recurso de destaque, mas da redução do esforço de configuração e da ampliação dos 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 adia trabalho suficiente para reduzir o tempo de partida a frio em aproximadamente 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 a 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 relaciona 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 completa, a recuperação retroativa do histórico do Discord fica ativada por padrão e os prompts clarify do Telegram e do Discord passam a usar botões nativos.
• A verificação após a escrita melhora. Depois das edições, o Hermes pode exibir, antes do turno seguinte, resumos das alterações em arquivos por turno e diagnósticos semânticos do servidor de linguagem, aproximando-se de um trabalho de agente orientado por evidências.
• As ferramentas de desktop e mídia ficam mais abrangentes. computer_use funciona por meio do cua-driver para provedores que não sejam da Anthropic, video_generate é unificado por trás de backends conectáveis e vision_analyze envia pixels brutos aos modelos que realmente conseguem enxergar.

Instalação

O instalador de uma linha é o método de instalação oficialmente compatível. 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 foram descontinuadas a partir da v0.19.0. O pacote PyPI introduzido na 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 muda para um pacote testado para Android).⁷ O Windows nativo agora é uma plataforma 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 explícita: 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 do Windows amadureça.¹⁹

Após a conclusão:

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

O único pré-requisito é o git. O instalador configura automaticamente o Python 3.11 por meio do uv (sem exigir sudo), o Node.js 26 (para automação do navegador e a integração com o WhatsApp), o ripgrep e o ffmpeg. O Node 26 é o requisito mínimo obrigatório 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 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ê precisa 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.⁷ 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, e 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 decomposiçã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 a partir de 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 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 provedores da documentação incluem 45 provedores de nuvem e assinatura, além de uma linha para endpoint personalizado, 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 agora rejeita tráfego anônimo originado fora do próprio cliente.⁵³ Na tag v0.21.6, a lista estática ainda tem 39 linhas e o número de diretórios chega a 41: lmstudio e tencent-tokenhub, que já tinham linhas estáticas, ganham diretórios de plugin, enquanto solstice, que não tem uma, entra pela extensão automática.⁵⁵ Além disso, há endpoints personalizados e três caminhos de autenticação distintos. Veja toda a superfície de autenticação, organizada por caminho para você encontrar 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. 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, permitindo vários cofres simultaneamente, precedência determinística, avisos de conflito e rastreabilidade por variável — o .env continua sendo a alternativa. (Isso é diferente do token de inicialização do Bitwarden Secrets Manager da v0.15.0, que consolidava as chaves dos provedores em um único token; 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 e armazena as credenciais em ~/.hermes/auth.json (também 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á persistida no config.yaml.²

A matriz completa de provedores

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

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

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

# 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 Anthropic OAuth pelo hermes model, o Hermes dá preferência ao armazenamento de credenciais do próprio Claude Code, em vez de copiar o token para ~/.hermes/.env. Isso permite que as credenciais atualizáveis da Claude continuem sendo atualizadas.² Se você já usa o Claude Code na mesma máquina, esse é o caminho mais simples.

Para fixar a Anthropic permanentemente no config.yaml:

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

--provider claude e --provider claude-code também funcionam como formas abreviadas de --provider anthropic.²

GitHub Copilot: 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

A autenticação é verificada nesta ordem, conforme a documentação original:² 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 OAuth via hermes model

O tipo de token faz diferença. A API do Copilot não aceita Personal Access Tokens clássicos (ghp_*). Os tipos aceitos são tokens OAuth (gho_*), PATs refinados (github_pat_* com a permissão Copilot Requests) e tokens do GitHub App (ghu_*). Se o seu gh auth token retornar um token ghp_*, use hermes model para fazer a autenticação via 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.²

A 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 direcioná-las ao mesmo servidor durante uma sessão de conversa, reutilizando 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 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 OAuth do mesmo provider — isso é ú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 do 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 fonte única 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 auxiliar de roteamento provider: "main", portanto não as exclua sem verificar se você as usa nessa função.)⁴

Como alternar entre 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 nome de modelo, apenas o comando) consulta o endpoint /v1/models da sua API 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 executará. Cada um foi projetado para criar um endpoint funcional ao qual o Hermes possa se conectar.²

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 usando OLLAMA_CONTEXT_LENGTH ou um Modelfile — a 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 uso com agentes, defina pelo menos 16k–32k.

vLLM — servidor de 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

O uso de ferramentas exige --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 retornarão como texto simples.²

SGLang — servidor rápido com RadixAttention para reutilização do cache de 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 chamar ferramentas. Sem essa opção, o llama-server ignora completamente o parâmetro tools, e o modelo tenta chamar as 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 pela 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 do modelo no 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 de desenvolvimento local e um servidor de 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 usando 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/ para que provedores de inferência de terceiros possam ser adicionados sem modificar o núcleo.¹⁸ Se um provedor oferecer um modo de API compatível com OpenAI, Anthropic ou Codex, você poderá implementar uma subclasse de ProviderProfile que declare o caminho de autenticação, a URL base, o catálogo de modelos e os cabeçalhos de cache; o Hermes a resolve pelo mesmo caminho runtime_provider.py usado pelos provedores integrados. Essa é a mudança arquitetônica 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 expõe um endpoint local compatível com OpenAI, baseado no provedor OAuth no qual o Hermes já está conectado — Claude Pro, ChatGPT Pro, SuperGrok ou outro provedor compatível configurado.¹⁹ Isso significa que ferramentas que esperam uma API no estilo da OpenAI, incluindo Codex CLI, Aider, Cline, Continue ou scripts personalizados, podem reutilizar a autenticação do Hermes vinculada à sua assinatura sem precisar de uma chave de API separada. Trate o proxy como infraestrutura de desenvolvimento local: vincule-o de forma intencional, não o exponha amplamente e considere os termos específicos de cada provedor.

Detecção do tamanho do contexto

Segundo a documentação upstream, duas configurações são confundidas com frequência:²

• 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 compactar 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 tem relação com o 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 as janelas de contexto: substituição na configuração → configuração por modelo do provedor personalizado → cache persistente → endpoint /models → /v1/models da Anthropic → API do OpenRouter → Nous Portal → models.dev (registro mantido pela comunidade com mais de 3.800 modelos) → valores padrão de contingência (128K).² O sistema considera o provedor, portanto o mesmo modelo pode ter limites de contexto diferentes dependendo de quem o disponibiliza (por exemplo, claude-opus-4.6 oferece 1M diretamente pela Anthropic, mas 128K no GitHub Copilot).²

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

O Hermes não prende você a um único modelo de um único provedor. O roteamento inteligente de modelos é o conjunto de mecanismos que decide qual provedor e modelo realmente processará 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 os três em conjunto – eles fazem a diferença entre um agente que fica paralisado por um limite de uso e outro que continua trabalhando.

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

Modelo de fallback. Configure um provider:model de reserva para o qual o Hermes alternará automaticamente quando o modelo principal falhar (limites de uso, 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 a 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

Hermes usa modelos “auxiliares” para tarefas secundárias: análise de imagens (visão), classificação para aprovação de comandos perigosos, compactação de contexto, geração de títulos de sessões, inserção de tags de áudio TTS, correspondência de skills, despacho de ferramentas do MCP, a família de especificação/decomposição do Kanban e, desde a v0.21.6, interações por voz (auxiliary.voice_chat, que executa uma interação falada em um modelo mais rápido, com reasoning_effort: none por padrão, e mantém o modelo principal quando a solicitação não se encaixa no limite de compactação do modelo de voz).⁴³⁴⁵⁵ Por padrão (auxiliary.*.provider: "auto"), todas as tarefas auxiliares são executadas no seu modelo de chat principal – o mesmo provider/model escolhido em hermes model. A documentação deixa claro que isso substituiu a antiga detecção automática de providers baratos: “Versões anteriores direcionavam usuários de agregadores (OpenRouter, Nous Portal) para uma opção padrão barata no lado do provider. Isso era inesperado… agora, auto usa o modelo principal para todos, e as configurações específicas por tarefa em config.yaml continuam tendo prioridade.”³⁴ Você não precisa configurar nada para começar; a contrapartida é o custo – em modelos de raciocínio caros, as tarefas auxiliares geram gastos significativos, então direcione cada tarefa para modelos rápidos e baratos quando isso for importante.

Duas antigas tarefas auxiliares deixaram de usar um LLM: a extração da web (“web_extract e snapshots do navegador truncam conteúdos longos de forma determinística e armazenam o texto completo para paginação com read_file – sem envolver um LLM”) e a pesquisa 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 aparece nas configurações padrão dessa versão.³⁴

Você pode configurar qual modelo e provider cada tarefa auxiliar usa. 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 por 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 após a interação), 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 o YAML manualmente: execute hermes model e escolha “Configurar modelos auxiliares” para usar um seletor interativo por tarefa.³⁴

A opção de provider "main" significa “usar o mesmo provider do meu agente principal” – 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 model.provider do nível superior. Se você usa 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 seu modelo principal, a antiga armadilha de “configure o OpenRouter ou as tarefas auxiliares perderão qualidade silenciosamente” não existe mais – agora, a contrapartida é o custo. Se o seu modelo principal for um modelo de raciocínio caro, direcione 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 dessas camadas é um registro global de provedores que você não pode ver no config.yaml.

Estrutura dos arquivos de configuração

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

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

config.yaml vs .env — quando ambos estão definidos, o config.yaml prevalece para configurações que não sejam secretas.⁴ A regra é: - Segredos (chaves API, tokens de bot, 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 do 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, aquela com maior prioridade prevalece:⁴

1. Argumentos de CLI — hermes chat --model anthropic/claude-sonnet-4 (substituição válida apenas para essa execução)
2. Variáveis de ambiente — aplicadas na inicialização do processo
3. config.yaml — o arquivo principal de configurações
4. .env — somente 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 dashboard 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 mais 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 idioma original. O idioma é definido 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 ainda não coberto por uma tradução. A v0.21.6 torna os idiomas plugáveis: display.language aceita qualquer id fornecido pelos 17 catálogos incluídos, pelo diretório de sobreposição do profile ou por um pacote de idioma de plugin instalado, e hermes config set display.language <id> executa primeiro a descoberta de plugins para aceitar um pacote que você acabou de instalar; os textos do núcleo e da TUI ficam em camadas separadas (locales/<lang>.yaml e locales/<lang>.tui.yaml, com 16 pacotes de TUI na tag).⁵⁵

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 veja o estado do outro.⁶

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

Cada profile recebe seu próprio HERMES_HOME (~/.hermes-<name>/ por padrão), permitindo que vários profiles executem o gateway simultaneamente sem interferir uns nos outros.⁶³

A partir da v0.21.2, o limite de isolamento é aplicado com mais rigor: um conjunto de correções eliminou vazamentos reais entre profiles em configurações com gateway multiplexado, 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 arquivos .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 promessa de isolamento passa a ser efetivamente cumprida — 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, veja 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 leva você ao 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 vai diretamente para uma seção:⁶

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

hermes logs — Consulta estruturada de logs

hermes logs é mais poderoso que tail -f nos arquivos de log porque 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 — toda a atividade do agente (chamadas do API, despacho de ferramentas, ciclo de vida das sessões, INFO+) - errors.log — somente avisos e erros (um subconjunto filtrado de agent.log) - gateway.log — atividade do gateway de mensagens (conexões com plataformas, despacho, webhooks)

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

hermes doctor — Diagnóstico

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

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

Comandos de barra

Os comandos de barra são executados dentro de uma sessão de chat ativa (CLI ou plataforma de mensagens). Eles são encaminhados por meio 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 é a principal ferramenta 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 de modelo válida por um único turno que retorna automaticamente ao modelo anterior depois da resposta.⁶⁰ Desde a série de versões v0.20.5, o seletor de /model também oferece busca aproximada: ele filtra os resultados enquanto você digita.²³³⁵

Ferramentas, skills e informações

Comandos de barra dinâmicos para skills

Cada skill instalada é exposta automaticamente como um comando de barra:⁹

/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 chamadas de skills por comandos de barra podem ser empilhadas: /skill-a /skill-b do XYZ carrega as duas skills em ordem no mesmo turno, com preenchimento automático e texto fantasma para os nomes encadeados.⁶⁰

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

Comandos específicos para plataformas de mensagens

Alguns comandos funcionam somente 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) — marca 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> transmite o motivo da sua recusa ao agente para que ele ajuste a abordagem em vez de tentar novamente sem entender o problema⁶⁰
• /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.⁹

Ferramentas e toolsets

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

Categorias de alto nível

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

Gerenciamento de ferramentas

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

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

Backends de terminal

A ferramenta de terminal inclui sete 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 os 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+). Fornecedores externos de sandboxes não precisam mais fazer parte do repositório principal: um plugin registra um TerminalEnvironmentProvider no momento do 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 dos backends integrados são reservados — o registro rejeita provedores cujo nome entre em conflito com um backend presente no 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/cwd em 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 fixa de nomes.³²

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

terminal:
  backend: ssh

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

Backend Docker:

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

Recursos do contêiner (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 persistem 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 capacidades 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 ferramenta de terminal oferece suporte à execução em segundo plano com gerenciamento explícito de processos:¹⁰

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

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

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

Sudo

Se um comando precisar de sudo, o Hermes solicitará sua senha (que ficará em cache durante a sessão). Você também pode 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 durável que acompanha tarefas, status e identidade dos workers entre agentes e reinicializações.¹⁸ É o quadro que faz com que um swarm de workers do Hermes realmente conclua o trabalho em vez de travar em transferências interrompidas.

O quadro Kanban combina naturalmente com /goal (loop Ralph com objetivo bloqueado) no lado do objetivo e com a ferramenta delegate_task existente para a semântica de spawn. O resultado é um padrão de swarm no qual todos os agentes compartilham uma única fonte confiável sobre o que fazer em seguida, quem está fazendo e o que está travado.

O que é um swarm do Hermes?

Um swarm é formado por vários workers do Hermes executados em paralelo sobre um único quadro Kanban compartilhado. Não é um subsistema separado que você precisa ativar — é o que o quadro torna possível. O quadro oferece algo que os agentes paralelos não conseguem fornecer sozinhos: uma resposta única e confiável para qual tarefa devo assumir agora e alguém já está trabalhando nela?

A v0.15.0 elevou esse padrão a uma topologia oficialmente compatível, 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, as substituições de modelo por tarefa, as tarefas agendadas e o gerenciamento de worktrees, para que workers paralelos não entrem em conflito no mesmo checkout.⁶³

Na prática, funciona assim: dê 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 os resultados. O limite de tentativas é definido por tarefa (max_retries), portanto, uma única subtarefa frágil não consome toda a tolerância da execução. Como o quadro é durável, um swarm sobrevive a reinicializações — os workers se reconectam e retomam o trabalho a partir do mesmo estado.

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

Sistema de skills

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

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

Divulgação progressiva

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

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

Formato do SKILL.md

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

# Skill Title

## When to Use
Trigger conditions for this skill.

## Procedure
1. Step one
2. Step two

## Pitfalls
- Known failure modes and fixes

## Verification
How to confirm it worked.

Ativação condicional

Os skills podem ser exibidos ou ocultados dependendo das 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: o skill integrado duckduckgo-search usa fallback_for_toolsets: [web]. Quando você define FIRECRAWL_API_KEY, o toolset web fica disponível e o agente usa web_search — o skill do DuckDuckGo permanece oculto. Sem a chave API, o skill do DuckDuckGo aparece automaticamente como fallback.¹¹

Skills gerenciados pelo agente

O agente pode criar, atualizar e excluir seus próprios skills por meio da ferramenta skill_manage. Essa é a memória procedural do agente — quando ele descobre um fluxo de trabalho não trivial, salva a abordagem como um 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:¹¹

Hub de skills

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

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

Fontes integradas ao hub:¹¹

Taps padrão do GitHub (podem ser explorados 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

Todos os skills instalados pelo hub passam por um scanner de segurança que verifica exfiltração de dados, injeção de prompt, comandos destrutivos, sinais de comprometimento da 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 diretórios adicionais 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 aceitam a expansão de ~ e a substituição de variáveis de ambiente ${VAR}. Diretórios externos são somente leitura — quando o agente cria ou edita um skill, ele sempre grava em ~/.hermes/skills/. O diretório local tem precedência quando existe um skill com o mesmo nome nos dois lugares.¹¹

Skills fixados: skills.auto_load (janela da v0.21.4)

Os nomes de skills listados em skills.auto_load no config.yaml são fixados e carregados por completo 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 desativado gera um aviso e é ignorado, sem causar falha na sessão, e HERMES_IGNORE_RULES (o mecanismo por trás de --ignore-rules) suprime a lista como ocorre com o restante do contexto injetado automaticamente. Esse é o complemento de instruções permanentes para -s/--skills, que pré-carrega skills apenas para uma sessão.⁵¹

Memória persistente

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

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

Padrão de snapshot imutável: 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 persistidas imediatamente no disco, mas só aparecem no prompt do sistema na sessão seguinte.¹²

O que salvar

Salve estas informações (o agente faz isso de forma proativa):¹² - 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 nos comandos do Docker, o usuário está no grupo docker” → memory - Convenções: “O projeto usa tabulações, linhas com até 120 caracteres e docstrings no estilo Google” → memory - Trabalho concluído: “O banco de dados foi migrado do MySQL para o PostgreSQL em 15 de janeiro de 2026” → memory

Não salve estas informações:¹² - Informações triviais ou óbvias - Fatos que podem ser redescobertos facilmente - Despejos de dados brutos (grandes demais para a memória) - Informações temporárias 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 agente 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 diretamente o conteúdo do banco de dados”), o que a tornou 4.500 vezes mais rápida e eliminou seu custo de API.¹²⁶³³⁴

Duas adições do período 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 definido 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 mencionem um intervalo de tempo; sort continua sendo uma tendência de ranqueamento, 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 dessas palavras. Portanto, quando a consulta exata e todas as alternativas por substring não retornam resultados, a busca consulta novamente o índice procurando QUALQUER termo, com a ordem de classificação priorizando 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, com um único termo ou encaminhadas para CJK permanecem inalteradas.⁵¹

Provedores externos de memória

Para uma memória persistente mais profunda, além de MEMORY.md e USER.md, o Hermes inclui dois plugins externos de memória na v0.21.7: RetainDB e ByteRover. Outros seis são instalados pelo catálogo de plugins: Holographic, que deixou a árvore principal na v0.21.7; Honcho, OpenViking, Mem0 e Supermemory, que saíram na v0.21.6; e Hindsight, que saiu na v0.21.5. Os seis são entradas da categoria comunitária mantidas por seus respectivos fornecedores.¹²⁵⁵⁵⁷

O 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; Honcho, Mem0, OpenViking e Supermemory seguiram o mesmo caminho na v0.21.6, e Holographic na v0.21.7. As configurações existentes migram sozinhas: se memory.provider especificar um deles, hermes update instalará o plugin do catálogo em cada diretório inicial de profile que o especificar, e a primeira inicialização do agente fará a instalação caso ele ainda esteja ausente. Com security.allow_lazy_installs: false, a inicialização do agente apenas registra uma mensagem, então execute hermes plugins install <name> por conta própria. O plugin é instalado em ~/.hermes/plugins/<name>/ 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 do pip hermes-agent[hindsight] 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)

Somente 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 sobreviver a interrupções durante a execução do agente. O gateway retoma automaticamente as sessões interrompidas após uma reinicialização; as reinicializações com /update preservam o estado da sessão durante a atualização; recarregamentos 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 redefinem mais sua janela de contexto quando o processo é reiniciado.

Checkpoints v2 (v0.13.0+)

A persistência de estado foi reescrita na v0.13.0 como uma arquitetura de armazenamento único, com limpeza real, proteções de disco e nenhum repositório-sombra órfão.¹⁸ O sistema anterior de checkpoint acumulava estado no disco em profiles executados por longos períodos; o armazenamento v2 impõe um limite rígido ao armazenamento local de checkpoints e elimina a duplicação de registros responsável por 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 o espaço nº 1 no prompt do sistema, substituindo a identidade padrão definida diretamente no código.¹³

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

O que incluir no SOUL.md

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

Use-o com menos frequência para:¹³ - instruções específicas de um único projeto - caminhos de arquivos - convenções do repositório - detalhes temporários do fluxo de trabalho

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

SOUL.md versus AGENTS.md

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

SOUL.md — identidade, tom, estilo, padrões de comunicação e comportamento ligado à 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 observações sobre implantação.

Uma regra útil: se algo deve acompanhar você em todos os lugares, deve estar no SOUL.md. Se pertence a um projeto, deve estar no AGENTS.md.¹³

Personalidades integradas

O Hermes inclui personalidades integradas que você pode ativar com /personality:¹³³³

Personalidades personalizadas no config.yaml:¹³

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

Depois, alterne com /personality codereviewer.

SOUL.md versus /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 em uma conversa de tutoria ou /personality creative em um brainstorming.

Nous Tool Gateway (v0.10.0+)

Desde o Hermes Agent v0.10.0 (2026-04-16), assinantes pagos do Nous Portal têm acesso gerenciado a um conjunto selecionado de ferramentas usando as credenciais que já possuem no Portal — sem chaves API adicionais para gerenciar.⁶⁵ O CLI do Hermes continua licenciado sob a licença MIT e totalmente open source. A mudança é que agora sua autenticação do Portal oferece acesso a mais do que apenas inferência de modelos.

O caminho mais rápido é hermes setup --portal, apresentado no README como “Um comando a partir de uma instalação nova”: ele faz seu login via OAuth, define o 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 pelo Nous. hermes portal status continua disponível como um alias oculto para compatibilidade retroativa de info, e a referência do CLI na documentação dessa tag ainda apresenta o subcomando como status, portanto ambos funcionam.²⁸

O que está incluído no gateway

Como funciona

O gateway é ativado separadamente 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 dessa ferramenta 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 é importante para a cobrança — as chamadas do 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 OAuth do Portal que você já tem em hermes auth — não há uma etapa de login separada. 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 disponível, 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édito. O aplicativo para desktop tem uma aba correspondente nas 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 do 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 fornecer um agente funcional: inferência e conectores gratuitos já vêm prontos para uso, com um único comando para fazer login, e /login inicia o processo dentro de um chat. As ferramentas dos conectores (Gmail, Linear, Notion e os 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; apenas 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 tomada na inicialização é registrada no ambiente do backend iniciado para impedir que um valor herdado seja aplicado indevidamente.⁴⁸

Desde o período de lançamento da v0.21.4, conectar esses conectores passou a ser uma única operação controlada pelo backend, em vez de uma lógica distribuída entre os frontends: uma chamada à ferramenta manage_connections aciona no backend uma máquina de estados de conexão baseada apenas em dados (com um prazo fixo de 300 segundos para a operação – deliberadamente, não é uma chave de configuração), e Desktop, TUI e CLI exibem o mesmo cartão de configuração. O cartão apresenta um campo para cada credencial ausente (nome, instrução, obrigatoriedade) e mantém sua ação desativada até que todos os campos obrigatórios contenham texto; o backend impõe em todos os frontends a mesma separação exclusiva para segredos.⁵¹

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 condicionadas ao 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 licenciado 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 a ninguém. A v0.10.0 adiciona uma opção conveniente para usuários que já assinam o Nous Portal — ela não remove nada do caminho gratuito.

Gateway de mensagens

O Hermes pode ser executado como um processo de gateway de longa duração que se conecta a 28 plataformas de mensagens a partir de um único processo de gateway: Telegram, Discord, Slack, WhatsApp, Signal, SMS, Email, Home Assistant, Mattermost, Matrix, DingTalk, Feishu/Lark, WeCom, Weixin (WeChat), BlueBubbles (iMessage), QQBot, Microsoft Teams, Tencent Yuanbao, Google Chat, LINE, SimpleX Chat, Photon (iMessage), WhatsApp Cloud API, WeCom Callback, Raft, IRC, ntfy, Buzz e um adaptador genérico de Webhook.^364171819 Esse total de 28 vem da tabela Platform Comparison da documentação na tag v2026.8.31; por baixo disso, 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 qualquer outro nome sob demanda para um dos 22 diretórios de adaptadores incluídos em plugins/platforms/, portanto uma simples contagem do enum ou dos diretórios não corresponderá ao número da documentação.²⁵ A v0.9.0 adicionou 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 conclui a stack do Microsoft Teams de ponta a ponta, com autenticação 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 Mac ou relay do BlueBubbles), o adaptador oficial do WhatsApp Business Cloud API (substituindo a exigência de um processo de bridge), grupos do SimpleX e anexos nativos, além do Raft como plugin de plataforma incluído.²¹ Outras duas aparecem na tabela da documentação sem destaque nas notas de versão: ntfy é um canal leve de push por pub-sub 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 uma instância auto-hospedada, sem necessidade de SDK nem daemon), enquanto o Buzz conecta o Hermes a uma comunidade Buzz, a plataforma open source de colaboração entre pessoas e agentes da Block baseada no protocolo Nostr, invocando o CLI buzz para mensagens de saída e usando uma assinatura nativa WebSocket do Nostr para mensagens de entrada. Ambas são configuradas 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 de API, IDs de bots, mapeamentos de canais e listas de permissões.⁶ Desde a v0.21.6, a etapa do Discord verifica o token do bot, exibe um link de convite com os bits de permissão necessários para o adaptador e alerta sobre a opção Message Content Intent caso ela ainda esteja desativada, o que faz o Discord recusar a conexão do bot.⁵⁴⁵⁵

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 pelo CLI. É por isso que os comandos slash funcionam de forma idêntica nos dois lugares e que uma tarefa cron agendada 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 baseado em profiles e entrega durável. Um único gateway multiplexado que compartilha 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 único profile configurado incorretamente derrube todo o gateway. Internamente, o índice de roteamento foi movido para state.db (sessions.json agora é um espelho legado opcional), e as respostas finais são registradas em um ledger durável de obrigações de entrega em torno do envio pela plataforma — se uma resposta concluída for atingida por 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 corrigiu 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 MCP via stdio, anexos MEDIA: entre profiles e o bearer do Nous de um profile irmão permanecendo em memos por processo (#107609-#107630).⁴⁸

A v0.21.1 torna os limites das conversas exclusivamente explícitos. A documentação do ciclo de vida das sessões na tag v2026.9.7 define o contrato em quatro frases: “A inatividade e o tempo de relógio nunca alternam uma conversa. /new e /reset criam um limite explícito; a compressão de contexto continua gerenciando históricos longos. A configuração legada de temporizadores é ignorada. O tipo de dados existente SessionResetPolicy contém dados inertes 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 limites finalizados em vez de reabri-los e a remoção motivada apenas por recursos mantém as conversas retomáveis. Se uma sessão no seu gateway parecer “nunca expirar”, agora esse é o comportamento esperado; alterne-a você mesmo com /new.⁴³

Desde o período da v0.21.4, um segundo hermes gateway run se conecta ou recusa a execução em vez de fazer bind duplicado. A regra é um hermes serve e um hermes gateway run por host e usuário do sistema operacional, cada um multiplexando todos os profiles. Iniciar um gateway para um profile que o multiplexador em execução já atende apenas se conecta e encerra com código 0; se ele ainda não atender esse profile, o Hermes solicita uma nova varredura de profiles/ e se conecta assim que o profile for encontrado; se não for possível fazê-lo atender o profile, o comando recusa a execução em vez de iniciar silenciosamente um segundo gateway. Agora, --replace tem como alvo esse processo no host, independentemente do profile que o iniciou, e --force ignora totalmente a pergunta quando o proprietário está travado. Gateways independentes ainda coexistem: se o gateway em execução for o gateway independente (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 perder o bloqueio do host será encerrado com o código 75, que todos os supervisores gerados pelo Hermes tentam novamente; nesse momento, o registro do vencedor já existe, então a nova tentativa se conecta ou recusa a execução conforme as regras acima. Os bloqueios 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 esteja inativo ou tenha sido reutilizado por outro processo é considerado obsoleto e ignorado, portanto uma falha do gateway não bloqueia a próxima inicialização. O aplicativo Desktop segue a mesma regra, conectando-se ao backend em execução no host em vez de iniciar um segundo.⁵¹

Desde a v0.21.5, a multiplexação não é mais opcional. gateway.multiplex_profiles tem um único valor válido, true: uma chave ausente é resolvida como ativada e gravada no config.yaml do profile padrão, enquanto um false explícito é reescrito no próprio arquivo como true, acompanhado de um aviso em destaque exibido uma vez nessa inicialização do gateway e novamente no resumo da próxima execução de hermes update. Dois controles substituem a antiga opção de desativação. Para colocar um profile offline sem interromper os bots de todos os outros, execute hermes -p <name> gateway stop: o host o estaciona (com um marcador profiles/<name>/gateway.parked), e 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 define gateway.standalone: true no seu próprio config.yaml; o host nunca o atende, e seus comandos stop/start operam no processo 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 fora do diretório profiles/ da home 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í, esse usuário fica autorizado.⁶

unauthorized_dm_behavior determina o que a mensagem direta de um desconhecido recebe antes do pareamento: pair envia um código de pareamento por mensagem direta, ignore descarta a mensagem silenciosamente e decline, valor adicionado no período da v0.21.4, envia uma única recusa educada e depois permanece em silêncio para esse remetente por 24 horas (#88028). A recusa é deduplicada por plataforma e remetente, inclusive entre aliases, e seu texto vem de unauthorized_dm_decline_message (uma chave global; vazio significa usar 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, onde 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 nada está definido, o padrão efetivo depende das suas listas de permissões. Sem nenhuma configurada, ele é pair; assim que qualquer lista de permissões for definida (GATEWAY_ALLOWED_USERS ou uma variável de usuários permitidos, usuários permitidos em grupos ou chats de grupo permitidos de uma plataforma), ele passa a ser ignore, porque a lista de permissões indica um gateway deliberadamente restrito, e enviar códigos para contatos desconhecidos gera ruído e pode vazar informações (#9337). Um valor global ignore ou decline substitui essa regra, mas um pair global não pode fazer isso, pois é interpretado da mesma forma que o padrão; para manter o pareamento junto com uma lista de permissões, defina pair por plataforma. (A configuração dm_policy própria de um adaptador de plataforma, quando definida, é consultada antes da regra da lista de permissões.) Como o Email funciona como uma caixa de entrada, seu padrão é ignore, a menos que uma chave própria da plataforma o habilite; um valor global não se aplica a ele. hermes gateway setup oferece a opção de recusa como uma das respostas ao configurar uma plataforma sem uma lista de permissões.⁵¹

Tarefas agendadas (Cron)

O Hermes tem um sistema de cron nativo no qual os jobs são tarefas do agente, não comandos shell. Cada job agendado é executado por um novo AIAgent com o prompt configurado, 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 de forma conversacional em 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 ficam armazenados em JSON e persistem após reinicializações.³

A v0.21.0 deu memória e capacidade de julgamento aos jobs agendados. São 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. Assim, um agente de reconhecimento ou monitoramento “acorda vendo o que relatou na última vez e pode eliminar duplicidades e continuar de onde parou” — a orientação injetada é “evitar repetir o que já foi relatado”, a primeira execução não muda e, internamente, a flag é armazenada como a entrada reservada self em context_from. Ative ou desative esse recurso 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 KV para anotações temporárias, como 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 byte por byte) impede completamente a execução do agente — sem chamada a LLM, sem entrega, apenas uma execução silenciosa no_change — enquanto uma alteração injeta um bloco de diff e executa o agente normalmente. Gere uma saída estável nos scripts de monitoramento, senão cada ciclo parecerá uma alteração.³⁷
• Nível de raciocínio por job e entrega no Bot Chat. --reasoning-effort fixa o nível de raciocínio de um job (none a ultra), substituindo as configurações globais e específicas do 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 exige uma 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 em 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 nomes 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 do servidor MCP são exibidas em agent.log.⁶⁰

A v0.21.1 adiciona um fluxo com 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 com código de dispositivo conforme a RFC 8628 para máquinas remotas ou sem interface gráfica — e a flag substitui a configuração oauth.flow do servidor. Essa mesma versão aplica a propriedade do profile durante toda a sessão de OAuth, ignora caches de metadados de OAuth inválidos em vez de travar um servidor e encaminha o OAuth do MCP no desktop por callbacks locais do cliente; -t/--toolsets agora também filtra quais servidores MCP configurados serão iniciados, portanto uma execução com escopo definido não perde tempo inicializando servidores desnecessários.⁴⁴

A v0.21.0 transforma a interface de MCP do desktop em uma central de comando: os servidores e o 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 avisam sobre autenticações prestes a expirar antes que uma chamada de ferramenta falhe, uma sobreposição de custos e uso da frota mostrando estimativas de tokens do schema 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 pode conectar 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 gera um aviso no log e faz o sistema voltar 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 comprime automaticamente conversas longas para mantê-las dentro da janela de contexto do seu modelo. O sumarizador de compressão faz uma chamada separada a LLM — você pode direcioná-lo a qualquer provedor ou endpoint.⁴ Desde a v0.20.6, a política de preservaçã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 do 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, 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 ao sumarizador auxiliar por tentativa), um índice de âncoras extraído mecanicamente (números de PR, SHAs, caminhos e mensagens 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. Resultado medido pela documentação em sessões reais com 500 mil tokens: cerca de 49 mil tokens preservados, em vez de aproximadamente 162 mil. Resultados antigos de ferramentas dentro do trecho final lean são reduzidos a linhas únicas 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 modelo principal, pois recebe toda a parte intermediária da conversa em uma única chamada — se a janela for menor, a chamada falhará e os turnos intermediários serão descartados sem um resumo.⁴³¹

Avisos de pressão sobre o orçamento

Quando o agente trabalha em uma tarefa complexa com muitas chamadas de ferramentas, ele pode consumir 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 avisa automaticamente o modelo:⁴

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 é aumentado para 30 minutos em endpoints locais porque LLMs locais podem levar vários minutos para realizar o prefill de contextos grandes antes de produzir o primeiro token.⁴

Dashboard web local (v0.9.0+)

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

Monitoramento de processos em segundo plano (v0.9.0+)

watch_patterns permite definir padrões para monitorar a saída de processos em segundo plano e receber notificações em tempo real quando houver correspondência.¹⁶ Monitore erros, aguarde eventos específicos (“listening on port”) ou acompanhe logs de build — tudo sem polling. Combinado com notify_on_complete da v0.8.0 (que envia uma notificação quando uma tarefa em segundo plano é concluída), o Hermes agora tem uma camada completa de observabilidade para processos em segundo plano.¹⁵

Context engine conectável (v0.9.0+)

O gerenciamento de contexto agora é um slot conectável por meio de hermes plugins. Você pode usar context engines personalizados que controlam o que o agente vê a cada turno — com filtragem, resumo ou injeção de contexto específico do domínio.¹⁶ Isso desacopla 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 confiável com colegas de equipe.

Compatibilidade com Termux e 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, compatibilidade com 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 um padrão em benefício do usuário.¹⁸ Em seguida, a v0.14.0 corrigiu outros 12 problemas P0 e 50 P1, incluindo proteção contra ataques de força bruta ao sudo e uso do sudo via stdin, correções para formas de contornar o bloqueio de comandos perigosos, sanitização de erros de ferramentas antes de reinjetá-los no modelo, autenticação de API de plugins do dashboard, cobertura contra SSRF no skills-hub e verificação de alertas da cadeia de suprimentos durante a instalação.¹⁹

Se você mantém uma implantação do Hermes, considere as versões v0.13.0 e v0.14.0 atualizações relevantes para a segurança, não apenas lançamentos de novos recursos. A v0.13.0 corrige a forma de contornar as restrições entre servidores do Discord e duas janelas de TOCTOU; a v0.14.0 adiciona outra rodada de reforços ao tratamento do sudo, à reinjeção de erros de ferramentas, aos APIs de plugins, à proteção contra SSRF no skills-hub e aos alertas sobre 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. Assim, um agente que sofreu injeção de prompt não pode reescrever silenciosamente suas próprias instruções permanentes. Essa proteção vem ativada por padrão (security.protected_instruction_files: true, com uma lista de extensões de nomes-base no formato fnmatch em protected_instruction_extra_patterns), e o código-fonte identifica exatamente o vetor 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 e, portanto, “qualquer AGENTS.md em um local do qual o agente possa ser executado posteriormente é um alvo ativo”.³⁵³⁹ A mesma versão corrige brechas de vazamento de segredos em erros do terminal, leituras de arquivos .env, checkpoints e logs de ACP; ensina ao sistema de aprovação os comandos e caminhos destrutivos do Windows; faz com que as permissões do 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 Blender no catálogo de MCP e a respectiva skill após o comprometimento de um componente upstream; e adiciona verificação de segurança Tier-1 às instalações de plugins.³⁵³⁹

A v0.21.6 adiciona uma quinta rodada. Quatro correções de autenticação do dashboard relatadas pela Tenable Research (falsificação de X-Forwarded-For para contornar o limite de tentativas de login, gravações ilimitadas na auditoria de autenticação geradas por solicitações não autenticadas, ausência de limite para o tamanho do corpo nas rotas públicas /auth/ e envio de códigos de login para um redirecionamento fora do loopback, o que permitia o sequestro da sessão), chamadas automáticas do git que não executam mais os programas de filtro clean, smudge ou process definidos por um repositório não confiável antes do primeiro prompt e um cabeçalho de e-mail From analisado com parseaddr para impedir que um nome de exibição entre aspas passe pela lista de permissões. Veja os detalhes em Novidades da v0.21.6.⁵⁴⁵⁵

Arquitetura para profissionais

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

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 do projeto original.³

“47 tools / 20 toolsets” em comparação com “28 tools” no seu banner. A contagem de “47 tools” representa o registro total de tools do repositório original — todas as tools cujo código-fonte acompanha o Hermes, em todos os toolsets. A CLI que você estiver executando mostrará 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 pesadas de scraping etc. O total do registro indica “o que está disponível”; o número do banner indica “o que está habilitado no seu profile atual”. Confira quais toolsets estão ativos com hermes tools --list e habilite ou desabilite toolsets individualmente 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 durante a 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 de 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 do projeto original.³

Ordem de montagem do prompt

A pilha do prompt inclui:¹³

1. SOUL.md (identidade do agente — ou alternativa integrada, caso não esteja disponível)
2. Orientações de comportamento específicas para as 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 de 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 compactaçõ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 resolveu a classe de fragilidades do state.db da época da v0.21.0 (segundos processos de gravação cancelando os bloqueios uns dos outros, bancos de dados íntegros relatados como corrompidos e uma única linha inválida fazendo sessions list falhar) e transferiu a coordenação de salas hospedadas do armazenamento raiz para um shared-state.db dedicado, para que os gateways dos profiles nunca abram o armazenamento mestre de sessões com permissão de escrita. Agora, hermes doctor identifica separadamente danos estruturais e danos ao índice FTS; danos ao FTS degradam a pesquisa em vez de interromper a interação; e hermes sessions recover --inspect-only (offline, não destrutivo e vinculado 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 de journal incorreto do SQLite, o ciclo 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 de 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.6, plugins.isolation: host (o padrão é in_process) mantém o código de plugins Python de terceiros fora do processo do Hermes: plugins gerais são carregados em um processo host de plugins por profile e se comunicam com o Hermes somente por meio de ctx; todos os demais caminhos que importariam código do usuário dentro do processo (provedores de categorias, profiles de provedores de modelos e APIs de plugins do dashboard) recusam a operação com uma justificativa explícita; e os plugins incluídos continuam sendo executados dentro do processo. Assim, se um plugin travar ou falhar, ele derrubará seu host, não o gateway.⁵⁵ Desde a v0.21.2, também existe um catálogo selecionado de plugins, com hashes SHA fixados, que você pode consultar 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; a instalação do pack se desdobra em instalações fixadas comuns; e o consentimento de capacidades continua sendo concedido individualmente para cada plugin.⁴⁸

O ciclo 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 cresceu de 9 entradas em v2026.9.14 para 228 em v2026.9.21 — uma YAML revisada por plugin (nome, repositório, mantenedor, nível, categoria e capacidades), fixada em um SHA de commit exato de 40 caracteres, sendo que a presença no diretório constitui admissão — e foi 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>) com base nesses 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 no momento da compilação que remove HTML brutos, com ordenação por adição/atualização baseada nas datas dos commits. Os dez plugins da comunidade citados na versão v0.21.4 são todos entradas do catálogo nessa tag, com seus slugs reais no catálogo: 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 aplicativo para desktop, a central de Plugins agora pode desinstalar um plugin mediante uma caixa de diálogo de confirmação — plugins do catálogo por meio de plugins.manage remove e plugins independentes para 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+)

Janela de compatibilidade (v0.21.1), agora expirada: 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 costumavam importar, 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 previsto 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 é desabilitado — não carregado —, com um aviso vermelho no banner da CLI, em hermes doctor e hermes update, uma caixa de diálogo exibida uma única vez no desktop e o motivo informado em hermes plugins list. Para autores: hermes plugins compat <path> ainda mostra cada file:line com caminho antigo -> caminho novo e encerra com 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, v2026.9.21, v2026.9.24 e em main até 24 de setembro (o ciclo da v0.21.4 alterou o módulo de compatibilidade apenas para armazenar verificações de plugins em cache e normalizar caminhos do Windows; o ciclo da v0.21.5 não alterou hermes_cli/plugin_compat.py e removeu somente as entradas do manifesto referentes ao módulo Hindsight excluído). Essa saída de emergência deixa de funcionar assim que a reversão for incorporada, porque os próprios caminhos antigos desaparecem. Somente nomes públicos de nível superior estavam cobertos; nomes privados e pontos de substituição temporária usados em testes nunca fizeram parte da interface e não são restaurados.⁴²⁵³ Na v0.21.6, essa saída de emergência foi fechada: o manifesto, os shims, o verificador hermes plugins compat e plugins.allow_deprecated_imports foram removidos, e hermes_cli/plugin_compat.py agora é um stub inerte, mantido para atualizadores que ainda são executados em checkouts mais antigos; um plugin que ainda importe um caminho anterior à decomposição não conseguirá ser importado.⁵⁵

Princípios de design

Da página de arquitetura do projeto original:³

Migração do OpenClaw

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

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

hermes claw migrate lê de ~/.openclaw por padrão (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), padrões do agente (nível 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ções 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 de log, 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 na seguinte ordem de prioridade: valores da 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 encontrado em toda instalação nova: o Hermes ainda não identificou um provedor. A mensagem significa exatamente o que diz — nenhum dos três métodos de autenticação resultou em um provedor utilizável. Execute:

hermes model

O seletor interativo apresenta 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 detectar. 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 perfil do shell), uma credencial OAuth expirada em ~/.hermes/auth.json ou um endpoint personalizado no config.yaml que perdeu seu base_url. Os métodos de autenticação são abordados em detalhes em Autenticação e provedores.²⁷

“Chave API não definida”

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

“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 as chamadas de ferramentas ativadas ou o modelo não oferece suporte a elas por meio da implementação do servidor.²

As respostas são interrompidas no meio da 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 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 escutar em 0.0.0.0, não em 127.0.0.1 — defina OLLAMA_HOST=0.0.0.0 para o Ollama, adicione --host 0.0.0.0 para llama-server/SGLang ou ative “Serve on Network” no LM Studio.²

O limite de iterações ignora agent.max_turns

Se a linha de atividade exibir N/90 (ou outro limite desatualizado), enquanto o config.yaml especificar agent.max_turns: 500, a causa provável será uma linha HERMES_MAX_ITERATIONS obsoleta em ~/.hermes/.env: anteriormente, o assistente de configuração gravava o limite nos dois locais e, se a ponte de inicialização fosse interrompida devido a um erro anterior de análise da configuração, o valor fantasma do .env prevalecia silenciosamente. Desde a v0.21.1, hermes doctor detecta esse par conflitante, e hermes doctor --fix exclui a linha do .env, deixando o config.yaml como fonte autoritativa.⁴¹

Onde fica cada coisa?

hermes status e hermes dump são úteis 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 o Hermes Agent e o Claude Code?

O Claude Code é o CLI oficial da Anthropic, limitado aos modelos da Anthropic. O Hermes Agent é um framework de agente de código aberto da Nous Research que funciona com qualquer provedor compatível com a OpenAI — Nous Portal, OpenRouter, Anthropic, GitHub Copilot, z.ai, Kimi, MiniMax, DeepSeek, Hugging Face, Google ou seu próprio endpoint auto-hospedado.¹² O Hermes também inclui um gateway de mensagens para Telegram/Discord/Slack/WhatsApp/Signal, recurso que o Claude Code não oferece.

Posso usar o 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 — o 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 mais indicada se você já usa o 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 como antes. 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 pelo seu modelo de chat principal. Assim, uma configuração exclusiva da 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) não existe mais: “auto agora usa o modelo principal para todos, e as substituições específicas por tarefa em config.yaml continuam tendo precedência”.³⁴

Se uma tarefa auxiliar ainda falhar, procure uma substituição explícita por tarefa que aponte para um provedor que você nunca configurou (auxiliary.<task>.provider / .model em config.yaml) ou chaves legadas desatualizadas: 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 não é mais uma tarefa de LLM (“nenhum LLM envolvido”), portanto uma falha na sumarização da web não é um problema do modelo auxiliar nas versões atuais.³⁴ 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 define 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 projeto.¹³ Se 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ções, memória, sessões e PID do gateway:⁶

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

O Hermes oferece suporte a LLMs locais?

Sim, por meio do caminho de endpoint personalizado. O Hermes funciona com qualquer servidor compatível com a OpenAI: Ollama, vLLM, SGLang, llama.cpp/llama-server, LM Studio, LocalAI, Jan ou um servidor próprio.² Consulte Endpoints personalizados e auto-hospedados para ver a configuração específica de cada servidor.

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

O guia menciona 47 tools/20 toolsets do registro de arquitetura do projeto upstream — esse é o número total de tools cujo código-fonte acompanha o Hermes em todos os toolsets. Sua instalação em execução mostra um número menor no banner (a instalação de referência usada neste guia informa 28 tools) porque o Hermes habilita apenas o conjunto padrão de toolsets na inicialização. Muitos toolsets precisam ser habilitados explicitamente: adaptadores do gateway de mensagens, automação de navegador, stacks de scraping mais pesados e várias integrações especializadas precisam ser listados 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 tools com a nova estrutura).

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

Configure um bloco fallback_model em config.yaml:²

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