Ambientes de execução para agentes autônomos costumam priorizar distribuições Linux e contêineres Docker, empurrando usuários de outros ecossistemas para máquinas virtuais ou camadas de compatibilidade. Há quem veja nessa centralização em Linux uma barreira técnica desnecessária para operadores de desktop. Outros defendem que padronizar em servidores POSIX evita incompatibilidades de chamadas de sistema e bibliotecas compiladas. O ecossistema de ferramentas, contudo, começou a se mover para acomodar o usuário corporativo em sua estação diária de trabalho.
O Windows permanece como a estação primária de trabalho de boa parte dos desenvolvedores corporativos e analistas de dados. Trazer agentes de raciocínio diretamente para o sistema operacional da Microsoft viabiliza integrações com processos locais sem a sobrecarga de gerenciar hipervisores.
Nous Research (abre em nova aba) estruturou o Hermes Agent (abre em nova aba) para funcionar tanto via linha de comando quanto em interface gráfica no Windows, suportando conexões diretas com plataformas de mensagens. A integração com o WhatsApp permite transformar o agente em um assistente pessoal ou em um canal de automação para equipes, operando sem a infraestrutura burocrática de contas empresariais de nuvem.
Arquitetura e pré-requisitos no ambiente Windows
A execução nativa do Hermes Agent no Windows não exige a inicialização do Subsistema do Windows para Linux (WSL2), embora o projeto ofereça suporte a esse caminho. Na instalação nativa pura, os binários, ambientes virtuais e arquivos de configuração ficam centralizados no diretório %LOCALAPPDATA%\hermes. Caso o operador prefira isolar a execução dentro de uma distribuição Linux sob WSL2, a estrutura é gravada em ~/.hermes.
Dois pontos de entrada compõem o sistema: a interface de terminal direta, invocada pelo comando hermes, e o serviço de mensageria em segundo plano, chamado gateway. O gateway conecta modelos de linguagem a clientes como Telegram, Discord, Slack e WhatsApp.
Para a conexão com o WhatsApp, o Hermes Agent utiliza a biblioteca Baileys, uma implementação em TypeScript que emula o protocolo de WebSockets do WhatsApp Web. Essa abordagem elimina a necessidade de obter um token na Meta Cloud API, dispensando verificação de empresa ou aprovação formal de modelos de mensagem. A autenticação depende exclusivamente da leitura de um QR code gerado no terminal pelo aparelho celular principal.
Antes de rodar instaladores externos via PowerShell, confira a política de execução de scripts do usuário atual. Políticas restritivas impedem o carregamento de instaladores remotos.
Get-ExecutionPolicy -Scope CurrentUserSe a saída for Restricted ou Undefined, libere temporariamente a execução de scripts remotos assinados para o escopo do seu usuário:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUserEssa mudança permite que o script de configuração inicial rode sem interferências das permissões padrão do PowerShell.
Escolha do método de instalação no Windows
Existem dois caminhos oficiais para implantar o Hermes Agent no Windows. O primeiro consiste no instalador gráfico MSIX com suporte a atualizações contínuas via App Installer. O segundo é a instalação direta via script em PowerShell, indicada para quem opera predominantemente pelo terminal.
Método 1: Pacote desktop com instalador MSIX
A instalação gráfica distribui a aplicação através de um arquivo .appinstaller. Esse pacote orienta o Windows App Installer a baixar e registrar o pacote MSIX assinado digitalmente pelo projeto, gerenciando o ciclo de vida e a busca automática por novas versões.
- Acesse o portal oficial do Hermes Agent.
- Baixe o instalador destinado ao Windows (
.appinstaller). - Dê um duplo clique no arquivo baixado para disparar o assistente de instalação do Windows.
- Confirme as permissões solicitadas na tela e aguarde o término do download dos componentes nativos.
Ao final do processo, o Hermes Desktop estará registrado no menu Iniciar do Windows. Essa instalação inclui as ferramentas de linha de comando no ambiente de execução interna, permitindo interações híbridas entre tela e prompt.
Método 2: Instalação nativa via PowerShell
Para administradores de sistemas e desenvolvedores que preferem configurar servidores Windows ou estações sem interface gráfica desnecessária, o instalador CLI configura todos os utilitários de uma só vez.
Abra o PowerShell como usuário comum (sem necessidade de privilégios de administrador de domínio) e execute o comando abaixo:
iex (irm https://hermes-agent.nousresearch.com/install.ps1)O comando baixa a rotina de provisionamento remota via Invoke-RestMethod (irm) e executa o bloco no interpretador por meio de Invoke-Expression (iex). Durante esse procedimento, os utilitários de execução são compilados e depositados na pasta local:
dir "$env:LOCALAPPDATA\hermes"Os arquivos do sistema, scripts de suporte e configurações persistentes residirão nesse local.
Se você iniciou a configuração apenas pela linha de comando e posteriormente desejar utilizar a interface gráfica oficial sem refazer o provisionamento, execute:
hermes desktopO utilitário baixará os módulos visuais necessários e iniciará a aplicação gráfica mantendo os mesmos arquivos de configuração criados pelo terminal.
Configuração inicial do agente e do modelo de IA
Após concluir o instalador, feche e abra novamente a janela do PowerShell para que o caminho de execução (PATH) seja recarregado.
Teste a invocação do binário digitando:
hermesNa primeira execução, o assistente perguntará quais modelos de linguagem devem alimentar o raciocínio do agente. O sistema suporta provedores externos comerciais e instâncias de modelos abertos hospedadas localmente via endpoints compatíveis com a especificação da OpenAI.
Caso precise alterar qualquer parâmetro operacional posteriormente, quatro comandos centrais dividem as responsabilidades de reconfiguração:
hermes model: redefine o provedor de inteligência artificial, o identificador do modelo (por exemplo, modelos da família Nous Hermes, Claude ou GPT) e a chave de autenticação da API.hermes tools: habilita ou restringe o acesso do agente a ferramentas de sistema, como execução de comandos de terminal, navegação na web e manipulação de arquivos locais.hermes gateway setup: aciona o assistente de configuração de canais externos de comunicação, incluindo mensageiros.hermes setup: reinicia o processo completo de perguntas sobre credenciais e comportamento padrão.
Execute a definição do modelo:
hermes modelSiga as instruções exibidas, selecione o fornecedor desejado e insira sua credencial. O Hermes Agent salvará as configurações dentro de arquivos criptografados ou variáveis de ambiente locais.
Integração com o WhatsApp via gateway
O gateway do Hermes atua como um barramento de eventos assíncronos. Ele traduz mensagens recebidas de redes de terceiros em chamadas de raciocínio do modelo e devolve a resposta gerada ao remetente original.
No caso específico do WhatsApp, o agente oferece duas modalidades operacionais de atendimento:
- Modo Bot (
bot): o número conectado reage a mensagens recebidas de contatos autorizados, atuando como um interlocutor dedicado. - Modo Autoconversa (
self-chat): o agente responde a notas e mensagens enviadas pelo próprio titular para si mesmo (o recurso "Mensagem para mim mesmo" do WhatsApp), servindo como assistente particular sem interferir nas conversas de terceiros.
Para iniciar o processo guiado de vinculação, digite:
hermes whatsappO assistente interativo guiará os quatro passos fundamentais de conexão.
Primeiro, escolha entre bot e self-chat conforme sua intenção operacional.
Segundo, o instalador verificará a presença das dependências do Baileys e fará o download dos pacotes de emulação de navegador caso estejam ausentes.
Terceiro, um QR code em formato de texto será desenhado diretamente na janela do seu PowerShell.
Quarto, abra o aplicativo do WhatsApp no aparelho celular correspondente.
Navegue até Configurações (no iOS) ou Mais opções (os três pontos no Android) e selecione Aparelhos conectados.
Toque em Conectar um aparelho.
Aponte a câmera do telefone para o QR code desenhado na janela do terminal. Assim que a sincronização for concluída, a sessão de autenticação criptografada será salva no diretório de dados do Hermes.
Ajuste de variáveis no arquivo de ambiente
O assistente interativo preenche automaticamente os parâmetros principais, mas determinados controles de segurança devem ser inspecionados manualmente para evitar respostas indesejadas a desconhecidos.
As opções de mensageria residem no arquivo .env. Na instalação do Windows nativo, localize o arquivo executando:
notepad "$env:LOCALAPPDATA\hermes\.env"Caso você esteja operando sob o WSL2, o caminho equivalente será:
nano ~/.hermes/.envGaranta que as seguintes variáveis estejam preenchidas de acordo com sua necessidade:
WHATSAPP_ENABLED=true
WHATSAPP_MODE=bot
WHATSAPP_ALLOWED_USERS=5511999999999,5521988888888O formato de WHATSAPP_ALLOWED_USERS é crítico para a segurança.
O valor deve ser uma lista de números separados por vírgula, sem espaços, contendo o código do país (DDI) e o código de área (DDD), omitindo o sinal de adição (+) e quaisquer traços ou parênteses.
55 é o código internacional do Brasil. Se o número de telefone for (11) 99999-9999, o preenchimento correto é 5511999999999.
Se o parâmetro for deixado vazio, o comportamento padrão dependerá da versão instalada, podendo expor a automação a responder qualquer contato que envie uma mensagem para o chip pareado. Limite os remetentes exclusivamente aos números de teste e aos membros autorizados da equipe técnica.
Inicialização e execução do serviço de mensageria
Com as credenciais salvas e o pareamento ativo, o gateway pode ser iniciado em modo de depuração para inspeção visual de tráfego.
Inicie o processo pelo PowerShell:
hermes gatewayEssa chamada ativa o listener local. Enquanto o comando estiver em execução, qualquer mensagem recebida no WhatsApp vinda de um número listado em WHATSAPP_ALLOWED_USERS disparará a rotina de geração de resposta da LLM configurada, exibindo logs estruturados no console.
[Gateway] Conexão WhatsApp estabelecida com sucesso.
[Gateway] Mensagem recebida de: 5511999999999
[Agent] Processando requisição via modelo configurado...
[Gateway] Resposta enviada ao remetente.Para encerrar o monitoramento manual, pressione Ctrl + C na janela do PowerShell.
Se o objetivo for manter o Hermes Agent respondendo em segundo plano sem a dependência de uma janela de prompt aberta indefinidamente na área de trabalho, registre o gateway como um serviço do sistema:
hermes gateway installO comando registra uma tarefa em segundo plano gerenciada pelo próprio ciclo de vida do Windows, iniciando o listener de mensagens automaticamente na inicialização da máquina.
Validação prática do funcionamento
Para garantir que toda a cadeia de comunicação está operando conforme o planejado, execute um teste de ponta a ponta:
- Mantenha o gateway em execução via
hermes gateway. - Pegue o celular autorizado cujo número foi inserido em
WHATSAPP_ALLOWED_USERS. - Envie uma mensagem simples para o número que realizou o pareamento do QR code, como:
Qual é o status da sua execução local?. - Observe a saída do terminal no Windows. O console registrará o recebimento do payload pelo Baileys, o envio do prompt para a API do modelo e a devolução do texto.
- Verifique se a resposta chegou no chat do WhatsApp em poucos segundos.
Se o modo configurado tiver sido self-chat, abra o chat do seu próprio número no WhatsApp e envie a mensagem de teste lá. O agente deverá responder dentro da mesma conversa privada.
Diagnóstico de problemas frequentes
A operação de ponta a ponta pode apresentar falhas decorrentes de políticas de rede corporativa, alterações de permissão do sistema operacional ou mudanças na sessão remota de WebSockets.
Erro de execução de script no PowerShell
Se o comando de instalação iex (irm ...) retornar mensagens em vermelho indicando que a execução de scripts está desabilitada no sistema, a restrição de segurança do Windows está bloqueando o carregamento dinâmico.
Para resolver, execute explicitamente:
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
iex (irm https://hermes-agent.nousresearch.com/install.ps1)O parâmetro -Scope Process garante que a autorização dure apenas enquanto aquela janela de terminal estiver aberta, restaurando os padrões normais do sistema ao fechar o processo.
Falhas de renderização do QR Code no terminal
Fontes rasterizadas antigas no console clássico do Windows (conhost.exe) podem corromper os caracteres ASCII/ANSI usados para desenhar o QR code, tornando a imagem ilegível para o aplicativo do telefone.
Instale e utilize o Windows Terminal (disponível nativamente nas versões recentes do Windows 10 e Windows 11). Ele suporta fontes TrueType modernas (como Cascadia Code ou Consolas) e codificação UTF-8 completa.
Se o código continuar ilegível, reduza o tamanho da fonte do terminal nas configurações ou utilize a combinação Ctrl + Scroll do mouse para diminuir o zoom do console até que o bloco quadrado se torne nítido.
Desconexões e perda de pareamento
O WhatsApp periodicamente invalida conexões de emulação web caso o aparelho principal fique sem conexão com a internet por mais de 14 dias contínuos ou se houver divergência criptográfica na chave de sessão.
Quando o terminal registrar erros contínuos de handshake de WebSocket:
- Interrompa o gateway com
Ctrl + C. - Acesse a pasta
%LOCALAPPDATA%\hermes. - Reconfigure o canal executando novamente
hermes whatsapp. - Conecte um novo aparelho lendo o QR code renovado.
Conflitos com o formato dos números autorizados
Caso envie mensagens pelo WhatsApp e o console do gateway permaneça em silêncio, sem acusar recebimento, o filtro de usuários autorizados quase certamente descartou o pacote.
O erro mais comum reside no nono dígito do sistema de telefonia móvel brasileiro ou na inclusão inadvertida do caractere +.
Abra o arquivo de configuração e certifique-se de que a linha não contém símbolos adicionais:
# Incorreto:
WHATSAPP_ALLOWED_USERS=+55 (11) 99999-9999
# Correto:
WHATSAPP_ALLOWED_USERS=5511999999999Em determinadas regiões do Brasil, o identificador do WhatsApp para contas antigas pode omitir o dígito 9 no protocolo interno de identificação (JID). Se o seu número continuar sem resposta, adicione as duas variações separadas por vírgula no .env: a versão com o 9 e a versão sem o 9 (exemplo: 5511999999999,551199999999).
Próximos passos operacionais
Após estabelecer o fluxo de mensagens com estabilidade, configure o ferramental expandido do agente.
Execute no terminal:
hermes toolsNessa interface, ative recursos complementares como execução de scripts PowerShell, consultas SQL ou buscas em repositórios de dados locais. Conectar ferramentas ao agente transforma a conversa do WhatsApp em uma interface de comando remoto, permitindo que a IA inspecione logs de servidores, execute rotinas de manutenção ou resuma relatórios de bancos de dados diretamente na janela de bate-papo.
É necessário ponderar que a biblioteca Baileys opera por meio de engenharia reversa do protocolo do WhatsApp Web, sem homologação oficial da Meta. Essa característica confere facilidade imediata de implantação para testes internos e uso individual, mas mantém o serviço exposto a eventuais mudanças unilaterais nos servidores da plataforma, o que pode quebrar a ponte de comunicação ou levar à suspensão de números que apresentem tráfego com padrão estritamente automatizado.