📋 Pré-requisitos: o que já precisa estar na máquina
O v3 não instala nada além dos pacotes do npm install. Ele assume quatro coisas prontas na máquina: Node, o Ollama rodando como serviço do systemd na porta 11434, o CLI claude no PATH e o .env do v2 em ~/projetos/openpcbotv2/.env, de onde vêm as API keys compartilhadas (OpenRouter, Anthropic e as demais). Se um desses faltar, o npm run doctor mostra exatamente qual.
Legenda: os quatro itens da esquerda são de fora do repo. O doctor (tracejado) só lê e relata; quem sobe o processo é a unit do tópico 5.
✓ Assim o v3 sobe limpo
- ✓Ollama só pelo serviço do systemd, falando HTTP na 11434.
- ✓
claudeinstalado em~/.local/binou~/.npm-global/bin: a unit põe esses dois no PATH. - ✓O v2 continua no ar (
systemctl --user is-active openpcbot=active); o v3 roda ao lado.
✗ Assim ele quebra
- ✗
ollama servenum terminal paralelo: o doctor conta os processos e acusa. - ✗Copiar as API keys do v2 para o
.envdo v3: elas são lidas em runtime, nunca duplicadas. - ✗Sem o
.envdo v2: o doctor marca falha crítica, e o tier barato/premium fica sem key.
⌘ Copie e rode: instalar dependências e checar a máquina
Objetivo: baixar os pacotes e ver, antes de configurar qualquer coisa, o que falta na máquina. O doctor não altera nada.
cd ~/projetos/openpcbotv3
npm install
npm run doctorComo verificar: cada linha sai com ✅, ⚠️ ou ❌. Nesta altura é normal ver .env v3 e TELEGRAM_BOT_TOKEN_V3 em aviso. Os críticos que precisam estar ✅ já: .env v2 (keys compartilhadas), Ollama, modelo roteador, modelo geral e claude CLI. A última linha diz Tudo crítico OK ou quantas falhas críticas há; o processo sai com código 1 quando há alguma.
✦ Dica prática
A versão mínima de Node vem do package.json (engines: node >=20). O README não repete esse número; se o seu Node for mais antigo, o npm install avisa antes de qualquer outra coisa.
🤖 Bot próprio no BotFather e o TELEGRAM_BOT_TOKEN_V3
O v3 fala no Telegram como @inemav3bot; o v2 continua no @inemaclaudebot. Cada bot tem um token, e o v3 exige o dele em TELEGRAM_BOT_TOKEN_V3. Isso não é preferência: dois processos chamando getUpdates com o mesmo token recebem 409 do Telegram e os dois bots ficam surdos. Por isso o boot do v3 reconhece o prefixo do token do v2 e recusa subir com ele.
Crie o bot no BotFather
No Telegram
Abra o @BotFather, peça um bot novo e guarde o token que ele devolve. O formato é <número>:<letras-e-números>; o número antes dos dois-pontos é o id do bot, e é por ele que o doctor identifica de qual bot é o token.
Cole em TELEGRAM_BOT_TOKEN_V3
No .env do v3
Copie .env.exemplo para .env e preencha só essa variável. As outras do exemplo já vêm com o default ou comentadas.
Confirme com o doctor
Sem chamar o Telegram
A linha TELEGRAM_BOT_TOKEN_V3 passa a mostrar bot id <número>. Se aparecer "é o token do v2" ou "formato inválido", você colou o token errado. O doctor nunca chama getUpdates: token em uso pelo serviço não pode ser consultado assim.
⌘ Copie e rode: criar o .env a partir do exemplo
Objetivo: ter um .env do v3 com o token próprio. Troque o valor entre < > pelo token que o BotFather deu.
cd ~/projetos/openpcbotv3
cp .env.exemplo .env
# edite a linha TELEGRAM_BOT_TOKEN_V3=<token-do-seu-bot-novo>
npm run doctorComo verificar: .env v3 fica ✅ com o caminho do arquivo, e TELEGRAM_BOT_TOKEN_V3 mostra bot id seguido de um número diferente do id do v2.
⚠ Sem token o serviço sobe mesmo assim
Sem TELEGRAM_BOT_TOKEN_V3 o v3 sobe só com HTTP em 127.0.0.1:3142 e CLI. Isso é útil para testar sem bot, mas alertas e conversa pelo Telegram ficam desligados. Nunca "resolva" pegando o token do v2 emprestado: além de ser recusado no boot, um 409 derruba o bot que já está em produção.
⚙️ O .env do v3: só o que é específico deste bot
O .env do v3 é curto de propósito. A regra é: keys compartilhadas vivem no .env do v2 e são carregadas em runtime; o arquivo do v3 vem por cima e só traz o que é deste bot (token, porta, piso de RAM, orçamento, token do dashboard). A precedência é fixa: variável já presente no processo (systemd ou shell) ganha do .env do v3, que ganha do .env do v2.
Legenda: leia de baixo para cima. Nada é copiado entre arquivos: cada camada só preenche variável que ainda não existe no processo.
▦ As variáveis do .env do v3 (README, seção 13)
| Variável | Default | Para quê |
|---|---|---|
TELEGRAM_BOT_TOKEN_V3 | (vazio) | token próprio; o do v2 é recusado |
ALLOWED_CHAT_ID | (vem do .env do v2) | o único chat que o bot responde e onde os alertas chegam; o .env do v3 pode sobrescrever |
PORT_V3 | 3142 | porta do HTTP, do /health e do dashboard |
HTTP_BIND_V3 | 127.0.0.1 | onde o HTTP escuta; 0.0.0.0 só junto com o token abaixo |
DASHBOARD_TOKEN_V3 | (vazio) | protege / e /api/*; o /health continua aberto |
PISO_RAM_GB | 40 | GB livres exigidos para carregar um modelo grande não residente |
ORCAMENTO_MENSAL_USD | 50 | teto do mês; sobrescreve mensal_usd do orcamento.yaml |
SLACK_ENABLED / WHATSAPP_ENABLED | 0 | ficam em 0 até o corte: o v2 é dono do token e da sessão |
AGE_RECIPIENT | (vazio) | cifra o backup noturno com age; sem ele, gzip |
CLAUDE_BIN / CODEX_BIN | claude / codex | binários dos agentes, se não estiverem com esse nome no PATH |
⌘ Copie e rode: ler o exemplo em vez de adivinhar
Objetivo: ver o modelo comentado que o repo entrega. Ele explica cada variável e diz quais só entram depois do corte. Nunca imprima o seu .env real em chat ou log.
cd ~/projetos/openpcbotv3
cat .env.exemploComo verificar: o arquivo começa avisando que keys compartilhadas e ALLOWED_CHAT_ID vêm do v2 em runtime, traz TELEGRAM_BOT_TOKEN_V3, PORT_V3, PISO_RAM_GB e ORCAMENTO_MENSAL_USD ativos, e o resto comentado (DASHBOARD_TOKEN_V3, canais do v2, AGE_RECIPIENT, HTTP_BIND_V3, chats do Telegram, conta Google padrão).
✦ Dica prática
Mudou o .env? O serviço só relê no restart: bash scripts/instalar-servico.sh (tópico 5). A unit carrega o arquivo com EnvironmentFile=-, então a ausência dele não impede o boot; o que impede é faltar coisa crítica dentro dele.
🧩 config/*.yaml: papéis do Ollama, preços e orçamento
Três arquivos YAML em config/ definem o comportamento que não muda por chat: ollama.yaml (que modelo faz cada papel), precos.yaml (USD por milhão de tokens e o modelo de cada tier) e orcamento.yaml (teto mensal, aviso e trava). Os três já vêm prontos; o doctor confere que existem e, se faltarem, o código usa defaults embutidos.
▦ ollama.yaml: os papéis (README, seção 7)
| Papel | Modelo | keep_alive | Por quê |
|---|---|---|---|
roteador | llama3.2 | 10m | classificação em JSON, 2 s, 4 GB |
geral | qwen3.8:27b, residente | -1 (número) | mesma tag do v2: um único modelo serve os dois bots |
embed | bge-m3 | 10m | vetores da memória, 0,7 GB |
pesado | llama3.1:70b, ativo: false | 42 GB; só depois do corte |
Abaixo dos papéis ficam piso_ram_gb: 40, descarregar_alheios: false, probe_segundos: 60 e latencia_alerta_ms: 5000.
✓ Pode mexer
- ✓
keep_alivedogeral:-1fixa 17 GB na RAM; trocar para"10m"solta o modelo depois de dez minutos ocioso. - ✓
orcamento.yaml:mensal_usd,aviso_pct: 70,trava_pct: 100. O.envsobrescreve só o valor mensal. - ✓
precos.yaml: acrescentar um modelo novo na tabela quando o OpenRouter não devolverusage.cost.
✗ Não mexa enquanto o v2 estiver no ar
- ✗Trocar a tag do
geral: vira dois modelões residentes (um de cada bot) e a máquina vai a OOM. - ✗Ligar o
pesado: 42 GB que só cabem depois do corte. - ✗
descarregar_alheios: true: o v3 passaria a descarregar modelo que o v2 carregou.
⌘ Copie e rode: conferir que os papéis batem com o v2
Objetivo: ler os três YAML e deixar o doctor comparar o modelo geral do v3 com o OLLAMA_MODEL que o v2 usa.
cd ~/projetos/openpcbotv3
cat config/ollama.yaml config/orcamento.yaml config/precos.yaml
npm run doctorComo verificar: no doctor, modelo roteador, modelo geral e modelo embed aparecem ✅ com a tag ao lado (as tags precisam existir no Ollama), mesmo modelo geral que o v2 mostra v2=... v3=... iguais, e as três linhas config/*.yaml dizem ok.
✦ Dica prática
Lição registrada no FALHAS.md do repo: keep_alive: -1 é número, não a string "-1". Com aspas, o Ollama responde 400 ("missing unit in duration") na primeira conversa. Durações, sim, vão entre aspas: "10m".
🛠 instalar-servico.sh: build, unit de usuário e teto de memória
Um único script sobe e atualiza o v3: bash scripts/instalar-servico.sh. Ele copia a unit para ~/.config/systemd/user/, compila (npm run build), recarrega o systemd do usuário, habilita e reinicia o serviço, mostra o status e o MemoryMax. Tudo com systemctl --user: sem sudo, sem tocar no v2. É o mesmo comando para o primeiro boot e para qualquer restart depois de mudar src/ ou .env.
Copia a unit
cp systemd/openpcbotv3.service ~/.config/systemd/user/
A unit é de usuário. Antes disso o script garante XDG_RUNTIME_DIR, que o systemctl --user precisa quando roda fora de uma sessão gráfica.
Compila
npm run build (tsc)
O serviço roda dist/index.js, não o TypeScript. Sem esse passo, mudar src/ não muda nada no ar.
Recarrega, habilita, reinicia
daemon-reload · enable · restart openpcbotv3
Espera 2 s, imprime as 12 primeiras linhas do status, o MemoryMax lido do systemd e o curl do /health para você colar.
Legenda: o teto de 2 GB é do cgroup inteiro, então os claude -p filhos contam junto com o Node. Por isso a lane agente roda um de cada vez. Pico observado no README: cerca de 1 GB com um agente rodando.
⌘ Copie e rode: subir (ou reiniciar) o serviço
Objetivo: instalar a unit, compilar e colocar o v3 no ar. Se a porta estiver diferente do default, troque 3142 pelo seu PORT_V3.
cd ~/projetos/openpcbotv3
bash scripts/instalar-servico.sh
systemctl --user is-active openpcbotv3
curl -s localhost:3142/healthComo verificar: o script termina imprimindo MemoryMax: 2G (se sair infinity, o cgroup não foi delegado e o doctor acusa em v3 MemoryMax). is-active responde active. O curl devolve um JSON com "ok":true quando o Ollama está online, há 10 GB ou mais de RAM e o heartbeat é recente. Se algo falhar, os logs estão em journalctl --user -u openpcbotv3 -n 50 --no-pager -o cat (módulo 2.2).
✦ Dica prática
A unit põe ~/.local/bin e ~/.npm-global/bin no PATH de propósito: para o systemd --user, o claude e o yt-dlp instalados pelo usuário não existem sem isso. Se um agente falhar com "comando não encontrado" só quando roda pelo serviço, olhe primeiro essa linha Environment=PATH=.
💬 Primeira conversa: /versao, /health, /chatid e o CLI
Com o serviço active, a primeira conversa serve para provar três coisas: que o processo que responde é o que você acabou de compilar (/versao), que ele enxerga Ollama, RAM e fila (/health) e que o seu chat é o permitido (/chatid). Se o Telegram ainda não estiver configurado, o mesmo teste sai pelo CLI, sem bot.
▦ Os três comandos da primeira conversa
| Comando | O que volta | O que provar com ele |
|---|---|---|
/versao | openpcbot v3.2.3 · instância <host>:<pid> | a versão bate com o CHANGELOG e o pid muda a cada restart: você está falando com o binário novo |
/health | Ollama (modelos carregados, latência), RAM e swap, RSS do processo e uptime, fila em voo e pendente, heartbeat, canais ativos, orçamento | Ollama online, o qwen3.8:27b residente e telegram entre os canais |
/chatid | chat_id: <número> (telegram) | é o mesmo valor de ALLOWED_CHAT_ID; se o bot nem responder, o chat não é o permitido |
⌘ Copie e rode: falar com o bot sem Telegram
Objetivo: mandar uma mensagem pelo CLI e pelo HTTP local. Os dois passam pelo mesmo orquestrador que o Telegram; a resposta direta sai do Ollama residente, custo zero.
cd ~/projetos/openpcbotv3
npm run cli -- "/versao"
npm run cli -- "<uma-pergunta-curta-sua>"
curl -s -X POST http://127.0.0.1:3142/mensagem -H 'content-type: application/json' -d '{"texto":"/health"}'Como verificar: a primeira linha devolve openpcbot v3.2.3. A pergunta curta volta como resposta direta em segundos (se demorar, o qwen3.8:27b estava sendo carregado). O POST /mensagem só é aceito em 127.0.0.1; se você definiu DASHBOARD_TOKEN_V3, ele protege / e /api/*, não o /health.
✓ Sinais de que subiu certo
- ✓
/healthlistatelegramem canais e o heartbeat não diznuncadepois da primeira meia hora. - ✓
/statusmostra as cinco lanes (chat,agente,ollama,cron,io) com 0 rodando. - ✓O v2 continua respondendo no @inemaclaudebot: nada do que você fez o tocou.
✗ Sinais de problema
- ✗O bot não responde nada no Telegram: chat fora do
ALLOWED_CHAT_ID, ou token ausente (o serviço subiu só com HTTP e CLI). - ✗
/versaodevolve uma versão antiga: você editousrc/mas não rodou o script de instalação (semnpm run buildodist/é o velho). - ✗
/healthcom aviso de Ollama fora: confira o serviço do Ollama antes de mexer no bot.
O v3 recusa subir com o token do v2. Qual é o motivo técnico?
✅ Resumo do módulo
Próximo módulo:
2.2 - Operar no dia a dia