openclaw/skills/vk-bridge/SKILL.md

name, description

name	description
vk-bridge	Интеграция ВКонтакте (сообщество) через Bots Long Poll API: слушать message_new, извлекать текст/метаданные, проксировать запрос в локальный AI-обработчик и отправлять ответ в VK через messages.send. Использовать, когда нужно подключить входящие сообщения VK к ассистенту и отвечать пользователям автоматически.

VK Bridge

Подключай сообщество VK к локальному обработчику ответов через Long Poll.

Что входит

• scripts/vk-longpoll-bridge.mjs — раннер Long Poll + отправка ответов в VK.
• scripts/vk-openclaw-endpoint.mjs — локальный HTTP endpoint /vk/inbound, который проксирует сообщения в OpenClaw /v1/responses.
• references/.env.example — пример конфигурации.

Быстрый запуск

1. Скопируй конфиг:
   • cp skills/vk-bridge/references/.env.example .env.vk
2. Заполни VK_TOKEN и OPENCLAW_GATEWAY_TOKEN.
3. Запусти локальный endpoint:
   • node skills/vk-bridge/scripts/vk-openclaw-endpoint.mjs --env .env.vk
4. В отдельном процессе запусти Long Poll worker:
   • node skills/vk-bridge/scripts/vk-longpoll-bridge.mjs --env .env.vk

Требования

• Токен сообщества VK с правами messages.
• Включённые сообщения сообщества в настройках группы.
• Long Poll API включён для сообщества.
• Локальный HTTP-обработчик, который принимает входящее сообщение и возвращает текст ответа.
• В Gateway включён HTTP endpoint POST /v1/responses и известен токен доступа.

Протокол AI-обработчика

Bridge делает POST на OPENCLAW_BRIDGE_URL с JSON:

• source: vk
• group_id
• user_id
• peer_id
• text
• payload
• attachments
• raw

Ожидает JSON-ответ:

• reply (string) — текст для отправки в VK.
• silent (boolean, optional) — если true, не отправлять ответ.

Дополнительные настройки

• VK_ALLOWED_EVENTS — список типов событий через запятую (по умолчанию message_new).
• VK_SYNC_LONGPOLL_SETTINGS=1 — при старте проверяй groups.getLongPollSettings и включай нужные события через groups.setLongPollSettings.
• VK_API_VERSION=5.199 — рекомендуемая версия (раннер предупреждает, если другая).

Надёжность

• При failed=1 обновляй ts.
• При failed=2|3 запрашивай новый server/key/ts через groups.getLongPollServer.
• Игнорируй пустые/служебные сообщения и события вне списка VK_ALLOWED_EVENTS.
• Не отвечай на исходящие (out=1).