# Fehlerbehebung

Haeufige Probleme und deren Loesung.

---

## Gateway-Probleme

### Gateway startet nicht

- **Port-Konflikt** -- Ein anderer Prozess verwendet moeglicherweise Port 18789. Pruefen Sie mit `lsof -i :18789`.
- **Konfigurationsfehler** -- Ungueltiges JSON in `neotask.json`. Das Gateway validiert die Konfiguration beim Start und meldet spezifische Fehler.
- **Gateway-Sperre** -- Eine vorherige Instanz hat moeglicherweise eine veraltete Sperrdatei hinterlassen. Das Diagnosetool kann dies erkennen und beheben.
- **Node.js-Version** -- Neotask erfordert Node 22+.

### Gateway startet, aber keine Channels verbinden sich

- **Fehlende Anmeldedaten** -- Jeder Channel benoetigt seine eigene Authentifizierung (Bot-Token, QR-Scan, API-Schluessel).
- **Netzwerkprobleme** -- Channels benoetigen Internetzugang, um sich mit Messaging-Plattform-APIs zu verbinden.
- **Rate Limits** -- Einige Plattformen begrenzen neue Verbindungen. Warten Sie und versuchen Sie es erneut.

### Verbindung von der Desktop-App nicht moeglich

- **Falscher Port** -- Stellen Sie sicher, dass die Desktop-App den richtigen Gateway-Port verwendet.
- **Auth-Abweichung** -- Das Gateway-Token muss uebereinstimmen.
- **Firewall** -- Stellen Sie sicher, dass der Port erreichbar ist, wenn sich das Gateway auf einem anderen Rechner befindet.

---

## Channel-Probleme

### WhatsApp verbindet sich nicht

- **QR abgelaufen** -- QR-Codes laufen nach ~60 Sekunden ab. Scannen Sie schnell erneut.
- **Multi-Device-Limit** -- WhatsApp begrenzt die Anzahl verknuepfter Geraete.
- **Session beschaedigt** -- Loeschen Sie das WhatsApp-Session-Verzeichnis und koppeln Sie erneut.

### Telegram-Bot empfaengt keine Nachrichten

- **Bot-Token ungueltig** -- Ueberpruefen Sie Ihr Bot-Token mit BotFather.
- **Datenschutzmodus** -- Bots sehen standardmaessig nur Nachrichten, wenn sie in Gruppen erwaehnt werden.
- **Webhook-Konflikt** -- Ein anderer Dienst verarbeitet moeglicherweise die Nachrichten.

### Discord-Bot antwortet nicht

- **Fehlende Intents** -- Aktivieren Sie die erforderlichen Gateway Intents im Discord Developer Portal.
- **Fehlende Berechtigungen** -- Der Bot benoetigt Lese- und Sendeberechtigungen in den Zielchannels.

---

## Modell-Probleme

### Auth-Fehler

- **Schluessel nicht konfiguriert** -- Stellen Sie sicher, dass der Anbieter-API-Schluessel gesetzt ist.
- **Schluessel abgelaufen** -- Einige OAuth-Tokens laufen ab. Authentifizieren Sie sich erneut.
- **Rate Limit** -- Schluesselrotation wechselt automatisch, wenn Sie mehrere Schluessel haben.

### Langsame Antworten

- **Modellwahl** -- Groessere Modelle sind langsamer. Versuchen Sie ein schnelleres Modell fuer einfache Aufgaben.
- **Kontextgroesse** -- Lange Gespraeche verlangsamen die Verarbeitung. Versuchen Sie `/compact`.
- **Netzwerklatenz** -- Pruefen Sie die Verbindung zu Ihrem Modellanbieter.

---

## Node-Probleme

### Begleit-App kann das Gateway nicht finden

- **Bindungsmodus** -- Das Gateway muss an LAN oder Tailnet gebunden sein (nicht Loopback) fuer externe Geraete.
- **Gleiches Netzwerk** -- Fuer Bonjour-Erkennung muessen beide Geraete im selben Netzwerk sein.
- **Manuelle Eingabe** -- Geben Sie Gateway-Host und -Port manuell in den App-Einstellungen ein.

---

## Session-Probleme

### Kontextfenster ueberschritten

- **Komprimieren** -- Verwenden Sie `/compact`, um den Kontext zusammenzufassen und zurueckzusetzen.
- **Auto-Komprimierung aktivieren** -- Setzen Sie einen Komprimierungsschwellenwert in der Konfiguration.
- **Neue Session** -- Starten Sie neu mit `/new`.

---

## Diagnose

Das integrierte Diagnosetool prueft auf haeufige Probleme und kann viele automatisch beheben:

- Konfigurationsvalidierung
- Dateiberechtigungen
- Channel-Konnektivitaet
- Modell-Auth-Status
- Node.js-Kompatibilitaet
- Netzwerkkonfiguration

Pruefen Sie die Gateway-Logs fuer detaillierte Fehlerinformationen. Der `/health`-Endpunkt bietet maschinenlesbaren Status aller Komponenten.

---

## Hilfe erhalten

1. Fuehren Sie das Diagnosetool fuer automatisierte Fehlerbehebungen aus
2. Pruefen Sie die Gateway-Logs fuer detaillierte Fehlermeldungen
3. Kontaktieren Sie den Support ueber das Intercom-Chat-Widget in der Desktop-App