4.1 Tokens, .env e hermes config set

🚫 Por que NUNCA colar token no chat

Tudo que você digita no chat do Hermes é persistido. As sessões ficam em ~/.hermes/state.db (SQLite com FTS5) e ficam pesquisáveis pela ferramenta session_search. Se você cola um token ali "só pra testar", ele vira parte do histórico para sempre.

⚠️O que acontece quando você cola um token

•Vai pro SQLite indexado — pesquisável por anos
•Aparece em backups automáticos da VPS
•Pode ser enviado pro provedor de inferência em compressões/sumarizações
•Fica no contexto de sessões futuras via session_search

🛡️O que fazer (e o que NÃO fazer)

✓Use hermes config set KEY value sempre
✓Se vazou por engano: revogue a credencial imediatamente e gere outra
✗Não tente "limpar" o histórico — assuma vazado
✗Não cole o token "só pra ele testar se funciona"

⌨️ hermes config set KEY value

Comando oficial pra escrever variável de ambiente sem expô-la. Ele lê o valor por stdin (ou argv tratado), persiste em /root/.hermes/.env dentro do container e confirma sem ecoar o valor.

📋 Exemplos comuns

hermes config set TELEGRAM_TOKEN 123456:abc...

hermes config set OPENROUTER_API_KEY sk-or-...

hermes config set OPENAI_API_KEY sk-...

hermes config set GITHUB_TOKEN ghp_...

hermes config set TELEGRAM_HOME_CHANNEL @meu_canal

🐳Em Docker

Sempre exec dentro do container antes:

docker exec -it hermes hermes config set TELEGRAM_TOKEN 123:abc

Sem o exec, você está rodando no host — onde o Hermes nem está instalado, ou está numa versão diferente.

🐳 .env do container vs .env do host

É a confusão #1 da comunidade. O Docker isola sistemas de arquivos. O .env da raiz do projeto no host não chega ao processo a menos que você monte explicitamente.

✗ O que NÃO funciona

✗Editar /home/voce/projeto/.env no host
✗Esperar que o Hermes "veja" sem volume montado
✗Reiniciar o container e achar que funcionou

✓ O que funciona

✓Volume ~/.hermes:/root/.hermes montado
✓Variáveis em /root/.hermes/.env do container
✓hermes config set escreve no caminho certo

🔍Como confirmar que está certo

docker exec -it hermes env | grep TELEGRAM

Se a variável aparece, está visível para o processo. Se não aparece, volta no volume mount do docker-compose.yml ou no nome da var.

📝 Editar/deletar via nano

O config set sobrescreve ou adiciona, mas não tem subcomando delete amigável. Quando você troca de provedor (saiu da OpenAI, foi pra OpenRouter), a chave antiga continua no .env. Limpe manualmente.

🔧 Procedimento seguro

1.
Backup: docker exec hermes cp /root/.hermes/.env /root/.hermes/.env.bak
2.
Editar: docker exec -it hermes nano /root/.hermes/.env
3.
Apagar a linha da chave que não usa mais
4.
Reiniciar gateway: hermes gateway restart
5.
Confirmar: docker exec hermes env | grep KEY_ANTIGA (deve sumir)

💡Dica

Mantenha um comentário no topo do .env com data da última revisão e quem é dono de cada chave. Em 6 meses você não lembra qual API_KEY serve pra quê.

🎯 Tokens com escopo limitado

Token vazado é prejuízo proporcional ao escopo. Token classic de GitHub com acesso a todos seus repos privados = catástrofe. Token fine-grained com acesso só ao repo X = incidente contido.

🔑 GitHub: classic vs fine-grained

Classic: escolhe scopes amplos (repo, workflow, gist...). Sem expiração obrigatória. Acesso a todos os repos onde você tem permissão.
Fine-grained: escolhe repos específicos + permissões granulares (read/write por área). Expiração obrigatória (max 1 ano).
Recomendação: sempre fine-grained, escopado ao mínimo de repos, com 90 dias de expiração.

🤖 OpenAI / OpenRouter

OpenAI: use project keys. Cada projeto pode ter limites de gasto e modelos próprios. Restringe blast radius.
OpenRouter: crie chaves nomeadas por agente. Defina limite mensal por chave. Ative alerta de gasto.
Anthropic: workspaces separam billing. Use um workspace por agente.

⚠️Regra prática

Comece com escopo mínimo. Quando o agente reclamar "permission denied", expanda só o necessário. Nunca o contrário (full access "porque é mais fácil").

🔇 Auto-redação de secrets nos logs

O Hermes redige automaticamente valores conhecidos de variáveis de ambiente quando aparecem em mensagens de erro. Você pode pedir suporte, postar pedaços do log no Discord da comunidade — sem vazar credencial. Mas confira sempre antes de compartilhar.

📁 Onde olhar

~/.hermes/logs/errors.log — erros do agente, com auto-redação
~/.hermes/logs/gateway.log — eventos de mensageria
~/.hermes/logs/cron.log — execução de jobs agendados
~/.hermes/state.db — sessões (use session_search)

🛡️O que a redação cobre

✓Variáveis com nomes conhecidos (TELEGRAM_TOKEN, *_API_KEY, *_SECRET)
✓Padrões de tokens reconhecidos (sk-..., ghp_...)
✗Valores hardcoded em código que você passou no chat
✗Strings em mensagens livres que parecem texto comum

💡Antes de compartilhar log

Sempre abra e leia. Procure por sk-, ghp_, 123456: (formato de token Telegram), URLs com tokens em query string. Confirme que estão como ***REDACTED*** ou similar.

🎯Resumo do módulo

✓

Token colado no chat fica para sempre no SQLite — use sempre hermes config set.

✓

Em Docker, o .env é em /root/.hermes/.env do container — o do host não é lido sem volume montado.

✓

Para apagar chave antiga, edite via nano e reinicie o gateway — o config set não tem delete fácil.

✓

Use tokens com escopo limitado — fine-grained no GitHub, project keys na OpenAI, chaves nomeadas no OpenRouter.

✓

Logs têm auto-redação de secrets — mas confira antes de compartilhar.

Próximo módulo:

4.2 - 🛡️ Firewall, portas e IP allowlist

← Voltar para Trilha Próximo Módulo →