# Rozwiązywanie problemów

Typowe problemy i sposoby ich rozwiązania.

---

## Problemy z Gateway

### Gateway nie uruchamia się

- **Konflikt portów**, Inny proces może używać portu 18789. Sprawdź za pomocą `lsof -i :18789`.
- **Błąd konfiguracji**, Nieprawidłowy JSON w `neotask.json`. Gateway sprawdza konfigurację podczas uruchamiania i zgłasza konkretne błędy.
- **Blokada Gateway**, Poprzednie wystąpienie mogło pozostawić nieaktualny plik blokady. Narzędzie diagnostyczne może to wykryć i naprawić.
- **Wersja Node.js**, Neotask wymaga Node 22+.

### Gateway uruchamia się, ale żadne kanały się nie łączą

- **Brakujące poświadczenia**, Każdy kanał wymaga własnego uwierzytelnienia (token bota, skanowanie QR, klucz API).
- **Problemy z siecią**, Kanały potrzebują dostępu do internetu, aby połączyć się z API platform komunikacyjnych.
- **Limity szybkości**, Niektóre platformy ograniczają nowe połączenia. Poczekaj i spróbuj ponownie.

### Nie można połączyć się z aplikacji desktopowej

- **Nieprawidłowy port**, Upewnij się, że aplikacja desktopowa łączy się z właściwym portem Gateway.
- **Niezgodność tokenu**, Token Gateway musi pasować.
- **Zapora sieciowa**, Upewnij się, że port jest dostępny, jeśli Gateway znajduje się na innej maszynie.

---

## Problemy z kanałami

### WhatsApp nie łączy się

- **QR wygasł**, Kody QR wygasają po około 60 sekundach. Skanuj szybko.
- **Limit urządzeń wielosesyjnych**, WhatsApp ogranicza liczbę podłączonych urządzeń.
- **Uszkodzona sesja**, Usuń katalog sesji WhatsApp i sparuj ponownie.

### Bot Telegram nie odbiera wiadomości

- **Nieprawidłowy token bota**, Zweryfikuj token bota przez BotFather.
- **Tryb prywatności**, Boty domyślnie widzą tylko wiadomości, gdy są wspomniane w grupach.
- **Konflikt webhooka**, Inna usługa może pobierać wiadomości.

### Bot Discord nie odpowiada

- **Brakujące intenty**, Włącz wymagane Gateway Intents w Discord Developer Portal.
- **Brakujące uprawnienia**, Bot potrzebuje uprawnień do odczytywania i wysyłania wiadomości w docelowych kanałach.

---

## Problemy z modelem

### Błędy uwierzytelniania

- **Klucz nieskonfigurowany**, Upewnij się, że klucz API dostawcy jest ustawiony.
- **Klucz wygasł**, Niektóre tokeny OAuth wygasają. Uwierzytelnij się ponownie.
- **Limit szybkości**, Rotacja kluczy przełączy się automatycznie, jeśli masz wiele kluczy.

### Wolne odpowiedzi

- **Wybór modelu**, Większe modele są wolniejsze. Wypróbuj szybszy model dla szybkich zadań.
- **Rozmiar kontekstu**, Długie rozmowy spowalniają przetwarzanie. Spróbuj `/compact`.
- **Opóźnienie sieci**, Sprawdź łączność z dostawcą modelu.

---

## Problemy z węzłem

### Aplikacja towarzysząca nie może znaleźć Gateway

- **Tryb wiązania**, Gateway musi być powiązany z LAN lub Tailnet (nie loopback) dla zewnętrznych urządzeń.
- **Ta sama sieć**, W przypadku wykrywania przez Bonjour oba urządzenia muszą być w tej samej sieci.
- **Ręczne wprowadzanie**, Wprowadź ręcznie host i port Gateway w ustawieniach aplikacji.

---

## Problemy z sesją

### Przekroczono okno kontekstu

- **Compact**, Użyj `/compact`, aby podsumować i zresetować kontekst.
- **Włącz automatyczne kompaktowanie**, Ustaw próg kompaktowania w konfiguracji.
- **Nowa sesja**, Zacznij od nowa za pomocą `/new`.

---

## Diagnostyka

Wbudowane narzędzie diagnostyczne sprawdza typowe problemy i wiele z nich może naprawić automatycznie:

- Walidacja konfiguracji
- Uprawnienia do plików
- Łączność kanałów
- Status uwierzytelniania modelu
- Kompatybilność Node.js
- Konfiguracja sieci

Sprawdź logi Gateway, aby uzyskać szczegółowe informacje o błędach. Punkt końcowy `/health` zapewnia odczytywalny maszynowo status wszystkich komponentów.

---

## Uzyskiwanie pomocy

1. Uruchom narzędzie diagnostyczne w celu automatycznych napraw
2. Sprawdź logi Gateway, aby znaleźć szczegółowe komunikaty o błędach
3. Skontaktuj się z pomocą techniczną przez widget czatu Intercom w aplikacji desktopowej