@openclaw-vk/vk-workspace
v0.1.15
Published
OpenClaw channel for VK Workspaces / VK Teams bots
Maintainers
Readme
OpenClaw — VK Workspace
Канал OpenClaw для корпоративных VK Workspaces / VK Teams. Он получает сообщения через long polling, поэтому публичный webhook и входящий порт не нужны.
Это не интеграция социальной сети «ВКонтакте». Для неё используйте openclaw-vk.
Поддерживаются личные и групповые чаты, несколько ботов, pairing и allowlist, упоминания, ответы с цитатой в группах, Markdown, кнопки, выбор модели через /models, редактирование сообщений бота, файлы, изображения, стикеры и голосовые сообщения. Очередь входящих событий сохраняется на диск и переживает перезапуск Gateway.
Требования
- OpenClaw
>=2026.9.3 <2027; проверки выполняются на baseline2026.9.3; - Node.js
24.16–24.xили26.1+— тот же диапазон, что у OpenClaw 2026.9.3; - URL Bot API и токен бота VK Teams.
Gateway, агент, модель и её credentials должны быть настроены в OpenClaw заранее: канал их не создаёт. Node.js 25 не поддерживается. У пакета нет runtime-зависимостей, кроме OpenClaw.
Быстрый старт
Установите и включите плагин:
openclaw plugins install @openclaw-vk/vk-workspace openclaw plugins enable vk-workspaceЕсли OpenClaw требует capability consent или отменяет установку из-за отсутствия trust metadata, сначала проверьте источник пакета и запрошенные capabilities. Только после этого подтвердите установку:
openclaw plugins install --force --accept-capabilities @openclaw-vk/vk-workspace openclaw plugins enable --accept-capabilities vk-workspaceСоздайте бота в Metabot на вашем сервере VK Teams. Получите токен и уточните URL Bot API у администратора: адрес может отличаться от URL веб-клиента.
Добавьте канал в существующий
~/.openclaw/openclaw.json:{ "plugins": { "allow": ["vk-workspace"], "entries": { "vk-workspace": { "enabled": true } } }, "channels": { "vk-workspace": { "enabled": true, "baseUrl": "https://teams.example.com/bot/v1", "botToken": "YOUR_BOT_TOKEN", "dmPolicy": "pairing" } } }Не заменяйте примером весь конфиг.
plugins.allow— ограничивающий список, а не добавление одного разрешения. При его создании перечислите все используемые плагины, включая встроенные провайдеры (например,openaiдля STT); при изменении сохраните существующие записи и добавьтеvk-workspace. Иначе работавшие провайдеры могут отключиться; так же объединитеplugins.entries, модели, агентов и каналы.YOUR_BOT_TOKEN— плейсхолдер, не настоящий токен.Перезапустите Gateway и проверьте соединение:
openclaw gateway restart openclaw channels status --probeProbe проверяет
/self/get. Канал считается подключённым после успешного/events/get.Напишите боту в личный чат. Он вернёт pairing-код. Одобрите его и отправьте сообщение повторно:
openclaw pairing list vk-workspace openclaw pairing approve vk-workspace <code>
Обновление
Публикация в npm не обновляет уже установленную копию автоматически:
openclaw plugins update vk-workspace
openclaw gateway restart
openclaw plugins inspect vk-workspace
openclaw plugins list
openclaw channels status --probeСверьте версию и путь загруженного плагина с ожидаемым релизом. Обновлённый пакет на диске ещё не означает, что работающий Gateway использует новый код: нужен успешный restart. После него отправьте обычный текст и голосовое и проверьте openclaw logs --follow; один успешный probe не проверяет скачивание CDN или STT.
Пакет публикуется как @openclaw-vk/vk-workspace через npm Trusted Publishing с provenance и без постоянного NPM_TOKEN. История версий находится в GitHub Releases.
Доступ к чатам
Личные чаты
По умолчанию действует dmPolicy: "pairing". До одобрения неизвестный пользователь не передаёт сообщения агенту.
pairing— доступ после ручного одобрения;allowlist— только пользователи изallowFrom;open— все пользователи; не рекомендуется для агента с инструментами;disabled— личные чаты отключены.
Пример allowlist:
{ "dmPolicy": "allowlist", "allowFrom": ["[email protected]"] }Идентификаторы сохраняйте полностью, включая @, домен и другие символы. Если session.dmScope не задан, канал использует per-account-channel-peer, чтобы разные пользователи и боты не делили один личный диалог.
Групповые чаты
В безопасной конфигурации нужно разрешить и чат, и отправителей:
{
"channels": {
"vk-workspace": {
"baseUrl": "https://teams.example.com/bot/v1",
"tokenFile": "/absolute/path/to/vk-workspace.token",
"groupPolicy": "allowlist",
"groupAllowFrom": ["[email protected]"],
"groups": {
"[email protected]": { "requireMention": true }
}
}
}
}groupAllowFrom содержит пользователей, а ключ в groups — точный payload.chat.chatId Bot API. Личный pairing не разрешает доступ к группам.
По умолчанию бот отвечает на нативное упоминание, ответ на своё сообщение или mention pattern OpenClaw. Настройки конкретной группы (allowFrom, requireMention, enabled, systemPrompt) переопределяют общие; groups["*"] задаёт правило для всех групп. groupPolicy: "disabled" отключает группы, а open разрешает любые группы и участников, но не отменяет проверку управляющих команд OpenClaw.
В личном чате ответ приходит без цитаты. В группе он цитирует входящее сообщение; callback сохраняет привязку к сообщению с кнопкой.
Несколько ботов
{
"channels": {
"vk-workspace": {
"defaultAccount": "office",
"dmPolicy": "pairing",
"accounts": {
"office": {
"baseUrl": "https://teams.example.com/bot/v1",
"tokenFile": "/run/secrets/office.token"
},
"support": {
"baseUrl": "https://support.example.com/proxy/bot/v1",
"tokenFile": "/run/secrets/support.token"
}
}
}
}
}Аккаунты наследуют общие политики и URL, но никогда не наследуют чужие токены. Настройка default через --use-env сохраняет его собственные URL и политики внутри аккаунта и не меняет соседних ботов. Для маршрутизации к агенту задайте стандартный binding OpenClaw с channel: "vk-workspace" и нужным accountId.
Токен и URL API
Вместо botToken рекомендуется обычный файл с единственной строкой токена. Это фрагмент channels.vk-workspace или конкретного accounts.<id>:
{
"baseUrl": "https://teams.example.com/bot/v1",
"tokenFile": "/absolute/path/to/vk-workspace.token"
}Путь должен быть абсолютным; каталог, символическая ссылка и специальные файлы запрещены. FIFO отклоняется без ожидания записи в него. Максимальный размер — 64 КиБ. На Linux/macOS ограничьте доступ командой chmod 600. Нельзя одновременно задавать botToken и tokenFile.
Автоматически VK_WORKSPACE_BOT_TOKEN подхватывает только неявный аккаунт default. Для явно описанного accounts.default настройка с --use-env записывает в его botToken ссылку ${VK_WORKSPACE_BOT_TOKEN}: OpenClaw подставляет значение при загрузке, сам секрет в конфиг не копируется. Пустой accounts.default без такой настройки токен не заимствует. VK_WORKSPACE_BASE_URL также применяется к явно описанному accounts.default, если у него нет собственного baseUrl. Переменные должны быть заданы у процесса Gateway, а не только в интерактивном терминале.
baseUrl принимает адрес сервера или полный endpoint /bot/v1; префикс reverse proxy сохраняется. URL с credentials, query или fragment отклоняются. По умолчанию требуется HTTPS. Для внутреннего CA используйте NODE_EXTRA_CA_CERTS; allowInsecureHttp: true явно разрешает незашифрованный HTTP и передачу токена открытым текстом.
Основные настройки
Большинство параметров можно задавать на уровне channels.vk-workspace и внутри accounts.<id>. Поля accounts и defaultAccount существуют только на корневом уровне канала.
| Параметр | По умолчанию | Назначение |
|---|---:|---|
| enabled | true | Включает канал или отдельный аккаунт. |
| name | — | Отображаемое имя аккаунта. |
| baseUrl | встроенный fallback | URL сервера или endpoint /bot/v1; оператору следует задавать явно. |
| botToken / tokenFile | — | Один из двух способов передать токен. |
| dmPolicy | pairing | pairing, allowlist, open или disabled. |
| allowFrom | [] | Пользователи для личного allowlist. |
| groupPolicy | allowlist | allowlist, open или disabled. |
| groupAllowFrom | [] | Общий список разрешённых отправителей групп. |
| groups | {} | Настройки конкретных chatId; поддерживается ключ *. |
| requireMention | true | Требовать обращение к боту в группе. |
| defaultTo | — | Получатель по умолчанию для исходящих сообщений. |
| textFormat | markdown | markdown или точный plain. |
| pollTime | 30 | Long polling, 1–60 секунд. |
| requestTimeoutMs | 30000 | Тайм-аут обычного запроса, 1000–300000 мс. |
| mediaMaxMb | 20 | Лимит одного файла, 1–100 МБ. |
| mediaAllowedOrigins | [] | Дополнительные точные origin для входящих файлов. |
| allowInsecureHttp | false | Разрешить HTTP вместо HTTPS. |
| defaultAccount | — | Аккаунт по умолчанию при нескольких ботах; только корневой уровень. |
| accounts | — | Именованные аккаунты; только корневой уровень. |
Идентификатор аккаунта: до 64 строчных латинских букв, цифр, _ и -; первый символ — буква или цифра.
Форматирование, кнопки и медиа
Текст
textFormat: "markdown" поддерживает жирный и курсивный текст, зачёркивание, HTTP(S)-ссылки, заголовки, inline-код и fenced code blocks. HTML экранируется; таблицы и неизвестные конструкции остаются текстом. Длинные ответы разбиваются без потери символов. Для буквальной передачи задайте textFormat: "plain".
Для одного сообщения инструмент message может переопределить формат:
{
"action": "send",
"channel": "vk-workspace",
"target": "[email protected]",
"message": "**Этот текст останется буквальным**",
"vkTextFormat": "plain"
}Кнопки и выбор модели
Команда /models показывает нативные кнопки провайдеров и моделей с пагинацией; текущая модель отмечена галочкой.
Пример аргументов инструмента message:
{
"action": "send",
"channel": "vk-workspace",
"target": "[email protected]",
"message": "Продолжить?",
"vkButtons": [[
{ "text": "Да", "callbackData": "Продолжить", "style": "primary" },
{ "text": "Документация", "url": "https://teams.vk.com/botapi/" }
]]
}У кнопки должно быть ровно одно действие: url или callbackData. Стили: base, primary, attention. Максимум — 10 рядов по 8 кнопок, 128 UTF-16 единиц в подписи и 256 UTF-8 байт в callback. Принятое нажатие погашает всё меню; срок действия — 24 часа.
Меню из входящего хода привязано к его отправителю. Меню, созданное без пользовательского контекста, доступно любому отправителю, который проходит политики доступа канала. Callback всегда привязан к боту, аккаунту, чату и сообщению. Управляющая команда из callback отдельно проходит авторизацию OpenClaw; доступ к чату не выдаёт этих прав. Кнопки не подтверждают привилегированные инструменты OpenClaw.
Для редактирования передайте action: "edit", messageId ранее отправленного текстового сообщения и новый message. vkButtons: [] удаляет кнопки; если поле отсутствует, существующие кнопки сохраняются. Чужие и неизвестные сообщения не редактируются. Плагин хранит до 1000 отправленных сообщений на аккаунт не дольше 7 дней.
После проверки прав плагин сохраняет отключение прежних callback-кнопок до запроса редактирования. Если эта запись не удалась, запрос не отправляется. Если сервер уже принял изменение, а сохранить новый журнал не удалось, прежнее меню остаётся отключённым и автоматического повтора нет. Проверьте текст и кнопки в клиенте Teams перед следующим редактированием; не удаляйте журнал ради повтора.
При вызове из входящего хода редактирование требует совпадения отправителя с записью в журнале либо доверенного senderIsOwner OpenClaw. В OpenClaw 2026.9.3 стандартный путь отправки через инструмент message не передаёт отправителя в outbound-адаптер: у такого ответа запись может быть без владельца, хотя callback-кнопка привязана к пользователю. Из входящего хода редактировать или удалить этот ответ может только доверенный владелец OpenClaw. Привязка кнопки не подтверждает владение сообщением. Ограничение действует и для старых записей без отправителя; обновление не восстанавливает его задним числом. Обычные ответы через входящий dispatcher сохраняют отправителя и остаются доступны ему для редактирования и удаления.
Файлы и голосовые
Для повторного использования файла без скачивания передайте vkFileId. vkVoice: true отправляет одно вложение AAC, OGG или M4A как нативное голосовое; forceDocument: true принудительно отправляет его обычным файлом. Плагин не транскодирует звук. В одном исходящем сообщении допускается до 10 источников вложений.
{
"action": "send",
"channel": "vk-workspace",
"target": "[email protected]",
"vkFileId": "EXISTING_VOICE_FILE_ID",
"vkVoice": true,
"message": "Голосовой ответ"
}Входящие voice распознаются перед передачей в STT OpenClaw: сигнатура содержимого имеет приоритет над audio MIME в metadata, расширением имени и HTTP Content-Type. Это исправляет и application/octet-stream, и ошибочный конкретный MIME. Поддерживаются контейнеры OGG/Opus, MP3, AAC/ADTS, M4A, WAV и WebM; расширение сохраняется даже у длинных имён. Это определение формата, не декодирование и не перекодирование звука. В группе с requireMention: true одиночное голосовое может пройти предварительную транскрипцию только для проверки произнесённого обращения к боту. Доступ отправителя проверяется до скачивания.
Если голосовое прошло проверку упоминания и включён tools.media.audio.echoTranscript, канал публикует расшифровку с echoFormat OpenClaw. Ошибка публикации не повторяет запрос и не мешает ответу агента. При остановке Gateway новые части расшифровки не отправляются, в том числе после ожидания записи сессии; уже отправленная часть может остаться в чате.
Корпоративный OpenAI-compatible STT
Обычный chat provider с произвольным именем (например, ai-gateway) не становится media provider с transcribeAudio. Для совместимого /v1/audio/transcriptions используйте встроенный media provider openai, отдельную STT-модель и корпоративный baseUrl. Ниже фрагмент для объединения с существующим конфигом OpenClaw 2026.9.3, не замена моделей, агентов и плагинов:
{
"models": {
"providers": {
"openai": {
"baseUrl": "https://ai.example.com/v1",
"api": "openai-completions",
"auth": "api-key",
"apiKey": "YOUR_STT_API_KEY",
"request": { "allowPrivateNetwork": true },
"models": []
}
}
},
"tools": {
"media": {
"models": [{
"type": "provider",
"provider": "openai",
"model": "YOUR_STT_MODEL",
"capabilities": ["audio"],
"baseUrl": "https://ai.example.com/v1"
}],
"audio": { "enabled": true, "preferredModel": "openai/YOUR_STT_MODEL" }
}
}
}YOUR_STT_API_KEY и YOUR_STT_MODEL — плейсхолдеры. В production используйте поддерживаемые OpenClaw env/file-backed secrets; убедитесь, что они доступны именно сервису Gateway. Не затирайте уже настроенный models.providers.openai: его URL, credentials и request policy используются и другими обращениями к этому provider. Сохраните существующие модели и записи tools.media.models. Встроенный плагин openai должен быть включён и присутствовать в plugins.allow, если этот список задан.
allowPrivateNetwork нужен только для контролируемого endpoint, который резолвится в private/internal IP; для публичного сервера удалите request. Не отключайте SSRF или TLS глобально. Это отдельная настройка от channels.vk-workspace.mediaAllowedOrigins: первая разрешает запрос STT к доверенному провайдеру, вторая — скачивание файла с CDN. Успешный chat completion не подтверждает работоспособность STT.
Отказ STT, который OpenClaw обработал без исключения, сам по себе не делает событие failed. Без транскрипта одиночное голосовое в группе с обязательным упоминанием не обходит mention gate; следующее текстовое обращение продолжает обрабатываться. Реальная ошибка dispatch/delivery остаётся в очереди и требует решения оператора.
Вложения и безопасность сети
Файл скачивается напрямую только с origin Bot API или из mediaAllowedOrigins:
{ "mediaAllowedOrigins": ["https://files.example.com"] }Origin из ответа files/getInfo может отличаться от Bot API (включая дополнительный CDN или redirect). Сверьте его с администратором и внесите каждый доверенный origin отдельно. Указывайте точный origin без пути, query и конечного /; каждый redirect проверяется заново. Добавление origin означает явное доверие этому серверу и для входящих файлов, и для исходящих URL. Остальные исходящие URL проходят SSRF-защиту OpenClaw, поэтому не добавляйте произвольные внутренние сервисы. Токен бота не отправляется файловому серверу, а подписанный URL не передаётся модели. Поддерживается до 10 входящих вложений; исходящие файлы ограничены 100 МБ суммарно.
Локальные исходящие файлы доступны только внутри media roots OpenClaw. Чтение использует публичный файловый API SDK с проверкой открытого дескриптора; перед использованием результата канал также проверяет итоговый путь по исходным разрешённым корням. Символические ссылки внутри этих корней допустимы; выход за их пределы, hard links и специальные файлы отклоняются. FIFO не должен задерживать остановку Gateway. Проверки путей и дескрипторов не заменяют ограничения доступа к каталогам средствами ОС.
Bot API передаёт токен и текст в query. Плагин скрывает полные URL и сырые API-ошибки, но access-логи сервера и reverse proxy также должны скрывать query. Не запускайте два long-poll потребителя с одним токеном: они будут забирать события друг у друга.
Ошибки очереди и восстановление
Ошибка обработки события блокирует только свой чат и сохраняется в <OPENCLAW_STATE_DIR>/vk-workspace/<hash>.json (обычно внутри ~/.openclaw). Другие чаты продолжают работать. Автоматического повтора нет, потому что прерванный ход мог уже отправить сообщение или выполнить инструмент. Ошибка записи, переполнение или повреждение очереди останавливает монитор до вмешательства оператора.
При ошибке записи во время обработки монитор отменяет все активные ходы и ждёт их завершения, удерживая блокировку очереди. Новые ходы не запускаются; начатые незавершённые события сохраняются для ручного восстановления. Если обработчик OpenClaw не реагирует на отмену, остановка ждёт его завершения, чтобы второй consumer не начал работать одновременно с ним.
Очередь вмещает не более 1000 событий и 16 МиБ. При заполнении освободите её только осознанным retry или discard; не удаляйте JSON и не сбрасывайте курсор.
В failed-событии сохраняются безопасные stage, code, message: отдельно metadata, download, normalize, media-store, agent-dispatch и reply-delivery. Наличие аудиовложения не доказывает, что сбой доставки вызван STT. Сырые provider errors и подписанные URL в эту диагностику не копируются; подробности провайдера ищите в Gateway logs с учётом его политики редактирования секретов.
Утилита входит в установленный npm-пакет; доступ к GitHub для восстановления не нужен. Путь плагина найдите через openclaw plugins inspect vk-workspace и подставьте вместо /absolute/plugin. В checkout доступна та же утилита через node scripts/inbox.mjs.
openclaw gateway stop
node /absolute/plugin/dist/inbox-cli.js status /absolute/path/to/inbox.json
# Выберите ОДНО действие после проверки уже выполненных ответов и внешних действий:
node /absolute/plugin/dist/inbox-cli.js retry /absolute/path/to/inbox.json EVENT_ID
# Или отбросьте только выбранное событие, не трогая следующие pending:
node /absolute/plugin/dist/inbox-cli.js discard /absolute/path/to/inbox.json EVENT_ID
openclaw gateway startВыберите файл *.json, но не *.messages.json и не *.backup-*, в каталоге vk-workspace; hash зависит от URL и токена. При нескольких ботах сопоставьте очередь по ID событий. status не меняет JSON и не печатает тексты сообщений; interrupted перечисляет ID начатых, но не завершённых pending-событий. Команды retry и discard принимают ID из failed или interrupted; обычные ещё не начатые pending не затрагиваются. Повтор всех таких событий возможен только явно: retry /absolute/path/to/inbox.json --all.
Перед изменениями утилита под тем же эксклюзивным lock создаёт рядом копию *.json.backup-<uuid> с правами 0600 и выводит её путь. Если копирование или синхронизация не удались, очередь не меняется. Прерванные ходы карантинируются только после backup; затем выполняется выбранное действие. Курсор и остальные сообщения сохраняются. Копия содержит исходные сообщения: храните её как приватные данные. retry может повторить уже выполненные побочные эффекты; discard сознательно отказывается от повторного выполнения выбранного хода. Утилита не удаляет lock автоматически и не создаёт новую очередь при ошибке в пути.
Если после аварии остался .lock, сначала остановите все процессы Gateway с этим ботом и только затем удалите lock именно выбранной очереди:
/bin/rm -f /absolute/path/to/inbox.json.lockНе удаляйте сами inbox.json и *.messages.json. Lock удаляйте только у выбранной очереди после остановки всех процессов Gateway. Повреждённую очередь восстановите из резервной копии; не обнуляйте курсор.
Диагностика окружения
openclaw config validate
openclaw gateway status --deep
openclaw channels status --probe
openclaw logs --followECONNREFUSED 127.0.0.1:18789 означает, что TUI не подключился к Gateway, а не ошибку VK Bot API. Проверьте запуск через openclaw gateway start. На macOS сбои LaunchAgent и предупреждения о Node из nvm проверяйте через openclaw doctor; плагин не должен переустанавливать сервис или менять системный PATH. Недоступность внешнего каталога моделей не равна отказу канала, если настроенные локальные сервисы работают.
Нативные возможности Workspace
Пересылки и цитаты доступны агенту отдельно от текста отправителя: чужой /reset, /model или упоминание не запускают команду и не обходят mention gate. Автор, вложенность и границы цитаты сохраняются; собственные сообщения бота помечаются bot (you). Контекст ограничен 16 000 символами, 20 сообщениями и четырьмя уровнями вложенности. Это ограничения плагина, а не заявленные лимиты сервера.
contextVisibility действует в группах: all разрешает чужой контекст; allowlist оставляет только авторов из эффективного списка участников и самого бота; allowlist_quote дополнительно разрешает прямые цитаты, но не произвольные пересылки. Приоритет: конкретная группа, аккаунт/канал, channels.defaults.contextVisibility, затем all. Скрытый родитель скрывает всё вложенное. Личные сообщения не фильтруются этой настройкой.
Из чужих вложений загружаются только изображения, подтверждённые и метаданными files/getInfo, и сигнатурой PNG/JPEG/GIF/WebP. Чужие голосовые, аудио, видео и документы остаются обозначенными в тексте и не передаются в STT. Неподдерживаемый или недоступный preview не блокирует само обращение; агент получает отметку об ограничении. Правила доверенных origin и общий предел десяти вложений сохраняются.
Треды
Новые сообщения с parent_topic используют разрешения родительской группы и наследуют её binding OpenClaw. У треда отдельная сессия, а ответ отправляется в его нативный chatId, не в родительскую группу. Отдельное правило треда может сузить allowlist или отключить его; оно не разрешает доступ к запрещённому родителю. Mention policy можно переопределить для треда явно.
Чтобы написать в существующий тред, используйте обычный send с его ID как target; для непривычного формата ID задайте vk-workspace:chat:<threadId>. Передача родительского target вместе с другим threadId отклоняется, чтобы ответ случайно не ушёл всей группе. Подписка и доступность тредов зависят от сервера: плагин не включает автоподписку самостоятельно.
Дополнительные действия агента
Это фрагмент channels.vk-workspace или accounts.<id>, а не замена остальных настроек:
{
"contextVisibility": "allowlist_quote",
"actions": {
"delete": true,
"forward": false,
"pins": false,
"chatInfo": false,
"threads": false,
"chatManagement": false
}
}Удаление собственных ответов включено по умолчанию. Остальные дополнительные действия требуют явного true; аккаунт наследует флаги канала и может переопределить каждый из них. Флаг threads разрешает создание тредов инструментом; приём уже существующих разрешённых тредов от него не зависит. Обычные отправка, редактирование и кнопки работают как раньше.
| Действие message | Параметры | Ограничения |
|---|---|---|
| delete | target, messageId | Только сохранённый ответ этого бота; обычный пользователь — только ответ на своё обращение в текущем аккаунте и чате. |
| send с пересылкой | vkForward: { "chatId": "[email protected]", "messageIds": ["id1", "id2"] } | actions.forward; исходный чат должен совпадать с доверенным текущим чатом/аккаунтом либо вызывать должен владелец. replyTo несовместим с пересылкой. |
| pin, unpin | target, messageId | actions.pins, доверенный владелец OpenClaw и необходимые права бота на сервере. |
| channel-info | target, vkInfo: info, members, admins, thread-subscribers | actions.chatInfo; текущий чат/аккаунт разрешённого пользователя либо владелец. members и thread-subscribers возвращают одну страницу и cursor. |
| member-info | target, userId, при необходимости vkCursor | Те же права; точный поиск до 20 страниц. При достижении предела возвращается complete: false и курсор для продолжения, а не ложное «участника нет». |
| thread-create | Родительский target, messageId | actions.threads; пользователь может открыть тред на текущем входящем сообщении или своём сохранённом ответе бота. Возвращает настоящий threadId. |
| channel-edit | target, vkChatUpdate | actions.chatManagement и доверенный владелец. Ровно одно поле: title, about, rules или threadAutoSubscribe; только для последнего допускается includeExistingThreads. |
target также принимается как chatId/channelId. vkCursor передаётся без преобразования. Метаданные чата не включают invite links, подписанные URL, произвольные дополнительные поля сервера или время последнего посещения участников. dryRun проверяет аргументы и права вызывающего без сетевых запросов; он не подтверждает существование сообщения или права бота на сервере.
Владелец определяется только доверенным senderIsOwner OpenClaw, а не текстом запроса, параметрами модели или ролью пользователя/бота в Teams. Не передавайте агенту административные возможности без необходимости. У сервера могут быть дополнительные ограничения; логический отказ при HTTP 200 не считается успехом.
Удаление использует тот же приватный журнал ответов с удержанием 7 дней / 1000 сообщений. До запроса API он сохраняет запрет на повторное удаление/редактирование и отключает callback-кнопки. При подтверждённом удалении запись убирается; deletedMessage также очищает её, не запуская агента. После неоднозначного сбоя запись остаётся заблокированной: проверьте сообщение в клиенте Teams и при необходимости удалите его вручную. Не удаляйте весь журнал и не сбрасывайте очередь ради повтора. Пересылки не помещаются в повторяемый prepared payload: право на исходный чат относится к текущему вызову, а не к будущему запуску очереди.
Основания и границы поддержки
Сверка выполнена 25 сентября 2026 года. Основные источники: официальный Python SDK, официальный Go SDK, его события и parent_topic, контракт n8n-интеграции. Повторяющиеся msgId / forwardMsgId, query-параметры при multipart и обязательный токен сверены между реализациями; ранее зафиксированная проверка живого API в n8n — свидетельство того проекта, не live-тест этого плагина.
Для сравнения с другим каналом использован openclaw-vk. Перенесены разделение управляющего ввода и чужого контекста, ограничение пересылаемых медиа и настройки видимости. Социальные VK ID, wall-вложения, реакции, read receipts и ограничения перекодирования VK не переносятся в Teams по аналогии. Интеграция проверяется с контрактами OpenClaw v2026.9.3, а не с произвольной новой версией SDK.
Официальная веб-спецификация и её api.yaml, params.json, schemas.json не удалось получить из среды проверки. Поэтому источники выше не выдаются за проверку актуальной конфигурации вашего Workspace. Перед включением административных функций нужны smoke-сценарии на тестовом боте и тестовой группе именно вашего сервера.
Не предоставляются история/поиск сообщений, реакции, опросы, отметки прочтения и список всех тредов: в проверенных Bot API контрактах их поддержка не подтверждена. Создание чатов, добавление/массовое удаление участников, блокировки и разрешение заявок требуют отдельной модели административных полномочий; наличие отдельных таких методов в SDK не является достаточной причиной выдавать их чат-агенту. Provisioning и модерацию следует выполнять отдельной административной интеграцией, не расширяя права разговорного бота.
Ограничения
- Новые сообщения (включая разрешённые треды) и callback запускают агента. Редактирования и административные события не запускают новый ход; удаления только очищают журнал ответов.
- Изменение названия/описания/правил, закрепления и автоподписка на треды доступны только как явно включённые действия владельца. Provisioning и массовая модерация не предоставляются.
- Потоковое редактирование ответа на каждом токене не поддерживается.
- Локальные тесты не заменяют проверку корпоративных proxy, TLS, прав бота и файлового origin на вашем сервере.
Разработка
Проверки, пользовательские сценарии и процедура выпуска описаны в CONTRIBUTING.md.
Лицензия
Дополнения общего контракта Python / Go / Java
Несколько цитат и удаление частей ответа
message(action="send") принимает vkReplyToIds: ["ID_1", "ID_2"]: только сообщения целевого чата, максимум 20 уникальных ID. Они цитируются в первой физической отправке; следующие части длинного ответа не повторяют цитаты. Не совмещайте поле с replyTo или vkForward.
message(action="delete") принимает либо обычный messageId, либо vkMessageIds: ["ID_1", "ID_2"]. Второй вариант позволяет удалить части длинного ответа. Все ID сначала проверяются в журнале бота на принадлежность чату и отправителю, затем блокируются одной записью на диск и передаются одним запросом. Если хотя бы один ID неизвестен или запрещён, запрос удаления не выполняется и ни одно меню не блокируется. После неоднозначной ошибки все выбранные сообщения остаются заблокированными для повторной операции; автоматического повтора нет.
Нативная разметка
vkFormat задаёт структурированную разметку буквального message, без интерпретации HTML или Markdown:
{
"action": "send",
"channel": "vk-workspace",
"target": "[email protected]",
"message": "А😀 важный текст",
"vkFormat": {
"bold": [{ "offset": 0, "length": 3 }],
"underline": [{ "offset": 4, "length": 6 }]
},
"vkReplyToIds": ["MESSAGE_ID_1", "MESSAGE_ID_2"]
}Поля и индексы примера относятся к исходному буквальному тексту: локальный интерфейс использует UTF-16, поэтому эмодзи вне BMP занимает две единицы. Плагин проверяет границы символов, длины, дополнительные поля и HTTP(S)-ссылки без credentials. Поддержаны bold, italic, underline, strikethrough, link с url, mention, inline_code, pre с необязательным language, ordered_list, unordered_list, quote. Суммарно допускается 100 диапазонов и 16 КиБ JSON разметки.
При разбиении текста смещения пересчитываются для каждой части. Диапазон упоминания никогда не разрывается и не повторяется: слишком длинный диапазон отклоняется до отправки. vkFormat несовместим с явным vkTextFormat: "markdown"; обычный Markdown по умолчанию не меняется. При редактировании с vkFormat передайте также новый текст. Изменение одних кнопок сохраняет разметку исходного сообщения. Точное отображение нативных стилей и упоминаний необходимо проверить на используемой версии сервера и клиента Teams.
Кнопки, активность и изменённые сообщения
Отказы и просроченные callback-меню получают showAlert: true; успешное принятие — обычное подтверждение. Это не подтверждение привилегированных инструментов. Индикатор typing явно снимается после завершения либо ошибки. Запросы активности сериализованы, чтобы запоздавший запрос не включил его снова; после отмены Gateway новые запросы не отправляются. HTTP-обёртка также поддерживает looking, но не выдаёт его за отметку прочтения.
Уже полученное editedMessage обновляет текст ещё не начатого входящего задания только при совпадении чата, типа чата, сообщения и автора. Старые вложения не сохраняются, если событие редактирования их не содержит. Политики доступа и команд проверяются при последующей обычной обработке заново. Уже полученное deletedMessage отменяет только не начатое задание. Эти решения сохраняются на диск вместе с курсором.
Это не мгновенная отмена: монитор не опрашивает новые события во время обработки текущего пакета. Начатые, завершённые и quarantined-ходы не перезапускаются и не отменяются автоматически. Удаление сообщения не откатывает выполненные инструменты. Служебные события закрепления и состава участников не запускают агента и не выдают доступ.
Событие изменения видимого текста сохранённого ответа бота обезвреживает прежнее меню; совпадающее эхо собственного редактирования сохраняет его. Изменение только клавиатуры вне плагина без отличающегося текста нельзя надёжно определить по событию API, поэтому изменяйте меню через плагин, а не сторонними клиентами.
Дополнительные источники контракта: Java Messages, Java ChatAction, типизированный Python Format, схемы n8n. Контрактные тесты проверяют настоящие локальные HTTP-запросы; это не проверка живого корпоративного сервера.
