Hermes Agent: o guia de referência do profissional (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 uma identidade durável e memória persistente no disco, reúne skills que melhoram com o uso e funciona com qualquer provedor LLM compatível com OpenAI — Nous Portal, OpenRouter, Anthropic, Copilot da GitHub, z.ai, Kimi, MiniMax, DeepSeek, Qwen Cloud, Hugging Face, Google, xAI/SuperGrok ou seu próprio endpoint self-hosted.¹²¹⁹ A partir da v0.14.0 (16 de maio de 2026), Hermes adiciona OAuth SuperGrok com contexto de 1M no grok-4.3, um proxy local compatível com OpenAI para provedores OAuth (hermes proxy), x_search nativo, suporte à instalação via PyPI (descontinuada na v0.19.0 — o instalador de uma linha é o caminho suportado), instalações de dependências sob demanda, 28 plataformas de mensagens com LINE e SimpleX Chat, /handoff, diagnósticos semânticos de LSP após escritas, video_generate unificado, computer_use via cua-driver para provedores que não são Anthropic, beta nativo para Windows e 12 fechamentos P0 / 50 P1.¹⁹ A parte mais difícil para a maioria dos novos usuários é a autenticação de provedores: Hermes oferece suporte a cerca de 20 provedores de primeira classe, além de endpoints personalizados, e a três caminhos distintos de autenticação (chave API em .env, OAuth via hermes model ou endpoint personalizado em config.yaml). O modelo de autenticação é a primeira coisa a aprender — todo o resto depende de qual provedor foi resolvido.

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

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

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

Principais conclusões

• A autenticação de provedores tem três caminhos, não um. Chave API em .env, OAuth via hermes model/hermes auth ou endpoint personalizado em config.yaml. Escolha o caminho compatível com seu provedor, não o que parece familiar.
• Trocar de provedor exige um único comando. hermes model guia você interativamente por todos os provedores compatíveis, incluindo logins OAuth, e /model provider:model troca no meio da sessão sem perder o histórico.²
• Dois arquivos 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 por Hermes — você pode editar SOUL.md manualmente, mas o restante é manipulado pelo próprio agente.⁴
• Hermes é o sucessor do OpenClaw. Se você estiver migrando, hermes claw migrate importa automaticamente mais de 30 categorias de estado.⁵
• A qualidade do serviço depende do seu modelo auxiliar. Visão, resumo da web, compressão e descarregamento de memória usam um LLM auxiliar separado. Por padrão, é o Gemini Flash por meio de detecção automática (OpenRouter → Nous → Codex) — se nenhum deles estiver configurado, esses recursos se degradam silenciosamente até que você aponte os slots auxiliares para seu provedor principal.⁴

O que muda na v0.14

A v0.14.0 é menos sobre um recurso de destaque e mais sobre reduzir o atrito de configuração enquanto amplia os lugares onde Hermes pode funcionar.¹⁹ As principais mudanças operacionais:

• A instalação e a inicialização estão mais leves. pip install hermes-agent funciona via PyPI, adaptadores pesados são instalados sob demanda no primeiro uso, e o caminho de inicialização adia trabalho suficiente para reduzir a partida a frio em aproximadamente 19 segundos. (Desde então, a v0.19.0 descontinuou instalações via pip — consulte Instalação.)
• Assinaturas podem se tornar endpoints API locais. hermes proxy transforma provedores respaldados por OAuth, como Claude Pro, ChatGPT Pro e SuperGrok, em um endpoint local compatível com OpenAI para ferramentas como Codex, Aider, Cline e Continue.
• O alcance do gateway se expande. LINE e SimpleX Chat elevam a contagem de plataformas para 22, Microsoft Teams está conectado de ponta a ponta, o preenchimento de histórico do Discord vem ativado por padrão, e os prompts clarify do Telegram/Discord agora usam botões nativos.
• A verificação no momento da escrita melhora. Após as edições, Hermes pode mostrar resumos por turno das mutações de arquivos e diagnósticos semânticos do servidor de linguagem antes do próximo turno, o que o aproxima do trabalho de agentes orientado por evidências.
• As ferramentas de desktop e mídia se ampliam. computer_use funciona por meio do cua-driver para provedores que não são Anthropic, video_generate é unificado por trás de backends conectáveis, e vision_analyze envia pixels brutos a modelos que realmente conseguem enxergar.

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

Escolha seu caminho

Como o Hermes funciona: o modelo mental

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

1. Monta o prompt do sistema a partir de SOUL.md, MEMORY.md, USER.md, skills, arquivos de contexto e orientações sobre ferramentas por meio de prompt_builder.py³
2. Resolve o provedor de runtime por meio de runtime_provider.py — esta é a etapa que escolhe sua autenticação, URL base e modo de API³
3. Chama o provedor usando um dos três modos de API: chat_completions, codex_responses ou anthropic_messages³
4. Encaminha todas as chamadas de ferramentas retornadas por meio de model_tools.py e do registro central de ferramentas (tools/registry.py)³
5. Repete o loop até que o modelo produza uma resposta final e, depois, salva a sessão no SQLite com FTS5³

Entender esse loop é importante porque todos os recursos — personalidades, memória, skills, compactação, fallback — se conectam a uma dessas etapas. Quando você lê uma chave de configuração e se pergunta o que ela faz, a resposta geralmente é: “ela ajusta a 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 de barra 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ê quer saber “onde o Hermes armazena X”, a resposta está entre esses arquivos.

Novidades da v0.20.0 (The Herald Release)

O Hermes Agent v0.20.0 (tag v2026.8.3, 3 de agosto de 2026) é a versão atual com novos recursos; a v0.20.1 (13 de agosto) e a v0.20.2 (16 de agosto) são tags de estabilização lançadas sobre ela, e a v0.20.3 (tag v2026.8.16.2, publicada em 17 de agosto) e a v0.20.4 (tag v2026.8.18, 18 de agosto) mantêm a sequência de rollups, cada uma com sua própria janela de 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 instruções das versões anteriores deste guia. Leia-as antes de todo o resto:

• 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, o heal e o upgrade aplicam essa exigência. Observe que a página de instalação do site de documentação ainda indica o Node v22 — o script do instalador e as notas de versão são as fontes mais recentes e confiáveis.²⁴
• pip e Homebrew foram descontinuados, não apenas marcados como obsoletos. Nas palavras da própria equipe: “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 método não recebe mais atualizações.²⁴
• O limite padrão de iterações para chamadas de ferramentas passou de 90 para 500. Execuções autônomas longas deixaram de esbarrar em um limite artificial, e todos os limites de pressão de orçamento abaixo são calculados com base nesse novo teto. read_file também passou 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 à antiga solicitação da issue nº 514.²⁴
• Webhooks de saída assinados. Antes, hermes webhook aceitava apenas entradas; a v0.20.0 adiciona webhooks de ciclo de vida de saída assinados com HMAC para eventos de sessão, turno e ferramenta.²⁴
• Citações fundamentadas. Uma nova skill com um modo de verificação de fatos.²⁴
• Onda de recursos avançados para CLI. !command executa um comando de 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 conteúdo e permite recuperar linhas ocultas; Ctrl+S guarda um prompt escrito pela metade. hermes import-agent migra uma configuração de Claude Code ou Codex CLI com um único comando.²⁴
• Novidades na interface de secrets. Uma fonte de secrets baseada em comando auxiliar que pode ser combinada com qualquer cofre, rotação de tokens com um único comando e erros acionáveis na inicialização, um cache criptografado de emergência opcional para Bitwarden, chaves injetadas pelo cofre e limitadas ao diretório inicial de cada profile e paridade de SecretRef ${env:VAR} entre config.yaml e a configuração do MCP. O modelo de autenticação por três caminhos descrito abaixo permanece inalterado.²⁴
• Inicialização a quente mais rápida. O tempo de inicialização a frio de hermes -w caiu de aproximadamente 14s para 1,8s.²⁴
• O desktop virou uma plataforma. Artefatos com cartões versionados e visualização ao vivo em sandbox, um SDK de plugins com o Kanban como plugin inaugural para desktop, um atalho global para entrada rápida, várias janelas da GUI, modo de backend remoto SSH e login nativo conforme a RFC 8252.²⁴

Os rollups v0.20.3 e v0.20.4 (17 e 18 de agosto)

Após a v0.20.0, o projeto adotou um ritmo de rollups com tags em alta frequência, e os dois mais recentes vão além da estabilização. Ambos afirmam que “full curated release notes for this window will ship with v0.21.0” — por isso, os resumos abaixo vêm das descrições das janelas nas próprias versões, e não de uma lista selecionada de recursos.²³

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

• Migração para o SDK do MCP 2.x, com suporte ao protocolo sem estado de 28 de julho de 2026. O Hermes passa a usar a geração atual do SDK do MCP e se comunica pela revisão sem estado do protocolo.²³
• O Bot Mode é distribuído como um plugin integrado (hermes-bots) que inclui o protocolo central de colegas de equipe.²³
• Um plugin do provedor CommandCode passa a fazer parte do catálogo de provedores.²³
• Contratos de runtime do Cua Driver 0.20 para uso do computador, além do reforço da propriedade do runtime do subprocesso 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 de sessões, autorrecuperação da conexão do desktop com o gateway remoto e uma leva de melhorias no 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 (aproximadamente 146 commits e 74 PRs desde a v0.20.3):

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

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.²³

Novidades da v0.19.0 (A versão Quicksilver)

O Hermes Agent v0.19.0 (tag v2026.7.20, 20 de julho de 2026) recebeu esse nome pela velocidade do próprio deus mensageiro: a base da versão é a capacidade de resposta bruta, com uma redução de ~80% no tempo até o primeiro token do primeiro turno em todas as plataformas. Em torno disso estão faturamento no terminal, fontes de secrets de 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 do projeto até agora: ~2.245 commits, ~1.065 PRs mesclados, ~3.300 issues fechadas e mais de 450 contribuidores da comunidade.²⁵

• ~80% mais rápido até o primeiro token, em todos os lugares. O envio a frio→dispatch caiu de ~4,3s para ~0,9s no CLI, gateway, TUI, desktop e cron — a detecção de capacidade do Discord saiu do caminho crítico, a sondagem do Ollama é ignorada para providers conhecidos que não usam Ollama e o trabalho bloqueante foi removido da inicialização do agent. A latência percebida também recebeu atenção: modelos de reasoning agora fazem streaming do raciocínio ao vivo por padrão (display.show_reasoning está ON), e a caixa de resposta é renderizada por token, não por linha.²⁵
• Onda de renderização no desktop e na TUI. O app desktop recebeu uma reformulação de velocidade com ~20 PRs: 14× menos CPU no separador de streaming Markdown por meio de análise léxica incremental de blocos, diffs virtualizados no painel de revisão, troca ágil de sessão em transcrições grandes e fim das novas renderizações da barra lateral e das linhas de tools a cada token. A TUI agora renderiza Markdown em streaming incrementalmente por bloco.²⁵
• Instalações por pip e Homebrew foram descontinuadas. Ambos os caminhos foram marcados como instalações legadas “não compatíveis”, com remoção planejada. Essa remoção já ocorreu na v0.20.0 — os canais brew e pip/PyPI wheel foram aposentados, restando o instalador via shell, Docker e Nix como canais compatíveis.²⁵²⁴
• Secrets podem vir do seu gerenciador de senhas. Uma nova interface plugável SecretSource busca secrets do Bitwarden e do 1Password (referências op://) no carregamento, com vários vaults ativados simultaneamente, precedência determinística, avisos de conflito e proveniência por variável — as chaves API não precisam mais ficar em um .env de texto simples. Providers de vault futuros entram como plugins.²⁵
• Aprovações inteligentes agora são o padrão. Quando Hermes quer executar um comando sinalizado, um revisor LLM independente o avalia em vez de solicitar sua confirmação para cada um — e cada veredito cobre somente aquele comando exato. As regras de negação definidas pelo usuário bloqueiam comandos correspondentes até mesmo no modo YOLO, /deny <reason> transmite seu motivo de recusa para que o agent corrija o rumo, e a ação de aprovação pre_tool_call do plugin (restabelecida com chaves de regra) eleva uma tool call para uma etapa de aprovação humana.²⁵
• Faturamento no terminal: /subscription e /topup. Gerencie seu plano do Nous Portal sem sair do terminal — veja seu plano e a franquia restante, visualize exatamente o custo de um upgrade ou quando um downgrade entra em vigor e aplique a alteração com opção de desfazer. O app desktop ganha uma aba correspondente de configurações de faturamento.²⁵
• Acompanhe o trabalho dos subagentes; nunca perca uma resposta concluída. Os dispatches 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 tool call, resultado e resposta em streaming, em um log legível por humanos para cada 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 ledger de obrigação de entrega em state.db e entregues novamente na próxima inicialização se o gateway falhar no meio do envio. A opção de configuração max_async_children está descontinuada em favor de limites unificados de concorrência de delegação.²⁵
• Um gateway, muitos profiles. Um único gateway multiplexado que compartilha um token de bot pode direcionar guilds, canais ou threads específicos para profiles diferentes — cada um com config, skills, memória e secrets totalmente isolados — com uma substituição GATEWAY_MULTIPLEX_PROFILES. O índice de roteamento foi movido para state.db; sessions.json agora é um espelho legado opcional.²⁵
• Onda de providers e modelos. Fireworks AI chega como opção de primeira classe (estimativa de custo, posição nº 2 no seletor de provider), acompanhado de DeepInfra e Upstage Solar. Os catálogos adicionam GPT-5.6 (Sol/Terra/Luna + Pro, conectado de ponta a ponta), grok-4.5 (GA), kimi-k3 (kimi-k2.x aposentado) e Claude Sonnet 5 totalmente conectado. Uma flag enabled: false por provider e a configuração excluded_providers removem providers não utilizados dos seletores e da resolução de /model.²⁵
• O esforço de reasoning vira um controle. Novos níveis de esforço max e ultra chegam a todas as superfícies, com substituições por modelo na config, esforço por slot nos presets de MoA (advisors pensam mais, o sintetizador permanece rápido), esforço por tarefa para modelos auxiliares e um /reasoning com escopo de sessão no CLI.²⁵
• Superfície de CLI e MCP. hermes sessions export grava formatos Markdown, Quarto, HTML, somente prompt e rastreamento do Hugging Face com limpeza opcional via --redact; /model --once fornece uma substituição de modelo para um turno; invocações de slash-skill são encadeadas (/skill-a /skill-b do XYZ); --safe-mode ajuda na solução de problemas; hermes config get/unset completam o gerenciamento de config; hermes serve se torna um backend verdadeiramente headless; e as tools MCP adotam a convenção de nomenclatura mcp__server__tool.²⁵

Se você estiver fazendo upgrade da v0.18.x, duas mudanças merecem atenção antes de qualquer outra: uma instalação por pip ou Homebrew agora avisa que é um legado não compatível (migre para o instalador de uma linha), e max_async_children está descontinuado em favor dos limites unificados de concorrência de delegação. Todo o restante é aditivo — os principais motivos para fazer upgrade são a redução de ~80% na latência do primeiro turno, as aprovações inteligentes e o ledger de entrega que torna respostas concluídas resistentes a falhas.

Novidades da v0.18.0 (A versão Judgment)

O Hermes Agent v0.18.0 (tag v2026.7.1, 1º de julho de 2026) recebeu esse nome por causa do julgamento: o agent verificando seu próprio trabalho em vez de alegar sucesso, e ensemble reasoning que você realmente pode inspecionar. Ele também fecha todo o backlog P0/P1 — cerca de 692 itens de maior prioridade resolvidos em doze dias.²²

• Mixture-of-Agents como modelo de primeira classe. MoA agora pode ser selecionado como qualquer outro modelo em todas as interfaces, e o ensemble reasoning é visível: a saída completa de cada modelo de referência é renderizada como seu próprio bloco identificado, com streaming da resposta ao vivo — você pode observar o ensemble raciocinar em vez de receber uma resposta mesclada opaca.²²
• Contratos de conclusão para /goal. O agent verifica seu próprio trabalho executando as verificações do projeto antes de informar que um objetivo foi concluído, em vez de apenas alegar sucesso — julgamento aplicado a si mesmo.²²
• /learn — descreva qualquer coisa e transforme 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.²²
• Expansã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 torna 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 escalonamento para zero. Gateways podem ficar inativos quando ociosos e coordenar drains para deployments sem interrupções — relevante para qualquer pessoa que execute Hermes como um serviço sempre ativo.²²
• Suporte ao Google Vertex AI. Acesso ao Gemini por contas de serviço do GCP com atualização automática do token OAuth2, entrando no catálogo de providers.²²
• Comando de editor /prompt. Abre $EDITOR para compor prompts de várias linhas em vez de lutar com a linha de entrada.²²

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

Novidades na v0.17.0 (A versão Reach)

O Hermes Agent v0.17.0 (tag v2026.6.19, 19 de junho de 2026) recebeu esse nome pela abrangência que o agente agora alcança — novos canais de mensagens, novos provedores de modelos e controles mais profundos para desktop e dashboard. Ela é incremental em relação à v0.16.x; a superfície do CLI permanece inalterada.²¹

• Novos canais de mensagens. O iMessage agora funciona sem um relay Mac por meio do Photon Spectrum (código de dispositivo OAuth, hermes photon login); o WhatsApp Business Cloud API é um adaptador oficial da Meta que elimina a necessidade de um processo de bridge; o SimpleX ganha grupos, anexos nativos, processamento de texto em lote e aceitação automática; e o Raft entra como um plugin de plataforma incluído, 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 (o modelo do Cursor via xAI OAuth, contexto de 200k). O padrão da xAI mudou para grok-build-0.1, e os modelos adaptativos Anthropic agora seguem o contrato moderno de thinking (eles nunca enviam um campo reasoning).²¹
• Desktop e dashboard. O desktop adiciona subagentes em segundo plano com streaming ao vivo em “watch-windows” da atividade delegada (delegate_task(background=true)), um seletor de modelo Composer, atalhos de teclado reatribuíveis, notificações nativas do sistema operacional, rascunhos do composer por thread, temas do VS Code Marketplace e interface em japonês + chinês tradicional. O dashboard adiciona um criador completo de profiles (modelo/skills/MCPs sem editar config.yaml), um alternador global de profile, um Skills Hub reformulado com verificação de segurança, Automation Blueprints (templates parametrizados em formulário, slash command, conversa e documentação) e um login seguro que retorna 401 por trás do gate OAuth.²¹
• Skills e tools. image_generate agora pode editar e transformar uma imagem de origem, não apenas criar uma do zero, em todos os provedores de imagem compatíveis; a tool memory ganhou um array operations para adicionar/substituir/remover em lote de forma atômica em uma única chamada; uma nova skill simplify-code executa uma etapa paralela de revisão e limpeza com três agentes, condicionada a um nível de risco da Chesterton’s Fence; e um write_approval booleano substitui o write_mode de três estados.²¹
• Arquitetura. Subagentes em segundo plano retornam um handle imediatamente e inserem seu resultado como um novo turno; um manipulador de elicitação MCP permite confirmação durante uma chamada de tool, e tools MCP conectadas tardiamente são expostas entre turnos (seguro para cache); 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 uma configuração imutável para o usuário, junto a um relay Gateway-Gateway para topologias com múltiplos gateways.²¹
• Novos comandos. /version, /billing (faturamento interativo no terminal), hermes photon login (autenticação do iMessage) e hermes curator run --consolidate — a consolidação agora é opcional, então a curadoria rotineira em segundo plano não consome tokens.²¹
• Segurança. A v0.17.0 corrige um bypass da denylist de escape de shell, falha de forma segura quando módulos de aprovação e adaptadores de gateway de política própria estão ausentes, sanitiza o ambiente para subprocessos de scripts de jobs cron, oculta secrets em dumps de depuração de solicitações, verifica configurações stdio 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 o CLI; são novos canais, modelos e superfícies em torno do mesmo agente. Os adaptadores de iMessage sem relay e WhatsApp oficial, além do escopo Managed para administradores, são os principais motivos para atualizar.

Novidades na v0.16.0 (A versão Surface)

O Hermes Agent v0.16.0 (tag v2026.6.5, 5 de junho de 2026) recebeu esse nome pelas novas superfícies que coloca diante do agente com foco no CLI. O destaque é que o Hermes deixou de ser exclusivo do terminal.²⁰

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

Se você estiver atualizando da v0.15.x, nada disso é uma mudança incompatível no próprio CLI; são superfícies e provedores incrementais em torno do mesmo agente. O app desktop e o painel de administração são o motivo para atualizar se você quiser executar o Hermes para usuários que não usam terminal ou administrar um gateway remoto pelo navegador.

Instalação

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

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

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

Funciona no Linux, macOS, WSL2 e Android/Termux (o instalador detecta automaticamente o Termux e muda para um pacote Android testado).⁷ O Windows nativo agora é uma plataforma Tier 1, em vez da 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 é apenas para Apple Silicon, e Macs Intel não são compatíveis.²⁴ Historicamente, a v0.14.0 adicionou suporte nativo ao Windows em 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 o caminho para Windows amadureça.¹⁹

Depois que ele terminar:

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

O único pré-requisito é git. O instalador provisiona automaticamente Python 3.11 via uv (sem necessidade de sudo), Node.js 26 (para automação de navegador e a ponte do WhatsApp), ripgrep e ffmpeg. O Node 26 é um requisito mínimo rígido desde a v0.20.0 — o instalador recusa qualquer versão anterior e instala uma versão do Node gerenciada pelo Hermes.²⁴⁷

Verifique a instalação

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

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

Instalação manual

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

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

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

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

Autenticação e provedores

Hermes oferece suporte a cerca de 22 provedores de primeira linha, além de endpoints personalizados (a v0.19.0 adiciona Fireworks AI, DeepInfra e Upstage Solar), e três caminhos distintos de autenticação. Aqui está toda a superfície de autenticação, organizada por caminho para que você encontre o que corresponde ao que tem.

Os três caminhos de autenticação

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

Caminho 1 — chave API em .env. Coloque sua chave em ~/.hermes/.env e o Hermes a lê na inicialização. Usado por OpenRouter, AI Gateway, z.ai/GLM, Kimi/Moonshot, MiniMax (e MiniMax China), Alibaba Cloud/DashScope, Kilo Code, OpenCode Zen, OpenCode Go, DeepSeek, Hugging Face, Google/Gemini e a maioria dos provedores de terceiros.² 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 do Bitwarden ou 1Password (referências op://) durante o carregamento, com vários cofres ativados simultaneamente, precedência determinística, avisos de conflito e procedência por variável — .env continua sendo a alternativa de fallback. (Isso é diferente do token de bootstrap do Bitwarden Secrets Manager da v0.15.0, que consolidava as chaves de provedores por trás de um único token; SecretSource substitui o próprio arquivo de texto simples, e futuros provedores de cofre podem ser adicionados como plugins.)²⁵

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

Caminho 3 — endpoint personalizado em config.yaml. Para qualquer API compatível com OpenAI — Ollama, vLLM, SGLang, llama.cpp, LM Studio, proxy LiteLLM, Together AI, Groq, Azure OpenAI ou seu próprio servidor hospedado por você. Configurado uma vez por hermes model → Custom endpoint e então persistido em config.yaml.²

A matriz completa de provedores

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

A partir da v0.19.0, você também pode remover os provedores que não usa: uma flag enabled: false por provedor e uma chave de configuração excluded_providers os removem dos seletores /model e da resolução de provedores integrada.²⁵

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

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

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

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

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

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

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

Para fixar Anthropic permanentemente em config.yaml:

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

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

GitHub Copilot: dois modos

Copilot tem suporte em dois modos: API direto do Copilot (recomendado) e Copilot ACP (que inicia o CLI local do Copilot como subprocesso).²

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

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

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

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

Provedores chineses de AI (suporte de primeira linha)

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

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

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

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

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

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

As URLs base podem ser substituídas pelas variáveis de ambiente GLM_BASE_URL, KIMI_BASE_URL, MINIMAX_BASE_URL, MINIMAX_CN_BASE_URL ou DASHSCOPE_BASE_URL.²

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

xAI (Grok) ativa automaticamente o cache de prompt. Quando a URL base contém x.ai, Hermes envia o cabeçalho x-grok-conv-id em todas as solicitações para encaminhar à mesma instância do servidor durante uma sessão de conversa, reutilizando prompts de sistema e histórico em cache.² É automático; nenhuma configuração é necessária.

O comando hermes auth

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

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

Pools de credenciais permitem alternar entre várias chaves API ou tokens OAuth do mesmo provedor — útil para distribuir limites de taxa entre várias chaves sem alterar código.⁶ Os comandos legados hermes login / hermes logout foram removidos; use hermes auth em seu lugar.⁶

Endpoints personalizados e hospedados por você

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

Configuração interativa (recomendada):

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

config.yaml manual:

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

Ambas as abordagens persistem em config.yaml, que é a fonte única da verdade para modelo principal, provedor e URL base.² As variáveis de ambiente legadas OPENAI_BASE_URL e LLM_MODEL não são mais lidas para a configuração do modelo principal — use hermes model ou edite config.yaml diretamente.² (OPENAI_BASE_URL + OPENAI_API_KEY ainda são respeitados como fallback para o caminho de roteamento auxiliar provider: "main", portanto não os exclua sem pensar se estiver usando-os nesse caso.)⁴

Alternando 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) consulta o API /v1/models do seu endpoint e seleciona automaticamente o modelo se houver exatamente um carregado — útil para servidores locais que executam um único modelo.²

Servidores LLM locais (modelos de configuração)

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

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

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

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

vLLM — serving 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

A chamada de ferramentas requer --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 retornam como texto simples.²

SGLang — serving rápido com RadixAttention para reutilização do cache KV:

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

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

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

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

--jinja é obrigatório para chamadas de ferramentas. Sem ele, llama-server ignora completamente o parâmetro tools e o modelo tenta chamar ferramentas escrevendo JSON no texto da resposta — algo que Hermes não consegue analisar como chamadas de ferramentas reais.²

LM Studio — aplicativo desktop com GUI:

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

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

Provedores personalizados nomeados

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

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

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

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

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

Arquitetura de provedores conectáveis (v0.13.0+)

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

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

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

Detecção de comprimento de contexto

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

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

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

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

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

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

Hermes não prende você a um único modelo em um único provedor. O roteamento inteligente de modelos é o conjunto de mecanismos que decide qual provedor e modelo realmente atende a uma determinada solicitação: pools de credenciais distribuem a carga entre chaves, um fallback configurado assume quando o principal falha, e os slots auxiliares abaixo direcionam tarefas paralelas para modelos mais baratos independentemente do seu modelo principal.²⁶ Configure esses três juntos – eles são a diferença entre um agente que para em um limite de taxa e outro que continua trabalhando.

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

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

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

O fallback troca o modelo e o provedor no meio da sessão sem perder sua conversa. Ele é acionado no máximo uma vez por sessão.² Provedores compatíveis com fallback: openrouter, nous, openai-codex, copilot, copilot-acp, anthropic, huggingface, zai, kimi-coding, minimax, minimax-cn, deepseek, ai-gateway, opencode-zen, opencode-go, kilocode, alibaba, custom.²

Modelos auxiliares

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

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

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

A opção de provedor "main" significa “usar o provedor que meu agente principal usa” — válida somente dentro das configurações auxiliary:, compression: e fallback_model:. Ela não é válida para sua configuração de nível superior model.provider. Se você usar um endpoint personalizado compatível com OpenAI como modelo principal, defina provider: custom na sua seção model:.⁴

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

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

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

Sistema de configuração

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

Layout dos arquivos de configuração

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

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

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

Você pode referenciar secrets de config.yaml usando interpolação no estilo shell:⁴

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

Gerenciando a configuração

hermes config                # View current configuration
hermes config show           # Same as above
hermes config edit           # Open config.yaml in your editor
hermes config set KEY VAL    # Set a specific value
hermes config 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 opções de configuração recém-adicionadas que o seu arquivo ainda não tem.⁶

Precedência de configuração

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

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

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

Localização (v0.13.0+)

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

Profiles — várias instâncias isoladas do Hermes

Profiles permitem que você tenha várias instâncias isoladas do Hermes, cada uma com sua própria configuração, sessões, skills, memória e PID do gateway. É assim que você executa o “Hermes de trabalho” e o “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), portanto vários profiles podem executar o gateway simultaneamente sem interferir uns nos outros.⁶³

Comandos CLI

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

Opções globais

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

Comandos de nível superior

hermes chat — O principal ponto de entrada

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

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

Opções principais:

hermes setup — Assistente completo

Executa o assistente 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 do que usar tail -f nos arquivos de log, pois 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 API, despacho de tools, ciclo de vida da sessão, INFO+) - errors.log — apenas avisos e erros (um subconjunto filtrado de agent.log) - gateway.log — atividade do gateway de mensagens (conexões de plataforma, despacho, webhooks)

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

hermes doctor — Diagnóstico

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

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

Comandos Slash

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

Controle da sessão

Configuração e modelo

O comando /model é o principal recurso para alternar de provider no meio da sessão:⁹

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

A v0.19.0 adiciona /model --once — uma substituição de modelo para um turno que volta automaticamente ao modelo anterior após a resposta.²⁵

Tools, skills e informações

Comandos slash dinâmicos de skills

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

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

Desde a v0.19.0, as invocações de skills via slash se acumulam: /skill-a /skill-b do XYZ carrega ambas as skills em ordem em um único turno, com autocomplete e ghost text para os nomes encadeados.²⁵

Você também pode definir comandos rápidos em config.yaml que associam um nome curto a um prompt mais longo:⁹

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

Depois, digite /review, /deploy ou /morning no CLI.

Correspondência por prefixo

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

Comandos específicos de mensagens

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

• /status — mostre informações da sessão
• /sethome (alias /set-home) — marque o chat atual como home da plataforma
• /approve [session|always] — aprove um comando perigoso pendente
• /deny [reason] — rejeite um comando perigoso pendente. Desde a v0.19.0, /deny <reason> encaminha seu motivo de recusa ao agente para que ele corrija o rumo em vez de tentar novamente às cegas²⁵
• /update — atualize Hermes Agent para a versão mais recente
• /commands [page] — navegue por todos os comandos e skills (paginado)

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

Ferramentas e toolsets

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

Categorias de alto nível

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

Gerenciamento de ferramentas

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

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

Backends de terminal

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

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

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

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

terminal:
  backend: ssh

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

Backend Docker:

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

Recursos de container (aplica-se 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 permanecem entre as sessões.¹⁰

Todos os backends de container são executados com reforço de segurança: sistema de arquivos raiz somente leitura (Docker), todos os recursos do Linux removidos, exceto DAC_OVERRIDE, CHOWN e FOWNER, sem escalonamento de privilégios, limites de PID (256 processos), isolamento completo de namespaces e espaço de trabalho persistente por 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 ferramentas interativas de CLI, como Codex e Claude Code.¹⁰

Sudo

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

Kanban multiagente (v0.13.0+)

A v0.13.0 transforma a colaboração multiagente em um recurso fundamental: um quadro Kanban durável que acompanha tarefas, status e a identidade do worker entre agentes e após reinicializações.¹⁸ O quadro é o que faz um enxame de workers do Hermes realmente concluir o trabalho, em vez de travar em transferências sem continuidade.

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

O que é um enxame Hermes?

Um enxame é formado por vários workers do Hermes executados em paralelo em um único quadro Kanban compartilhado. Não é um subsistema separado que você ativa – é o que o quadro possibilita. O quadro fornece a única coisa que agentes paralelos não conseguem fornecer por conta própria: uma resposta única e autoritativa para o que devo assumir em seguida e alguém já está trabalhando nisso?

A v0.15.0 elevou isso de um padrão a uma topologia compatível, adicionando topologia de enxame para coordenação de workers em paralelo, decomposição automática de um objetivo de alto nível em subtarefas, substituições de modelo por tarefa, tarefas agendadas e gerenciamento de worktrees para que workers paralelos não entrem em conflito no mesmo checkout.²⁸

Na prática: dê um objetivo ao enxame, deixe a decomposição automática dividi-lo em tarefas no quadro e permita que os workers reivindiquem, executem e retornem resultados. O orçamento de tentativas é por tarefa (max_retries), portanto, uma subtarefa frágil não consome a tolerância de toda a execução. Como o quadro é durável, um enxame sobrevive a reinicializações – os workers se reconectam e retomam a partir do mesmo estado.

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

Sistema de skills

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

Todas as skills ficam em ~/.hermes/skills/ — o diretório principal e fonte da verdade. Em uma instalação nova, as skills incluídas são copiadas do repositório. Skills instaladas pelo Hub e criadas pelo agente também ficam aqui.¹¹

Divulgação progressiva

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

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

Formato do SKILL.md

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

# Skill Title

## When to Use
Trigger conditions for this skill.

## Procedure
1. Step one
2. Step two

## Pitfalls
- Known failure modes and fixes

## Verification
How to confirm it worked.

Ativação condicional

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

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

Skills gerenciadas pelo agente

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

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

Ações:¹¹

Skill Hub

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

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

Fontes integradas do hub:¹¹

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

Varredura de segurança

Todas as skills instaladas pelo hub passam por um scanner de segurança que verifica exfiltração de dados, prompt injection, comandos destrutivos, sinais 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 veredito de varredura dangerous.¹¹

Diretórios de skills externos

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

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

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

Memória persistente

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

Padrão de snapshot congelado: a inserção no system prompt é capturada uma vez no início da sessão e nunca muda durante a sessão. Isso é intencional — preserva o cache de prefixo do LLM para manter o desempenho. As alterações feitas durante uma sessão são persistidas no disco imediatamente, mas não aparecem no system prompt até a próxima sessão.¹²

O que salvar

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

Ignore estes itens:¹² - Informações triviais ou óbvias - Fatos que podem ser descobertos novamente com facilidade - Dumps de dados brutos (grandes demais para a memória) - Informações efêmeras específicas da sessão - Informações que já estão em arquivos de contexto

Busca de sessões

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

Provedores de memória externos

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

Os provedores externos funcionam junto da memória integrada (sem nunca substituí-la) e acrescentam recursos como grafos de conhecimento, busca semântica, extração automática de fatos e modelagem de usuários entre sessões:⁶¹²

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

Apenas um provedor externo pode estar ativo por vez. A memória integrada está sempre ativa.⁶

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

A v0.13.0 torna interrupções no meio da execução do agente recuperáveis. O gateway retoma automaticamente sessões interrompidas após uma reinicialização; reinicializações via /update preservam o estado da sessão durante a atualização; recarregamentos de arquivos-fonte durante o desenvolvimento mantêm a sessão ativa em vez de forçar uma nova.¹⁸ Na prática, trabalhos de gateway de longa duração 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 um design de armazenamento único com limpeza real, proteções de disco e nenhum repositório sombra órfão.¹⁸ O sistema anterior de checkpoints acumulava estado no disco em profiles de longa duração; o armazenamento v2 estabelece um limite rígido para o armazenamento local de checkpoints e remove o controle duplicado que causava esse crescimento. Nenhuma alteração de configuração voltada ao usuário é necessária; a próxima gravação de checkpoint usa o caminho v2.

Personalidade e SOUL.md

SOUL.md é a identidade principal de uma instância do Hermes. Ele ocupa o slot nº 1 no system prompt, substituindo a identidade padrão codificada.¹³

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

O que pertence ao SOUL.md

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

Use-o menos para:¹³ - instruções pontuais de 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 vs AGENTS.md

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

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

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

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

Personalidades integradas

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

Personalidades personalizadas em config.yaml:¹³

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

Depois, alterne com /personality codereviewer.

SOUL.md vs /personality

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

Nous Tool Gateway (v0.10.0+)

A partir do Hermes Agent v0.10.0 (16 de abril de 2026), assinantes pagos do Nous Portal têm acesso gerenciado a um conjunto selecionado de ferramentas por meio das credenciais existentes do Portal — sem chaves API extras para gerenciar.³⁰ O próprio CLI do Hermes continua licenciado sob MIT e totalmente open source. O que mudou foi que sua autenticação no Portal agora libera mais do que inferência de modelo.

O que há no gateway

Como funciona

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

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

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

Habilitando o gateway

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

A assinatura é detectada automaticamente a partir das 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 dentro de uma sessão: /subscription mostra seu plano e a franquia restante, exibe exatamente quanto custa um upgrade ou quando um downgrade passa a valer, e aplica a alteração com avisos de mudança agendada e opção de desfazer; /topup adiciona crédito. O aplicativo desktop tem uma aba correspondente de configurações de cobrança.²⁵

Preços e acesso

Os preços e nomes dos níveis são publicados na página de preços do Nous Portal (https://portal.nousresearch.com/pricing). Este guia não lista os níveis 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 níveis atuais.

Aviso de descontinuação

• A variável de ambiente HERMES_ENABLE_NOUS_MANAGED_TOOLS foi removida na v0.10.0. As ferramentas gerenciadas agora são habilitadas pelo campo de configuração use_gateway de cada ferramenta e dependem do status da sua assinatura do Portal.³⁰

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

O CLI do Hermes Agent não é bloqueado por uma assinatura. O projeto continua licenciado sob MIT, e todos os recursos principais (CLI, skills, memória, messaging gateway, cron, MCP, dashboard local, BYOK para todos os provedores) funcionam de ponta a ponta sem pagar ninguém. A v0.10.0 adiciona um caminho prático para usuários que já pagam pelo 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 e um adaptador Webhook genérico.^329171819 A v0.9.0 adicionou iMessage via BlueBubbles (registro automático de webhook, assistente de configuração, resiliência a falhas) e suporte nativo ao WeChat via iLink Bot API com modo de callback do WeCom para aplicativos empresariais.¹⁶ A v0.11.0 adicionou QQBot.²⁹ A v0.12.0 adicionou Microsoft Teams e Tencent Yuanbao.¹⁷ A v0.13.0 adicionou o Google Chat como a 20ª plataforma, usando a mesma arquitetura de adaptadores plugáveis; IRC e Microsoft Teams também foram migrados para o novo padrão de adaptador com hooks genéricos de plugin env_enablement_fn / cron_deliver_env_var.¹⁸ A v0.14.0 adiciona LINE e SimpleX Chat e completa a stack do Microsoft Teams de ponta a ponta com autenticação Graph, listener de webhook, runtime de pipeline e entrega de saída.¹⁹ A v0.17.0 (19 de junho de 2026) adiciona iMessage sem relay via Photon Spectrum (autenticação de código de dispositivo OAuth com hermes photon login — sem necessidade de relay Mac/BlueBubbles), o adaptador oficial da WhatsApp Business Cloud API (substituindo a exigência de um processo de bridge), grupos e anexos nativos do SimpleX, e Raft como um plugin de plataforma incluído.²¹

Configuração

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

A configuração interativa orienta você na conexão de cada plataforma: tokens API, IDs de bot, mapeamentos de canais e allowlists.⁶

Como as mensagens fluem

Da documentação de arquitetura upstream:³

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

Todas as plataformas de mensagens passam pelo mesmo loop de conversa AIAgent que o CLI. É por isso que os comandos slash funcionam de forma idêntica nos dois lugares e que um trabalho cron agendado no Telegram pode entregar sua saída no Discord — a diferença entre plataformas está apenas na borda.³

A v0.19.0 adiciona roteamento de mensagens baseado em profile 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ção, skills, memória e segredos totalmente isolados — com uma substituição GATEWAY_MULTIPLEX_PROFILES, e uma série de reforços garante que um profile configurado incorretamente não possa mais derrubar 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 — uma resposta concluída que encontra uma falha no gateway é reenviada na próxima inicialização, em vez de ser perdida silenciosamente.²⁵

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 aleatórios conversem com seu gateway. Um usuário envia um código de pareamento pela plataforma de mensagens; você o aprova com hermes pairing approve; a partir de então, ele fica autorizado.⁶

Tarefas agendadas (Cron)

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

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

Ou crie um conversacionalmente dentro de um chat de 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 persistem em JSON e sobrevivem a reinicializações.³

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 sua superfície de ferramentas:

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

Ou manualmente em config.yaml:¹⁴

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

A partir da v0.19.0, as ferramentas MCP são expostas ao modelo seguindo a convenção de nomenclatura mcp__server__tool — cada nome de ferramenta inclui o nome do servidor, para que dois servidores que exponham a mesma ferramenta não entrem mais em conflito — e notificações de log do servidor MCP são exibidas em agent.log.²⁵

Como servidor — exponha conversas do Hermes a outros agentes:

hermes mcp serve
hermes mcp serve -v    # Verbose

Compressão de contexto

Hermes comprime automaticamente conversas longas para se manter dentro da janela de contexto do seu modelo. O resumidor de compressão é uma chamada LLM separada — você pode direcioná-lo a qualquer provider ou endpoint.⁴

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

Opções de provider:⁴

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

Avisos de pressão no orçamento

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

Timeouts de stream

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

O timeout de leitura do socket é aumentado para 30 minutos em endpoints locais, pois LLMs locais podem levar minutos no prefill de contextos grandes antes de produzir o primeiro token.⁴

Dashboard web local (v0.9.0+)

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

Monitoramento de processos em 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 notifica quando uma tarefa em segundo plano é concluída), Hermes agora conta com uma camada completa de observabilidade de 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. Troque por context engines personalizadas que controlam o que o agente vê a cada turno — filtragem, sumarização ou injeção de contexto específica ao domínio.¹⁶ Isso desacopla a estratégia de contexto do loop principal do agente, permitindo a personalização de contexto por projeto ou domínio.

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

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

Suporte a Termux / Android (v0.9.0+)

Hermes é executado nativamente no Android via Termux. Caminhos de instalação adaptados, otimizações de TUI para telas móveis, suporte a backend de voz e o comando /image funcionam 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.¹⁸ A v0.14.0 vem em seguida com mais 12 correções P0 e 50 P1, incluindo reforço contra força bruta em sudo / sudo-stdin, correções para contornar comandos perigosos, sanitização de erros de ferramentas antes da reinjeção no modelo, autenticação de API de plugins do dashboard, cobertura de SSRF no skills-hub e verificação de avisos da cadeia de suprimentos durante a instalação.¹⁹

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

Arquitetura para profissionais

Esta seção é para pessoas que querem entender o que acontece por trás dos bastidores, para depurar, estender ou analisar o desempenho. É uma síntese da documentação de arquitetura upstream.³

Pontos de entrada → AIAgent

Todos os pontos de entrada no Hermes acabam chamando AIAgent.run_conversation():

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

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

“47 tools / 20 toolsets” vs. “28 tools” no seu banner. A contagem de “47 tools” é o registro total de tools do repositório upstream — todas as tools para as quais o Hermes inclui código-fonte, em todos os toolsets. A sua instalação CLI em execução mostrará um número menor no banner de inicialização (a instalação em que verifiquei este guia informa 28 tools / 89 skills). Isso não é um bug. Muitos toolsets são opcionais e precisam ser ativados explicitamente em config.yaml, em toolsets: — adaptadores de plataformas de mensagens, automação de navegador, tools de scraping mais pesadas etc. O total do registro representa “o que está disponível”; o número do banner representa “o que está ativado no seu profile atual”. Veja quais toolsets estão ativos com hermes tools --list e ative ou desative toolsets individuais com o bloco toolsets: em ~/.hermes/config.yaml (ou /tools list / /tools enable <name> / /tools disable <name> em uma sessão em execução — remover uma tool dispara uma redefinição da sessão para que o agente reconstrua o manifesto de tools).

Os três modos API

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

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

Fluxo de dados em uma sessão CLI

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

Da página de arquitetura upstream.³

Ordem de montagem do prompt

A pilha de prompts inclui:¹³

1. SOUL.md (identidade do agente — ou fallback integrado se indisponível)
2. Orientações de comportamento compatíveis com tools
3. Contexto de memória/usuário (MEMORY.md, USER.md)
4. Orientações de skills
5. Arquivos de contexto (AGENTS.md, .cursorrules)
6. Timestamp
7. Dicas de formatação específicas da plataforma
8. Sobreposições opcionais de system prompt, como /personality

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

Armazenamento de sessões

Armazenamento de sessões baseado em SQLite com busca de texto completo FTS5. As sessões têm rastreamento de linhagem (pai/filho entre compressões), isolamento por plataforma e gravações atômicas com tratamento de contenção.³

Sistema de plugins

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

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

Princípios de design

Da página de arquitetura upstream:³

Migração do OpenClaw

Hermes Agent é o sucessor do OpenClaw. Se você 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 (também detecta automaticamente os diretórios legados ~/.clawdbot e ~/.moldbot) e grava em ~/.hermes.⁶

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

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

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

Solução de problemas

“No inference provider configured. Run ‘hermes model’ to choose a provider and model”

O primeiro erro que toda instalação nova encontra: o Hermes ainda não tem um provider definido. Isso significa exatamente o que diz — nenhum dos três caminhos de autenticação produziu um provider utilizável. Execute:

hermes model

O seletor interativo percorre todos os providers compatíveis, incluindo os fluxos de device code do OAuth (Nous Portal, GitHub Copilot, Anthropic, OpenAI Codex) e endpoints personalizados para servidores auto-hospedados. Se você esperava que um provider já estivesse configurado, hermes doctor mostra quais credenciais o Hermes realmente consegue encontrar; as causas mais comuns são uma chave API definida no lugar errado (ela deve ficar em .env ou ser configurada com hermes config set, não no perfil do seu shell), uma credencial OAuth expirada em ~/.hermes/auth.json ou um endpoint personalizado em config.yaml que perdeu seu base_url. Os caminhos de autenticação são abordados em profundidade em Autenticação e providers.²⁷

“Chave API não definida”

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

“Context limit: 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 em config.yaml:²

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

Chamadas de tool aparecem como texto em vez de serem executadas

Seu servidor não tem tool calling ativado ou o modelo não oferece suporte a isso pela implementação do servidor.²

As respostas são cortadas no meio da frase

Há duas causas possíveis:²

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

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

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

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

[wsl2]
networkingMode=mirrored

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

Alternativa com IP do host (versões mais antigas do Windows): obtenha o IP do host Windows de dentro do WSL2 e use-o no lugar de localhost:

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

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

Onde está tudo?

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

Perguntas frequentes

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

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

Posso usar o Hermes com uma chave API da Anthropic?

Sim. Há três formas:²

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

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

Como alterno entre providers sem perder minha conversa?

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

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

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

Você está encontrando o fallback do modelo auxiliar. Vision, resumo da web, compressão e outras tarefas secundárias usam um LLM auxiliar separado — por padrão, Gemini Flash por autodetecção (OpenRouter → Nous → Codex). Se nenhum deles estiver configurado e você tiver apenas Anthropic configurado, esses recursos se degradam silenciosamente.⁴

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

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

compression:
  summary_provider: "main"

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

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

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

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

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

O Hermes oferece suporte a LLMs locais?

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

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

O guia cita 47 tools / 20 toolsets do registro de arquitetura upstream — essa é a contagem total de tools cujo código-fonte o Hermes inclui em todos os toolsets. Sua instalação em execução mostra um número menor no banner (a instalação de referência usada neste guia informa 28 tools), porque o Hermes ativa apenas o conjunto padrão de toolsets na inicialização. Muitos toolsets são opt-in: adaptadores de gateway de mensagens, automação de navegador, stacks de scraping mais pesadas e várias integrações especializadas precisam ser listados explicitamente em toolsets: no arquivo ~/.hermes/config.yaml antes de serem carregados. Total do registro = “o que está disponível se você ativar”. 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 desativados. Ative ou desative toolsets individuais em tempo de execução com /tools enable <name> e /tools disable <name> (desativar aciona uma redefinição de sessão para que o agente reconstrua seu manifesto de tools com a nova configuração).

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

Configure um bloco fallback_model em config.yaml:²

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

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

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

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

Há integração com IDE?

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

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

Registro de alterações

Referências