# Hermes Agent: Guia completo de configuração inicial e execução em VPS > Guia técnico passo a passo para implantar o agente de IA autoaprendente Hermes em um VPS: comparação com OpenClaw e Paperclip, uso do Docker, otimização de custos via OpenRouter e criação de skills autônomas. ## 1. Arquitetura e escolha do agente: Hermes, OpenClaw ou Paperclip No ecossistema de agentes autônomos de 2026, não existe uma ferramenta universal que resolva todas as tarefas com a mesma eficiência. Os três principais sistemas open-source — **Hermes**, **OpenClaw** e **Paperclip** — representam paradigmas arquitetônicos fundamentalmente distintos. Eles não competem diretamente; em ambientes de produção, é comum vê-los coexistindo no mesmo servidor. ```mermaid flowchart TD subgraph Ecosystem ["Три архітектурні парадигми агентів"] H["Hermes Agent
Агент-фахівець, що навчається
(Накопичує досвід у MEMORY.md та створює власні скіли)"] O["OpenClaw
Шлюз та автономний співробітник
(50+ месенджерів, статичні SOUL.md інструкції)"] P["Paperclip
Оркестратор цифрової компанії
(Ієрархія CEO + ролі, ліміти бюджету, координація)"] end VPS[("Один VPS-сервер (Ubuntu + Docker)")] --> H VPS --> O VPS --> P ``` ### Matriz comparativa das plataformas de agentes | Característica | Hermes Agent | OpenClaw | Paperclip | | :--- | :--- | :--- | :--- | | **Papel principal** | Pesquisador e especialista autoaprendiz | Colaborador autônomo multicanal | Orquestrador de equipe com 5+ agentes | | **Gestão de memória** | Dinâmica: atualiza `MEMORY.md`, `USER.md` e skills a cada 10 passos | Estática: regras fixas definidas em `SOUL.md` | Orientada ao projeto: estado compartilhado de tarefas e hierarquia | | **Canais de comunicação** | 6 principais (CLI, Telegram, Discord, WhatsApp, etc.) | 50+ integrações (Teams, Slack, iMessage, Signal) | Gerencia outros agentes via adaptadores | | **Capacidade de aprendizado** | **Alta**: compila automaticamente fluxos de trabalho em skills | **Inexistente**: requer atualização manual das regras | **Indireta**: delega execução a agentes externos | | **Limiar de viabilidade** | Eficaz a partir de 1 tarefa autônoma | Ideal para comunicação omnichannel | Desbloqueia seu potencial com 5 agentes simultâneos | > [!NOTE] > Todos os três frameworks utilizam portas de rede e runtimes isolados. Você pode executar o Hermes como pesquisador de dados, o OpenClaw como gateway para suporte ao cliente e o Paperclip como coordenador na mesma máquina, sem quaisquer conflitos. --- ## 2. Requisitos de sistema e preparação da infraestrutura O Hermes pode operar como uma ferramenta CLI leve, mas para funcionar plenamente de forma autônoma (com automação de navegador, gateways em background e persistência de memória vetorial), é necessária uma base de servidor estável. ### Requisitos de hardware para VPS - **Processador:** Mínimo de 2 vCPUs (recomendado para parsing paralelo e embeddings). - **Memória RAM:** 8 GB (garante folga durante a operação do navegador Playwright e do daemon Docker). - **Espaço em disco:** 100 GB NVMe SSD (para cache de modelos, logs e snapshots de páginas web). - **Sistema operacional:** Ubuntu 24.04 LTS ou Debian 12 com Docker Engine pré-instalado. ### Serviços de terceiros necessários 1. **Hosting com suporte a Docker:** Hetzner, DigitalOcean, Vultr ou qualquer VPS KVM. 2. **Gateway único de API (OpenRouter):** Em vez de gerenciar chaves separadas para Anthropic, OpenAI e Moonshot, utilize o OpenRouter. Isso oferece acesso a mais de 200 modelos através de um saldo unificado e permite alterar instantaneamente os papéis dos agentes sem reiniciar o serviço. --- ## 3. Implantação passo a passo do Hermes no VPS via Docker A maneira mais confiável de implantar o Hermes é utilizando a imagem oficial do Docker da Nous Research. Isso elimina conflitos de versões de Python e bibliotecas do sistema. ```mermaid flowchart LR A["1. Створення VPS
(Ubuntu + Docker)"] --> B["2. SSH-підключення
до сервера"] B --> C["3. Перевірка контейнера
(docker ps)"] C --> D["4. Запуск майстра
(hermes setup)"] D --> E["5. Тестовий прогін
(hermes CLI)"] ``` ### Passo 1. Conexão ao servidor via SSH Após criar o servidor, acesse seu terminal e faça login como superusuário: ```bash ssh root@YOUR_VPS_IP ``` ### Passo 2. Verificação do container Docker Certifique-se de que o container Hermes foi inicializado com sucesso: ```bash docker ps ``` Na lista de processos ativos, deve aparecer a imagem `nousresearch/hermes-agent:latest`. Acesse o diretório de configuração e conecte-se ao shell do container: ```bash cd /docker/hermes-agent-* docker compose exec -it hermes-agent /bin/bash ``` ### Passo 3. Inicialização interativa via assistente de configuração Dentro do container, execute o assistente de configuração inicial: ```bash hermes setup ``` O assistente guiará você por quatro etapas sequenciais: 1. **Seleção do provedor LLM:** Escolha `OpenRouter`. 2. **Autorização:** Insira sua chave de API do OpenRouter (`sk-or-v1-...`). 3. **Seleção do modelo base:** Escolha um modelo inicial temporário (na próxima seção, configuraremos um stack multimodal otimizado). 4. **Canais de comunicação:** Conexão opcional com Telegram ou Discord (pode ser ignorada nesta fase). ### Passo 4. Primeiro teste de execução da CLI Verifique a funcionalidade do ambiente do agente: ```bash hermes ``` Após a exibição do banner de boas-vindas, envie um comando de teste para verificar o acesso ao sistema de arquivos: ```text What files are in my current directory? ``` Se o Hermes retornar a listagem de arquivos do diretório, a camada de ferramentas (Tool Calling) está funcionando corretamente. Caso ocorra um erro, execute o diagnóstico do sistema: ```bash hermes doctor ``` --- ## 4. Configuração de modelos e otimização de orçamento via OpenRouter Por padrão, o Hermes está configurado para consultar modelos premium de ponta (como Claude Opus). Isso gera uma carga financeira excessiva: > [!WARNING] > **Armadilha da configuração monomodelo:** Usar um único modelo nível Opus para todas as fases da sessão (planejamento, chamadas de utilitários, parsing de saída) gera custos entre $0.50–$2.00 por sessão. Com 90 sessões mensais, isso representa **$45–$180** apenas em custos de API. ### Arquitetura de distribuição de papéis Para reduzir os custos para **$12–$22 mensais** sem perda de qualidade, distribuímos as responsabilidades entre modelos especializados. ![Comparação de preços e características dos modelos para Hermes Agent](/api/guides-media/ai_agents/hermes-agent-initial-setup-guide/images/hermes-agent-initial-setup-guide-extra-02.webp) ![Modelos rápidos para chamadas massivas de ferramentas](/api/guides-media/ai_agents/hermes-agent-initial-setup-guide/images/hermes-agent-initial-setup-guide-extra-03.webp) ### Matriz de modelos recomendados | Papel no agente | Modelo recomendado | Identificador OpenRouter | Preço de entrada ($/1M) | Finalidade principal | | :--- | :--- | :--- | :--- | :--- | | **Planner & Backbone** | MiniMax M2.7 | `minimax/minimax-m2.7` | $0.30 | Orquestração, planejamento diário, lógica da sessão | | **Reviewer & Reasoning** | Kimi K2.6 | `moonshotai/kimi-k2.6` | $0.60 | Raciocínio profundo, code review, verificação | | **Fast Executor** | DeepSeek V4 Flash | `deepseek/deepseek-v4-flash` | $0.14 | Chamadas massivas de bash/tools, coleta de dados brutos | | **Vision Subsystem** | Gemma 4 26B IT | `google/gemma-4-26b-a4b-it:free` | Gratuito | Análise de screenshots e elementos visuais | ### Arquivo de configuração do roteador multimodal Abra o arquivo de configuração para edição: ```bash hermes config edit ``` Substitua o bloco de definição de modelos pelo YAML estruturado abaixo: ```yaml model: provider: openrouter default: minimax/minimax-m2.7 roles: planner: minimax/minimax-m2.7 executor: deepseek/deepseek-v4-flash reviewer: moonshotai/kimi-k2.6 vision: google/gemma-4-26b-a4b-it:free fallback: - deepseek/deepseek-v4-flash - google/gemma-3-12b-it:free compression: enabled: true threshold: 0.50 ``` Se a chave do OpenRouter não tiver sido inserida anteriormente, defina-a via comando: ```bash hermes config set OPENROUTER_API_KEY sk-or-v1-your-key-here ``` > [!TIP] > **Controle de custos:** Configure obrigatoriamente um limite mensal rígido no dashboard do OpenRouter (`Settings` → `Credits` → `Monthly limit`). Para começar, recomenda-se estabelecer um teto de **$15/mês**, protegendo contra loops infinitos em caso de erros nos scripts de automação. --- ## 5. Segurança e conexão de gateways de mensagens O Hermes permite gerenciar processos via mensageiros, transformando o servidor em um assistente pessoal no Telegram ou Discord. > [!IMPORTANT] > **Requisito crítico de segurança:** Qualquer usuário que enviar um comando ao bot no mensageiro obtém **acesso total ao terminal do servidor** com os privilégios do processo em execução. Nunca execute um bot público sem uma whitelist de IDs! ### Configuração do Gateway Telegram :::tabs @tab 1. Criação do bot 1. Abra o `@BotFather` no Telegram. 2. Crie um novo bot usando o comando `/newbot`. 3. Salve o token recebido (formato `123456789:ABCdef...`). @tab 2. Obtenção do User ID 1. Envie uma mensagem ao bot `@userinfobot` no Telegram. 2. Copie seu identificador numérico (ex.: `987654321`). @tab 3. Configuração do ambiente Adicione as variáveis ao arquivo de configuração `.env`: ```bash TELEGRAM_BOT_TOKEN="123456789:ABCdef..." TELEGRAM_ALLOWED_USERS="987654321" ``` ::: Execute e verifique o status do gateway em background: ```bash # Перевірка статусу шлюзу hermes gateway status # Перегляд логів взаємодії в реальному часі tail -f ~/.hermes/logs/gateway.log ``` --- ## 6. Workflow prático: autoaprendizado e geração de skills reutilizáveis A principal vantagem do Hermes sobre chamadas comuns de LLM reside no **compound de conhecimento**. O agente analisa automaticamente ações bem-sucedidas em múltiplas etapas e as registra no diretório de skills `~/.hermes/skills/`. ```mermaid sequenceDiagram autonumber actor User as Інженер participant H as Hermes Agent participant Web as Reddit API / Веб participant Disk as ~/.hermes/skills/ User->>H: Надіслати промпт дослідження H->>Web: Пошук трендових фреймворків у r/LocalLLaMA Web-->>H: Сирі обговорення та посилання H->>H: Аналіз та форматування (голос автора) H->>Disk: Збереження алгоритму в reddit-trending-frameworks.md H-->>User: Готовий стислий звіт Note over User,Disk: Наступний запуск User->>H: "Run reddit-trending-frameworks on r/aiagents" H->>Disk: Читання скомпільованого скіла H->>Web: Пряме виконання без зайвих роздумів H-->>User: Миттєвий структурований звіт ``` ### Demonstração da criação de uma skill autônoma Envie ao agente o seguinte prompt de trabalho: ```text Research the top 3 trending AI agent frameworks on r/LocalLLaMA this week. Use my voice — punchy, no jargon, no AI-speak. Three bullets per framework. Save this whole workflow as a reusable skill called reddit-trending-frameworks. ``` ### Registro passo a passo do resultado 1. **Execução:** O Hermes realiza a busca, agrega feedbacks da comunidade e filtra spam autonomamente. 2. **Formatação:** Gera 9 teses claras (3 por framework) na tonalidade solicitada. 3. **Salvamento da skill:** Cria o arquivo `~/.hermes/skills/reddit-trending-frameworks.md`. Verifique se a skill salva está presente no sistema: ```bash ls -la ~/.hermes/skills/ ``` ### Reexecução em nova fonte de dados Agora, para realizar uma pesquisa análoga em outra plataforma, não é necessário escrever prompts detalhados novamente nem ajustar o tom. Basta um único comando: ```text Run my reddit-trending-frameworks skill on r/aiagents instead ``` O Hermes lerá instantaneamente o algoritmo salvo e executará a tarefa com menos passos e tokens do que na primeira execução. --- ## 7. Diagnóstico e resolução de problemas Durante a primeira implantação do agente em um servidor limpo, podem ocorrer erros típicos de configuração do ambiente. ![Tabela de referência para solução de erros comuns do Hermes](/api/guides-media/ai_agents/hermes-agent-initial-setup-guide/images/hermes-agent-initial-setup-guide-extra-01.webp) ### Matriz de troubleshooting | Sintoma | Causa raiz | Solução validada | | :--- | :--- | :--- | | `command not found: hermes` | O shell do sistema não atualizou os caminhos `PATH` após a instalação. | Execute `source ~/.bashrc` (ou `source ~/.zshrc`). | | Container encerra imediatamente após iniciar | Chave de API ausente ou sintaticamente incorreta no `.env`. | Verifique os logs: `docker logs hermes`. Certifique-se de que não há espaços ao redor do `=`. | | Erro `HTTP 400` na primeira mensagem | Identificador de modelo incorreto para o provedor. | Para OpenRouter, use o formato `provedor/modelo` (ex.: `minimax/minimax-m2.7`). | | Bot do Telegram silencioso/não responde | Mensagens vindas de usuários não autorizados. | Verifique os logs: `tail -f ~/.hermes/logs/gateway.log`. Adicione seu ID à `TELEGRAM_ALLOWED_USERS`. | --- ## 8. Checklist final de prontidão para operação Antes de colocar o Hermes em modo de assistente diário, certifique-se de que cada item foi cumprido: - [ ] VPS provisionado com no mínimo 2 vCPUs e 8 GB de RAM. - [ ] Container `nousresearch/hermes-agent:latest` rodando com sucesso no Docker. - [ ] Comando `hermes doctor` não reporta erros críticos de ambiente. - [ ] Distribuição multimodal de papéis configurada em `~/.hermes/config.yaml`. - [ ] Limite mensal de gastos definido na conta do OpenRouter. - [ ] Whitelist `TELEGRAM_ALLOWED_USERS` configurada no arquivo `.env`. - [ ] Teste de execução da CLI realizado e primeira skill customizada salva.