Documentação oficial desta página · v0.20.6

Perguntas frequentes e solução de problemas

Respostas rápidas e correções para as dúvidas e os problemas mais comuns.

Perguntas frequentes

Quais provedores de LLM funcionam com o Hermes?

O Hermes Agent funciona com qualquer API compatível com a OpenAI. Entre os provedores suportados estão:

OpenRouter — acesse centenas de modelos com uma única chave de API (recomendado pela flexibilidade)
Nous Portal — o gateway por assinatura da Nous Research — mais de 300 modelos, além de web/imagem/TTS/navegador, com um único login OAuth (recomendado para quem está começando)
OpenAI — GPT-5.4, GPT-5-codex, GPT-4.1, GPT-4o, etc.
Anthropic — modelos Claude (API direta, OAuth via hermes auth add anthropic, OpenRouter ou qualquer proxy compatível)
Google — modelos Gemini (API direta pelo provedor gemini, OpenRouter ou proxy compatível)
z.ai / ZhipuAI — modelos GLM
Kimi / Moonshot AI — modelos Kimi
MiniMax — endpoints global e da China
Modelos locais — via Ollama, vLLM, llama.cpp, SGLang ou qualquer servidor compatível com a OpenAI

Defina o seu provedor com hermes model ou editando o ~/.hermes/.env. Veja a referência de Variáveis de ambiente para todas as chaves de provedor.

Funciona no Windows/Android/Termux/na minha plataforma??

Veja Suporte de plataformas para a matriz completa de disponibilidade por plataforma.

Rodo o Hermes no WSL2. Qual é o melhor jeito de controlar o meu Chrome normal do Windows?

Prefira uma ponte MCP ao /browser connect.

Padrão recomendado:

rode o Hermes dentro do WSL2
continue usando o seu Chrome normal, já logado, no Windows
adicione o chrome-devtools-mcp como servidor MCP através do cmd.exe ou do powershell.exe
deixe o Hermes usar as ferramentas de navegador MCP resultantes

Isso é mais confiável do que tentar forçar o transporte de navegador nativo do Hermes a se conectar direto atravessando a fronteira WSL2/Windows.

Veja:

Os meus dados são enviados para algum lugar?

As chamadas de API vão somente para o provedor de LLM que você configurar (por exemplo, OpenRouter ou a sua instância local do Ollama). O Hermes Agent não coleta telemetria, dados de uso nem analytics. As suas conversas, memórias e skills ficam guardadas localmente em ~/.hermes/.

Dá para usar offline / com modelos locais?

Dá. Rode hermes model, escolha Custom endpoint e informe a URL do seu servidor:

hermes model
# Selecione: Custom endpoint (enter URL manually)
# API base URL: http://localhost:11434/v1
# API key: ollama
# Model name: qwen3.5:27b
# Context length: 64000   ← mínimo do Hermes; ajuste para a janela de contexto real do seu servidor

Ou configure direto no config.yaml:

model:
  default: qwen3.5:27b
  provider: custom
  base_url: http://localhost:11434/v1

O Hermes guarda o endpoint, o provedor e a URL base no config.yaml, então isso sobrevive a reinícios. Se o seu servidor local tem exatamente um modelo carregado, o /model custom detecta sozinho. Você também pode definir provider: custom no config.yaml — é um provedor de primeira classe, não um apelido para outra coisa.

Isso funciona com Ollama, vLLM, servidor do llama.cpp, SGLang, LocalAI e outros. Veja o guia de Configuração para os detalhes.

Quem usa Ollama

Se você define um num_ctx personalizado no Ollama (por exemplo, ollama run --num_ctx 64000), lembre de definir o comprimento de contexto correspondente no Hermes — o /api/show do Ollama informa o contexto máximo do modelo, não o num_ctx efetivo que você configurou.

Tempos limite com modelos locais

O Hermes detecta endpoints locais automaticamente e afrouxa os tempos limite de streaming (o tempo limite de leitura sobe de 120s para 1800s e a detecção de fluxo parado é desativada). Se você ainda esbarrar em tempos limite com contextos muito grandes, defina HERMES_STREAM_READ_TIMEOUT=1800 no seu .env. Veja o guia de LLM local para os detalhes.

Quanto custa?

O Hermes Agent em si é gratuito e de código aberto (licença MIT). Você paga só pelo uso da API de LLM do provedor que escolher. Modelos locais são totalmente gratuitos de rodar.

Várias pessoas podem usar uma instância só?

Podem. O gateway de mensagens permite que vários usuários interajam com a mesma instância do Hermes Agent por Telegram, Discord, Slack, WhatsApp ou Home Assistant. O acesso é controlado por listas de permissão (IDs de usuário específicos) e por pareamento em DM (o primeiro usuário a mandar mensagem toma o acesso).

Qual é a diferença entre memória e skills?

Memória guarda fatos — coisas que o agente sabe sobre você, os seus projetos e as suas preferências. As memórias são recuperadas automaticamente conforme a relevância.
Skills guardam procedimentos — instruções passo a passo de como fazer as coisas. As skills são lembradas quando o agente encontra uma tarefa parecida.

As duas persistem entre sessões. Veja Memória e Skills para os detalhes.

Dá para usar no meu próprio projeto Python?

Dá. Importe a classe AIAgent e use o Hermes programaticamente:

from run_agent import AIAgent

agent = AIAgent(model="anthropic/claude-opus-4.7")
response = agent.chat("Explique computação quântica brevemente")

Veja o guia da biblioteca Python para o uso completo da API.

Solução de problemas

Problemas de instalação

`hermes: command not found` depois da instalação

Causa: o seu shell não recarregou o PATH atualizado.

Solução:

# Recarregue o perfil do seu shell
source ~/.bashrc    # bash
source ~/.zshrc     # zsh

# Ou abra uma nova sessão de terminal

Se mesmo assim não funcionar, confira o local da instalação:

which hermes
ls ~/.local/bin/hermes

dica

O instalador acrescenta ~/.local/bin ao seu PATH. Se você usa uma configuração de shell fora do padrão, adicione export PATH="$HOME/.local/bin:$PATH" manualmente.

Versão do Python velha demais

Causa: o Hermes exige Python 3.11 ou mais recente.

Solução:

python3 --version   # Confira a versão atual

# Instale um Python mais novo
sudo apt install python3.12   # Ubuntu/Debian
brew install python@3.12      # macOS

O instalador cuida disso automaticamente — se você vê esse erro durante uma instalação manual, atualize o Python primeiro.

Os comandos do terminal dizem `node: command not found` (ou `nvm`, `pyenv`, `asdf`, …)

Causa: o Hermes monta um retrato do ambiente por sessão rodando bash -l uma vez na inicialização. Um shell de login do bash lê /etc/profile, ~/.bash_profile e ~/.profile, mas não carrega o ~/.bashrc — então ferramentas que se instalam ali (nvm, asdf, pyenv, cargo, exportações personalizadas de PATH) ficam invisíveis para o retrato. Isso acontece com mais frequência quando o Hermes roda sob o systemd ou em um shell mínimo, onde nada carregou antes o perfil de shell interativo.

Solução: o Hermes carrega o ~/.bashrc automaticamente por padrão. Se isso não bastar — por exemplo, você usa zsh e o seu PATH mora no ~/.zshrc, ou você inicializa o nvm a partir de um arquivo separado —, liste os arquivos extras a carregar no ~/.hermes/config.yaml:

terminal:
  shell_init_files:
    - ~/.zshrc                     # quem usa zsh: traz o PATH gerido pelo zsh para o retrato do bash
    - ~/.nvm/nvm.sh                # init direto do nvm (funciona em qualquer shell)
    - /etc/profile.d/cargo.sh      # arquivos rc de todo o sistema
  # Quando esta lista é definida, o carregamento automático padrão do ~/.bashrc NÃO é acrescentado —
  # inclua-o explicitamente se você quiser os dois:
  #   - ~/.bashrc
  #   - ~/.zshrc

Arquivos que não existem são pulados em silêncio. O carregamento acontece no bash, então arquivos que dependem de sintaxe exclusiva do zsh podem dar erro — se isso preocupa você, carregue só a parte que define o PATH (por exemplo, o nvm.sh do nvm diretamente) em vez do arquivo rc inteiro.

Para desativar o carregamento automático (só a semântica estrita de shell de login):

terminal:
  auto_source_bashrc: false

`uv: command not found`

Causa: o gerenciador de pacotes uv não está instalado ou não está no PATH.

Solução:

curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.bashrc

Erros de permissão negada durante a instalação

Causa: permissões insuficientes para escrever no diretório de instalação.

Solução:

# Não use sudo com o instalador — ele instala em ~/.local/bin
# Se você instalou com sudo antes, faça a limpeza:
sudo rm /usr/local/bin/hermes
# Depois rode de novo o instalador padrão
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

Problemas de provedor e modelo

O agente diz que uma "política do Hermes" ou as "guardas do Hermes" recusaram o meu pedido

Um modelo não consegue identificar de forma confiável por que recusou um pedido. Se a recusa aparece só na prosa do assistente, a afirmação de que uma política oculta do runtime do Hermes causou isso pode ser uma explicação alucinada ou uma restrição aplicada pelo modelo ou pelo provedor selecionado.

A aplicação de regras do Hermes é explícita: uma ação de ferramenta bloqueada devolve um erro de ferramenta nomeando o comando ou o caminho negado, e uma ação que exige aprovação mostra um pedido de aprovação. O Hermes não transforma silenciosamente esses controles de execução em uma camada geral de recusa de conteúdo. Controles no nível do provedor ainda podem valer quando configurados, como o Amazon Bedrock Guardrails.

Para isolar a origem:

Rode /status para confirmar o modelo e o provedor ativos.
Verifique se a recusa inclui um erro de ferramenta ou um pedido de aprovação de verdade do Hermes. Se for só prosa, não trate a atribuição do modelo como prova sobre o runtime.
Tente de novo em uma sessão nova com outro modelo ou provedor configurado. Uma recusa que muda conforme o modelo é comportamento do modelo/provedor, não um controle de execução do Hermes.
Se aparecer um erro explícito de ferramenta, use o texto exato dele ao relatar o problema.

Veja Segurança para os controles de execução documentados do Hermes e Provedores para a configuração de provedor.

O `/model` só mostra um provedor / não consigo trocar de provedor

Causa: o /model (dentro de uma sessão de conversa) só troca entre provedores que você já configurou. Se você só configurou o OpenRouter, é só isso que o /model vai mostrar.

Solução: saia da sua sessão e use hermes model no terminal para adicionar novos provedores:

# Saia antes da sessão de conversa do Hermes (Ctrl+C ou /quit)

# Rode o assistente completo de configuração de provedores
hermes model

# Isso permite: adicionar provedores, fazer OAuth, informar chaves de API, configurar endpoints

Depois de adicionar um provedor novo com hermes model, inicie uma sessão nova de conversa — o /model agora vai mostrar todos os provedores configurados.

Referência rápida

Você quer...	Use
Adicionar um provedor novo	`hermes model` (no terminal)
Informar/trocar chaves de API	`hermes model` (no terminal)
Trocar de modelo no meio da sessão	`/model <nome>` (dentro da sessão)
Trocar para outro provedor já configurado	`/model provedor:modelo` (dentro da sessão)

A chave de API não funciona

Causa: a chave está faltando, expirou, foi definida errada ou é de outro provedor.

Solução:

# Confira a sua configuração
hermes config show

# Configure o provedor de novo
hermes model

# Ou defina diretamente
hermes config set OPENROUTER_API_KEY sk-or-v1-xxxxxxxxxxxx

aviso

Confirme que a chave combina com o provedor. Uma chave da OpenAI não funciona no OpenRouter e vice-versa. Procure entradas conflitantes no ~/.hermes/.env.

Modelo indisponível / modelo não encontrado

Causa: o identificador do modelo está errado ou o modelo não está disponível no seu provedor.

Solução:

# Liste os modelos disponíveis no seu provedor
hermes model

# Defina um modelo válido
hermes config set HERMES_MODEL anthropic/claude-opus-4.7

# Ou especifique por sessão
hermes chat --model openrouter/meta-llama/llama-3.1-70b-instruct

Limite de taxa (erros 429)

Causa: você passou dos limites de taxa do seu provedor.

Solução: espere um pouco e tente de novo. Para uso contínuo, considere:

Melhorar o seu plano no provedor
Trocar para outro modelo ou provedor
Usar hermes chat --provider <alternativo> para direcionar a outro backend

Comprimento de contexto excedido

Causa: a conversa ficou longa demais para a janela de contexto do modelo, ou o Hermes detectou o comprimento de contexto errado para o seu modelo.

Solução:

# Comprima a sessão atual
/compress

# Ou comece uma sessão nova
hermes chat

# Use um modelo com janela de contexto maior
hermes chat --model openrouter/google/gemini-3-flash-preview

Se isso acontece já na primeira conversa longa, o Hermes pode estar com o comprimento de contexto errado para o seu modelo. Confira o que ele detectou:

Olhe a linha de inicialização da CLI — ela mostra o comprimento de contexto detectado (por exemplo, 📊 Context limit: 128000 tokens). Você também pode conferir com /usage durante uma sessão.

Para corrigir a detecção de contexto, defina o valor explicitamente:

# No ~/.hermes/config.yaml
model:
  default: nome-do-seu-modelo
  context_length: 131072  # a janela de contexto real do seu modelo

Ou, para endpoints personalizados, defina por modelo na entrada do provedor:

providers:
  meu-servidor:
    api: "http://localhost:11434/v1"
    models:
      qwen3.5:27b:
        context_length: 64000

(Configurações mais antigas usam a lista legada custom_providers: — ainda suportada e migrada automaticamente para providers:.)

Veja Detecção de comprimento de contexto para entender como a detecção automática funciona e todas as opções de sobreposição.

Problemas de terminal

Comando bloqueado como perigoso

Causa: o Hermes detectou um comando potencialmente destrutivo (por exemplo, rm -rf, DROP TABLE). Isso é um recurso de segurança.

Solução: quando aparecer o pedido, revise o comando e digite y para aprová-lo. Você também pode:

Pedir ao agente que use uma alternativa mais segura
Ver a lista completa de padrões perigosos na documentação de Segurança

dica

Isso está funcionando como deveria — o Hermes nunca roda comandos destrutivos em silêncio. O pedido de aprovação mostra exatamente o que vai ser executado.

O `sudo` não funciona pelo gateway de mensagens

Causa: o gateway de mensagens roda sem um terminal interativo, então o sudo não tem como pedir a senha.

Solução:

Evite sudo nas mensagens — peça ao agente que encontre alternativas
Se você precisa mesmo usar sudo, configure sudo sem senha para comandos específicos em /etc/sudoers
Ou passe para a interface de terminal nas tarefas administrativas: hermes chat

O backend do Docker não conecta

Causa: o daemon do Docker não está rodando ou o usuário não tem permissão.

Solução:

# Confira se o Docker está rodando
docker info

# Adicione o seu usuário ao grupo docker
sudo usermod -aG docker $USER
newgrp docker

# Verifique
docker run hello-world

Problemas de mensagens

O bot não responde às mensagens

Causa: o bot não está rodando, não está autorizado, ou o seu usuário não está na lista de permissões.

Solução:

# Veja se o gateway está rodando
hermes gateway status

# Inicie o gateway
hermes gateway start

# Procure erros nos logs
cat ~/.hermes/logs/gateway.log | tail -50

As mensagens não são entregues

Causa: problemas de rede, token do bot expirado ou webhook da plataforma mal configurado.

Solução:

Confirme que o token do seu bot é válido com hermes gateway setup
Confira os logs do gateway: cat ~/.hermes/logs/gateway.log | tail -50
Em plataformas baseadas em webhook (Slack, WhatsApp), garanta que o seu servidor é acessível publicamente

Confusão com a lista de permissões — quem pode falar com o bot?

Causa: o modo de autorização determina quem tem acesso.

Solução:

Modo	Como funciona
Lista de permissões	Só os IDs de usuário listados na configuração podem interagir
Pareamento por DM	O primeiro usuário a mandar mensagem em DM toma o acesso exclusivo
Aberto	Qualquer um pode interagir (não recomendado em produção)

Configure no ~/.hermes/config.yaml, nos ajustes do seu gateway. Veja a documentação de Mensagens.

O gateway não inicia

Causa: dependências faltando, conflitos de porta ou tokens mal configurados.

Solução:

# Instale as dependências centrais do gateway de mensagens
cd ~/.hermes/hermes-agent && uv pip install -e ".[messaging]"  # Telegram, Discord, Slack e dependências comuns do gateway

# Procure conflitos de porta
lsof -i :8080

# Verifique a configuração
hermes config show

WSL: o gateway fica caindo ou o `hermes gateway start` falha

Causa: o suporte a systemd do WSL não é confiável. Muitas instalações do WSL2 não têm o systemd habilitado e, mesmo quando têm, os serviços podem não sobreviver a reinícios do WSL ou a desligamentos por ociosidade do Windows.

Solução: use o modo em primeiro plano em vez do serviço do systemd:

# Opção 1: primeiro plano direto (o mais simples)
hermes gateway run

# Opção 2: persistente via tmux (sobrevive ao fechar o terminal)
tmux new -s hermes 'hermes gateway run'
# Reconecte depois: tmux attach -t hermes

# Opção 3: em segundo plano via nohup
nohup hermes gateway run > ~/.hermes/logs/gateway.log 2>&1 &

Se você quiser tentar o systemd mesmo assim, garanta que ele está habilitado:

Abra o /etc/wsl.conf (crie o arquivo se ele não existir)
Acrescente:
```
[boot]
systemd=true
```
No PowerShell: wsl --shutdown
Abra de novo o seu terminal WSL
Verifique: systemctl is-system-running deve dizer "running" ou "degraded"

Início automático ao ligar o Windows

Para um início automático confiável, use o Agendador de Tarefas do Windows para lançar o WSL + o gateway no logon:

Crie uma tarefa que rode wsl -d Ubuntu -- bash -lc 'hermes gateway run'
Defina o gatilho para o logon do usuário

macOS: o gateway não encontra o Node.js / o ffmpeg / outras ferramentas

Causa: os serviços do launchd herdam um PATH mínimo (/usr/bin:/bin:/usr/sbin:/sbin) que não inclui o Homebrew, o nvm, o cargo nem outros diretórios de ferramentas instaladas pelo usuário. Isso costuma quebrar a ponte do WhatsApp (node not found) ou a transcrição de voz (ffmpeg not found).

Solução: o gateway captura o PATH do seu shell quando você roda hermes gateway install. Se você instalou ferramentas depois de configurar o gateway, rode a instalação de novo para capturar o PATH atualizado:

hermes gateway install    # Refaz o retrato do seu PATH atual
hermes gateway start      # Detecta o plist atualizado e recarrega

Você pode verificar se o plist está com o PATH correto:

/usr/libexec/PlistBuddy -c "Print :EnvironmentVariables:PATH" \
  ~/Library/LaunchAgents/ai.hermes.gateway.plist

Problemas de desempenho

Respostas lentas

Causa: modelo grande, servidor de API distante ou prompt de sistema pesado com muitas ferramentas.

Solução:

Experimente um modelo mais rápido/menor: hermes chat --model openrouter/meta-llama/llama-3.1-8b-instruct
Reduza os conjuntos de ferramentas ativos: hermes chat -t "terminal"
Confira a sua latência de rede até o provedor
Em modelos locais, garanta que você tem VRAM de GPU suficiente

Uso alto de tokens

Causa: conversas longas, prompts de sistema verbosos ou muitas chamadas de ferramenta acumulando contexto.

Solução:

# Veja exatamente quanto custa o prompt fixo — detalhado por bloco
# (prompt de sistema, índice de skills, memória, esquemas de ferramentas). Roda offline.
hermes prompt-size

# Comprima a conversa para reduzir tokens
/compress

# Confira o uso de tokens da sessão
/usage

Se a linha de base já parece alta antes de você digitar qualquer coisa, esse é o orçamento do prompt fixo — o prompt de sistema mais os esquemas de ferramentas enviados em toda chamada. Rode hermes prompt-size para medir e depois enxugue: desative os conjuntos de ferramentas que você não usa (hermes tools) e desinstale ou desative as skills de que você não precisa (hermes skills).

dica

Use /compress com frequência em sessões longas. Ele resume o histórico da conversa e reduz bastante o uso de tokens, preservando o contexto.

A sessão está ficando longa demais

Causa: conversas prolongadas acumulam mensagens e saídas de ferramenta, chegando perto dos limites de contexto.

Solução:

# Comprima a sessão atual (preserva o contexto principal)
/compress

# Comece uma sessão nova com uma referência à antiga
hermes chat

# Retome uma sessão específica depois, se precisar
hermes chat --continue

Problemas com MCP

O servidor MCP não conecta

Causa: binário do servidor não encontrado, caminho de comando errado ou runtime ausente.

Solução:

# Garanta que as dependências de MCP estão instaladas (já vêm na instalação padrão)
cd ~/.hermes/hermes-agent && uv pip install -e ".[mcp]"

# Em servidores baseados em npm, garanta que o Node.js está disponível
node --version
npx --version

# Teste o servidor manualmente
npx -y @modelcontextprotocol/server-filesystem /tmp

Verifique a configuração de MCP no seu ~/.hermes/config.yaml:

mcp_servers:
  filesystem:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/docs"]

As ferramentas do servidor MCP não aparecem

Causa: o servidor iniciou mas a descoberta de ferramentas falhou, as ferramentas foram filtradas pela configuração, ou o servidor não suporta a capacidade MCP que você esperava.

Solução:

Procure erros de conexão MCP nos logs do gateway/agente
Garanta que o servidor responde ao método RPC tools/list
Revise quaisquer ajustes de tools.include, tools.exclude, tools.resources, tools.prompts ou enabled daquele servidor
Lembre que as ferramentas utilitárias de recurso/prompt só são registradas quando a sessão realmente suporta essas capacidades
Use /reload-mcp depois de mudar a configuração

# Verifique se os servidores MCP estão configurados
hermes config show | grep -A 12 mcp_servers

# Reinicie o Hermes ou recarregue o MCP depois de mudar a configuração
hermes chat

Veja também:

Erros de tempo limite no MCP

Causa: o servidor MCP está demorando demais para responder, ou travou durante a execução.

Solução:

Aumente o tempo limite na configuração do seu servidor MCP, se ele suportar isso
Verifique se o processo do servidor MCP ainda está rodando
Em servidores MCP HTTP remotos, confira a conectividade de rede

aviso

Se um servidor MCP trava no meio de uma requisição, o Hermes vai relatar um tempo limite. Confira os logs do próprio servidor (não só os do Hermes) para diagnosticar a causa raiz.

Perfis

Qual a diferença entre perfis e simplesmente definir HERMES_HOME?

Perfis são uma camada gerenciada em cima do HERMES_HOME. Você poderia definir manualmente HERMES_HOME=/algum/caminho antes de cada comando, mas os perfis cuidam de toda a encanação para você: criam a estrutura de diretórios, geram apelidos de shell (hermes-work), registram o perfil ativo em ~/.hermes/active_profile e sincronizam automaticamente as atualizações de skills entre todos os perfis. Eles também se integram ao autocompletar, então você não precisa decorar caminhos.

Não. Cada plataforma de mensagens (Telegram, Discord, etc.) exige acesso exclusivo a um token de bot. Se dois perfis tentarem usar o mesmo token ao mesmo tempo, o segundo gateway não vai conseguir conectar. Crie um bot separado por perfil — no Telegram, fale com o @BotFather para criar bots adicionais.

Não. Cada perfil tem o seu próprio repositório de memória, banco de dados de sessões e diretório de skills. Eles são completamente isolados. Se você quer começar um perfil novo com as memórias e sessões existentes, use hermes profile create newname --clone-all para copiar tudo do perfil atual, ou acrescente --clone-from <perfil> para copiar de um perfil de origem específico.

Esse isolamento também é o motivo para nunca rodar dois agentes contra o mesmo perfil ou a mesma home do Hermes: os dois escrevem memória automaticamente e cada um carrega as escritas do outro no início da sessão, então o estado guardado se degrada a cada sessão. Um agente por perfil; para memória de fato compartilhada entre agentes, use um provedor de memória externo.

O que acontece quando eu rodo `hermes update`?

O hermes update baixa o código mais recente e reinstala as dependências uma vez (não por perfil). Depois ele sincroniza automaticamente as skills atualizadas em todos os perfis. Você só precisa rodar hermes update uma vez — ele cobre todos os perfis da máquina.

Quantos perfis eu posso rodar?

Não existe limite rígido. Cada perfil é apenas um diretório dentro de ~/.hermes/profiles/. O limite prático depende do seu espaço em disco e de quantos gateways simultâneos o seu sistema aguenta (cada gateway é um processo Python leve). Rodar dezenas de perfis é tranquilo; cada perfil ocioso não consome recursos.

Fluxos de trabalho e padrões

Usar modelos diferentes para tarefas diferentes (fluxos multimodelo)

Cenário: você usa o GPT-5.4 no dia a dia, mas o Gemini ou o Grok escreve conteúdo melhor para redes sociais. Trocar de modelo manualmente toda vez é chato.

Solução: configuração de delegação. O Hermes pode direcionar os subagentes para outro modelo automaticamente. Defina isto no ~/.hermes/config.yaml:

delegation:
  model: "google/gemini-3-flash-preview"   # os subagentes usam este modelo
  provider: "openrouter"                    # provedor dos subagentes

Agora, quando você diz ao Hermes "escreva uma thread no Twitter sobre X" e ele cria um subagente com delegate_task, esse subagente roda no Gemini em vez do seu modelo principal. A sua conversa principal continua no GPT-5.4.

Você também pode ser explícito no seu prompt: "Delegue uma tarefa para escrever posts de rede social sobre o lançamento do nosso produto. Use o seu subagente para a escrita em si." O agente vai usar o delegate_task, que pega automaticamente a configuração de delegação.

Para trocas pontuais de modelo sem delegação, use o /model na CLI:

/model google/gemini-3-flash-preview    # troca nesta sessão
# ... escreva o seu conteúdo ...
/model openai/gpt-5.4                   # volta ao anterior

aviso

Cada troca com /model zera o cache de prompt — a chave do cache inclui o modelo, então a primeira mensagem depois de cada troca relê a conversa inteira pelo preço cheio de entrada. Em sessões longas, prefira delegação (os subagentes ganham o próprio contexto novo) ou uma sessão nova, em vez de ficar trocando para lá e para cá.

Veja Delegação para subagentes para mais detalhes de como a delegação funciona.

Rodar vários agentes em um número de WhatsApp só (vínculo por conversa)

Cenário: no OpenClaw, você tinha vários agentes independentes vinculados a conversas específicas do WhatsApp — um para o grupo da lista de compras da família, outro para a sua conversa privada. O Hermes faz isso?

Limitação atual: cada perfil do Hermes exige o seu próprio número/sessão de WhatsApp. Você não pode vincular vários perfis a conversas diferentes no mesmo número de WhatsApp — a ponte do WhatsApp (Baileys) usa uma sessão autenticada por número.

Alternativas:

Use um único perfil com troca de personalidade. Crie arquivos de contexto AGENTS.md diferentes ou use o comando /personality para mudar o comportamento por conversa. O agente enxerga em qual conversa está e consegue se adaptar.
Use tarefas de cron para atividades especializadas. Para acompanhar uma lista de compras, crie uma tarefa de cron que monitore uma conversa específica e cuide da lista — sem precisar de outro agente.
Use números separados. Se você precisa mesmo de agentes independentes, pareie cada perfil com o seu próprio número de WhatsApp. Números virtuais de serviços como o Google Voice funcionam para isso.
Use Telegram ou Discord em vez disso. Essas plataformas suportam vínculo por conversa de forma mais natural — cada grupo do Telegram ou canal do Discord ganha a própria sessão, e você pode rodar vários tokens de bot (um por perfil) na mesma conta.

Veja Perfis e configuração do WhatsApp para mais detalhes.

Controlar o que aparece no Telegram (escondendo logs e raciocínio)

Cenário: você vê logs de execução do gateway, o raciocínio do Hermes e detalhes de chamadas de ferramenta no Telegram, em vez de só a saída final.

Solução: o ajuste display.tool_progress no config.yaml controla quanta atividade de ferramenta aparece:

display:
  tool_progress: "off"   # opções: off, new, all, verbose

off — só a resposta final. Sem chamadas de ferramenta, sem raciocínio, sem logs.
new — mostra as novas chamadas de ferramenta conforme acontecem (linhas curtas).
all — mostra toda a atividade de ferramenta, inclusive os resultados.
verbose — detalhe completo, com argumentos e saídas das ferramentas.

Em plataformas de mensagens, off ou new costuma ser o que você quer. Depois de editar o config.yaml, reinicie o gateway para as mudanças valerem.

Você também pode alternar isso por sessão com o comando /verbose (se estiver habilitado):

display:
  tool_progress_command: true   # habilita o /verbose no gateway

Gerenciar skills no Telegram (limite de comandos de barra)

Cenário: o Telegram tem um limite de 100 comandos de barra e as suas skills estão passando disso. Você quer desativar as skills de que não precisa no Telegram, mas os ajustes de hermes skills config parecem não fazer efeito.

Solução: use hermes skills config para desativar skills por plataforma. Isso escreve no config.yaml:

skills:
  disabled: []                    # skills desativadas globalmente
  platform_disabled:
    telegram: [skill-a, skill-b]  # desativadas só no telegram

Depois de mudar isso, reinicie o gateway (hermes gateway restart ou encerre e suba de novo). O menu de comandos do bot do Telegram é reconstruído na inicialização.

dica

Skills com descrições muito longas são truncadas em 40 caracteres no menu do Telegram, para caber nos limites de tamanho de payload. Se as skills não aparecem, pode ser um problema de tamanho total do payload, e não do limite de 100 comandos — desativar skills não usadas ajuda nos dois casos.

Sessões de thread compartilhadas (vários usuários, uma conversa)

Cenário: você tem uma thread no Telegram ou no Discord onde várias pessoas mencionam o bot. Você quer que todas as menções naquela thread façam parte de uma conversa compartilhada, e não de sessões separadas por usuário.

Comportamento atual: o Hermes cria sessões chaveadas por ID de usuário na maioria das plataformas, então cada pessoa ganha o seu próprio contexto de conversa. Isso é intencional, por privacidade e isolamento de contexto.

Alternativas:

Use o Slack. As sessões do Slack são chaveadas por thread, não por usuário. Vários usuários na mesma thread compartilham uma conversa — exatamente o comportamento que você descreveu. É o encaixe mais natural.
Use um grupo com um único usuário. Se uma pessoa é a "operadora" designada e repassa as perguntas, a sessão continua unificada. As outras podem acompanhar a leitura.
Use um canal do Discord. As sessões do Discord são chaveadas por canal, então todos os usuários do mesmo canal compartilham contexto. Use um canal dedicado para a conversa compartilhada.

Exportar o Hermes para outra máquina

Cenário: você acumulou skills, tarefas de cron e memórias em uma máquina e quer mover tudo para uma máquina Linux nova e dedicada.

Solução:

Instale o Hermes Agent na máquina nova:

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

Na máquina de origem, crie um backup completo:
```
hermes backup
```
Isso cria um zip de todo o seu diretório ~/.hermes/ — configuração, chaves de API, memórias, skills, sessões e perfis — salvo no seu diretório pessoal como ~/hermes-backup-<timestamp>.zip.

Copie o zip para a máquina nova e importe:

# Na máquina de origem
scp ~/hermes-backup-<timestamp>.zip maquinanova:~/

# Na máquina nova
hermes import ~/hermes-backup-<timestamp>.zip

Na máquina nova, rode hermes setup para conferir se as chaves de API e a configuração de provedor estão funcionando.

Mover um único perfil para outra máquina

Cenário: você quer mover ou compartilhar um perfil específico — não a instalação inteira.

# Na máquina de origem
hermes profile export work ./work-backup.tar.gz

# Copie o arquivo para a máquina de destino e então:
hermes profile import ./work-backup.tar.gz work

O perfil importado vai ter toda a configuração, as memórias, as sessões e as skills da exportação. Você pode precisar atualizar caminhos ou se autenticar de novo nos provedores, se a máquina nova tiver uma configuração diferente.

`hermes backup` vs. `hermes profile export`

Recurso	`hermes backup`	`hermes profile export`
Caso de uso	Migração completa de máquina	Portar/compartilhar um perfil específico
Escopo	Global (todo o diretório `~/.hermes`)	Local (diretório de um único perfil)
Inclui	Todos os perfis, configuração global, chaves de API, sessões	Um único perfil: SOUL.md, memórias, sessões, skills
Credenciais	Incluídas (`.env` e `auth.json`)	Excluídas (removidas para compartilhamento seguro)
Formato	`.zip`	`.tar.gz`

Alternativa manual (rsync): se você prefere copiar os arquivos diretamente, exclua o repositório de código:

rsync -av --exclude='hermes-agent' ~/.hermes/ maquinanova:~/.hermes/

dica

O hermes backup produz um retrato consistente mesmo com o Hermes rodando. O arquivo restaurado exclui arquivos de runtime locais da máquina, como gateway.pid e cron.pid.

Permissão negada ao recarregar o shell depois da instalação

Cenário: depois de rodar o instalador do Hermes, o source ~/.zshrc dá erro de permissão negada.

Causa: isso costuma acontecer quando o ~/.zshrc (ou o ~/.bashrc) está com as permissões de arquivo erradas, ou quando o instalador não conseguiu escrever nele direito. Não é um problema específico do Hermes — é uma questão de permissão na configuração do shell.

Solução:

# Confira as permissões
ls -la ~/.zshrc

# Corrija se precisar (deve ser -rw-r--r-- ou 644)
chmod 644 ~/.zshrc

# Depois recarregue
source ~/.zshrc

# Ou simplesmente abra uma janela nova de terminal — ela pega as mudanças de PATH sozinha

Se o instalador acrescentou a linha do PATH mas as permissões estão erradas, você pode adicioná-la manualmente:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc

Erro 400 na primeira execução do agente

Cenário: a configuração termina sem problema, mas a primeira tentativa de conversa falha com HTTP 400.

Causa: normalmente é uma divergência de nome de modelo — o modelo configurado não existe no seu provedor, ou a chave de API não tem acesso a ele.

Solução:

# Veja qual modelo e qual provedor estão configurados
hermes config show | head -20

# Rode de novo a seleção de modelo
hermes model

# Ou teste com um modelo que você sabe que funciona
hermes chat -q "olá" --model anthropic/claude-opus-4.7

Se você usa o OpenRouter, confirme que a sua chave de API tem créditos. Um 400 do OpenRouter muitas vezes significa que o modelo exige um plano pago ou que o ID do modelo tem um erro de digitação.

Ainda travado?

Se o seu problema não está coberto aqui:

Procure nas issues existentes: GitHub Issues
Pergunte à comunidade: Discord da Nous Research
Abra um relato de bug: inclua o seu sistema operacional, a versão do Python (python3 --version), a versão do Hermes (hermes --version) e a mensagem de erro completa