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