# Risoluzione dei Problemi

Problemi comuni e come risolverli.

---

## Problemi del Gateway

### Il Gateway non si avvia

- **Conflitto di porta**, Un altro processo potrebbe utilizzare la porta 18789. Verifica con `lsof -i :18789`.
- **Errore di configurazione**, JSON non valido in `neotask.json`. Il Gateway valida la configurazione all'avvio e segnala errori specifici.
- **Gateway lock**, Un'istanza precedente potrebbe aver lasciato un file di lock obsoleto. Lo strumento di diagnostica può rilevare e risolvere questo problema.
- **Versione Node.js**, Neotask richiede Node 22+.

### Il Gateway si avvia ma nessun canale si connette

- **Credenziali mancanti**, Ogni canale necessita della propria autenticazione (token bot, scansione QR, chiave API).
- **Problemi di rete**, I canali necessitano di accesso a Internet per connettersi alle API delle piattaforme di messaggistica.
- **Limiti di velocità**, Alcune piattaforme limitano le nuove connessioni. Attendi e riprova.

### Impossibile connettersi dall'app desktop

- **Porta errata**, Assicurati che l'app desktop si connetta alla porta del Gateway corretta.
- **Token non corrispondente**, Il token del Gateway deve corrispondere.
- **Firewall**, Assicurati che la porta sia accessibile se il Gateway si trova su un'altra macchina.

---

## Problemi dei Canali

### WhatsApp non si connette

- **QR scaduto**, I codici QR scadono dopo circa 60 secondi. Esegui la scansione rapidamente.
- **Limite dispositivi multipli**, WhatsApp limita i dispositivi collegati.
- **Sessione corrotta**, Elimina la directory della sessione WhatsApp ed esegui nuovamente il pairing.

### Il bot Telegram non riceve messaggi

- **Token bot non valido**, Verifica il tuo token bot con BotFather.
- **Modalità privacy**, Per default, i bot vedono solo i messaggi quando vengono menzionati nei gruppi.
- **Conflitto webhook**, Un altro servizio potrebbe consumare i messaggi.

### Il bot Discord non risponde

- **Intent mancanti**, Abilita i Gateway Intent richiesti nel Discord Developer Portal.
- **Permessi mancanti**, Il bot necessita dei permessi di lettura e invio nei canali target.

---

## Problemi dei Modelli

### Errori di autenticazione

- **Chiave non configurata**, Assicurati che la chiave API del provider sia impostata.
- **Chiave scaduta**, Alcuni token OAuth scadono. Ri-autenticati.
- **Limite di velocità**, La rotazione delle chiavi passerà automaticamente se hai più chiavi.

### Risposte lente

- **Scelta del modello**, I modelli più grandi sono più lenti. Prova un modello più veloce per compiti rapidi.
- **Dimensione del contesto**, Le conversazioni lunghe rallentano l'elaborazione. Prova `/compact`.
- **Latenza di rete**, Controlla la connettività al tuo provider di modelli.

---

## Problemi dei Nodi

### L'app companion non riesce a trovare il Gateway

- **Modalità di binding**, Il Gateway deve essere legato alla LAN o al Tailnet (non loopback) per i dispositivi esterni.
- **Stessa rete**, Per la scoperta Bonjour, entrambi i dispositivi devono essere sulla stessa rete.
- **Inserimento manuale**, Inserisci manualmente l'host e la porta del Gateway nelle impostazioni dell'app.

---

## Problemi delle Sessioni

### Finestra di contesto superata

- **Compact**, Usa `/compact` per riassumere e resettare il contesto.
- **Abilita la compattazione automatica**, Imposta una soglia di compattazione nella configurazione.
- **Nuova sessione**, Inizia da capo con `/new`.

---

## Diagnostica

Lo strumento di diagnostica integrato controlla i problemi comuni e può risolverne molti automaticamente:

- Validazione della configurazione
- Permessi dei file
- Connettività dei canali
- Stato dell'autenticazione dei modelli
- Compatibilità Node.js
- Configurazione di rete

Controlla i log del Gateway per informazioni dettagliate sugli errori. L'endpoint `/health` fornisce lo stato leggibile dalle macchine di tutti i componenti.

---

## Ottenere Aiuto

1. Esegui lo strumento di diagnostica per correzioni automatiche
2. Controlla i log del Gateway per messaggi di errore dettagliati
3. Contatta il supporto tramite il widget chat Intercom nell'app desktop