Solucao de Problemas

Problemas comuns e como resolve-los.

Problemas do Gateway

Gateway nao inicia

• Conflito de porta -- Outro processo pode estar usando a porta 18789. Verifique com lsof -i :18789.
• Erro de configuracao -- JSON invalido em neotask.json. O Gateway valida a configuracao na inicializacao e relata erros especificos.
• Lock do Gateway -- Uma instancia anterior pode ter deixado um arquivo de lock obsoleto. A ferramenta de diagnostico pode detectar e corrigir isso.
• Versao do Node.js -- Neotask requer Node 22+.

Gateway inicia mas nenhum canal conecta

• Credenciais faltando -- Cada canal precisa de sua propria autenticacao (token de bot, leitura de QR, API key).
• Problemas de rede -- Canais precisam de acesso a internet para se conectar as APIs de plataformas de mensagens.
• Limites de taxa -- Algumas plataformas limitam a taxa de novas conexoes. Aguarde e tente novamente.

Nao consegue conectar pelo app desktop

• Porta errada -- Garanta que o app desktop se conecta a porta correta do Gateway.
• Auth incompativel -- O token do Gateway deve corresponder.
• Firewall -- Garanta que a porta esteja acessivel se o Gateway estiver em outra maquina.

Problemas de Canal

WhatsApp nao conecta

• QR expirou -- QR codes expiram apos ~60 segundos. Re-escaneie rapidamente.
• Limite de multi-dispositivo -- WhatsApp limita dispositivos vinculados.
• Sessao corrompida -- Delete o diretorio de sessao do WhatsApp e pare novamente.

Bot do Telegram nao recebe mensagens

• Token de bot invalido -- Verifique seu token de bot com o BotFather.
• Modo de privacidade -- Bots so veem mensagens quando mencionados em grupos por padrao.
• Conflito de webhook -- Outro servico pode estar consumindo mensagens.

Bot do Discord nao responde

• Intents faltando -- Habilite os Gateway Intents necessarios no Discord Developer Portal.
• Permissoes faltando -- O bot precisa de permissoes de leitura e envio nos canais alvo.

Problemas de Modelo

Erros de auth

• Chave nao configurada -- Garanta que a API key do provedor esteja definida.
• Chave expirada -- Alguns tokens OAuth expiram. Re-autentique.
• Limite de taxa -- A rotacao de chaves trocara automaticamente se voce tiver multiplas chaves.

Respostas lentas

• Escolha de modelo -- Modelos maiores sao mais lentos. Tente um modelo mais rapido para tarefas rapidas.
• Tamanho do contexto -- Conversas longas tornam o processamento mais lento. Tente /compact.
• Latencia de rede -- Verifique a conectividade com seu provedor de modelo.

Problemas de Node

App companion nao encontra o Gateway

• Modo de vinculacao -- O Gateway deve estar vinculado a LAN ou Tailnet (nao loopback) para dispositivos externos.
• Mesma rede -- Para descoberta Bonjour, ambos os dispositivos devem estar na mesma rede.
• Entrada manual -- Insira o host e porta do Gateway manualmente nas configuracoes do app.

Problemas de Sessao

Janela de contexto excedida

• Compactar -- Use /compact para resumir e resetar o contexto.
• Habilitar auto-compactacao -- Defina um limiar de compactacao na configuracao.
• Nova sessao -- Comece do zero com /new.

Diagnosticos

A ferramenta de diagnostico integrada verifica problemas comuns e pode corrigir muitos automaticamente:

• Validacao de configuracao
• Permissoes de arquivo
• Conectividade de canais
• Status de autenticacao de modelos
• Compatibilidade do Node.js
• Configuracao de rede

Verifique os logs do Gateway para informacoes detalhadas de erro. O endpoint /health fornece status legivel por maquina de todos os componentes.

Obtendo Ajuda

1. Execute a ferramenta de diagnostico para correcoes automaticas
2. Verifique os logs do Gateway para mensagens de erro detalhadas
3. Entre em contato com o suporte pelo widget de chat Intercom no app desktop