Como Instalar o Hermes AI Agent com Ollama: Guia Passo a Passo (Grátis)
Hermes Agent · Nous Research · Ollama · IA Local · Linux · macOS · Windows WSL2
O Hermes AI Agent, desenvolvido pela Nous Research, é um agente de IA open-source com memória persistente entre sessões, criação automática de skills e suporte a mais de 70 ferramentas integradas. Combinado com o Ollama, permite correr modelos de linguagem completamente locais — sem custos de API, sem dados a sair da rede, e com um agente que aprende e melhora com o uso.
Este guia cobre a instalação completa do Hermes Agent com Ollama em Linux, macOS e Windows (via WSL2) — desde os pré-requisitos de hardware até ao primeiro prompt funcional, com os modelos recomendados e a configuração do contexto obrigatório de 64K tokens.
ℹ O que é o Hermes AI Agent
Hermes é um agente de IA auto-melhorável: aprende padrões de interacção, transforma o que aprende em skills reutilizáveis, guarda memória entre sessões, e executa tarefas com ferramentas reais — ficheiros, terminal, pesquisa web. Licença MIT, gratuito. GitHub: NousResearch/hermes-agent
Neste artigo
- Pré-requisitos de hardware e software
- Modelos recomendados para uso local com Ollama
- Instalar o Ollama
- Configurar WSL2 no Windows (obrigatório)
- Descarregar o modelo e configurar o contexto 64K
- Instalar o Hermes Agent
- Configurar o provider Ollama no Hermes
- Iniciar e verificar o agente
- Comandos essenciais do Hermes
- Ligar ao Telegram (opcional)
- Resolução de problemas comuns
1. Pré-requisitos de Hardware e Software
O Hermes Agent em modo local (com Ollama) requer um mínimo de hardware para que o modelo corra a uma velocidade utilizável. A regra principal é simples: o modelo tem de caber inteiramente em memória — RAM unificada (Apple Silicon) ou VRAM (GPU NVIDIA/AMD).
| Requisito | Mínimo | Recomendado |
|---|---|---|
| Sistema operativo | Linux, macOS 11+, WSL2 | Ubuntu 22.04 LTS, macOS 13+, Windows 11 com WSL2 |
| RAM / VRAM (modelos 7B) | 8 GB | 16 GB para conforto e multi-tasking |
| RAM / VRAM (modelos 14B) | 16 GB | 24 GB para velocidade adequada |
| RAM / VRAM (modelos 27-32B) | 24 GB VRAM ou 32 GB RAM unificada | Mac Mini M4 Pro 48 GB ou GPU RTX 3090/4090 |
| Espaço em disco | 20 GB livres | 50 GB+ para múltiplos modelos |
| Python | 3.11+ | 3.12 (o script instala automaticamente via uv) |
| Contexto do modelo | 64.000 tokens — OBRIGATÓRIO | 128K tokens para sessões longas |
⚠ Windows nativo não é suportado
O Hermes Agent requer um ambiente Unix. No Windows é obrigatório usar WSL2 (Windows Subsystem for Linux). Ver a Secção 4 deste guia para a instalação do WSL2.
2. Modelos Recomendados para Uso Local com Ollama
O Hermes Agent exige um modelo com pelo menos 64.000 tokens de contexto — modelos com janela menor são rejeitados no arranque. Modelos com janela inferior não conseguem manter memória de trabalho suficiente para tarefas multi-passo com chamadas a ferramentas.
| Modelo | RAM/VRAM | Desempenho agentic | Ideal para |
|---|---|---|---|
| qwen2.5:7b | 8 GB | Adequado para tarefas simples | Início, hardware limitado, testes |
| qwen2.5:14b | 16 GB | Bom para uso diário | Sysadmin, scripting, documentação |
| qwen2.5:32b ⭐ | 24 GB | 79% TAU2 — favorito da comunidade | Uso agentic geral — sweet spot |
| qwen2.5-coder:14b | 16 GB | Excelente para código | Desenvolvimento, PowerShell, Python |
| gemma3:27b | 24 GB | 76.9% TAU2 | Alternativa ao Qwen 32B |
ℹ Modelos locais vs. cloud — quando usar cada um
Modelos locais via Ollama são ideais para privacidade, uso offline e custo zero. Para tarefas de raciocínio complexo, automação de browser ou multi-step avançado, modelos cloud (Claude, DeepSeek, Kimi) têm vantagem. O Hermes permite alternar entre providers a qualquer momento com hermes model.
3. Instalar o Ollama
Linux (e WSL2 no Windows)
curl -fsSL https://ollama.com/install.sh | sh
# Verificar instalação e iniciar o serviço
ollama –version
ollama serve # corre em background na porta 11434
# Verificar que o Ollama está a responder
curl http://localhost:11434/v1/models
macOS
brew install ollama
# Ou descarregar o instalador directamente em ollama.com/download/mac
# O Ollama inicia automaticamente como serviço de sistema após instalação
# Verificar
ollama –version
curl http://localhost:11434/v1/models
4. Configurar WSL2 no Windows (Obrigatório)
O Hermes Agent não corre nativamente em Windows. É necessário o WSL2 com Ubuntu — o Ollama pode correr tanto no Windows nativo como dentro do WSL2.
Passo 1 — Instalar o WSL2
wsl –install
# Reiniciar o PC quando pedido
# Após reinício, abrir o Ubuntu pelo menu Iniciar e configurar utilizador
Passo 2 — Configurar o Ollama no Windows com acesso do WSL2
O Ollama pode ser instalado no Windows nativo (mais simples, com suporte a GPU) e acedido a partir do WSL2:
# Instalar o Ollama for Windows em ollama.com/download/windows
# O Ollama fica disponível em localhost:11434 no Windows
# Para o WSL2 aceder ao Ollama do Windows, activar o modo mirrored (Windows 11 22H2+)
# Criar ou editar %USERPROFILE%\.wslconfig
notepad “$env:USERPROFILE\.wslconfig”
# Adicionar estas linhas ao ficheiro:
[wsl2]
networkingMode=mirrored
# Reiniciar o WSL2
wsl –shutdown
# Dentro do WSL2 (Ubuntu) — verificar acesso ao Ollama do Windows
curl http://localhost:11434/v1/models
ℹ Opção B — Ollama também dentro do WSL2
Se preferir correr o Ollama dentro do WSL2 (Linux), seguir o comando de instalação da Secção 3. Neste caso localhost funciona directamente dentro do WSL2 sem configuração adicional — mas o acesso à GPU NVIDIA requer o CUDA toolkit instalado no WSL2.
5. Descarregar o Modelo e Configurar o Contexto 64K
O Hermes Agent rejeita modelos com janela de contexto inferior a 64.000 tokens. É necessário definir explicitamente o contexto ao iniciar o modelo no Ollama.
ollama pull qwen2.5:7b # 8 GB RAM — hardware mínimo
ollama pull qwen2.5:14b # 16 GB RAM — uso diário
ollama pull qwen2.5:32b # 24 GB VRAM / 32 GB RAM — sweet spot agentic
# Verificar modelos disponíveis
ollama list
O Ollama por defeito não define o contexto a 64K. É necessário criar um Modelfile ou usar a flag -c:
cat > Modelfile << ‘EOF’
FROM qwen2.5:14b
PARAMETER num_ctx 65536
EOF
ollama create qwen2.5-14b-64k -f Modelfile
ollama run qwen2.5-14b-64k # testar que inicia correctamente
# Método B — Definir contexto directamente na linha de comando
ollama run qwen2.5:14b –num-ctx 65536
⚠ O contexto deve corresponder ao configurado no Hermes
O Ollama reporta o contexto máximo do modelo via ollama show — não o num_ctx efectivo que configurou. Ao definir o contexto no Hermes (Secção 7), usar o mesmo valor do Modelfile — por exemplo 65536.
6. Instalar o Hermes Agent
O Hermes instala-se com um único comando que trata automaticamente de Python 3.11+, dependências, o gestor de pacotes uv, Node.js e o comando hermes no PATH.
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
# Após instalação, recarregar o shell para activar o comando hermes
source ~/.bashrc # bash
source ~/.zshrc # zsh (macOS)
# Verificar instalação
hermes –version
✓ O que o script instala automaticamente
- Gestor de pacotes
uv(Python rápido) - Python 3.11+ via uv (se não estiver instalado)
- Node.js (necessário para algumas skills)
- Todas as dependências do Hermes Agent
- Comando
hermesdisponível globalmente - Directório
~/.hermes/com configuração, memória e skills
ℹ Instalação manual (alternativa ao script)
Se preferir controlo total sobre a instalação, o repositório tem instruções para instalação manual via git clone + uv pip install -e ".[all]". Ver docs.nousresearch.com.
7. Configurar o Provider Ollama no Hermes
Após a instalação, o Hermes lança automaticamente o assistente de configuração. Se não arrancar automaticamente, executar hermes model para configurar o provider.
Via assistente interactivo (recomendado)
# O assistente apresenta uma lista de providers — seleccionar:
# → Custom endpoint (self-hosted / VLLM / etc.)
#
# Responder às perguntas seguintes:
#
# API base URL: http://localhost:11434/v1
# API key: ollama (qualquer texto — o Ollama não valida a chave)
# Model name: qwen2.5:14b (ou o nome do modelo que descarregou)
# Context length: 65536 (deve corresponder ao num_ctx configurado no Modelfile)
Via configuração directa no ficheiro config.yaml
nano ~/.hermes/config.yaml
# Adicionar ou editar a secção model:
model:
provider: custom
model: qwen2.5:14b
base_url: http://localhost:11434/v1
api_key: ollama
context_length: 65536
Via linha de comandos (configuração rápida)
hermes config set api_base http://localhost:11434/v1
hermes config set model qwen2.5:14b
hermes config set context_length 65536
8. Iniciar e Verificar o Agente
ollama serve & # em background (Linux/macOS)
# Iniciar o Hermes — modo CLI clássico
hermes
# Iniciar o Hermes — modo TUI moderno (recomendado)
hermes –tui
# Testar com um prompt simples para verificar que tudo funciona
# No prompt do Hermes:
Lista os ficheiros do directório actual e diz-me o que encontras.
O Hermes deve apresentar um banner de boas-vindas com o modelo activo, as ferramentas disponíveis e as skills carregadas. Se o agente responder ao prompt com acções reais (listar ficheiros, executar comandos), a instalação está correcta.
✓ Verificação rápida da configuração
hermes config show
# Verificar que o Ollama tem o modelo disponível
ollama list
# Testar o endpoint directamente
curl http://localhost:11434/v1/models | python3 -m json.tool
9. Comandos Essenciais do Hermes
| Comando | Função |
|---|---|
| hermes | Iniciar sessão de chat (modo CLI) |
| hermes –tui | Interface TUI moderna — recomendado para uso diário |
| hermes model | Alterar provider ou modelo — sem perder a configuração |
| hermes config show | Ver configuração activa (provider, modelo, contexto) |
| hermes skills list | Listar as skills disponíveis (mais de 70 integradas) |
| hermes chat –continue | Retomar a sessão anterior (memória persistente) |
| hermes update | Actualizar o Hermes Agent para a versão mais recente |
| hermes gateway setup | Configurar gateway para Telegram, Discord, Slack, etc. |
Dentro de uma sessão de chat, os seguintes comandos especiais estão disponíveis:
| Comando na sessão | Função |
|---|---|
| /compress | Comprimir o histórico da conversa — reduz consumo de tokens em sessões longas |
| /model | Mudar de modelo dentro da sessão actual |
| /skills | Ver e instalar skills disponíveis |
| /voice on | Activar modo de voz (requer pip install "hermes-agent[voice]") |
10. Ligar ao Telegram (Opcional)
O Hermes pode ser acedido via Telegram, Discord, Slack, WhatsApp, Signal ou email — o agente responde a mensagens como se estivesse no terminal, com toda a memória e skills activas.
hermes gateway setup
# O assistente pergunta a plataforma — seleccionar Telegram
# Criar um bot no Telegram:
# 1. Abrir o Telegram e pesquisar @BotFather
# 2. Enviar /newbot e seguir as instruções
# 3. Copiar o token do bot (formato: 123456789:AAF…)
# 4. Colar o token quando o hermes gateway setup pedir
# Instalar o gateway como serviço do sistema (arranque automático)
hermes gateway install
hermes gateway start
# Verificar estado do gateway
hermes gateway status
ℹ Gateway em Windows/WSL2
No Windows com WSL2, o Hermes só corre enquanto a sessão WSL2 estiver activa. Para funcionamento contínuo (24/7) com gateway de Telegram, considerar um VPS Linux (Hetzner, Contabo, DigitalOcean) a partir de 5€/mês — ou manter o PC/Mac sempre ligado.
11. Resolução de Problemas Comuns
| Problema | Causa provável | Solução |
|---|---|---|
| “Model context too small” | O modelo não tem 64K de contexto configurado | Criar Modelfile com PARAMETER num_ctx 65536 e recriar o modelo |
| Connection refused ao Ollama | O serviço Ollama não está a correr | Executar ollama serve num terminal separado; verificar com curl localhost:11434 |
| WSL2 não acede ao Ollama do Windows | Rede WSL2 não configurada em modo mirrored | Adicionar networkingMode=mirrored ao .wslconfig e executar wsl --shutdown |
| Resposta muito lenta (1-3 t/s) | Modelo demasiado grande para a RAM disponível — a usar swap | Usar um modelo mais pequeno: ollama pull qwen2.5:7b |
| hermes: command not found | Shell não recarregado após instalação | Executar source ~/.bashrc ou abrir novo terminal |
| Timeout em respostas longas | Hermes tem timeout de streaming de 120s por defeito | Adicionar ao ~/.hermes/.env: HERMES_STREAM_READ_TIMEOUT=1800 |
Artigos relacionados no kbase.pt
