SkillFoxx
Telegram

Hermes VK Adapter — плагин

hermes-vk-adapter

Плагин подключает личные сообщения сообщества ВКонтакте к Hermes Agent через Bots Long Poll без публичного адреса и вебхука

  • 0 ★ репозитория
  • Последний коммит
  • MIT
Плагин

Расширенный доступ

Почему такой уровень

  • Ключ сообщества открывает личные сообщения и позволяет отвечать от имени сообщества
  • Агент Hermes исполняет запросы из внешнего чата, поэтому круг пользователей ограничивается списком
Все причины и проверки
Российский стек

luckdmst/hermes-vk-adapterАвтор:LuckDMST

Установка

Сервисы

Ручная установка

docker exec "$CONTAINER" hermes plugins enable vk-platform

После копирования `plugin.yaml`, `__init__.py` и `adapter.py` в `plugins/vk-platform` постоянного хранилища Hermes.

Доступ и проверки

Как мы проверяем

Расширенный доступИнструмент запускает код или ходит в сеть, а внешние данные только читает.

  • Ключ сообщества открывает личные сообщения и позволяет отвечать от имени сообщества
  • Агент Hermes исполняет запросы из внешнего чата, поэтому круг пользователей ограничивается списком

Это чужой код. Посмотрите файлы в репозитории перед установкой.

Что делает

Адаптер получает входящие личные сообщения сообщества по Bots Long Poll и отправляет ответы Hermes Agent методом `messages.send`. Публичный IP, входящий порт и Callback API не нужны. Цепочка такая: пользователь пишет сообществу, плагин принимает событие, Hermes отвечает, и ответ уходит в тот же диалог. Поддерживаются личные текстовые сообщения и обычные сессии Hermes с сохранением контекста между репликами. Доступ ограничен списком `VK_ALLOWED_USERS` для входящих и исходящих сообщений. Адаптер переподключает Long Poll, хранит его курсор между перезапусками и делит длинные ответы на части допустимого размера. При включенном событии `message_event` работает доставка с кнопкой подтверждения. Интеграция проверена на Hermes Agent 0.21.0 и VK API 5.199 в Docker. Установка включает копирование `plugin.yaml`, `__init__.py` и `adapter.py` в каталог `plugins/vk-platform` постоянного хранилища Hermes и команду `hermes plugins enable vk-platform`.

Для кого. Владельцам Hermes Agent в Docker, которые хотят общаться с агентом из личных сообщений своего сообщества ВКонтакте без открытых портов.

Подходит, если

  • Hermes Agent крутится на домашнем сервере за NAT, а переписка с ним нужна из VK
  • Доступ к агенту получают только несколько известных идентификаторов пользователей
  • После пересоздания контейнера контекст разговора и курсор Long Poll остаются на месте
  • Агент подтверждает опасное действие кнопкой в диалоге ВКонтакте

Не подходит, если

  • Беседы и вложения: групповые чаты, вложения и другие события VK адаптер не обрабатывает
  • Версия Hermes отличается от 0.21.0: другие версии автор не проверял
  • Плагин нельзя положить в постоянное хранилище, и после пересоздания контейнера он пропадет

Пример запроса к агенту

Напиши сообществу в личку «Что у меня запланировано на завтра?»: Hermes ответит в том же диалоге ВКонтакте.

Ограничения

Работает только с личными текстовыми сообщениями сообщества. Нужен ключ доступа сообщества с разрешениями `messages` и `manage`: ключ только с `messages` в проверенной установке давал ошибку VK 15 при запросе сервера Long Poll. Включите сообщения сообщества, Long Poll API и событие «Входящее сообщение», для кнопок еще «Действие с сообщением».

Переменные `VK_TOKEN`, `VK_GROUP_ID` и `VK_ALLOWED_USERS` читаются из окружения процесса Hermes, и простой `docker restart` их не применяет: контейнер надо пересоздать через Compose. Список разрешенных пользователей обязателен, минимум один идентификатор.

Как отключить. Выполните `docker exec <контейнер> hermes plugins disable vk-platform`, уберите переменные VK из окружения и пересоздайте контейнер.

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

Нужен ли публичный адрес для плагина?

Нет. Long Poll работает как исходящее соединение, поэтому ни домен, ни входящий порт, ни Callback API не нужны.

Какие права нужны ключу сообщества?

`messages` и `manage`. Без `manage` Long Poll в проверенной установке не заработал и VK вернул ошибку 15.

Как включить плагин в Hermes?

Скопируйте файлы в `plugins/vk-platform` постоянного хранилища и выполните `docker exec <контейнер> hermes plugins enable vk-platform`, затем перезапустите шлюз.

Кто может писать боту?

Только пользователи из списка `VK_ALLOWED_USERS`. Сообщение от идентификатора вне списка не обрабатывается.

Где хранится курсор Long Poll?

По умолчанию в `plugin-data/vk-platform` внутри каталога Hermes, путь можно сменить переменной `VK_STATE_DIR`. После перезапуска контейнера курсор подхватывается.

Обсуждение

Вопросов и отзывов пока нет.

ВКонтакте — все инструменты
Российский стек

Плагин ВКонтакте для Hermes Agent: бот группы принимает личные сообщения и беседы по Long Poll API, агент отвечает от имени сообщества

ПлагинРасширенный доступ1
Российский стек

Канал ВКонтакте для Hermes Agent: Long Poll, кнопки и выбор модели в диалоге, голосовые, картинки, доставка cron-отчетов и парное подтверждение

ПлагинРасширенный доступ
Российский стек

Плагин-канал Claude Code: переписка с сессией агента через сообщество ВКонтакте с мобильного или веба

ПлагинШирокий доступ2
Российский стек

MCP-сервер на 4 инструмента: забирает посты со стены VK, фильтрует по правилам и публикует в Telegram через Bot API

MCP-серверШирокий доступ
Российский стек

Плагин Claude Code: расширение браузера перехватывает токен веб-мессенджера VK и отдает read-only доступ к переписке через MCP

ПлагинРасширенный доступ
Российский стек

Локальный MCP-сервер для VK API: поиск людей и городов, профили, фото и видео с HTML-галереей, пул токенов и кэш SQLite

MCP-серверШирокий доступ

Коротко о README

README ведет по шагам: подготовка сообщества, поиск постоянного хранилища Hermes в Docker, установка плагина, переменные окружения, включение, проверка обмена, устранение неполадок и разработка, со скриншотами проверенного обмена.

Бейдж для README

Сообщить о проблеме