🚀 Instalar e operar

Quatro coisas prontas antes do primeiro boot: Node, o Ollama como serviço do systemd na porta 11434, o CLI claude no PATH e o .env do v2, de onde vêm as keys compartilhadas em runtime.

O npm run doctor aponta exatamente o que falta antes de você configurar qualquer coisa, e sai com código 1 se houver falha crítica.

Ollama via systemd · claude CLI · keys em runtime · doctor

Um bot novo no BotFather e o token dele em TELEGRAM_BOT_TOKEN_V3. O v3 reconhece o token do v2 e recusa subir com ele.

Dois processos chamando getUpdates com o mesmo token recebem 409 e os dois bots ficam surdos, inclusive o que já está em produção.

BotFather · getUpdates · 409 · bot id

Token, PORT_V3 (3142), HTTP_BIND_V3 (127.0.0.1), DASHBOARD_TOKEN_V3, PISO_RAM_GB (40) e ORCAMENTO_MENSAL_USD (50). As keys compartilhadas não se duplicam aqui.

A precedência é fixa: o que já está no processo ganha do .env do v3, que ganha do .env do v2. Saber disso evita caçar valor fantasma.

ALLOWED_CHAT_ID · PORT_V3 · PISO_RAM_GB · precedência

ollama.yaml define os papéis roteador, geral e embed (com piso de RAM e probe), precos.yaml traz USD por milhão de tokens por tier e orcamento.yaml o teto do mês.

As tags de modelo precisam ser as mesmas do v2: um modelo grande residente serve os dois bots. Mudar só de um lado leva a máquina a OOM.

Papel · tag do modelo · tier · keep_alive

Um script que copia a unit para ~/.config/systemd/user/, roda npm run build, recarrega o systemd, habilita e reinicia o serviço, e imprime status e MemoryMax.

É o mesmo comando para o primeiro boot e para qualquer restart depois de mexer em src/ ou no .env. Tudo com systemctl --user, sem tocar no v2.

unit de usuário · MemoryMax 2G · Restart=on-failure · npm run build

Três comandos que provam o essencial: qual binário respondeu, se o bot enxerga Ollama, RAM e fila, e se o seu chat é o permitido. Sem Telegram, o mesmo teste sai por npm run cli.

Você confirma o caminho inteiro antes de confiar tarefa nenhuma ao bot, e descobre cedo se ficou rodando uma versão antiga.

/versao · /health · /chatid · POST /mensagem

O npm run doctor lê configuração, RAM, modelos, CLIs e units sem mudar nada. O --deep acrescenta quatro probes reais: health, sendMessage, modelo roteador pelo gateway e um job na lane io.

Só o probe da fila revela serviço no ar com binário antigo, um erro que a configuração sozinha nunca mostra.

Falha crítica · probe · doctor-probe · lane io

Log pino em JSON no journal do systemd do usuário, e um dashboard em 127.0.0.1:3142 com health, Ollama e RAM, fila por lane, custo de 14 dias, memória e jobs recentes.

O log conta a sequência, o dashboard mostra o conjunto. Um responde "o que aconteceu", o outro "como está agora".

journalctl --user · -o cat · DASHBOARD_TOKEN_V3 · HTTP_BIND_V3

Três leituras no chat: saúde (Ollama, RAM e swap, RSS, fila, heartbeat), trabalho (fila por lane ou um job pelo id) e dinheiro (dia, semana, mês, por tier e por agente).

O ok do health tem critério: Ollama online, RAM de 10 GB ou mais e heartbeat de menos de 90 minutos. Sem esse critério, "está lento" vira palpite.

Lane · heartbeat · tier · /cancelar e /prioridade

Ollama fora, RAM baixa, lease morto, job zumbi, três falhas da mesma tarefa em uma hora, orçamento em 70 % e em 100 %, entregues no chat permitido com dedupe de 30 minutos por chave.

Cada alerta tem uma resposta certa e uma resposta que piora. Lease morto e zumbi, por exemplo, o heartbeat já recupera sozinho.

Dedupe por chave · lease · zumbi · ALLOWED_CHAT_ID

Às 4h15 o cron copia o SQLite com VACUUM INTO, cifra com age se houver AGE_RECIPIENT ou comprime com gzip, e mantém 14 arquivos em store/backups/.

Todo o estado do bot mora nesse arquivo: fila, memórias, custo e preferências. Conferir que o backup existe é mais barato que descobrir que não existe.

VACUUM INTO · WAL · age e gzip · retenção 14

Conter com /parar tudo, diagnosticar com journal e doctor, reinstalar com bash scripts/instalar-servico.sh e registrar uma linha no FALHAS.md antes da próxima tarefa.

A coluna da menor correção possível é a que ensina: quase sempre faltava uma proteção, não uma reescrita.

/parar e /retomar · prefs · drain gracioso · prompt ou infra