# Устранение неполадок

Распространённые проблемы и способы их решения.

---

## Проблемы с Gateway

### Gateway не запускается

- **Конфликт портов**, другой процесс может использовать порт 18789. Проверьте с помощью `lsof -i :18789`.
- **Ошибка конфигурации**, неверный JSON в `neotask.json`. Gateway проверяет конфигурацию при запуске и сообщает о конкретных ошибках.
- **Блокировка Gateway**, предыдущий экземпляр мог оставить устаревший файл блокировки. Диагностический инструмент может обнаружить и исправить это.
- **Версия Node.js**, Neotask требует Node 22+.

### Gateway запускается, но каналы не подключаются

- **Отсутствующие учётные данные**, каждый канал требует собственной аутентификации (токен бота, сканирование QR, ключ API).
- **Проблемы с сетью**, каналам нужен доступ в интернет для подключения к API платформ обмена сообщениями.
- **Ограничения частоты запросов**, некоторые платформы ограничивают скорость новых подключений. Подождите и повторите попытку.

### Не удаётся подключиться из десктопного приложения

- **Неверный порт**, убедитесь, что десктопное приложение подключается к правильному порту Gateway.
- **Несоответствие аутентификации**, токен Gateway должен совпадать.
- **Брандмауэр**, убедитесь, что порт доступен, если Gateway находится на другой машине.

---

## Проблемы с каналами

### WhatsApp не подключается

- **QR устарел**, QR-коды истекают примерно через 60 секунд. Быстро отсканируйте повторно.
- **Лимит multi-device**, WhatsApp ограничивает количество связанных устройств.
- **Повреждённая сессия**, удалите директорию сессии WhatsApp и выполните повторное сопряжение.

### Бот Telegram не получает сообщения

- **Недействительный токен бота**, проверьте токен бота через BotFather.
- **Режим конфиденциальности**, боты по умолчанию видят сообщения в группах только при упоминании.
- **Конфликт вебхука**, другой сервис может перехватывать сообщения.

### Бот Discord не отвечает

- **Отсутствующие интенты**, включите необходимые Gateway Intents на портале Discord Developer Portal.
- **Недостаточно разрешений**, бот нуждается в разрешениях на чтение и отправку в целевых каналах.

---

## Проблемы с моделями

### Ошибки аутентификации

- **Ключ не настроен**, убедитесь, что ключ API провайдера задан.
- **Ключ устарел**, некоторые OAuth-токены истекают. Выполните повторную аутентификацию.
- **Ограничение частоты запросов**, ротация ключей переключится автоматически, если у вас несколько ключей.

### Медленные ответы

- **Выбор модели**, более крупные модели работают медленнее. Попробуйте более быструю модель для быстрых задач.
- **Размер контекста**, длинные разговоры замедляют обработку. Попробуйте `/compact`.
- **Задержка сети**, проверьте подключение к провайдеру модели.

---

## Проблемы с узлами

### Компаньон-приложение не может найти Gateway

- **Режим привязки**, Gateway должен быть привязан к LAN или Tailnet (не loopback) для внешних устройств.
- **Одна сеть**, для обнаружения через Bonjour оба устройства должны быть в одной сети.
- **Ручной ввод**, введите хост и порт Gateway вручную в настройках приложения.

---

## Проблемы с сессиями

### Превышен лимит контекстного окна

- **Уплотнение**, используйте `/compact` для суммаризации и сброса контекста.
- **Включите автоуплотнение**, задайте порог уплотнения в конфигурации.
- **Новая сессия**, начните заново с `/new`.

---

## Диагностика

Встроенный диагностический инструмент проверяет наличие распространённых проблем и может исправить многие из них автоматически:

- Валидация конфигурации
- Права доступа к файлам
- Подключение каналов
- Статус аутентификации модели
- Совместимость с Node.js
- Конфигурация сети

Проверяйте логи Gateway для получения подробной информации об ошибках. Эндпоинт `/health` предоставляет машиночитаемый статус всех компонентов.

---

## Получение помощи

1. Запустите диагностический инструмент для автоматических исправлений
2. Проверьте логи Gateway для получения подробных сообщений об ошибках
3. Свяжитесь с поддержкой через виджет чата Intercom в десктопном приложении