# Probleemoplossing

Veelvoorkomende problemen en hoe ze op te lossen.

---

## Gateway-problemen

### Gateway start niet

- **Poortconflict**, Een ander proces kan poort 18789 gebruiken. Controleer met `lsof -i :18789`.
- **Configuratiefout**, Ongeldige JSON in `neotask.json`. De Gateway valideert de configuratie bij het opstarten en rapporteert specifieke fouten.
- **Gateway-vergrendeling**, Een vorige instantie kan een verlopen vergrendelingsbestand hebben achtergelaten. Het diagnostische hulpmiddel kan dit detecteren en oplossen.
- **Node.js-versie**, Neotask vereist Node 22+.

### Gateway start maar geen kanalen verbinden

- **Ontbrekende inloggegevens**, Elk kanaal heeft zijn eigen authenticatie nodig (bottoken, QR-scan, API-sleutel).
- **Netwerkproblemen**, Kanalen hebben internettoegang nodig om verbinding te maken met API's van berichtenplatformen.
- **Snelheidslimieten**, Sommige platforms beperken nieuwe verbindingen. Wacht en probeer opnieuw.

### Kan geen verbinding maken vanuit de desktopapp

- **Verkeerde poort**, Zorg ervoor dat de desktopapp verbinding maakt met de juiste Gateway-poort.
- **Authenticatiemismatch**, Het Gateway-token moet overeenkomen.
- **Firewall**, Zorg ervoor dat de poort toegankelijk is als de Gateway op een andere machine staat.

---

## Kanaalproblemen

### WhatsApp maakt geen verbinding

- **QR verlopen**, QR-codes verlopen na ~60 seconden. Scan snel opnieuw.
- **Limiet voor meerdere apparaten**, WhatsApp beperkt gekoppelde apparaten.
- **Sessie beschadigd**, Verwijder de WhatsApp-sessiemap en koppel opnieuw.

### Telegram-bot ontvangt geen berichten

- **Bottoken ongeldig**, Verifieer uw bottoken met BotFather.
- **Privacymodus**, Bots zien standaard alleen berichten wanneer ze worden vermeld in groepen.
- **Webhookconflict**, Een andere service kan berichten consumeren.

### Discord-bot reageert niet

- **Ontbrekende intents**, Schakel vereiste Gateway Intents in via de Discord Developer Portal.
- **Ontbrekende rechten**, De bot heeft lees- en verzendrechten nodig in doelkanalen.

---

## Modelproblemen

### Authenticatiefouten

- **Sleutel niet geconfigureerd**, Zorg ervoor dat de provider API-sleutel is ingesteld.
- **Sleutel verlopen**, Sommige OAuth-tokens verlopen. Herverificeer.
- **Snelheidslimiet**, Sleutelrotatie schakelt automatisch over als u meerdere sleutels heeft.

### Trage antwoorden

- **Modelkeuze**, Grotere modellen zijn langzamer. Probeer een sneller model voor snelle taken.
- **Contextomvang**, Lange gesprekken vertragen de verwerking. Probeer `/compact`.
- **Netwerklatentie**, Controleer de verbinding met uw modelprovider.

---

## Node-problemen

### Companion-app kan de Gateway niet vinden

- **Bindingsmodus**, De Gateway moet worden gebonden aan LAN of Tailnet (niet loopback) voor externe apparaten.
- **Zelfde netwerk**, Voor Bonjour-detectie moeten beide apparaten op hetzelfde netwerk zijn.
- **Handmatige invoer**, Voer de Gateway-host en -poort handmatig in de app-instellingen in.

---

## Sessieproblemen

### Contextvenster overschreden

- **Compact**, Gebruik `/compact` om context samen te vatten en te resetten.
- **Automatische compactie inschakelen**, Stel een compactiedrempel in de configuratie in.
- **Nieuwe sessie**, Begin opnieuw met `/new`.

---

## Diagnostiek

Het ingebouwde diagnostische hulpmiddel controleert op veelvoorkomende problemen en kan veel automatisch oplossen:

- Configuratievalidatie
- Bestandsrechten
- Kanaalconnectiviteit
- Modelauthenticatiestatus
- Node.js-compatibiliteit
- Netwerkconfiguratie

Controleer Gateway-logboeken voor gedetailleerde foutinformatie. Het `/health`-eindpunt biedt machine-leesbare status van alle componenten.

---

## Hulp krijgen

1. Voer het diagnostische hulpmiddel uit voor geautomatiseerde oplossingen
2. Controleer Gateway-logboeken voor gedetailleerde foutmeldingen
3. Neem contact op met ondersteuning via de Intercom-chatwidget in de desktopapp