O Hermes Agent (abre em nova aba) é um agente de IA de código aberto que combina modelo de linguagem, memória, ferramentas, permissões e capacidade de executar ações — inclusive comandos reais no terminal. Este guia mostra o que ele é, quais componentes o formam e como colocá-lo em execução em Windows e Linux, do zero até a verificação final.
Para quem é este guia
Este guia é para desenvolvedores, profissionais de dados e equipes técnicas que já usam terminal e querem aplicar IA na prática, com controle do que o agente pode ler e executar. Se você já sabe o que é uma API key, uma variável de ambiente e um contêiner Docker, o material flui sem obstáculos.
Ao final, você será capaz de: explicar a diferença entre um chatbot e um agente; preparar um ambiente local ou em servidor; configurar um provedor de modelo; configurar um canal de mensagens (Telegram como exemplo) para conversar com o agente; e inspecionar o estado do serviço. Você não vai precisar de outra fonte para cumprir o roteiro, mas manter a documentação oficial aberta é boa prática para versões mais novas.
Uma observação de enquadramento: um chatbot responde, enquanto um agente pode executar a ação errada. Ferramentas como Hermes Agent, OpenClaw e Grok Bot podem, dependendo da configuração, navegar na internet, abrir arquivos, operar navegadores autenticados, consultar e-mails, executar comandos e interagir com sistemas externos. Esse poder exige menor privilégio, isolamento e aprovação humana onde o impacto for alto. O guia trata isso em cada passo.
Pré-requisitos
Não existe, segundo as evidências disponíveis, um requisito de versão mínima fixada para o Hermes Agent; trate como referência a documentação oficial da sua distribuição e do projeto. Se algum comando abaixo divergir da sua instalação, priorize o que está no README do repositório.
O que você vai construir
Ao final deste roteiro, você terá:
- O Hermes Agent em execução em um contêiner, acessível por uma interface Web (WebUI) e/ou por um bot do Telegram;
- um provedor de modelo configurado (Base URL, API Key, modo de compatibilidade e nome do modelo);
- o gateway de mensagens configurado para que você converse com o agente pelo Telegram;
- comandos de verificação para confirmar que o agente responde e que a memória está operando;
- uma lista de checagens de segurança para reduzir o raio de impacto (blast radius) antes de dar ao agente acesso a arquivos, e-mails ou sistemas sensíveis.
Segundo a documentação do ZimaOS, o Hermes Agent aprende e se lembra das conversas, roda 24 horas por dia no hardware do usuário e mantém os dados localmente. O Hermes Desktop, repositório companheiro, é a interface desktop para esse agente.
Passo a passo
Passo 1 — Entenda os componentes antes de instalar
Antes de digitar comandos, saiba o que cada peça faz. Isso evita erros de configuração que só aparecem depois, no meio de uma tarefa.
| Componente | Função | Onde se configura |
|---|---|---|
| Modelo (LLM) | Gera as decisões e o texto | Provedor, Base URL, API Key, modelo |
| Memória | Retém o contexto das conversas entre sessões | Configuração inicial do agente |
| Ferramentas / skills | Terminal, arquivos, navegador, APIs | Permissões e ambiente |
| Gateway | Conecta o agente a canais de mensagem (Telegram) | hermes gateway setup |
| WebUI | Interface web para configurar e conversar | Navegador, no host |
Um agente é modelo + memória + ferramentas + permissões + ação. Cada combinação de ferramentas cria uma rota de exposição: arquivos com internet, arquivos com e-mail, banco de dados com mensageria. O risco raramente está em uma capacidade isolada; está na combinação. Guarde essa ideia para o Passo 7.
Passo 2 — Acesse o host por SSH (Linux) ou pelo WSL (Windows)
No Linux, conecte-se ao host onde o contêiner vai rodar. O SSH facilita copiar e colar comandos longos.
ssh <usuario>@<ip>
# Exemplo (substitua usuario e ip reais)
# ssh [email protected]Na primeira conexão, digite yes na pergunta de confirmação e pressione Enter. No Windows, abra o terminal do WSL2 e siga os mesmos comandos. Para instalar o WSL2, use a documentação oficial da Microsoft.
Passo 3 — Obtenha privilégios para acessar o contêiner
Se o seu usuário não executa docker diretamente, mude para root. Esses privilégios servem apenas para entrar no contêiner no host.
sudo -i
# O prompt deve indicar que você é rootPasso 4 — Entre no contêiner do Hermes
Alterne para o usuário hermes dentro do contêiner. Todo o restante da configuração ocorre ali dentro.
docker exec -it -u hermes hermes bash
# O prompt muda; você agora está dentro do contêinerSe sair sem querer no meio do processo, execute o mesmo comando novamente. Em seguida, ative o ambiente virtual do Hermes.
source /opt/hermes/.venv/bin/activate
# Depois disso, o executavel 'hermes' fica disponivel na shellCom o ambiente virtual ativo, o comando hermes passa a ser reconhecido diretamente.
Passo 5 — Inicie o assistente de configuração
Execute o assistente dentro do contêiner. Ele conduz você pela configuração inicial.
hermes setupSelecione Quick setup para começar. O item destacado é a opção atual; pressione Enter para confirmar.
5.1 — Serviço de modelo
Escolha o provedor de modelo correspondente. Você pode usar um provedor personalizado como exemplo. Na sequência, informe a Base URL e a API Key. Depois escolha o modo de compatibilidade da API.
Na escolha do modelo, selecione o que pretende usar. Em seguida, informe o comprimento do contexto — pode pressionar Enter para detecção automática. Defina o nome de apresentação e o backend do terminal; o padrão costuma ser suficiente.
5.2 — Plataforma de mensagens (exemplo com Telegram)
O gateway conecta o agente a canais de mensagem. O Telegram é o exemplo documentado.
hermes gateway setupEscolha a plataforma e siga as perguntas. Quando o bot estiver configurado, envie /start no Telegram para iniciar a conversa. Se algo sair do previsto, consulte a documentação do ZimaOS para o fluxo completo, inclusive o pedido de confirmação.
Passo 6 — Confirme o estado dos serviços
Antes de usar o agente em tarefas reais, inspecione os contêineres em execução. Este passo retorna dados do seu próprio ambiente — não invente números; observe a saída.
docker ps --format 'table {{.Names}}\t{{.Status}}'
# Procure o contêiner do Hermes na listaConfirme também que a WebUI responde no host. O endereço exato depende da sua instalação; verifique o README do projeto. Se você configurou o Telegram, use o chat do bot como teste mais direto.
Passo 7 — Defina permissões e limite o raio de impacto
Este passo não é opcional em ambientes com dados de terceiros. Antes de liberar um agente, faça um inventário do que ele pode ler, decidir e executar: arquivos, pastas, e-mails, navegadores, sessões abertas, APIs, canais de mensagem, banco de dados, tarefas agendadas e conectores.
Separe as permissões por efeito operacional. Se o agente obedecesse a uma instrução errada no pior momento, qual seria o dano? Se o efeito é apenas uma análise incorreta, a revisão humana pode bastar. Se envolve apagar documentos, enviar informações a destinatário inadequado ou transmitir uma obrigação, a arquitetura deve impedir tecnicamente essa ação. Comece com dados de coordenação; evite, no piloto, credenciais de folha de pagamento ou dados de identidade.
O princípio prático é: o agente deve receber apenas o acesso necessário para cumprir uma tarefa delimitada, nunca todos os acessos que talvez pudesse usar.
Se você precisa de um controle adicional, configure aprovação humana para ações de alto impacto (exclusões, envios externos, transações) e mantenha os logs de execução acessíveis para auditoria.
Passo 8 — Teste uma tarefa delimitada
Crie um teste com impacto baixo antes de produzir trabalho real. Um bom primeiro teste usa dados de exemplo e não toca em sistemas externos.
# Exemplo de tarefa inicial dentro do agente (via WebUI ou Telegram):
# "Liste os arquivos do diretório atual e resuma o que cada um faz."
# Observe: não há comandos destrutivos neste teste.Verifique se o agente mantém o contexto em uma segunda interação — por exemplo, pedindo um resumo da conversa anterior. É essa memória que o diferencia de um chatbot.
Como verificar se funcionou
Há três sinais de sucesso. Verifique-os na ordem:
- Modelo configurado: o assistente concluiu a configuração sem erro e o agente responde a uma pergunta simples.
- Gateway ativo: ao enviar
/startno Telegram, o bot responde. Se não responder, revise o token e as permissões do bot. - Memória: peça um resumo da conversa anterior em uma nova mensagem. Se o agente recuperar o contexto, a memória está operando.
Para inspeção técnica, use docker ps para confirmar que o contêiner não está reiniciando e consulte os logs do contêiner do Hermes. O comando exato de log varia por instalação; confira no README do projeto. Não presuma que um agente está saudável só porque não houve mensagem de erro: faça o teste funcional.
Erros comuns e soluções
| Problema | Causa provável | Solução |
|---|---|---|
hermes não é reconhecido | Ambiente virtual não ativado | Execute source /opt/hermes/.venv/bin/activate dentro do contêiner |
| Falha ao entrar no contêiner | Usuário sem permissão Docker | Use sudo -i e tente novamente |
| Agente responde mas não lembra | Memória mal configurada | Refaça a configuração inicial e teste com duas mensagens encadeadas |
| Bot do Telegram não responde | Gateway sem token válido | Revise o token pelo @BotFather e reexecute hermes gateway setup |
| Erros de API do modelo | Base URL ou modo de compatibilidade incorretos | Confira a Base URL do provedor e o modo de compatibilidade no Passo 5 |
| Saída truncada do modelo | Comprimento de contexto subestimado | Reconfigure o contexto ou deixe a detecção automática |
Próximos passos
Depois de verificar a instalação, aprofunde em três direções. Primeiro, amplie ferramentas de forma deliberada: adicione uma skill de cada vez e documente o que ela lê e escreve. Segundo, formalize a política de permissões — quem aprova a criação de uma nova conexão, quais ações exigem confirmação e onde os logs ficam retidos. Terceiro, reproduza o mesmo fluxo em um segundo ambiente (por exemplo, local + servidor) para detectar dependências não documentadas.
Para uma visão mais ampla de como avaliar agentes antes de expô-los a processos reais, o material sobre MCP Registry (abre em nova aba) discute registro e descoberta de ferramentas — útil quando o número de conectores cresce. E, antes de conectar o agente a sistemas de terceiros, volte ao Passo 7 e pergunte qual seria o pior efeito de uma decisão automática errada nesse sistema. A resposta orienta o nível de controle a implementar.