openclaw-max – плагин MAX для OpenClaw

Канал-плагин для подключения AI-ассистента OpenClaw к мессенджеру MAX (ex-VK Teams / ICQ New).

Что это

Плагин позволяет общаться с OpenClaw-ботом через мессенджер MAX — так же, как через Telegram. Поддерживает:

• Приём и отправку текстовых сообщений (MAX-диалект markdown: ++подчёркивание++, упоминания max://user/id)
• Вложения (фото, видео, аудио, файлы, стикеры, контакты, геолокация)
• Inline-кнопки: callback / link / message / clipboard / open_app / request_contact / request_geo_location
• Закрепление сообщений (pin/unpin)
• Long polling (с персистентным marker) и Webhook (с обязательным secret и мгновенным ACK)
• Реестр чатов из событий bot_added/bot_started (замена deprecated GET /chats)
• Ретраи на 429/сетевые сбои и attachment.not.ready
• Мультиаккаунт
• DM-security и pairing

TLS: сертификат Минцифры (важно!)

С июля 2026 MAX Bot API живёт на platform-api2.max.ru с сертификатом, выпущенным
Russian Trusted Sub CA (Минцифры), которого нет в стандартном доверенном наборе Node.js.
Плагин решает это сам: все запросы к API идут через выделенный undici-dispatcher,
в CA-набор которого добавлены Russian Trusted Root/Sub CA (встроены в пакет,
src/russian-trusted-ca.ts). Доверие ограничено только соединениями плагина —
процесс-wide trust store не трогается, NODE_EXTRA_CA_CERTS не требуется.

Структура проекта

openclaw-max/
├── index.ts                    # Точка входа плагина
├── openclaw.plugin.json        # Манифест плагина
├── package.json
├── tsconfig.json
├── README.md
├── src/
│   ├── types.ts                # TypeScript-типы MAX Bot API
│   ├── api.ts                  # HTTP-клиент MAX API (retry, TLS, upload)
│   ├── russian-trusted-ca.ts   # Встроенные сертификаты Минцифры
│   ├── send.ts                 # Send-хелперы (текст, медиа, кнопки, pin)
│   ├── format.ts               # Конвертация markdown в MAX-диалект
│   ├── monitor.ts              # Long polling / диспетчеризация update'ов
│   ├── webhook.ts              # Webhook-приёмник (secret, быстрый ACK)
│   ├── state.ts                # Персист: marker поллинга + реестр чатов
│   ├── channel.ts              # OpenClaw channel adapter
│   ├── accounts.ts             # Резолвинг аккаунтов из конфига
│   ├── actions.ts              # message-tool actions (send/edit/delete/pin/…)
│   ├── config-schema.ts        # Zod-схема конфига
│   ├── model-buttons.ts        # Кнопки выбора модели
│   ├── onboarding.ts           # Setup wizard
│   └── sticker-cache.ts        # Кэш кодов стикеров
└── scripts/
    ├── test-api.mjs            # Проверка токена и API
    └── test-send.mjs           # Тест send + edit + delete

Установка

1. Создать бота в MAX

1. Зайти на business.max.ru (нужно юрлицо/ИП)
2. Создать профиль организации и пройти верификацию
3. Раздел Чат-боты → Создать (название, лого 500x500, описание)
4. Дождаться модерации (до 48ч по рабочим дням)
5. После модерации: Чат-боты → Интеграция → Получить токен

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

# Скопировать папку плагина в extensions
cp -r openclaw-max ~/.openclaw/extensions/openclaw-max

# Загрузить плагин
openclaw plugins load ~/.openclaw/extensions/openclaw-max

3. Настроить конфиг

Добавить секцию в ~/.openclaw/openclaw.json:

{
  "channels": {
    "max": {
      // Токен бота из business.max.ru → Чат-боты → Интеграция
      "botToken": "ваш_токен_бота",

      // Список user_id, которым разрешено писать боту
      // Узнать свой user_id: написать боту, посмотреть в логах
      "allowFrom": ["12345678"],

      // Политика DM-доступа:
      // "allowlist" — только из allowFrom (по умолчанию)
      // "open" — любой может писать
      // "pairing" — новые контакты проходят pairing-код
      "dmSecurity": "allowlist"
    }
  }
}

4. Перезапустить gateway

openclaw gateway restart

Настройка — описание полей

* Обязательно при dmPolicy: "allowlist".

Использование

Как написать боту

1. Найти бота в MAX по нику (например @idИНН_bot)
2. Нажать Старт или отправить любое сообщение
3. Бот ответит, если ваш user_id в allowFrom

Как узнать свой user_id

Написать боту, затем посмотреть в логах OpenClaw:

openclaw logs --follow
# В логах будет: sender.user_id: 12345678

Или запустить тест-скрипт:

MAX_BOT_TOKEN=xxx node scripts/test-api.mjs
# В разделе updates будет виден ваш user_id

allowFrom и pairing

• allowlist (по умолчанию): только user_id из списка могут общаться с ботом
• open: любой пользователь MAX может писать боту
• pairing: новый пользователь получает код, который нужно подтвердить у владельца

Мультиаккаунт

Можно подключить несколько ботов MAX — например, рабочий и личный:

{
  "channels": {
    "max": {
      // Аккаунт по умолчанию
      "botToken": "токен_основного_бота",
      "allowFrom": ["12345678"],

      // Дополнительные аккаунты
      "accounts": {
        "zaya": {
          "botToken": "токен_второго_бота",
          "allowFrom": ["87654321"],
          "dmSecurity": "open"
        }
      }
    }
  }
}

Обращение к конкретному аккаунту:

openclaw --account zaya send "Привет из второго бота"

Разработка

Требования

• Node.js 18+ (встроенный fetch)
• TypeScript 5+

Сборка

cd openclaw-max
npm install
npm run build          # npx tsc

Проверка типов

npx tsc --noEmit

Тест API (проверка что токен работает)

# Проверить бота: GET /me + GET /updates
MAX_BOT_TOKEN=xxx node scripts/test-api.mjs

# С отправкой тестового сообщения в чат
MAX_BOT_TOKEN=xxx node scripts/test-api.mjs <chat_id>

Тест отправки (send + edit + delete)

# Полный цикл: отправить → подождать → отредактировать → подождать → удалить
MAX_BOT_TOKEN=xxx node scripts/test-send.mjs <chat_id> "Текст сообщения"

Запуск polling вручную

import { startPolling } from "./polling.js";

const stop = startPolling("мой_токен", async (update) => {
  console.log("От:", update.message.sender?.user_id);
  console.log("Текст:", update.message.body.text);
});

// Остановить через 60 сек:
setTimeout(stop, 60_000);

Поддержка

• Вопросы по использованию и предложения: GitHub Issues
• Сообщения об уязвимостях: Security policy
• Правила участия: CONTRIBUTING.md

MAX Bot API — краткая справка

Базовый URL: https://platform-api2.max.ru (старый platform-api.max.ru отключается 19.07.2026).

Авторизация: заголовок Authorization: <token>
Лимит: 30 запросов/сек
Документация: dev.max.ru/docs-api

Примечания:

• GET /chats объявлен deprecated (июнь 2026) — плагин собирает чаты в собственный реестр из событий.
• В группах long polling доставляет события только боту-администратору (проверяется в openclaw channels status --audit).
• Webhook: только HTTPS:443 с доверенным сертификатом; MAX ждёт HTTP 200 не дольше 30с (плагин отвечает мгновенно, обработка асинхронная).

Авторы

• Petlevoy - отец проекта
• Яков (@Helpdesk_VP_bot) — архитектура, координация
• Банзай (@KotBanzaiBot) — реализация модулей, типы, тесты
• openclaw-max subagent — интеграция с OpenClaw Plugin SDK