GitHub - RuslanStrogov/max-openclaw: MAX Messenger (max.ru) Bot API channel plugin for OpenClaw - native TypeScript plugin

🛠️ Технологии

MAX Messenger — Channel Plugin для OpenClaw

Нативный плагин-канал для подключения мессенджера MAX через Bot API к AI-агенту OpenClaw

_{🎨 Designed by BR-DESIGN}

📋 Содержание

Возможности
Требования
Установка
Настройка
Использование
Структура проекта
Архитектура
Конфигурация
MAX Bot API
Сравнение с Telegram Bot API
Разработка
Тестирование
Релизы и CI/CD
Лицензия

✨ Возможности

Что уже работает

Фича	Статус
Приём и отправка текстовых сообщений	✅
Inline keyboard (кнопки с callback)	✅
Индикатор «Печатает...» (heartbeat typing)	✅
Markdown-форматирование	✅
Белый список пользователей (DM policy)	✅
Webhook приём сообщений	✅
HMAC-SHA256 верификация webhook	✅
Отправка изображений (upload API)	✅
Отправка файлов (upload API)	✅
Отправка аудио (upload API)	✅
Групповые чаты (group/channel/supergroup)	✅
Per-group политики (allowlist/disabled)	✅
DM security: pairing, allowlist, open, disabled	✅
Pairing flow (код верификации)	✅
Автоматические релизы (GitHub Release)	✅
CI (тесты + линтер)	✅

📋 Требования

OpenClaw >= 2026.6.1
Node.js >= 22 (для разработки)
Сервер с публичным IP для приёма webhook
SSL-сертификат (Let's Encrypt или самоподписанный)

📦 Установка

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

# Из GitHub репозитория
openclaw plugins install github:RuslanStrogov/max-openclaw

# Или из локальной копии
git clone https://github.com/RuslanStrogov/max-openclaw.git
openclaw plugins install ./max-openclaw

# Перезапустите gateway
openclaw gateway restart

Из исходников (для разработки)

git clone https://github.com/RuslanStrogov/max-openclaw.git
cd max-openclaw
npm install
npm run build
openclaw plugins install .
openclaw gateway restart

⚙️ Настройка

1. Создайте бота в MAX

⚠️ Важно: Создание ботов на платформе MAX доступно только юридическим лицам, ИП и самозанятым (резидентам РФ). Физическим лицам создание ботов недоступно.

Тип профиля	Кол-во ботов
Организация / ИП	Несколько (не ограничено платформой)
Самозанятый	Ограничено

Пошаговая инструкция:

Перейдите на портал MAX для партнёров
Создайте и верифицируйте профиль организации, ИП или самозанятого
В панели управления нажмите «Добавить бота»
Заполните данные бота (карточку):
- Название — от 1 до 59 символов
- Никнейм — генерируется автоматически (должен заканчиваться на _bot)
- Сайт организации, логотип и описание
Нажмите «Готово» — бот создан и отправлен на модерацию
Дождитесь уведомления о прохождении модерации
После модерации получите токен бота

Подробнее: MAX для разработчиков — Создание чат-бота

2. Настройте конфигурацию OpenClaw

openclaw config set channels.max-messenger.token "YOUR_MAX_BOT_TOKEN"
openclaw config set channels.max-messenger.webhookUrl "https://your-domain.com/max-messenger/webhook"
openclaw config set channels.max-messenger.dmPolicy "open"

Или через JSON конфиг:

{
  channels: {
    "max-messenger": {
      enabled: true,
      token: "YOUR_MAX_BOT_TOKEN",
      webhookUrl: "https://your-domain.com/max-messenger/webhook",
      webhookSecret: "optional-hmac-secret",
      apiBaseUrl: "https://platform-api.max.ru",
      dmPolicy: "open",
      allowFrom: [],
      groupPolicy: "allowlist",
      groups: {
        "group_chat_id": {
          requireMention: true,
          enabled: true,
          allowFrom: []
        }
      },
      homeChannel: ""
    }
  }
}

3. Настройте сервер (Nginx)

server {
    listen 443 ssl http2;
    server_name your-domain.com;

    ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;

    location /max-messenger/webhook {
        proxy_pass http://127.0.0.1:18080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

4. Зарегистрируйте webhook в MAX

Плагин автоматически регистрирует webhook при запуске. Если нужно вручную:

curl -X POST "https://platform-api.max.ru/subscriptions" \
  -H "Authorization: YOUR_MAX_BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://your-domain.com/max-messenger/webhook", "events": ["message_created", "message_callback"]}'

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

openclaw gateway restart

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

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

Принимать сообщения от пользователей MAX
Передавать их агенту OpenClaw
Отправлять ответы обратно в MAX

DM Security Policies

Политика	Описание
`pairing`	Новые пользователи должны пройти верификацию (код)
`allowlist`	Только пользователи из белого списка
`open`	Все пользователи могут писать боту
`disabled`	DM отключены

Group Chat

В групповых чатах бот реагирует на сообщения в зависимости от настроек:

requireMention: true — только при упоминании бота
groupPolicy: "allowlist" — только разрешённые группы

Inline Keyboard

Агент может отправлять сообщения с кнопками:

{
  "text": "Выберите действие:",
  "attachments": [{
    "type": "inline_keyboard",
    "payload": {
      "buttons": [
        [{"text": "Да", "payload": "yes"}, {"text": "Нет", "payload": "no"}],
        [{"text": "Отмена", "payload": "cancel", "style": "danger"}]
      ]
    }
  }]
}

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

max-openclaw/
├── index.ts                  # defineChannelPluginEntry — точка входа
├── setup-entry.ts            # defineSetupPluginEntry — для wizard/setup
├── src/
│   ├── channel.ts            # createChatChannelPlugin — основная логика
│   ├── client.ts             # HTTP-клиент MAX Bot API
│   ├── types.ts              # TypeScript типы
│   └── webhook.ts            # Webhook handler (inbound)
├── dist/                     # Скомпилированный JS
│   ├── index.js
│   ├── setup-entry.js
│   └── src/
│       ├── channel.js
│       ├── client.js
│       ├── types.js
│       └── webhook.js
├── tests/
│   └── channel.test.ts       # Unit тесты
├── .github/workflows/
│   ├── ci.yml                # CI pipeline
│   └── release.yml           # Release automation
├── package.json
├── openclaw.plugin.json      # Plugin manifest
├── tsconfig.json
├── vitest.config.ts
├── CHANGELOG.md
├── LICENSE
└── README.md

🏗️ Архитектура

┌──────────┐   webhook    ┌─────────────────┐   native    ┌──────────────┐
│          │ ──────────►  │                 │ ──────────►  │              │
│ MAX Bot  │              │ MAX Messenger   │              │ OpenClaw     │
│ API      │ ◄──────────  │ Plugin          │ ◄──────────  │ Agent        │
│          │  send_msg    │ (TypeScript)    │  response    │              │
└──────────┘              └─────────────────┘              └──────────────┘

Поток сообщений

Пользователь пишет боту в MAX
MAX API отправляет webhook на плагин
Плагин верифицирует HMAC-SHA256 подпись
Плагин проверяет DM policy / allowlist
Плагин передаёт сообщение в OpenClaw Agent
Агент генерирует ответ
Плагин отправляет ответ обратно в MAX через Bot API

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

Поля конфигурации

Поле	Обязательное	По умолчанию	Описание
`token`	✅	—	Токен бота MAX
`webhookUrl`	❌	—	Публичный URL для webhook
`webhookSecret`	❌	—	HMAC-SHA256 секрет
`apiBaseUrl`	❌	`https://platform-api.max.ru`	Базовый URL API
`dmPolicy`	❌	`pairing`	DM политика
`allowFrom`	❌	`[]`	Белый список user ID
`groupPolicy`	❌	`allowlist`	Политика групповых чатов
`groups`	❌	`{}`	Per-group настройки
`homeChannel`	❌	—	Chat ID для cron/уведомлений

DM Policies

Политика	Поведение
`pairing`	Новый пользователь получает код верификации. После подтверждения — добавляется в allowlist
`allowlist`	Только пользователи из `allowFrom` могут писать
`open`	Все могут писать
`disabled`	DM полностью отключены

Group Policy

Политика	Поведение
`open`	Все группы разрешены
`allowlist`	Только группы с `enabled: true` в `groups`
`disabled`	Групповые чаты отключены

🔌 MAX Bot API

Отправка сообщения

POST https://platform-api.max.ru/messages?user_id=12345
Authorization: YOUR_BOT_TOKEN
Content-Type: application/json

{
  "text": "Привет!",
  "format": "markdown"
}

Для групповых чатов:

POST https://platform-api.max.ru/messages?chat_id=67890

Индикатор «Печатает...»

POST https://platform-api.max.ru/chats/67890/actions
Authorization: YOUR_BOT_TOKEN
Content-Type: application/json

{"action": "typing_on"}

Загрузка файлов

POST https://platform-api.max.ru/uploads?type=image
Authorization: YOUR_BOT_TOKEN
Content-Type: multipart/form-data

file: <binary data>

Inline Keyboard

{
  "text": "Выберите:",
  "attachments": [{
    "type": "inline_keyboard",
    "payload": {
      "buttons": [
        [{"text": "Кнопка 1", "payload": "btn1"}],
        [{"text": "Кнопка 2", "payload": "btn2", "style": "danger"}]
      ]
    }
  }]
}

Callback от кнопок

При нажатии кнопки MAX отправляет webhook с update_type: "message_callback":

{
  "update_type": "message_callback",
  "callback": {
    "id": "callback_id",
    "payload": "btn1",
    "text": "Кнопка 1"
  },
  "message": {
    "sender": {"user_id": 12345, "name": "User"},
    "recipient": {"chat_id": 67890}
  }
}

Подробнее: MAX Bot API — Документация

📊 Сравнение с Telegram Bot API

Возможность	Telegram	MAX Bot API
Webhook	✅	✅
Long Polling	✅	✅
Inline keyboard	✅	✅
Reply keyboard	✅	❌ (только inline)
Callback buttons	✅	✅
Send/Edit/Delete messages	✅	✅
Typing indicator	✅	✅
Read receipts	✅	❌
Bot commands menu	✅	❌
Send images/files	✅	✅ (через upload)
Group chats	✅	✅
Channels	✅	✅
DM Policy	✅ (via code)	✅ (native)

🛠️ Разработка

Требования

Node.js >= 22
TypeScript >= 5.5
OpenClaw >= 2026.6.1 (для тестирования)

Установка

git clone https://github.com/RuslanStrogov/max-openclaw.git
cd max-openclaw
npm install

Сборка

npm run build

Линтинг

npm run lint

Локальная установка в OpenClaw

npm run build
openclaw plugins install .
openclaw gateway restart

🧪 Тестирование

# Запуск тестов
npm test

# Запуск в watch режиме
npm run dev

# С покрытием
npx vitest run --coverage

Тесты покрывают:

MaxClient (создание, валидация токена)
MaxApiError (ошибки)
Target parsing (user:/chat:/group: префиксы)

🚀 Релизы и CI/CD

Git flow

main — стабильная ветка, релизы
develop — ветка разработки, интеграция изменений
Релизы помечаются тегами v* (например v1.0.0)

GitHub Actions

Workflow	Триггер	Описание
CI	push/PR в `main`, `develop`	Сборка + тесты + линтер
Release	тег `v*`	Сборка + тесты + GitHub Release

Создание релиза

# Собрать изменения в develop
git checkout develop
# ... коммиты ...

# Слить в main и создать тег
git checkout main
git merge develop --no-ff
git tag -a v1.1.0 -m "Release v1.1.0: описание"
git push origin main --tags

📄 Лицензия

MIT License. См. LICENSE.

🔗 Связанные проекты

Проект	Описание
MAX Hermes Bridge	Python-мост между MAX Bot API и Hermes Agent через CLI с поддержкой webhook, Docker и systemd.
MAX Hermes Plugin	Нативный платформенный плагин для Hermes Gateway. Прямая интеграция MAX без моста.

_{🎨 Designed by BR-DESIGN}

Name		Name	Last commit message	Last commit date
Latest commit History 7 Commits
.github/workflows		.github/workflows
src		src
tests		tests
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
index.ts		index.ts
openclaw.plugin.json		openclaw.plugin.json
package-lock.json		package-lock.json
package.json		package.json
setup-entry.ts		setup-entry.ts
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation

🛠️ Технологии

MAX Messenger — Channel Plugin для OpenClaw

📋 Содержание

✨ Возможности

Что уже работает

📋 Требования

📦 Установка

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

Из исходников (для разработки)

⚙️ Настройка

1. Создайте бота в MAX

2. Настройте конфигурацию OpenClaw

3. Настройте сервер (Nginx)

4. Зарегистрируйте webhook в MAX

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

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

DM Security Policies

Group Chat

Inline Keyboard

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

🏗️ Архитектура

Поток сообщений

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

Поля конфигурации

DM Policies

Group Policy

🔌 MAX Bot API

Отправка сообщения

Индикатор «Печатает...»

Загрузка файлов

Inline Keyboard

Callback от кнопок

📊 Сравнение с Telegram Bot API

🛠️ Разработка

Требования

Установка

Сборка

Линтинг

Локальная установка в OpenClaw

🧪 Тестирование

🚀 Релизы и CI/CD

Git flow

GitHub Actions

Создание релиза

📄 Лицензия

🔗 Связанные проекты

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages