@openclaw-vk/vk

v2026.9.10

Published

15 days ago

OpenClaw VK (VKontakte) channel plugin

0High
0Medium
0Low

pfrankov

openclaw openclaw-plugin openclaw-channel vk vkontakte vk-bot bot

openclaw-vk

Плагин OpenClaw для работы с ВКонтакте. Подключает AI-агента к сообществам VK через Bots Long Poll API — бот принимает и отвечает на сообщения в личных диалогах и групповых беседах.
Минимальная требуемая версия OpenClaw: v2026.8.1. Поддерживаются те же версии Node.js, что и OpenClaw 2026.8.1: 22.22.3–22.x, 24.15.0–24.x или 25.9.0+; Node.js 23 и 25.0–25.8 не поддерживаются.

Обычные ответы в личном диалоге отправляются без цитаты. В групповой беседе бот цитирует входящее сообщение, а ответы на callback-кнопки сохраняют привязку к сообщению с кнопкой.

Быстрый старт

1. Подготовка сообщества ВКонтакте

Создайте сообщество (группу или паблик), если его ещё нет.
Откройте Управление → Сообщения и включите их.
Откройте Управление → Работа с API → Ключи доступа, нажмите Создать ключ и выберите права:
- Сообщения сообщества
- Управление сообществом (необходимо для Bots Long Poll API)
- Фотографии / photos (обязательно для исходящих изображений, включая результаты image-edit)
- Документы / docs (обязательно для исходящих файлов, TTS audio и голосовых сообщений, потому что VK upload идёт через docs.getMessagesUploadServer)
Откройте Управление → Работа с API → Long Poll API:
- Включите Long Poll API.
- На вкладке Типы событий отметьте Входящие сообщения.
- Там же отметьте Действие с сообщением (message_event): без него нажатия на кнопки вопросов агента (ask_user, AskUserQuestion) до бота не доходят и кнопка крутится. Ответить на вопрос текстом («2», вариант или свой ответ) можно и без этого.
(Для работы в беседах) Откройте Управление → Сообщения → Настройки для бота и включите Разрешать добавлять сообщество в чаты.

2. Установка плагина

Установи OpenClaw-плагин для vk чётко по инструкции https://github.com/pfrankov/openclaw-vk
Вот мой токен: vk1.a...

# OpenClaw 2026.8.2 requires explicit trust and capability consent
openclaw plugins install @openclaw-vk/vk --force --accept-capabilities
openclaw plugins info vk --json

В OpenClaw 2026.8.2 успешная установка сразу включает плагин, поэтому отдельная команда openclaw plugins enable vk обычно не нужна. Выполните её только если openclaw plugins info vk --json явно показывает, что уже установленный плагин отключён:

openclaw plugins enable vk

Флаги --force --accept-capabilities подтверждают установку внешнего npm-пакета и запрошенные им возможности. Используйте их только для пакета, источник которого вы проверили.

2.1 Обновление плагина

# OpenClaw 2026.8.2 обновляет установленный плагин по его id
openclaw plugins update vk

# Или обновить все плагины
openclaw plugins update --all

# Установить конкретную версию
openclaw plugins install @openclaw-vk/[email protected] --force --accept-capabilities
openclaw gateway restart
openclaw channels status --json --probe

Только для локальной разработки: openclaw plugins install ~/path/to/openclaw-vk

Примечание про plugins.allow:

Если plugins.allow отсутствует или пуст, OpenClaw обычно подхватывает внешний плагин vk автоматически после openclaw plugins enable vk и включённого channels.vk.enabled.
Если у вас уже используется явный allowlist плагинов (plugins.allow не пуст), добавьте туда "vk" вручную. Команда openclaw plugins enable vk сейчас не дописывает plugins.allow автоматически.

Пример для конфигураций с явным allowlist:

{
  "plugins": {
    "allow": ["vk"]
  },
  "channels": {
    "vk": {
      "enabled": true,
      "token": "<ВАШ_ТОКЕН>",
      "dmPolicy": "pairing"
    }
  }
}

3. Настройка

Добавьте канал в ~/.openclaw/openclaw.json:

{
  "channels": {
    "vk": {
      "enabled": true,
      "token": "<ВАШ_ТОКЕН>",
      "dmPolicy": "pairing"
    }
  }
}

4. Запуск

Перезапустите шлюз:
```
openclaw gateway restart
```
Напишите боту любое сообщение со своего аккаунта ВКонтакте.
Бот ответит кодом подтверждения — это механизм авторизации pairing, защищающий от нежелательных сообщений.
Подтвердите доступ:
```
openclaw pairing approve vk <код>
```

Готово — бот отвечает на сообщения.

Конфигурация

Форматирование сообщений

Входящие ответы обрабатываются как Markdown, но для VK конвертируется только то, что поддерживается format_data:

**жирный**, *курсив*, ***жирный курсив***
[текст](https://example.com) (ссылка)

Вся остальная разметка остаётся без изменений.

Параметры

| Параметр | Описание | | --- | --- | | token / tokenFile | Ключ доступа сообщества или путь к файлу с токеном. Также поддерживается переменная окружения VK_TOKEN. Вместо самого ключа в token можно указать ссылку на секрет (SecretRef), см. ниже. | | dmPolicy | Политика личных сообщений: pairing (авторизация по коду), allowlist (по списку), open (без ограничений), disabled. | | allowFrom | Список ID пользователей, которым разрешён доступ при политике allowlist. | | defaultTo | Цель по умолчанию для исходящих сообщений, если target не был указан явно. | | groupPolicy | Политика для групповых бесед: allowlist, open, disabled. | | groupAllowFrom | Список ID пользователей, которым разрешено писать боту в групповых беседах при groupPolicy: "allowlist". Это не список peerId бесед. | | contextVisibility | Какой чужой контекст видит агент в группе: all (по умолчанию), allowlist (только авторы из groupAllowFrom) или allowlist_quote (те же пересылки, но цитаты видны). Можно переопределить для отдельного аккаунта. В личном диалоге фильтр не применяется. | | audio | Пределы исходящих голосовых сообщений для всего канала: maxVoiceMs, maxSegments, maxInputBytes, remoteMaxBytes, splitDeadlineMs, splitTimeoutMs. Значения должны быть положительными целыми числами; внутри accounts этот блок не допускается. | | streaming | Черновик шагов, как streaming.mode: "progress" у Telegram: при mode: "progress" ход с вызовами инструментов показывается в одном сообщении, которое правится на месте и в конце становится ответом. Строки шагов (🛠️ …) включает progress.toolProgress: true: в OpenClaw 2026.9.6 без него в черновике только заголовок. Заголовок задаётся progress.label. Остальные ключи progress — общие для каналов OpenClaw. Допустимы только режимы off и progress. Задаётся на весь канал; внутри accounts этот блок не допускается. По умолчанию выключен. |

Черновик шагов с заголовком и строками шагов:

{
  "channels": {
    "vk": {
      "streaming": {
        "mode": "progress",
        "progress": { "label": "⏳ Работаю", "toolProgress": true }
      }
    }
  }
}

В групповой беседе черновик цитирует входящее сообщение, как обычный ответ. Ответ на нажатие кнопки приходит обычным сообщением и снимает клавиатуру, а черновик удаляется.

Токен как ссылка на секрет (SecretRef)

Чтобы ключ не лежал в openclaw.json открытым текстом, token — на уровне канала или в accounts.<id> — может ссылаться на секрет, который шлюз достаёт при запуске:

{
  "channels": {
    "vk": {
      "token": { "source": "exec", "provider": "my-keychain", "id": "vk-group-token" }
    }
  }
}

Провайдер объявляется в secrets.providers; годится и { "source": "env", "provider": "default", "id": "VK_GROUP_TOKEN" }. Порядок прежний: VK_TOKEN, затем tokenFile, затем token. Поэтому при непустом tokenFile — своём у учётной записи или унаследованном с уровня канала — ссылка в token не разрешается вовсе и недоступной учётную запись не делает: читается файл. Если ссылку разрешить не удалось, шлюз помечает учётную запись недоступной и не запускает её, остальные каналы работают; в логе названа неразрешённая ссылка. Проверка — openclaw secrets audit, после починки провайдера — openclaw secrets reload.

Длинная озвучка отправляется несколькими голосовыми, если каждую часть удалось проверить. Если нарезка не удалась, исходный файл отправляется документом. Для этого на хосте нужны ffmpeg и ffprobe; в случае частичной доставки плагин не повторяет уже отправленную часть текстом. Посты со стены и пересланные сообщения видны агенту как контекст, но их текст не используется как команда или упоминание бота. Из чужих вложений загружаются только изображения.

Настройка отдельных бесед

Для каждой беседы можно задать индивидуальные параметры:

enabled: полностью отключить обработку конкретной беседы
allowFrom: переопределить sender allowlist только для этой беседы
requireMention: требовать упоминание бота
systemPrompt: отдельный системный prompt для конкретного чата

{
  "channels": {
    "vk": {
      "groups": {
        "2000000123": {
          "enabled": true,
          "allowFrom": [123456789],
          "requireMention": true,
          "systemPrompt": "Ты — помощник в рабочем чате. Отвечай кратко."
        },
        "*": {
          "requireMention": false
        }
      }
    }
  }
}

Если в беседе нужно разрешить сообщения только нескольким участникам, используйте groups.<peerId>.allowFrom. Это переопределяет общий groupAllowFrom для конкретного чата.

Несколько сообществ

Для подключения нескольких ботов к одному ядру используйте секцию accounts:

{
  "channels": {
    "vk": {
      "accounts": {
        "sales": {
          "enabled": true,
          "token": "<ТОКЕН_ПРОДАЖ>",
          "dmPolicy": "allowlist",
          "allowFrom": ["*"]
        },
        "support": {
          "enabled": true,
          "tokenFile": "/etc/openclaw/vk-support.token",
          "dmPolicy": "pairing"
        }
      }
    }
  }
}

Решение проблем

Проверьте статус подключения:

openclaw channels status --json --probe

Group authorization failed: group revoke access for this token — ключ доступа устарел или отозван. Перевыпустите токен в настройках сообщества, обновите конфигурацию и перезапустите шлюз.

Статус running: false при configured: true — неверный токен. Подробности в поле lastError вывода команды статуса.

APIError: Code №15 - Access denied: no access to call this method. It cannot be called with current scopes. при отправке изображений/аудио/документов — у текущего community token нет прав photos и/или docs.

Как исправить:

Откройте сообщество во ВКонтакте.
Перейдите в Управление → Дополнительно → Работа с API → Ключи доступа.
Нажмите Создать ключ.
В списке прав обязательно отметьте:
- Сообщения сообщества / messages
- Управление сообществом / manage
- Фотографии / photos
- Документы / docs
Подтвердите создание ключа в мобильном приложении VK.
Обновите channels.vk.token в ~/.openclaw/openclaw.json.
Перезапустите шлюз:
```
openclaw gateway restart
```

Проверка:

photos.getMessagesUploadServer требует право photos и используется для исходящих изображений.
docs.getMessagesUploadServer требует право docs и используется для doc и audio_message, поэтому без него исходящие файлы и голосовые не отправятся.
Исходящие audio/* вложения плагин отправляет как audio_message (голосовое). Если нужен обычный файл, используйте forceDocument.
Текущие права токена можно проверить через groups.getTokenPermissions.
Если после обновления токена groups.getTokenPermissions показывает только messages и manage, создайте новый ключ заново и убедитесь, что photos и docs отмечены при создании.

Отдельный симптом:

APIError: Code №100 - One of the parameters specified was missing or invalid: photo is undefined при отправке картинки по URL. Это означает, что исходный URL недоступен для загрузки как изображение (часто 404/403, редирект на HTML или временная ссылка без публичного доступа). Плагин пытается автоматически:
1. повторить отправку через локальный upload (скачать URL на стороне OpenClaw и загрузить в VK как файл),
2. если скачать не удалось, отправить текст + исходный URL, чтобы сообщение не терялось в очереди. Чтобы изображение ушло именно вложением, URL должен быть публичным, отдавать image/* и быть доступным с хоста OpenClaw (проверьте curl -I <url> прямо на сервере).

Официальная документация VK:

Настройки community token: https://dev.vk.com/ru/api/access-token/community-token/in-community-settings
Проверка прав токена: https://dev.vk.com/ru/method/groups.getTokenPermissions
Upload для изображений: https://dev.vk.com/ru/method/photos.getMessagesUploadServer
Upload для документов и голосовых: https://dev.vk.com/ru/method/docs.getMessagesUploadServer

Plugin "vk" state migration is pending в openclaw doctor / Startup migrations need attention в openclaw status — установлена версия плагина без Doctor-контракта (doctorContract в манифесте). Канал при этом работает, но шлюз стартует в «degraded state». Обновите плагин до версии с контрактом, затем выполните openclaw doctor --fix и перезапустите шлюз.

Бот не отвечает, ошибок нет — сообщения отклоняются политиками доступа. Проверьте dmPolicy, allowFrom и requireMention. Логи: ~/.openclaw/logs/commands.log (фильтруйте по "source":"vk").

Лицензия

Apache License 2.0.