Guia de socorro dos Mentores

Instalação em grupo. Quarta, 12/08.

Sua função: atender seu grupo. Se em 5 minutos você não resolveu, chame o condutor. Nunca digite pela pessoa: leia o comando em voz alta e deixe ela digitar. Quem digita, aprende.

As duas perguntas que resolvem metade dos casos: 1. "Está no servidor ou no seu computador?" A linha tem que começar com root@srv. 2. "Em que pasta você está?" Rode pwd. Tem que terminar em agente-pessoal-kit.

1. Não consegue entrar no servidor

Tela: Connection closed by remote host ou a senha é recusada, logo depois de criar a VPS. Causa: o servidor ainda está sendo montado. Aceita a conexão e desliga em seguida. Solução: esperar 10 minutos e tentar de novo. Se insistir, redefinir a senha de root no painel da Hostinger e esperar mais 5 minutos.

Tela: WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED! com um bloco grande de asteriscos. Causa: o servidor terminou de instalar o sistema e trocou de identidade. É esperado numa VPS nova, não é invasão. Solução: no computador da pessoa (não no servidor):

ssh-keygen -R SEU_IP

e conectar de novo.

Tela: Could not resolve hostname. Causa: um caractere a mais grudado no IP (til, espaço, ponto final). Aconteceu de verdade na véspera: ssh root@2.25.101.222~. Solução: digitar o comando de novo, com o IP limpo, sem nada colado nele.

Tela: command not found: seguido de um texto estranho (que é a senha da pessoa). Causa: colou a senha antes da hora, direto na linha de comando. A senha só entra quando o ssh perguntar password:. Solução: sem dano. Rodar o ssh root@SEU_IP de novo e colar a senha só quando pedir. Anotar pra depois: essa senha ficou no histórico do notebook; vale trocar no painel da Hostinger depois do encontro.

Tela: Operation timed out ou Connection closed do nada, depois de um tempo parado. Causa: a conexão caiu por inatividade. Normal em Wi-Fi doméstico ou de sala. Solução: reconectar assim (o -o mantém a conexão viva):

ssh -o ServerAliveInterval=60 root@SEU_IP

Se a instalação estava rodando dentro do tmux, ela não morreu: tmux attach -t instalacao.

Tela: Permission denied, please try again. Causa: senha errada, quase sempre porque foi colada com espaço no fim, ou é a senha do painel da Hostinger em vez da senha de root do servidor. Solução: redigitar na mão, sem colar. Se não souber a senha, redefinir no painel.

2. Está rodando no lugar errado

Tela: command not found em coisas que deveriam existir, ou o comando parece funcionar mas nada acontece. Causa: a pessoa está no próprio computador, não no servidor. É o erro mais comum do encontro. Solução: olhar o início da linha. Tem que estar root@srv.... Se não estiver:

ssh root@SEU_IP

Tela: bash: install.sh: No such file or directory. Causa: esqueceu de entrar na pasta. Solução:

pwd            # onde estou
ls             # o que tem aqui
cd agente-pessoal-kit
bash install.sh

Tela: permission denied: ./install.sh. Causa: rodou ./install.sh em vez de bash install.sh. Solução: rodar com bash na frente. Sempre.

3. Telegram

Tela (no BotFather): Sorry, this username is already taken. Causa: o nome do bot já existe no mundo inteiro. Solução: acrescentar as iniciais da pessoa. Nova_bot vira Nova_MS_bot. Precisa terminar em bot.

Tela (na checagem): Token do bot não respondeu. Causa: token incompleto (quase sempre cortado no meio ao copiar) ou colado com espaço. Solução: o token tem números, depois dois-pontos, depois uma sequência longa de letras. Pedir de novo ao BotFather com /mybots, copiar inteiro, colar de novo.

Sintoma: o instalador terminou com "PRONTO!", mas o bot não responde ao "oi". Causa mais provável: o user_id está errado, então o agente ignora a mensagem por segurança (ele só responde ao dono). Solução: confirmar o ID no @userinfobot (é só número, sem @) e conferir no servidor:

grep allowFrom -A3 ~/.openclaw/openclaw.json

Se o número estiver diferente, corrigir assim: abra o arquivo com

nano ~/.openclaw/openclaw.json

ande com as setas até o número dentro de allowFrom, corrija SÓ o número (não mexa em aspas, vírgulas nem colchetes), salve com Ctrl+O + Enter e saia com Ctrl+X. Depois reinicie:

systemctl restart openclaw-gateway

Segunda causa: a pessoa está mandando mensagem pro bot errado. Se ela criou dois bots testando, precisa ser o do token que ela usou.

Terceira causa: o token gravado no servidor está quebrado (o agente sobe, mas fica surdo). O instalador atual impede isso: ele mostra "Bot confirmado: @nome" na hora do token. Se essa linha apareceu na instalação, não é este o problema. Se a pessoa instalou sem ver essa linha, o conserto (trocando SEU_TOKEN pelo token do @BotFather):

sed -i '/^TELEGRAM_BOT_TOKEN=/d' ~/.openclaw/.env
echo 'TELEGRAM_BOT_TOKEN=SEU_TOKEN' >> ~/.openclaw/.env
systemctl restart openclaw-gateway

Espere 30 segundos e mande "oi" de novo.

Regra dos colchetes (vale pra instalação inteira): pergunta com valor entre [colchetes] = Enter confirma o que está ali. Pergunta SEM colchetes = Enter em branco não preenche nada, tem que digitar ou colar.

4. Codex (o login do cérebro)

Tela no navegador: erro, página não carrega, localhost recusou a conexão, ERR_CONNECTION_REFUSED. Causa: nenhuma. Isso é o comportamento correto. Solução: copiar o endereço inteiro da barra do navegador, com erro e tudo, e colar de volta no terminal. É esse endereço que autoriza o agente.

Sintoma: colou e o terminal reclamou ou não seguiu. Causa: colou só um pedaço, geralmente só o trecho depois de code=. Solução: tem que ser o endereço inteiro, começando em http, incluindo o ?code=.

Sintoma: a autorização não aparece ou pede pra assinar. Causa: o navegador está logado numa conta ChatGPT diferente da que tem o Plus, ou numa conta grátis. Solução: abrir chatgpt.com no mesmo navegador e conferir com qual conta está logado. Trocar de conta e refazer o login. Aba anônima costuma resolver quando há várias contas.

Tela: uma lista enorme de provedores (Anthropic, DeepSeek, Fireworks, Ollama...) em vez do endereço de login. Causa: a pessoa baixou uma versão antiga do kit. A versão atual vai direto pro endereço. Solução: não aperte Enter (o selecionado é o Anthropic, que está errado). Desça com a seta até OpenAI, cerca de 30 vezes, e aí sim Enter. Digitar o nome não filtra.

Sintoma: o comando de login não abre nada, some rápido. Causa: não está num terminal de verdade. Solução: garantir que a pessoa está dentro do tmux, no servidor:

tmux attach -t instalacao

5. Durante a instalação

Sintoma: a tela ficou parada por vários minutos no começo. Causa: é a base se instalando. Leva cerca de 8 minutos. Solução: esperar. Não fechar, não apertar nada.

Sintoma: a internet da pessoa caiu e o terminal fechou. Causa: nenhuma perda, se ela abriu o tmux. Solução: reconectar e voltar pra sessão:

ssh root@SEU_IP
tmux attach -t instalacao

Se ela não tinha aberto o tmux, a instalação morreu no meio. Recomeçar do bash install.sh: é seguro rodar de novo (testado), e se o login do Codex já tinha sido feito, ele nem pede outra vez.

Tela no passo 5: SKIP redator (sem workspace) e outros nomes. Causa: falha de verdade. Os subagentes não foram criados, então ficaram sem personalidade. Solução: conferir e refazer os dois passos. Atenção: os comandos abaixo precisam ser copiados inteiros, com o começo. Sem isso os subagentes nascem com o cérebro errado (GLM, que ninguém aqui tem) e ficam mudos. Primeiro veja o nome que a pessoa usou:

cat /root/prontidao.env

Depois, trocando NOME e NomeDoAgente pelo que apareceu ali (o cd garante que está na pasta certa):

cd /root/agente-pessoal-kit
openclaw agents list
MODEL="openai/gpt-5.5" bash scripts/build-agents.sh
NOME="Fulano" AGENT_NAME="NomeDoAgente" python3 scripts/apply-personas.py
systemctl restart openclaw-gateway

Se openclaw agents list vier vazio, chame o condutor.

Tela no fim: ⚠️ Verifique: journalctl -u openclaw-gateway -n 50. Causa: o agente não subiu. Solução: rodar o comando que ele indicou, ler as últimas linhas e tentar:

systemctl restart openclaw-gateway
sleep 10
systemctl is-active openclaw-gateway

Se continuar, chame o condutor com a tela do journalctl aberta.

Tela no fim: o religador aparece como não ativo. Causa: o vigia não armou. Solução:

bash scripts/setup-religador.sh
systemctl is-active agente-religador.timer

6. Não fez a lição de casa

Sintoma: o instalador não mostra nada entre colchetes. Causa: não existe o arquivo da checagem, então não há dados guardados. Solução: digitar tudo na mão (nome, nome do agente, token, user_id). Funciona igual, só dá mais trabalho. Se ela não tiver o token à mão, aí não dá pra seguir hoje.

Quando chamar o condutor, sem tentar resolver

Comandos que você vai usar o encontro inteiro

pwd                                       # onde estou
ls                                        # o que tem aqui
tmux attach -t instalacao                 # voltar pra sessão
openclaw agents list                      # o agente existe?
systemctl is-active openclaw-gateway      # está no ar?
systemctl restart openclaw-gateway        # reiniciar
journalctl -u openclaw-gateway -n 50      # por que quebrou