# 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