Módulo 3.2 — Providers, canais e migração

🔐 OpenRouter API key

OpenRouter é o provider padrão do Hermes. Uma só chave sk-or-... destrava Claude, GPT-4, Hermes-3 Llama, DeepSeek e mais 200 modelos. Free tier serve pra estudar.

Como obter a chave

Crie conta

Acesse openrouter.ai/keys e logue com Google ou GitHub.

Adicione créditos (opcional pra free)

$5 dá pra meses de uso casual. Modelos free (:free no nome) não consomem.

Crie a chave

"Create Key" → dê um nome (ex: hermes-laptop) → defina limite mensal ($1, $10, sem limite).

A chave aparece uma única vez — copie agora.

Configurando no Hermes

# Opção A — via wizard (recomendado)
hermes setup

# Opção B — via variável de ambiente (.env)
echo 'OPENROUTER_API_KEY=sk-or-v1-************' >> ~/.hermes/.env

# Opção C — via comando explícito (vai pro keyring do SO)
hermes config set provider.openrouter.api_key sk-or-v1-************

# Defina modelo padrão
hermes config set model.default "anthropic/claude-sonnet-4.5"

# Teste
hermes chat -p "Diga oi em três línguas"

💡 Dica — fallback chains

OpenRouter aceita lista de modelos: se o primeiro falhar (rate-limit, downtime), tenta o próximo. No Hermes: hermes config set model.fallback '["anthropic/claude-sonnet-4.5","openai/gpt-4o","meta-llama/llama-3.3-70b-instruct"]'

✈️ Telegram bot — BotFather + token

Telegram é o canal mais leve: 2 minutos de setup, funciona em qualquer celular, sem app extra. Ideal pra começar.

Criando o bot

Abra o BotFather

No Telegram, busque @BotFather (verificado, ✓ azul) e clique Iniciar.

Envie /newbot

Ele pergunta nome de exibição (ex: "Meu Hermes") e username (deve terminar em bot, ex: meu_hermes_bot).

Copie o token

Formato: 7123456789:AAH-abc...XYZ

Pegue chat_id em @userinfobot pra limitar acesso só ao seu user.

Conecte ao Hermes

hermes channel add telegram --token 7123:AAH-abc...XYZ --allowed-user 123456789
hermes channel start telegram

📊 Long-polling vs Webhook

Long-polling (default): Hermes pergunta ao Telegram "tem mensagem?". Funciona em qualquer máquina, inclusive sem IP público. Recomendado pra começar.
Webhook: Telegram empurra mensagens pra sua URL HTTPS. Mais escalável, mas precisa domínio + certificado.

Referência API: core.telegram.org/bots/api

🎮 Discord bot — Application + scopes

Discord exige mais cliques que Telegram (Application → Bot → Intents → OAuth), mas o resultado é multicanal num server inteiro, ideal pra times.

Setup do bot Discord

# 1. Vá em https://discord.com/developers/applications
# 2. "New Application" → dê nome (ex: "Meu Hermes")
# 3. Aba "Bot" → "Add Bot" → copie o token
# 4. Em "Privileged Gateway Intents" ative:
#    - MESSAGE CONTENT INTENT (obrigatório)
#    - SERVER MEMBERS INTENT (opcional)
# 5. Aba "OAuth2 > URL Generator":
#    Scopes:        [bot] [applications.commands]
#    Bot Permissions: [Send Messages] [Read Message History]
# 6. Copie a URL gerada, abra no browser e adicione ao seu server

# 7. Conecte no Hermes
hermes channel add discord \
  --token "MTIzNDU2Nz..." \
  --intents "messages,message_content"

hermes channel start discord

✓ Boas práticas

✓Use variável de ambiente pro token
✓Limite por canal: --channels 12345,67890
✓Ative apenas intents que usa (privacidade)
✓Use slash commands pra UX limpa

✗ Nunca faça

✗Hardcode do token em arquivo versionado
✗Subir .env pro Git (use .gitignore)
✗Ativar todas as intents "por garantia"
✗Permitir @everyone sem rate-limit

⚠️ Rate-limits do Discord

Discord aplica 5 mensagens/5s por canal. Hermes respeita automaticamente, mas se você bombardear via tools, o bot pode ser temporariamente banido. Use hermes config set channel.discord.rate_limit "5/5" pra ajustar.

💬 Slack app — Workspace + OAuth

Slack é o canal corporativo. Socket Mode evita a necessidade de URL pública e mantém o bot rodando do seu laptop ou servidor.

Criação da app Slack

# 1. Acesse https://api.slack.com/apps → "Create New App" → "From scratch"
# 2. Dê nome (ex: "Hermes") e escolha workspace

# 3. Em "Socket Mode" → Enable Socket Mode
#    Gere App-Level Token (xapp-...) com scope: connections:write

# 4. Em "OAuth & Permissions" → Bot Token Scopes:
#    app_mentions:read   chat:write   im:history   im:write

# 5. Em "Event Subscriptions" → Enable Events
#    Subscribe to bot events: app_mention   message.im

# 6. Em "Install App" → Install to Workspace
#    Copie Bot User OAuth Token (xoxb-...)

# 7. Conecte no Hermes
export SLACK_BOT_TOKEN=xoxb-************
export SLACK_APP_TOKEN=xapp-************

hermes channel add slack --socket-mode
hermes channel start slack

💡 Por que Socket Mode?

•Não precisa expor servidor à internet
•Funciona atrás de NAT, firewall, VPN corp
•Roda do laptop sem ngrok / cloudflare tunnel
•Reconecta automaticamente em quedas

🗣️ Primeira conversa — TUI e mensagens

Hora de fechar o ciclo. Você tem provider configurado, canal conectado — vamos conversar.

TUI no terminal

$ hermes chat

🪽 Hermes Agent · provider=openrouter · model=claude-sonnet-4.5
   Type /help for commands. Ctrl+D to exit.

you ❯ Resuma em 3 bullets o que faz um agente AI
hermes ❯
  • Recebe input em linguagem natural e mantém contexto entre turnos
  • Decide quando chamar tools externas (busca, código, APIs)
  • Sintetiza respostas combinando raciocínio + dados das tools

you ❯ /tools
Available tools:
  - web_search       (online lookup via SearXNG)
  - python_exec      (sandboxed code execution)
  - file_read        (read from ~/hermes-sandbox/)
  - mcp:github       (issues, PRs, code search)

you ❯ /history
[3 turns · 412 tokens used · $0.0012 cost]

you ❯ /exit

Mensagem one-shot (sem TUI)

# Pergunta única, resposta no stdout (útil pra scripts e pipes)
hermes chat -p "Qual a versão atual do Python?"

# Com modelo específico
hermes chat -p "Explique GIL" --model openai/gpt-4o

# Streaming pra arquivo
hermes chat -p "Gere README pro projeto X" --stream > README.md

# Modo silencioso (só a resposta, sem cabeçalhos)
hermes chat -p "Capital do Burkina Faso" --quiet

Conversa via Telegram

Se você conectou no Tópico 2, mande qualquer mensagem ao seu bot. Resposta chega em segundos. Comandos especiais:

/start     # apresentação do bot
/help      # lista comandos
/clear     # zera histórico do chat
/model     # mostra/troca modelo ativo
/tools     # lista tools disponíveis

💡 Dica — debugging

Se a primeira resposta demorar mais de 30s ou der erro, rode hermes doctor. Ele testa cada provider, canal e tool isoladamente e diz exatamente o que está falhando. Logs detalhados em ~/.hermes/logs/.

🔄 hermes claw migrate — Vindo do OpenClaw

Se você usava OpenClaw, não precisa refazer suas configs. Um único comando importa tudo — providers, prompts, tools MCP e profiles.

Migração em 3 passos

# 1. PREVIEW — veja o que vai migrar SEM aplicar nada
hermes claw migrate --dry-run

  → Found OpenClaw config at ~/.openclaw/
  → Would migrate:
      - 3 provider configs (anthropic, openai, openrouter)
      - 12 custom prompts
      - 5 MCP tool configs
      - 2 profiles (work, personal)
  → No changes made. Run without --dry-run to apply.

# 2. EXECUTE com backup
hermes claw migrate --backup

  → Backup saved: ~/.hermes/backups/pre-migrate-2026-05-24.tar.gz
  → Migrated: 22 items
  → Skipped: 1 (incompatible MCP version)
  → Done. Run `hermes doctor` to verify.

# 3. VERIFICA
hermes doctor
hermes chat -p "olá"   # confirma que tudo funciona

# Se algo deu errado: rollback total
hermes claw migrate --rollback

📊 O que é migrado

Providers: chaves de API (vão pro keyring), modelos default, fallbacks
Prompts: system prompts customizados → ~/.hermes/prompts/
Tools MCP: definições reescritas pro novo schema (compatibilidade 95%)
Profiles: cada profile do OpenClaw vira um ~/.hermes/profiles/<nome>.toml
Histórico: opcional via --include-history (cuidado com tamanho)

⚠️ Atenção

A migração NÃO apaga sua config do OpenClaw — ela só lê. Você pode manter os dois instalados em paralelo enquanto valida. Após confirmar que o Hermes está estável, remova OpenClaw com pipx uninstall openclaw (ou equivalente).

💡 Dica — comparar configs

Antes de remover o OpenClaw, rode hermes claw diff. Ele mostra lado a lado o que mudou na tradução (ex: nomes de tools, formato de prompts). Útil pra ajustar manualmente o que o auto-migrate não pegou.

✅ Resumo do Módulo

✓

OpenRouter configurado

Uma chave sk-or-... destrava 200+ modelos com fallback automático

✓

Bot Telegram rodando

BotFather → token → hermes channel start telegram

✓

Discord conectado

Application + MESSAGE CONTENT intent + OAuth URL

✓

Slack via Socket Mode

Sem URL pública, funciona atrás de qualquer firewall

✓

Primeira conversa concluída

TUI + Telegram funcionando, hermes doctor verde

✓

Migração do OpenClaw

--dry-run → --backup → doctor, com rollback se preciso

Próximo módulo:

3.3 — 👥 Multi-usuário e multi-tenancy: rode 1 instância pra família ou time isolando memórias, skills e API keys por pessoa.

← Voltar para Trilha Próximo →