Instalando o Hermes Agent no Windows com WSL2 e Ubuntu Link para o cabeçalho

Hermes dentro de uma casa diante de uma janela aberta com cores do Windows, segurando um pinguim que representa Linux.

O Hermes Agent é uma daquelas ferramentas que ficam no meio do caminho entre assistente pessoal, agente técnico e laboratório de automação. Ele conversa, usa ferramentas, mantém sessões, trabalha com provedores diferentes de modelo e pode crescer para fluxos mais avançados com gateway, skills, automações e integrações.

Este tutorial assume que você já tem Ubuntu rodando em WSL2. A escolha pelo Ubuntu aqui é pragmática: ele é uma das distribuições Linux mais usadas por desenvolvedores, tem documentação abundante, boa disponibilidade de pacotes e também aparece com frequência em ambientes de servidor. Para um tutorial de instalação, isso reduz atrito e facilita comparar erros, comandos e dependências com exemplos encontrados na documentação oficial e na comunidade.

Se essa base ainda não está pronta, comece pelo post de instalação e validação do WSL2:

WSL2 no Windows: Linux para desenvolvedores

Essa separação deixa cada coisa no seu lugar. O post de WSL2 explica como o Linux roda sobre o Windows, como abrir o Ubuntu, onde ficam /home e /mnt/c e como limitar memória. Aqui o foco é o próximo passo: instalar o Hermes dentro do Ubuntu/WSL2, autenticar com a conta ChatGPT/Codex e validar CLI, TUI, dashboard e Telegram.

A pegadinha principal continua valendo: no Windows, o caminho certo não é tentar instalar o Hermes direto no PowerShell como se fosse uma aplicação nativa. A documentação oficial do Hermes informa que Windows nativo não é suportado para esse fluxo; o caminho recomendado é executar o Hermes dentro de uma distribuição Linux, como Ubuntu no WSL2.

Se você já está em Linux fora do Windows, o caminho fica mais curto. Pode seguir a partir da instalação do Hermes, depois de garantir curl e git no sistema. Esse caminho tende a funcionar na maioria das distribuições Linux comuns, desde que o ambiente tenha os pré-requisitos esperados pelo instalador.

Vamos preparar o Ubuntu, rodar o instalador oficial do Hermes Agent e, no final, configurar o login usando a sua conta ChatGPT/Codex pelo provedor OpenAI Codex.

Quando pensar em VPS Link para o cabeçalho

WSL2 é excelente para desenvolvimento local, laboratório, testes e automações que dependem do seu computador ligado. Ele não é a melhor resposta para tudo.

Se a automação com Hermes precisa ficar ativa 24 por 7, responder mensagens sem depender do notebook, rodar tarefas agendadas com alta disponibilidade ou servir como agente persistente, aí vale estudar uma VPS dedicada. O caminho local com WSL2 é ótimo para aprender, validar e desenvolver; a VPS entra quando a necessidade cresce e o ambiente precisa ficar sempre online.

Antes de começar: onde cada comando roda Link para o cabeçalho

Essa é a parte mais importante do tutorial. Se você copiar o comando certo no terminal errado, o erro pode parecer mais misterioso do que realmente é.

Use esta regra:

PowerShell como Administrador: use para instalar ou atualizar o WSL.
PowerShell normal: use para conferir distribuições instaladas e versão do WSL.
Ubuntu/WSL: use para instalar e executar o Hermes.

O comando do Hermes com curl deve rodar dentro do Ubuntu/WSL, não no PowerShell nativo.

Pré-requisito: Ubuntu no WSL2 Link para o cabeçalho

Antes de começar, confirme no PowerShell normal:

wsl -l -v

A coluna VERSION deve mostrar 2 para o Ubuntu. Se aparecer 1, resolva isso primeiro pelo guia de WSL2. O Hermes até pode encontrar partes do caminho em outros ambientes, mas este tutorial foi escrito para Ubuntu em WSL2.

Você também precisa ter:

conexão com a internet;
acesso à sua conta ChatGPT/Codex, se pretende usar o provedor OpenAI Codex;
permissão de sudo dentro do Ubuntu;
alguns minutos para o instalador baixar dependências.

O Hermes também pode ser configurado com outros provedores, como OpenRouter, Nous Portal, Anthropic, GitHub Copilot e endpoints customizados. Aqui o foco é o caminho pedido: Hermes no Windows via WSL2 e login com a conta usada no Codex/ChatGPT.

Passo 1: preparar o Ubuntu Link para o cabeçalho

Agora abra o Ubuntu/WSL. Daqui em diante, os comandos são Linux.

Você pode fazer isso de três formas simples:

pelo Menu Iniciar do Windows, pesquisando por Ubuntu;
pelo Windows Terminal, clicando na seta ao lado da aba atual e escolhendo o perfil Ubuntu;
pelo PowerShell normal, chamando diretamente a distribuição:

wsl -d Ubuntu

Quando estiver no lugar certo, o prompt deixa de parecer PowerShell e passa a parecer um terminal Linux, algo como:

usuario@maquina:~$

Se quiser confirmar, rode:

pwd

Se a resposta começar com /home/..., você está dentro do Ubuntu. Para sair e voltar ao PowerShell depois, use exit.

Atualize a lista de pacotes:

sudo apt update

Instale curl e git:

sudo apt install -y curl git

Confirme o Git:

git --version

Confirme também a distribuição:

lsb_release -a

Confirmar Python, pip, venv e uv Link para o cabeçalho

O Hermes é instalado como uma aplicação Python. Em uma instalação comum do Ubuntu, o python3 costuma vir disponível, mas isso não é uma regra absoluta em imagens mínimas, containers, VPS enxutas ou instalações muito limpas do WSL. Além disso, mesmo quando o Python existe, o pip e o módulo venv podem não estar instalados.

Confira primeiro:

python3 --version
python3 -m pip --version

Se algum desses comandos falhar, instale a base Python no Ubuntu:

sudo apt update
sudo apt install -y python3 python3-pip python3-venv

Depois valide de novo:

python3 --version
python3 -m pip --version

O python3-venv merece uma explicação rápida. Um ambiente virtual Python é uma pasta isolada com um interpretador Python e dependências próprias. Ele evita instalar pacotes do Hermes diretamente no Python do sistema. Isso é importante porque agentes como o Hermes puxam várias bibliotecas, extras de dashboard, ferramentas auxiliares e versões específicas. Separar tudo em um venv reduz conflito com pacotes do Ubuntu, evita quebrar ferramentas do sistema e deixa a instalação mais fácil de atualizar ou remover.

O instalador oficial do Hermes normalmente cria esse ambiente virtual automaticamente dentro do diretório do Hermes. Você só precisa mexer nisso manualmente quando for instalar extras, como web e pty, ou quando estiver depurando uma instalação incompleta.

Também valide o uv, que é o gerenciador moderno usado no ecossistema Python para criar ambientes, instalar dependências e trabalhar com pacotes de forma mais rápida que o pip tradicional:

uv --version

Se o uv ainda não existir, instale pelo instalador oficial da Astral, dentro do Ubuntu/WSL:

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

Feche e abra o terminal Ubuntu novamente ou carregue o ambiente da sessão atual:

source "$HOME/.local/bin/env"

E confirme:

uv --version

Daqui em diante, quando o tutorial disser “rode no Linux”, entenda como “rode dentro desse Ubuntu no WSL2”.

A documentação do Hermes informa que Git é o pré-requisito manual principal. O instalador oficial cuida do restante do caminho padrão, incluindo Node.js, clone do repositório, ambiente virtual e comando global hermes. Ainda assim, deixar python3, pip, venv e uv validados antes reduz ruído quando você for instalar extras ou investigar problemas. Alguns recursos auxiliares, como ripgrep, ffmpeg e dependências completas de browser, podem depender de sudo no Ubuntu.

Passo 2: instalar o Hermes Agent Link para o cabeçalho

Ainda dentro do Ubuntu/WSL, rode o instalador oficial:

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

Em um terminal normal, esse é o caminho mais simples. Se você estiver automatizando a instalação em ambiente headless, sem interação humana, o instalador pode ficar aguardando algum prompt. Nesse caso, uma alternativa é baixar o script, executar sem assistente inicial e deixar a configuração para o hermes model:

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh -o /tmp/hermes-install.sh
chmod +x /tmp/hermes-install.sh
setsid bash /tmp/hermes-install.sh --skip-setup < /dev/null

Use essa alternativa só quando fizer sentido. Para a maioria dos usuários, o comando oficial com curl ... | bash é suficiente.

Quando terminar, recarregue o shell:

source ~/.bashrc

Se você usa zsh, o comando equivalente é:

source ~/.zshrc

Agora confira se o comando ficou disponível:

hermes --version

Se o terminal disser que hermes não foi encontrado, feche e abra o Ubuntu de novo. Se ainda falhar, verifique se ~/.local/bin está no PATH, porque é ali que o instalador por usuário costuma criar o atalho do comando.

Ao final da instalação, o Hermes pode oferecer um assistente de configuração. Para este tutorial, não tente configurar tudo de uma vez. Primeiro valide que o comando existe; depois use hermes model para configurar o provedor OpenAI Codex. Se você já instalou e quer voltar ao assistente depois, o comando é:

hermes setup

Em instalações já existentes, também existe o modo rápido, que pergunta apenas por itens ausentes ou ainda não configurados:

hermes setup --quick

Esse modo é útil para completar uma instalação, mas não substitui o fluxo principal deste post: hermes model, escolher OpenAI Codex e concluir o login pelo navegador.

Opcional: instalar recursos auxiliares Link para o cabeçalho

O Hermes básico não precisa de tudo isso para conversar. Depois que hermes --version funciona, você já pode seguir para o login no Codex. Ainda assim, alguns recursos extras deixam o ambiente mais completo.

`ripgrep`: busca rápida em arquivos Link para o cabeçalho

O ripgrep, chamado pelo comando rg, serve para busca rápida em código e arquivos. Agentes que leem projetos grandes costumam se beneficiar dele porque pesquisar com rg é muito mais eficiente do que cair no fallback com grep.

Se ele não estiver instalado, o Hermes não deixa de funcionar; o hermes doctor apenas avisa que vai usar fallback.

Instale no Ubuntu/WSL:

sudo apt update
sudo apt install -y ripgrep

Valide:

rg --version

`ffmpeg`: áudio, vídeo e conversões de mídia Link para o cabeçalho

O ffmpeg é usado para tarefas de mídia: converter áudio, preparar arquivos para transcrição, trabalhar com vídeo e dar suporte a ferramentas que dependem de processamento multimídia. Para chat de texto e login OpenAI Codex, ele não é obrigatório.

Instale:

sudo apt install -y ffmpeg

Valide:

ffmpeg -version

Browser/CDP: automação de navegador Link para o cabeçalho

Browser/CDP significa automação de navegador via Chrome DevTools Protocol. É o tipo de recurso usado quando o agente precisa abrir páginas, clicar em elementos, tirar screenshots, testar fluxos web ou inspecionar uma aplicação no navegador.

Isso é útil para automações mais avançadas, mas não é requisito para instalar o Hermes, logar com Codex, usar hermes chat ou configurar Telegram.

Para instalar as dependências de browser no ambiente do Hermes, rode no Ubuntu/WSL:

cd ~/.hermes/hermes-agent
npx playwright install --with-deps chromium

Esse comando pode pedir sudo, porque algumas dependências são pacotes do sistema Linux. Depois, valide:

hermes doctor

Se o doctor ainda mostrar browser ou browser-cdp como pendente, trate como pendência de ferramenta específica, não como falha da instalação principal.

Passo 3: logar com a conta ChatGPT/Codex Link para o cabeçalho

Depois que o binário existe, falta escolher o provedor de modelo. Para usar a conta do Codex/ChatGPT, o caminho documentado pelo Hermes é configurar o provedor OpenAI Codex pelo comando interativo:

hermes model

No menu, procure por OpenAI Codex. Não escolha pelo número da opção sem ler a tela, porque menus interativos mudam com o tempo.

Ao selecionar OpenAI Codex, o Hermes deve iniciar um fluxo de autenticação OAuth/device code. Esse é o ponto em que muita gente se perde, então pense nele como uma ponte entre o terminal Linux e o navegador:

mantenha o terminal aberto;
o Hermes mostra no terminal uma URL de autenticação, normalmente contendo /device ou apontando para uma página de ativação da OpenAI;
junto da URL, o terminal mostra um código curto de confirmação;
abra essa URL no navegador do Windows. No Windows Terminal, muitas vezes dá para usar Ctrl+clique; se não der, copie e cole a URL manualmente;
no site da OpenAI, informe o código mostrado no terminal quando a página pedir;
entre com a mesma conta OpenAI/ChatGPT que você usa no Codex;
autorize o acesso;
volte ao terminal e aguarde o Hermes concluir a configuração.

Não feche o terminal no meio desse processo. Ele fica esperando a confirmação do navegador para salvar a autenticação localmente.

Não cole a senha da sua conta no terminal. O fluxo correto acontece pelo navegador, com autorização da conta.

Depois disso, rode:

hermes status

O status mostra o estado atual do agente: diretório do projeto Hermes, modelo ativo, provedor escolhido, autenticações configuradas, plataformas de mensagem, gateway e sessões. Para este tutorial, o ponto mais importante é confirmar que o provedor aparece como OpenAI Codex e que a autenticação está marcada como logged in.

Depois rode:

hermes doctor

O doctor é o diagnóstico. Ele olha dependências, arquivos de configuração, autenticações, ferramentas externas, disponibilidade de toolsets e pendências opcionais. Em resumo: status responde “como o Hermes está configurado agora?”; doctor responde “o que está faltando ou pode quebrar?”.

Uma nota importante: Codex/ChatGPT não é a mesma coisa que OpenAI API key Link para o cabeçalho

Aqui mora uma confusão comum.

Logar no Hermes pelo provedor OpenAI Codex usa a sua conta ChatGPT/Codex via OAuth/device code, conforme a documentação do Hermes. Isso é diferente de configurar uma OPENAI_API_KEY.

A própria OpenAI separa ChatGPT e API Platform: a assinatura do ChatGPT e o faturamento/uso da API são gerenciados separadamente. A API tradicional usa chave de API e cobrança por uso na plataforma de desenvolvedores. Então, se você tem ChatGPT Plus, Pro, Business ou acesso ao Codex, isso não significa automaticamente que você configurou uma chave de API no Hermes.

Para este tutorial, o caminho principal é:

hermes model -> OpenAI Codex -> login no navegador

O caminho com API key é outro fluxo e só deve ser usado se você realmente quiser configurar um provedor baseado em chave ou endpoint compatível com OpenAI.

Por que usar OpenAI Codex em vez de Claude Code/Anthropic aqui Link para o cabeçalho

Isso não é uma crítica à qualidade dos modelos da Anthropic. Claude e Claude Code são excelentes ferramentas para desenvolvimento. O ponto deste tutorial é mais pragmático: usar o caminho mais direto, estável e documentado para o Hermes no Windows/WSL2.

Claude Code não deve ser tratado como “um login Claude que qualquer ferramenta pode reaproveitar”. Ele é o agente oficial da Anthropic, com cliente, credenciais e regras próprias.

A documentação oficial de legal/compliance do Claude Code deixa esse limite mais claro: OAuth do Claude Code/Claude.ai é para uso de assinantes Free, Pro, Max, Team e Enterprise no próprio Claude Code e nos aplicativos nativos da Anthropic. Para desenvolvedores criando produtos, serviços ou ferramentas externas, o caminho suportado é usar uma API key da Claude Console ou um provedor cloud compatível, como Bedrock, Vertex ou Microsoft Foundry. A Anthropic também afirma que terceiros não podem oferecer login Claude.ai nem rotear chamadas por credenciais Free/Pro/Max dos usuários, e se reserva o direito de aplicar essas restrições.

Então a frase correta não é “a Anthropic proibiu qualquer ferramenta de terceiro”. A leitura precisa é: a Anthropic restringe o uso de credenciais e assinaturas Claude.ai por ferramentas externas; para integrações de terceiros, o caminho suportado é API key ou provedor cloud autorizado.

Esse cuidado ficou mais visível depois do incidente com ferramentas de terceiros. Em janeiro de 2026, issues públicas em projetos como OpenClaw e OpenCode registraram que tokens OAuth vindos do Claude Code passaram a ser recusados fora do cliente autorizado. A mensagem de erro observada foi:

This credential is only authorized for use with Claude Code and cannot be used for other API requests.

No OpenClaw, a issue pública descreve que tokens OAuth sincronizados a partir do Claude Code deixaram de funcionar para chamadas externas. No OpenCode, uma issue semelhante pediu que a ferramenta detectasse credenciais específicas do Claude Code e orientasse o usuário a informar uma chave padrão da API da Anthropic. Em abril de 2026, reportagens também registraram uma mudança mais ampla: assinaturas Claude deixariam de cobrir certos usos em ferramentas externas como OpenClaw, empurrando esses fluxos para API key ou pacotes extras de uso. Essa reportagem é evidência jornalística; a base oficial, para o tutorial, é a regra de legal/compliance da própria Anthropic sobre credenciais e terceiros.

Em outras palavras: o problema não era “Claude é ruim”; o problema era credencial de Claude Code ou assinatura Claude.ai sendo usada fora do escopo suportado para aquela ferramenta.

No Hermes, a própria documentação também sinaliza uma diferença importante entre provedores. O provedor OpenAI Codex aparece como fluxo via hermes model, com OAuth/device code da conta ChatGPT/Codex e credenciais salvas pelo Hermes. Já o provedor Anthropic tem caminhos mais condicionais: API key Anthropic ou OAuth ligado a Claude Max com créditos extras. Há inclusive issues no repositório do Hermes relatando dificuldades no caminho Anthropic OAuth, como roteamento de assinatura, credenciais antigas, billing de “extra usage” e diferenças entre o que funciona no Claude Code oficial e o que funciona em um harness externo como o Hermes.

Por isso, para este tutorial, o caminho recomendado é:

Hermes + OpenAI Codex + login ChatGPT/Codex

Além de ser mais simples para quem já usa Codex, esse caminho não é um “plano B fraco”. Em abril de 2026, a OpenAI apresentou o GPT-5.5 como seu modelo mais forte para trabalho real em computador, com ganhos especialmente fortes em programação agentic, uso de ferramentas, navegação por ambiguidade e tarefas longas. No anúncio oficial, a OpenAI descreve o GPT-5.5 como capaz de escrever e depurar código, pesquisar, analisar dados, criar documentos e planilhas, operar software e se mover entre ferramentas até concluir uma tarefa.

Para desenvolvimento, o ponto mais importante é o Codex. A OpenAI afirma que o GPT-5.5 é seu modelo mais forte para agentic coding até então, com destaque para fluxos de terminal complexos, resolução de issues reais, refatoração, debugging, testes e validação. O anúncio também diz que as capacidades aparecem com especial clareza no Codex, onde o modelo pode assumir trabalho de engenharia indo de implementação e refatoração até depuração, testes e validação. Em Codex, o GPT-5.5 foi anunciado para planos Plus, Pro, Business, Enterprise, Edu e Go, com janela de contexto de 400 mil tokens, sujeito à disponibilidade do plano e da conta.

Esse é exatamente o tipo de cenário em que o Hermes brilha: CLI, TUI, dashboard, gateway, skills, sessões persistentes e execução com ferramentas. Se o Hermes estiver autenticado no provedor OpenAI Codex e a sua conta tiver acesso ao GPT-5.5, você não está apenas “usando OpenAI porque é mais fácil”; está usando um modelo de ponta para tarefas complexas em um harness que foi feito para orquestrar ferramentas, contexto e automação.

Se você quiser usar Claude no Hermes, use um caminho explícito e suportado: ANTHROPIC_API_KEY, créditos extras quando aplicável, outro provedor documentado ou uma camada avançada de ACP/ACPX quando o objetivo for orquestrar ferramentas nativas como Codex e Claude Code. Esse tema fica para o post de gateway, segurança e interoperabilidade. Para instalar, validar e ter uma primeira experiência estável no Windows com WSL2, OpenAI Codex é o caminho mais previsível.

Nota de segurança: a pasta `~/.hermes` Link para o cabeçalho

O Hermes guarda boa parte da vida operacional do agente dentro de ~/.hermes. Na instalação validada, essa pasta continha configuração, arquivo .env, autenticação local, logs, sessões, skills, memória, banco de estado e o checkout do próprio Hermes Agent.

Isso é útil para troubleshooting, backup e entendimento do ambiente, mas também exige cuidado. Não publique ~/.hermes, não coloque essa pasta em Git, não copie logs com tokens para um post e não apague tudo no impulso antes de entender o impacto. Se você precisar investigar problema de login, gateway, dashboard ou memória, trate ~/.hermes como pasta sensível.

Passo 4: chamar a CLI do Hermes Link para o cabeçalho

Depois de configurar o provedor, você pode chamar o Hermes de algumas formas diferentes dentro do Ubuntu/WSL.

Para abrir a experiência interativa padrão:

hermes

Para abrir a interface TUI moderna, quando disponível na versão instalada:

hermes --tui

A TUI é uma interface de terminal em tela cheia. A aparência exata pode mudar conforme a versão do Hermes, o tamanho do terminal e o tema usado, mas a ideia é esta: um banner do Hermes, o resumo do provider/modelo, a lista de ferramentas e skills disponíveis e, no rodapé, o prompt para conversar ou usar comandos como /help.

Interface TUI do Hermes Agent rodando dentro do Ubuntu/WSL, mostrando banner, ferramentas, skills, modelo ativo e prompt de comando.

Para enviar uma pergunta única e voltar para o terminal:

hermes chat -q "Explique em uma frase o que é o Hermes Agent."

Para forçar um provedor específico nessa chamada, use --provider. Por exemplo, depois de configurar o OpenAI Codex:

hermes chat --provider openai-codex -q "Responda usando o provedor Codex."

Também dá para escolher modelo, toolsets e skills no momento da chamada:

hermes chat --model "anthropic/claude-sonnet-4"

hermes chat --toolsets "web,terminal,skills"

hermes chat -s github-pr-workflow -q "Abra um checklist de revisão para este projeto."

Um detalhe importante: hermes model é o assistente completo de configuração de provedor, executado fora de uma sessão. Já /model, digitado dentro de uma conversa ativa do Hermes, só troca entre provedores e modelos que você já configurou. Se precisar adicionar OpenAI Codex, OAuth, API key ou endpoint novo, saia da sessão e rode:

hermes model

Passo 5: testar um chat real Link para o cabeçalho

Com o provedor configurado, teste o modo interativo:

hermes chat

Digite algo simples, verificável e curto:

Responda em uma frase: está funcionando?

Você também pode fazer um teste direto, sem abrir uma conversa interativa:

hermes chat -q "Responda em uma frase: está funcionando?"

Se preferir a interface clássica do Hermes, a documentação também mostra o comando:

hermes

O critério de sucesso é simples: o Hermes deve mostrar o provedor/modelo escolhido, responder sem erro e manter a conversa funcionando por mais de um turno.

Nesta instalação, depois do login pelo hermes model, a validação real ficou assim:

hermes status

Trecho importante:

Model:        gpt-5.5
Provider:     OpenAI Codex
OpenAI Codex  ✓ logged in

Também foi validado um chat direto:

hermes chat -q "Responda exatamente: OK CODEX"

Resposta esperada:

OK CODEX

Esse é o ponto em que dá para dizer que a instalação, o login pelo Codex e a inferência básica estão funcionando.

Passo 6: instalar e abrir o dashboard com chat Link para o cabeçalho

Além da CLI e da TUI no terminal, o Hermes também tem um dashboard web local. Ele serve para gerenciar configuração, sessões, chaves, logs, skills e, nas versões recentes, abrir uma aba Chat no navegador.

O dashboard não deve ser tratado como site público. Por padrão, rode em 127.0.0.1, só na sua máquina. Evite expor com --host 0.0.0.0 ou --insecure, porque o dashboard pode lidar com configuração sensível.

Instalar os extras do dashboard Link para o cabeçalho

A documentação do Hermes separa o dashboard em extras opcionais. Em instalações via pip, o comando documentado é:

pip install "hermes-agent[web,pty]"

Esse comando pressupõe que você sabe em qual Python está instalando o pacote. Se o Ubuntu reclamar de ambiente gerenciado externamente, não force instalação global com --break-system-packages. O melhor caminho é instalar os extras dentro do ambiente virtual do próprio Hermes.

O extra web instala a parte HTTP do dashboard, como FastAPI e Uvicorn. O extra pty é importante para o chat novo, porque ele permite embutir uma sessão de terminal/TUI dentro do navegador.

No caminho deste tutorial, instalado pelo script oficial dentro de ~/.hermes/hermes-agent, esses extras podem já estar presentes. Valide primeiro:

hermes dashboard --help

Se o comando existir e mostrar opções como --port, --host, --no-open e --tui, o dashboard já está disponível.

Se a sua instalação reclamar de dependências faltando, instale os extras dentro do checkout do Hermes:

cd ~/.hermes/hermes-agent
uv pip install -e ".[web,pty]" --python venv/bin/python

Aqui o uv pip install usa a interface compatível com pip, mas grava as dependências no Python indicado por --python venv/bin/python. Ou seja: os extras entram no ambiente virtual do Hermes, não no Python global do Ubuntu.

Depois, confirme de novo:

hermes dashboard --help

Abrir o dashboard Link para o cabeçalho

Para abrir o dashboard local na porta padrão 9119:

hermes dashboard

Se você não quiser que ele tente abrir o navegador automaticamente:

hermes dashboard --no-open

No Windows, acesse pelo navegador:

http://127.0.0.1:9119

Se a porta estiver ocupada, escolha outra:

hermes dashboard --port 9120 --no-open

E abra:

http://127.0.0.1:9120

Para ver se há dashboard rodando:

hermes dashboard --status

Para parar:

hermes dashboard --stop

Ativar o chat novo no dashboard Link para o cabeçalho

O chat embutido no dashboard é o recurso novo que coloca a experiência do hermes --tui dentro do navegador. Na versão validada, ele é ativado com --tui:

hermes dashboard --tui

Ou, se quiser combinar com porta e abertura manual:

hermes dashboard --tui --port 9120 --no-open

Também dá para ativar por variável de ambiente:

HERMES_DASHBOARD_TUI=1 hermes dashboard --no-open

Depois disso, abra a URL do dashboard e entre na aba Chat. Você deve ver uma interface parecida com esta:

Dashboard web do Hermes Agent com a aba Chat ativa, mostrando a TUI embutida no navegador, menu lateral, modelo ativo e painel de ferramentas.

Esse chat usa o provider/modelo configurado no Hermes. Então, antes de culpar o dashboard, valide a base no terminal:

hermes status
hermes chat -q "Responda apenas OK."

Se a CLI responde e o dashboard não, o problema tende a estar nos extras web/pty, na porta escolhida ou no processo do dashboard. Se nem a CLI responde, volte para hermes model, hermes doctor e autenticação do OpenAI Codex.

Passo 7: configurar o Telegram no Hermes Link para o cabeçalho

Depois que a CLI já responde, você pode ligar o Hermes ao Telegram. Aqui vale ser conservador: um bot do Telegram conectado a um agente com ferramentas pode ter acesso a terminal, arquivos e automações. Não publique token, não libere para todo mundo e configure uma allowlist.

Criar o bot no Telegram Link para o cabeçalho

No Telegram, abra uma conversa com @BotFather e envie:

/newbot

O BotFather vai pedir:

um nome de exibição, como Hermes Agent;
um username único terminado em bot, como meu_hermes_bot;
ao final, ele entrega um token de API do bot.

O token se parece com isto:

123456789:ABCdefGHIjklMNOpqrSTUvwxYZ

Esse valor é segredo. Trate como senha.

Descobrir seu ID numérico do Telegram Link para o cabeçalho

O Hermes controla acesso pelo ID numérico do usuário, não pelo @username.

O caminho mais simples é mandar uma mensagem para @userinfobot. Ele responde com seu ID. Outra alternativa comum é @get_id_bot.

Guarde esse número. Ele será usado como allowlist:

123456789

Configurar pelo assistente do Hermes Link para o cabeçalho

No Ubuntu/WSL, rode:

hermes gateway setup

No assistente, selecione Telegram quando aparecer a lista de plataformas. Ele deve pedir:

o token do bot criado no BotFather;
o ID numérico dos usuários permitidos;
se você quer iniciar ou reiniciar o gateway.

Se preferir configuração manual, a documentação do Hermes mostra estas variáveis no arquivo ~/.hermes/.env:

TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrSTUvwxYZ
TELEGRAM_ALLOWED_USERS=123456789

Para múltiplos usuários, separe por vírgula:

TELEGRAM_ALLOWED_USERS=123456789,987654321

Não use GATEWAY_ALLOW_ALL_USERS=true neste tutorial. Isso só faz sentido em cenários muito controlados; para um agente com ferramentas, é pedir para o acaso sentar no teclado.

Rodar o gateway no WSL Link para o cabeçalho

No Linux tradicional, o Hermes pode instalar e iniciar o gateway como serviço. No WSL, a própria referência de comandos recomenda usar o gateway em foreground, porque o suporte a systemd pode não ser confiável em todas as instalações.

Então, dentro do Ubuntu/WSL, rode:

hermes gateway run

Deixe esse terminal aberto. Depois, mande uma mensagem para o seu bot no Telegram.

Se quiser manter o gateway vivo sem ocupar seu terminal principal, use tmux:

sudo apt install -y tmux

tmux new -s hermes 'hermes gateway run'

Para sair da sessão sem derrubar o gateway, pressione Ctrl+B e depois D. Para voltar:

tmux attach -t hermes

Comandos úteis dentro do Telegram Link para o cabeçalho

Depois de conectado, você pode conversar normalmente com o bot. Alguns comandos úteis dentro do chat:

/new ou /reset: começa uma conversa nova;
/status: mostra informações da sessão;
/provider: mostra provedores disponíveis;
/model: troca entre modelos já configurados;
/stop: interrompe o agente se ele estiver executando algo;
/help: lista comandos disponíveis.

Lembre-se: /model no Telegram não configura OAuth novo. Para adicionar provedor novo, volte ao Ubuntu/WSL e rode:

hermes model

Passo 8: só depois pense em outros bots e automações Link para o cabeçalho

Quando o primeiro chat funcionar, aí sim faz sentido explorar os próximos recursos:

hermes tools list

hermes gateway setup

hermes skills list

hermes skills browse

Aqui vale uma correção importante: hermes skills sozinho existe, mas é um grupo de comandos. Na versão validada, ele mostra apenas o uso correto e pede um subcomando. Para listar skills instaladas, use hermes skills list; para procurar skills disponíveis, use hermes skills browse ou hermes skills search <termo>.

Mas não pule direto para Discord, Slack, WhatsApp, cron, Docker ou API server antes de validar o chat básico e o Telegram. Se a base não responde, adicionar mais camadas só espalha o problema.

Problemas comuns e como resolver Link para o cabeçalho

Rodei o instalador no PowerShell e falhou Link para o cabeçalho

Rode de novo dentro do Ubuntu/WSL. O comando:

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

é um comando Linux/macOS/WSL2. No Windows, o ambiente suportado é o WSL2.

Se você ainda não tem Ubuntu em WSL2, volte ao guia base: WSL2 no Windows: Linux para desenvolvedores .

`hermes: command not found` Link para o cabeçalho

Recarregue o shell:

source ~/.bashrc

Ou feche e reabra o Ubuntu. Se continuar, verifique:

echo $PATH

Procure por ~/.local/bin na saída. Se não aparecer, adicione ao ~/.bashrc:

export PATH="$HOME/.local/bin:$PATH"

Depois recarregue:

source ~/.bashrc

Rode novamente:

hermes model

Escolha OpenAI Codex e refaça o fluxo no navegador. Se o problema persistir, rode:

hermes doctor

Também vale confirmar se você está usando uma versão atual do Hermes:

hermes --version

Para verificar se existe atualização sem instalar nada:

hermes update --check

E, quando você decidir atualizar de fato, rode:

hermes update

Não trate atualização como primeira reação para qualquer erro. Primeiro leia a mensagem, rode hermes status e hermes doctor, e só então atualize se fizer sentido.

O modelo escolhido é recusado Link para o cabeçalho

A documentação do Hermes recomenda modelos com pelo menos 64K tokens de contexto para fluxos de agente com ferramentas. Se você escolher um modelo pequeno demais, o Hermes pode recusar ou funcionar mal. Para este tutorial, usar OpenAI Codex via hermes model evita boa parte dessa decisão manual.

O Telegram não responde Link para o cabeçalho

Verifique primeiro se o gateway está rodando:

hermes gateway run

Se ele mostrar erro de token, volte ao BotFather e confirme se você copiou o token completo. Se ele ignorar suas mensagens, confira se seu ID numérico está em TELEGRAM_ALLOWED_USERS.

Também rode:

hermes doctor

E confirme se a CLI funciona sem Telegram:

hermes chat -q "Responda apenas OK."

Se a CLI falha, o problema ainda é configuração do Hermes ou do provedor. Se a CLI funciona e o Telegram não, o foco passa a ser token, allowlist ou gateway.

Checklist final Link para o cabeçalho

Antes de considerar pronto, confirme:

o Ubuntu já está rodando em WSL2;
git --version funciona dentro do Ubuntu;
hermes --version funciona dentro do Ubuntu;
hermes model foi configurado com OpenAI Codex;
o login foi feito no navegador, não colando senha no terminal;
hermes status mostra Provider: OpenAI Codex;
hermes doctor mostra OpenAI Codex auth (logged in);
hermes chat -q "Responda exatamente: OK CODEX" recebe resposta;
se você vai usar dashboard, hermes dashboard --help mostra a opção --tui;
se você vai usar o chat web, hermes dashboard --tui abre a aba Chat no navegador;
se você instalou os opcionais, rg --version e ffmpeg -version funcionam;
se você vai usar browser/CDP, hermes doctor não mostra pendência bloqueante para browser;
se você vai usar Telegram, hermes gateway setup configurou token e usuário permitido;
se você vai usar Telegram, hermes gateway run deixa o bot online.

Se tudo isso passou, você tem um Hermes Agent instalado no Windows do jeito certo: Windows como desktop, Ubuntu/WSL2 como runtime Linux e sua conta ChatGPT/Codex como provedor principal.