# Dépannage

Problèmes courants et comment les résoudre.

---

## Problèmes de Gateway

### Le Gateway ne démarre pas

- **Conflit de port**, Un autre processus utilise peut-être le port 18789. Vérifiez avec `lsof -i :18789`.
- **Erreur de configuration**, JSON invalide dans `neotask.json`. Le Gateway valide la configuration au démarrage et signale des erreurs spécifiques.
- **Verrou du Gateway**, Une instance précédente a peut-être laissé un fichier verrou périmé. L'outil de diagnostic peut détecter et corriger ce problème.
- **Version Node.js**, Neotask nécessite Node 22+.

### Le Gateway démarre mais aucun canal ne se connecte

- **Identifiants manquants**, Chaque canal a besoin de sa propre authentification (jeton de bot, scan QR, clé API).
- **Problèmes réseau**, Les canaux ont besoin d'un accès Internet pour se connecter aux API des plateformes de messagerie.
- **Limites de taux**, Certaines plateformes limitent les nouvelles connexions. Attendez et réessayez.

### Impossible de se connecter depuis l'application de bureau

- **Mauvais port**, Assurez-vous que l'application de bureau se connecte au bon port du Gateway.
- **Incompatibilité d'authentification**, Le jeton du Gateway doit correspondre.
- **Pare-feu**, Assurez-vous que le port est accessible si le Gateway est sur une autre machine.

---

## Problèmes de canaux

### WhatsApp ne se connecte pas

- **QR expiré**, Les codes QR expirent après ~60 secondes. Re-scannez rapidement.
- **Limite d'appareils multi-dispositifs**, WhatsApp limite les appareils liés.
- **Session corrompue**, Supprimez le répertoire de session WhatsApp et re-couplez.

### Le bot Telegram ne reçoit pas de messages

- **Jeton de bot invalide**, Vérifiez votre jeton de bot avec BotFather.
- **Mode de confidentialité**, Les bots ne voient les messages que lorsqu'ils sont mentionnés dans les groupes par défaut.
- **Conflit de webhook**, Un autre service consomme peut-être les messages.

### Le bot Discord ne répond pas

- **Intents manquants**, Activez les Gateway Intents requis dans le Portail des développeurs Discord.
- **Permissions manquantes**, Le bot a besoin des permissions de lecture et d'envoi dans les canaux cibles.

---

## Problèmes de modèles

### Erreurs d'authentification

- **Clé non configurée**, Assurez-vous que la clé API du fournisseur est définie.
- **Clé expirée**, Certains jetons OAuth expirent. Ré-authentifiez-vous.
- **Limite de taux**, La rotation des clés basculera automatiquement si vous avez plusieurs clés.

### Réponses lentes

- **Choix du modèle**, Les modèles plus grands sont plus lents. Essayez un modèle plus rapide pour les tâches rapides.
- **Taille du contexte**, Les longues conversations ralentissent le traitement. Essayez `/compact`.
- **Latence réseau**, Vérifiez la connectivité à votre fournisseur de modèle.

---

## Problèmes de nœuds

### L'application compagnon ne trouve pas le Gateway

- **Mode de liaison**, Le Gateway doit être lié au LAN ou au Tailnet (pas à la boucle locale) pour les appareils externes.
- **Même réseau**, Pour la découverte Bonjour, les deux appareils doivent être sur le même réseau.
- **Saisie manuelle**, Entrez l'hôte et le port du Gateway manuellement dans les paramètres de l'application.

---

## Problèmes de sessions

### Fenêtre de contexte dépassée

- **Compacter**, Utilisez `/compact` pour résumer et réinitialiser le contexte.
- **Activer la compaction automatique**, Définissez un seuil de compaction dans la configuration.
- **Nouvelle session**, Commencez à nouveau avec `/new`.

---

## Diagnostics

L'outil de diagnostic intégré vérifie les problèmes courants et peut en corriger beaucoup automatiquement :

- Validation de la configuration
- Permissions de fichiers
- Connectivité des canaux
- Statut d'authentification du modèle
- Compatibilité Node.js
- Configuration réseau

Consultez les journaux du Gateway pour des informations d'erreur détaillées. Le point de terminaison `/health` fournit le statut lisible par machine de tous les composants.

---

## Obtenir de l'aide

1. Exécutez l'outil de diagnostic pour des corrections automatisées
2. Consultez les journaux du Gateway pour des messages d'erreur détaillés
3. Contactez le support via le widget de chat Intercom dans l'application de bureau