Skip to main content

​
Диагностика и частые вопросы

Эта страница помогает быстро вернуть Велес в рабочее состояние. Сначала найдите симптом в таблице, затем при необходимости пройдите набор диагностических команд по порядку.
Правило большого пальца: пока Велес не отвечает на простое сообщение из командной строки (veles agent -m "привет"), не добавляйте новые каналы, навыки и интеграции — сначала почините базовый чат.

​
Частые симптомы и решения

​
Набор диагностических команд

Проходите по порядку — каждая следующая команда сужает область поиска:
Если veles status показывает корректную модель и ключи, но veles agent всё равно не отвечает — проблема на стороне провайдера (ключ, баланс, доступность модели). Если чат из командной строки работает, а интерфейс нет — проблема в подключении интерфейса к серверу (токен, порт, запущен ли veles gateway).

​
Что делать, если vector.db занимает много места

  1. Остановите veles gateway и все процессы veles agent для той же рабочей области.
  2. Запустите veles vector-memory compact без --yes. Это только план: активная база не изменяется.
  3. Если запуск с --yes сообщает, что индекс занят, его владеет другой процесс. Найдите и штатно остановите его; не удаляйте файл блокировки и не обходите проверку. Процесс старой версии может не поддерживать эту блокировку, поэтому одной успешной проверки недостаточно — все процессы всё равно должны быть остановлены.
  4. Убедитесь, что на той же файловой системе достаточно места для теневой базы и полной резервной копии.
  5. Выполните veles vector-memory compact --yes. Команда создаст и проверит свежую теневую базу до атомарной замены и не будет обращаться к поставщику модели.
  6. Запустите Велес и проверьте несколько известных запросов поиска. Только после этого вручную переместите или удалите резервную копию с отметкой времени, путь к которой напечатала команда.
Если построение или проверка теневой базы завершаются ошибкой, активный vector.db остаётся прежним. Не запускайте вручную VACUUM, не удаляйте vector.db, vector.db-wal или vector.db-shm и не переносите их во время работы Велеса. Подробности и параметры команды описаны на странице «Командная строка и эксплуатация».

​
Что проверять, если ВКонтакте не отвечает

  1. Запустите veles gateway --verbose. При нормальном запуске в журнале появляются VK channel started и затем VK long poll initialized.
  2. Проверьте channels.vk.enabled, положительный groupId и наличие секрета channels.vk.token. После замены секрета перезапустите сервер: обновление секретов не заменяет ключ уже работающего канала.
  3. В настройках сообщества разрешите сообщения, включите долгий опрос и событие новых входящих сообщений message_new.
  4. Сверьте числовой идентификатор отправителя с allowFrom. Пустой список запрещает доступ всем; при отказе в журнале появляется Access denied for sender.
  5. Проверьте, что ключ создан для того же сообщества, которое указано в groupId, и имеет право работы с сообщениями.
Канал автоматически обрабатывает служебные ответы долгого опроса:
  • failed=1 обновляет указатель событий;
  • failed=2 заменяет сервер и ключ, сохраняя указатель;
  • failed=3 полностью пересоздаёт состояние подключения.
Такие ответы не требуют ручного перезапуска. В журнале могут появляться сообщения об истёкшем ключе или потерянном состоянии, после которых должно следовать успешное VK long poll initialized. Если восстановление не произошло, ориентируйтесь на следующую строку журнала:
  • VK API ... error — неверный ключ, идентификатор сообщества или права доступа;
  • повторяющийся VK long poll error — сетевая ошибка, ошибка DNS, TLS или недоступность ВКонтакте;
  • VK send failed after ... attempts — входящее сообщение обработано, но итоговый ответ не удалось доставить;
  • VK event processing failed — одно повреждённое событие пропущено; следующие события продолжают обрабатываться.
Канал отправляет только текст. Файл без текстового сопровождения завершится ошибкой доставки, а файл рядом с текстом будет пропущен с предупреждением. Полная настройка полей описана в разделе ВКонтакте.

​
Что проверять при проблемах с интерфейсом

  1. Сервер запущен: veles gateway (или systemctl --user status veles-gateway).
  2. Порт совпадает: интерфейс подключается к тому же gateway.port.
  3. Токен совпадает: интерфейс использует тот же gateway.token.
  4. GET /health отвечает; GET /status с токеном возвращает статус.
  5. В логах сервера нет ошибок авторизации (Unauthorized, код -32001).
Подробности контракта подключения и кодов ошибок — на странице API.

​
Что проверять при ошибке удаления маркетплейса

  1. Запустите шлюз командой veles gateway --verbose и повторите удаление из интерфейса.
  2. Найдите строку [skill-marketplace-delete] с нужным marketplace_id.
  3. Сообщение storage move failed означает ошибку до изменения конфигурации; storage cleanup failed — ошибку очистки; rollback failed — ошибку восстановления. Смотрите error_type, errno, winerror и затронутые пути.
  4. При WinError 5 или WinError 32 Велес автоматически повторяет атомарное переименование и очистку с короткими увеличивающимися паузами. Ошибка после всех попыток означает, что другой процесс удерживает путь дольше допустимого времени.
  5. WinError 145 на глубоко вложенной папке обычно означает, что обычный путь Windows не позволил очистить всё её содержимое; шлюз использует расширенный формат пути, чтобы обработать такое дерево.
  6. Строка deletion rolled back означает, что исходная конфигурация и папка восстановлены.
Настройки источника и секреты в эти записи не включаются. Для разбора достаточно передать строку с указанной меткой и трассировку исключения.

​
Что проверять, если маркетплейс не находит навыки

  1. Проверьте адрес источника. Для GitHub нужен публичный адрес HTTPS на github.com. Для GitLab допустим адрес HTTP или HTTPS на любом узле; он не должен содержать учётные данные, строку запроса или фрагмент.
  2. Запустите шлюз командой veles gateway --verbose и повторите добавление или синхронизацию маркетплейса.
  3. Найдите строки [skill-marketplace-scan] skill rejected. В каждой строке указаны относительный путь SKILL.md и точная причина отклонения в поле reason. Велес выводит не более первых 50 отклонений; количество остальных указывается отдельно.
  4. Итоговая строка [skill-marketplace-scan] no valid skills found содержит идентификатор и тип маркетплейса, количество отклонённых файлов и первую причину.
  5. Если rejected=0, в репозитории не найдено ни одного файла SKILL.md. Иначе исправьте перечисленные файлы: чаще всего имя навыка не совпадает с каталогом, вводная часть YAML повреждена или поле имеет неподдерживаемый тип.
Полный текст инструкций, настройки источника и секреты в журнал не записываются. Пути и причины переводятся в одну строку, ограничиваются по длине и количеству, чтобы данные внешнего репозитория не могли повредить структуру журнала.

​
Частые вопросы

Нужен ли интернет для работы Велеса? Зависит от модели. Для облачных провайдеров (OpenRouter, OpenAI и т.п.) — да. С локальной моделью базовый чат работает офлайн, но веб-поиск, MCP и часть навыков требуют сети. См. Провайдеры и модели. Где хранятся мои данные? В рабочей области и каталоге ~/.veles (конфигурация, память, служебное состояние, зашифрованные секреты). В Docker монтируйте ~/.veles, чтобы данные переживали перезапуск контейнера. Можно ли запустить несколько независимых Велесов? Да. Используйте отдельные --config, рабочие области и порты. См. Установка и первый запуск. Как безопасно хранить ключи и токены? Через панель секретов и зашифрованное хранилище, а не в сообщениях чата. См. Секреты и токены. Почему Велес «забыл» то, что я говорил раньше? Контекст одной сессии ограничен. Устойчивые факты и правила нужно явно сохранять в память. См. Память Велеса. Изменил конфигурацию — нужно ли перезапускать сервер? Секреты можно перечитать на лету (secrets.refresh). Изменения структуры конфигурации (порты, каналы, провайдеры) надёжнее применять перезапуском veles gateway. Почему объединённый сервис Railway перезапускается при завершении Велеса или Nerve? Сценарий запуска следит за обоими процессами. Если один из них завершается, сценарий останавливает второй и возвращает код ошибки, после чего политика ON_FAILURE из railway.toml перезапускает весь сервис. Проверка /health также завершается ошибкой, когда Nerve работает, но шлюз недоступен. Что означает сообщение об отсутствующем workspace/sessions/sessions.json? Это необязательное устаревшее хранилище скрытых служебных сессий Nerve. Если файл отсутствует, маршрут возвращает пустой список с кодом 200; данные Велеса и файлы _sessions.jsonl не повреждены. Актуальная версия не выводит это штатное состояние как ошибку в журнал.

​
Что читать дальше