Skip to main content

​
Каналы и интеграции

Канал — это способ доставить сообщение в Велес и получить ответ обратно. Каналом может быть интерфейс Велеса, CLI, Telegram, WhatsApp, Discord, Feishu, Slack, email, QQ, Matrix, DingTalk, WeCom, Mochat или интеграция-расширение.

​
Общая модель

Канал отвечает за доставку сообщений. Цикл работы Велеса остаётся общим: Это значит, что инструменты, память, модель и правила Велеса применяются независимо от того, пришло сообщение из интерфейса, CLI или Telegram.

​
Общие настройки channels

Для внешних каналов подсказки об инструментах лучше включать осторожно: они могут раскрывать имена файлов, команды или внутреннюю структуру задачи.

​
allowFrom

Большинство каналов поддерживает whitelist отправителей:
Правила:
  • [] — запретить всем;
  • ["*"] — разрешить всем;
  • список id — разрешить только указанным отправителям.
Не используйте ["*"] для публичного Велеса с включёнными файловыми инструментами, оболочкой или MCP.

​
Telegram

Telegram обычно требует токен Велеса Telegram и allowFrom.
После настройки запустите:
Подробнее: Команды Велеса в Telegram.

​
Другие встроенные каналы

В кодовой базе есть встроенные модули каналов для: Точные поля зависят от конфигурации канала. Общий принцип одинаковый: включить enabled, задать учётные данные, настроить allowFrom, запустить veles gateway.

​
Push-уведомления (Firebase Cloud Messaging)

Канал push доставляет исходящие сообщения агента как web push-уведомления на подписанные устройства: браузер и установленную PWA на Windows, Android и iPadOS/iOS (iOS 16.4+, PWA должна быть добавлена на домашний экран). Канал только исходящий: любое OutboundMessage с channel="push" рассылается на все зарегистрированные токены устройств (или на один токен, если chat_id совпадает с ним). Конфигурация в channels.push (config.json):
notifyOnReplies — зеркалирование ответов веб-чата в push. Когда включено, каждый финальный ответ агента в веб-сессии автоматически отправляется как push-уведомление, если ни одна вкладка/PWA сейчас не видима. Вкладки сообщают видимость через POST /push/presence; запись считается видимой в течение presenceTtlSeconds секунд после последней отметки. По умолчанию это 100 секунд, потому что Nerve повторяет видимую отметку примерно каждые 45 секунд. Это логика приложения, а не решение агента: прогресс-сообщения и повторы не зеркалируются. Переключается в Nerve → настройки конфигурации → каналы → push. presenceTtlSeconds — время в секундах, в течение которого последняя видимая вкладка/PWA подавляет push-уведомления с ответами веб-чата. Минимальное значение при чтении конфигурации — 1 секунда. Секреты хранятся в зашифрованном хранилище Велеса (см. Секреты):
  • channels.push.apiKey — web API key Firebase. Он в любом случае отдается браузеру (это публичное значение по модели Firebase), но по политике деплоя хранится в секретах.
  • channels.push.serviceAccount — полный JSON сервисного аккаунта Firebase. Это настоящий серверный секрет: им подписываются отправки через FCM HTTP v1.
Настройка Firebase (один раз на проект):
  1. Создайте проект в Firebase console и включите Cloud Messaging.
  2. Добавьте web-приложение для каждого домена/инстанса — каждое получает свой appId (остальные значения проекта общие).
  3. В Cloud Messaging → Web configuration сгенерируйте пару ключей Web Push (VAPID) — публичный ключ идет в vapidKey.
  4. В Project settings → Service accounts скачайте JSON сервисного аккаунта и сохраните его строкой в секрет channels.push.serviceAccount.
Изоляция инстансов: токены устройств хранятся per-instance в ~/.veles/push_subscriptions.json, каждый сервер знает только свои подписки. Учтите, что при общем Firebase-проекте сервисный аккаунт технически способен отправлять на токены любого инстанса этого проекта; для полной изоляции используйте отдельные проекты. Подписка устройств выполняется веб-интерфейсом (Nerve) автоматически: при открытии приложения запрашивается разрешение на уведомления (на Safari/iOS — через баннер с одним нажатием), затем FCM-токен регистрируется через POST /push/subscriptions. Недействительные токены (UNREGISTERED) удаляются автоматически при отправке.

​
WhatsApp и мост

Для WhatsApp используется мост. Вход запускается командой:
Команда готовит мост, запускает Node.js-процесс и показывает QR-код для привязки устройства. Полезные команды:

​
Каналы-расширения

Велес поддерживает архитектуру расширений для каналов. veles onboard добавляет конфигурацию по умолчанию для обнаруженных встроенных каналов и каналов-расширений, не перетирая существующие значения. Для разработки канала читайте Руководство по плагинам каналов.

​
Сессии по каналам

Обычно ключ сессии строится так:
Примеры:
Расписания и периодические проверки могут создавать отдельные служебные сессии, но доставка результата должна проходить через сервер Велеса, чтобы интерфейс и история видели тот же ответ, который получил пользователь.

​
Каналы и безопасность

Перед включением внешнего канала проверьте:
  • allowFrom не пустой случайно и не ["*"] без причины;
  • tools.restrictToWorkspace включён;
  • exec выключен или ограничен;
  • секреты не лежат в рабочей области открытым текстом;
  • токен интерфейса и сервера Велеса не опубликован;
  • прогресс и подсказки об инструментах не раскрывают лишнего.