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

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

Проблемы с 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 в десктопном приложении