6.3 Troubleshooting completo

📵 Telegram não responde

Sintoma: você manda mensagem e não recebe nada. Problema #1 mais comum. Em 90% dos casos é uma de quatro causas. Vamos pela ordem certa.

📋 Sequência de diagnóstico

Gateway está rodando?
hermes gateway status dentro do container.
Re-executar wizard se inconsistente:
hermes gateway setup
Ler logs:
tail -f ~/.hermes/logs/gateway.log
Conferir token e home channel:
grep TELEGRAM ~/.hermes/.env

🔑 TELEGRAM_TOKEN

Vem do BotFather. Se você revogou e gerou novo, atualiza aqui. Sem token válido = gateway nem inicia.

📮 TELEGRAM_HOME_CHANNEL

Chat ID onde o Hermes entrega resultados de cron. Sem isso configurado, mensagens automatizadas viram silêncio.

🐳 Em Docker

Confirme que o container tem acesso à internet (firewall/iptables). Teste: docker exec hermes curl -s https://api.telegram.org. Se não retornar 404 (esperado sem path), tem problema de rede no container.

🌐 Dashboard não abre

Sintoma: localhost:8080 não carrega. Em VPS sem IP público direto, é esperado — você precisa criar a ponte. Não é bug.

📋 Checklist

Confirme processo rodando na porta correta (dentro do VPS):
ss -tlnp | grep 8080
Crie SSH tunnel do laptop:
ssh -L 8080:localhost:8080 user@vps
Acesse http://localhost:8080 no navegador
Se quiser URL fixa: configure nginx como reverse proxy com auth básica + Let's Encrypt

🔄 Alternativas

•nginx + Let's Encrypt: URL fixa pública com HTTPS e auth
•Cloudflare Tunnel: sem expor porta na internet, sem certificado manual
•Tailscale: rede privada peer-to-peer, dashboard acessível só pelos seus dispositivos

⚠️Não confunda

"Dashboard não abre" muitas vezes é "ainda não criei o tunnel". Antes de assumir bug do Hermes, confirme que você fez a ponte de rede.

📦 .env do container vs root no Docker

Problema clássico de Docker: o .env do host não é automaticamente disponibilizado dentro do container. O Hermes lê o .env de dentro, não de fora.

📂 Caminho correto

•O .env certo fica em /root/.hermes/.env dentro do container
•No host, monte o volume: ~/.hermes:/root/.hermes
•Nunca coloque API keys no .env da raiz do projeto sem montar corretamente

🔍Como verificar

docker exec -it hermes env | grep TELEGRAM

Se não retornar suas vars, é porque o .env certo não está montado. Edite o docker-compose.yml e adicione o volume.

📜 Logs com auto-redação

Hermes redige secrets automaticamente nos logs em ~/.hermes/logs/errors.log. Você pode mandar pro suporte sem medo de vazar token. Mas confirme antes — auditoria de logs antes de compartilhar nunca é demais.

🗜️ Compactação automática de contexto

Sintoma: agente "esquecendo" coisa no meio da sessão. Hermes comprime conversas longas automaticamente antes do limite de contexto. A compressão é uma chamada LLM separada — pode ser configurada para provedor diferente do principal.

⌨️ Comandos úteis

•/compress — força compressão manual
•/usage — mostra tokens usados na sessão atual
•Status bar do TUI (v0.13.0+) exibe contagem de compressões

⚙️Configurar modelo barato pra compressão

compression:
  provider: "openrouter"
  model: "google/gemini-2.5-flash"

Modelo principal pode ser Claude (caro) e compressor pode ser Gemini Flash (barato). Reduz custo significativamente em sessões longas.

🧠Plugin LCM (lossless context management)

context:
  engine: "lcm"

Compressor alternativo sem chamada de LLM extra. Lossless — não perde informação por sumarização. Bom quando o sintoma "agente esqueceu" está aparecendo demais.

🕐 Timezone: container UTC vs local

Container Docker roda em UTC por padrão. Sem configurar timezone, cron pra "09:00" dispara às 09:00 UTC = 06:00 em Brasília. Você acorda 3h antes da expectativa e não entende.

⚙️Solução 1: config.yaml

timezone: "America/Sao_Paulo"

String IANA padrão. Outros exemplos: Europe/Lisbon, America/New_York, Asia/Tokyo.

🐳Solução 2: env var no Docker

environment:
  - TZ=America/Sao_Paulo

📅 O que isso afeta

•Timestamps em logs — todos os logs ficam em horário local
•Agendamento de cron — "09:00 todo dia" vira 09:00 do seu fuso
•Hora injetada no system prompt — agente sabe que horas são pra você

⚠️Não esqueça

Mudou timezone? Reinicie o container. Crons antigos podem ficar com a próxima execução calculada no fuso anterior. Após restart, recalcula corretamente.

🩺 Diagnóstico via terminal do container

Quando Telegram não responde e você precisa de uma porta de diagnóstico fora dele, vá pro terminal do container. É o "modo seguro" do Hermes — o CLI hermes tem subcomandos pra inspecionar tudo.

🔧 Comandos essenciais

# Entrar no container
docker exec -it hermes bash

# Status do gateway
hermes gateway status

# Listar crons
hermes cron list

# Ler config
hermes config get TELEGRAM_TOKEN

# Health check completo
hermes doctor

# Logs ao vivo
tail -f ~/.hermes/logs/gateway.log
tail -f ~/.hermes/logs/errors.log

📜Auto-redação de secrets nos logs

Logs em ~/.hermes/logs/ aplicam redação automática: tokens, API keys e segredos viram [REDACTED]. Pode compartilhar com suporte sem medo. Ainda assim, leia antes de mandar — paranoia saudável.

💡Quando o agente está vivo mas estranho

Antes de assumir bug do código, leia ~/.hermes/MEMORY.md e ~/.hermes/SOUL.md. 70% dos "comportamentos estranhos" são fato desatualizado lá dentro. Voltamos nisso no módulo 6.4.

🎯Resumo do módulo

✓

Telegram não responde — gateway status, gateway.log, TELEGRAM_TOKEN, TELEGRAM_HOME_CHANNEL.

✓

Dashboard não abre — SSH tunnel ou nginx; quase sempre é falta da ponte de rede.

✓

.env certo é dentro do container — montar volume ~/.hermes:/root/.hermes.

✓

Compressão automática + LCM — modelo barato pra compressão, ou plugin LCM lossless.

✓

Timezone vai em config.yaml ou TZ env var — sem isso, cron dispara em UTC.

✓

Terminal do container é o modo seguro — hermes doctor, logs com auto-redação.

Próximo módulo:

6.4 - 🔁 Rotina de manutenção contínua

← Módulo Anterior Próximo Módulo →