Channels

Max Plus

Name: Max Plus
Rating: 3.5 (1 reviews)
Author: MissiaL

By MissiaL 👁 66 views ▲ 0 votes

MAX messenger (max.ru) bot channel plugin for OpenClaw — AI-ассистент в мессенджере MAX. TypeScript, Bot API, long polling + webhook.

Homepage GitHub

Install

npm install
npm

Configuration Example

{ "plugins": { "entries": { "openclaw-max-plus": { "enabled": true } },
               "load": { "paths": ["/путь/к/openclaw-max-plus"] } } }

README

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

[![license](https://img.shields.io/github/license/MissiaL/openclaw-max-plus)](LICENSE)
[![TypeScript](https://img.shields.io/badge/TypeScript-ESM-blue)](https://www.typescriptlang.org/)
[![Node](https://img.shields.io/badge/node-%E2%89%A522.15-green)](https://nodejs.org/)

Канал-плагин для подключения AI-ассистента [OpenClaw](https://openclaw.ai) к мессенджеру [MAX](https://max.ru) (max.ru Bot API).

> **English:** `openclaw-max-plus` is a channel plugin that connects the [OpenClaw](https://openclaw.ai) AI assistant to the [MAX messenger](https://max.ru) (max.ru Bot API). It brings Telegram-level parity to MAX: text & markdown, media (photo/video/file/sticker/contact/location, incl. inline base64), inline buttons, reply/forward/edit/delete, pin/unpin, response streaming, typing indicator, long polling **and** webhook, multi-account, and DM security. Written in TypeScript (ESM), requires Node.js ≥ 22.15. Full setup guide below is in Russian.

## Что это

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

- Приём и отправку текстовых сообщений (markdown)
- Вложения: фото, видео, файлы, стикеры, контакт, локация (в т.ч. inline-base64 — напр. сгенерированные картинки)
- Длинные подписи к медиа (>4000 — остаток уходит follow-up-сообщениями)
- Inline-кнопки: `callback` (+цвет intent), `link`, `request_contact`, `request_geo_location`, `message`, `clipboard`, `open_app`; выбор модели
- Reply, **forward** (приём с атрибуцией автора/канала), edit, delete
- **Pin/unpin** сообщений (admin-only, группы/каналы)
- Стриминг ответа (`streamMode`: partial / block), typing-индикатор
- Long polling и Webhook (с валидацией secret/url)
- Мультиаккаунт, DM-security, pairing, групповые политики

> Реакции и опросы MAX Bot API **не поддерживает** (платформенное ограничение). Нативные голосовые заметки MAX боту не доставляет (баг платформы).

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

```
openclaw-max-plus/
├── openclaw.plugin.json    # Манифест плагина
├── package.json
├── tsconfig.json
├── README.md
├── src/
│   ├── index.ts            # Точка входа плагина (register → channel)
│   ├── types.ts            # TypeScript-типы MAX Bot API
│   ├── api.ts              # HTTP-клиент MAX API (send/edit/delete/upload/actions)
│   ├── monitor.ts          # Long polling + webhook (приём обновлений, dispatch)
│   ├── webhook.ts          # Обработчик webhook-запросов
│   ├── send.ts             # Высокоуровневые send-хелперы (текст/медиа/edit)
│   ├── channel.ts          # OpenClaw channel adapter
│   ├── config-schema.ts    # Zod-схема конфига канала
│   ├── accounts.ts         # Резолвинг аккаунтов из конфига
│   ├── runtime.ts          # Доступ к OpenClaw runtime
│   ├── actions.ts          # Действия/команды
│   ├── model-buttons.ts    # Кнопки выбора модели
│   ├── onboarding.ts       # Онбординг/настройка аккаунта
│   ├── format.ts           # Форматирование текста
│   └── sticker-cache.ts    # Кэш стикеров
└── scripts/
    ├── test-api.mjs        # Проверка токена и API (GET /me + GET /updates)
    └── test-send.mjs       # Тест send + edit + delete
```

## 🤖 Инструкция для агента: как настроить OpenClaw с этим плагином

Пошаговый runbook (выполнять по порядку, проверяя результат каждого шага).

**0. Предусловия**
- Node.js **≥ 22.15** (нужен `tls.setDefaultCACertificates` для авто-доверия CA Минцифры → домен `platform-api2.max.ru`). Проверка: `node -e "const t=require('node:tls');console.log(typeof t.setDefaultCACertificates)"` → должно быть `function`.
- Установлен `openclaw` (CLI/gateway). Проверка: `openclaw --version`.
- Есть токен бота MAX (см. «Установка → Создать бота в MAX» ниже). Никогда не печатать токен в логи/коммиты.

**1. Собрать плагин** (entry — `dist/index.js`; build кладёт и `dist/certs/` с CA):
```bash
cd /путь/к/openclaw-max-plus
npm install
npm run typecheck && npm run lint && npm test   # должно быть зелёным
npm run build
```

**2. Подключить плагин к OpenClaw.** Способ А — через CLI:
```bash
openclaw plugins install --link /путь/к/openclaw-max-plus   # симлинк (live-разработка)
```
Способ Б — прописать путь в `~/.openclaw/openclaw.json` (gateway грузит из рабочей папки):
```jsonc
{ "plugins": { "entries": { "openclaw-max-plus": { "enabled": true } },
               "load": { "paths": ["/путь/к/openclaw-max-plus"] } } }
```

**3. Настроить канал** в `~/.openclaw/openclaw.json` (минимум — токен + кто может писать):
```jsonc
{ "channels": { "max": {
  "enabled": true,
  "botToken": "ТОКЕН_БОТА",       // или "tokenFile": "/path/to/token", или env MAX_BOT_TOKEN
  "dmPolicy": "allowlist",         // pairing | allowlist | open
  "allowFrom": ["ВАШ_USER_ID"],    // см. шаг 6, как узнать user_id
  "streamMode": "partial"
  // "apiBaseUrl": "https://platform-api.max.ru"  // ОПЦ.: откат на legacy-домен (если Node < 22.15)
}}}
```
> Держать `src/config-schema.ts` ↔ `openclaw.plugin.json` в синхроне при добавлении полей.

**4. Индикатор «печатает…» — ОБЯЗАТЕЛЬНО задать глобально** (иначе индикатор будет мигать и обрываться, в MAX одиночный `typing_on` живёт ~5–6с):
```bash
openclaw config set session.typingIntervalSeconds 4
```

**5. Перезапустить gateway** — зависит от того, как он запущен:
- launchd-сервис (`launchctl list | grep openclaw` показывает `ai.openclaw.gateway`): `launchctl kickstart -k "gui/$(id -u)/ai.openclaw.gateway"`
- вручную: остановить и `openclaw gateway --port 18789` (или `openclaw gateway restart`, если поддерживается).
> **После ЛЮБОЙ правки кода:** `npm run build` → перезапуск gateway (плагин держится в памяти, на лету не подхватывается).

**6. Проверить и найти свой user_id:**
```bash
openclaw plugins inspect max --runtime        # канал max зарегистрирован?
# Живой лог gateway (stdout). Путь зависит от запуска:
tail -f ~/Library/Logs/openclaw/gateway.log   # macOS launchd
# Написать боту в MAX любой текст → в логе появится "Starting MAX provider (@bot)" и обработка;
# user_id отправителя виден в логах или: MAX_BOT_TOKEN=xxx node scripts/test-api.mjs (раздел updates)
```
Подставить найденный `user_id` в `allowFrom` (шаг 3) и перезапустить gateway. Бот должен ответить.

**7. Диагностика «бот не отвечает»** (по приоритету):
1. `getUpdates`/TLS падает → проверь домен: `curl -I -H "Authorization: ТОКЕН" https://platform-api2.max.ru/me` (200/401 = TLS ок; `TLS:20`/`UNABLE_TO_GET_ISSUER` = нет CA → Node < 22.15 или `npm run build` не клал `certs/` → временно `apiBaseUrl: "https://platform-api.max.ru"`).
2. Сообщение приходит, но ответа нет → смотри `~/.openclaw/agents/main/sessions/*.jsonl` (последние записи): дошёл ли inbound, не упал ли `toolResult` отправки (напр. `POST /messages → 404` = неверный chat_id; `ENAMETOOLONG` = inline-медиа; LLM-биллинг = квота).
3. `dmPolicy`/`allowFrom` блокируют отправителя → проверь user_id в `allowFrom`.

## Установка

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

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

### 2. Собрать и подключить плагин

```bash
cd openclaw-max-plus
npm install
npm run build                          # собирает dist/ (entry: dist/index.js)

# Подключить плагин к OpenClaw из локальной папки
openclaw plugins install ./.           # или абсолютный путь к папке плагина
```

Альтернатива для разработки — указать путь к плагину прямо в конфиге
`~/.openclaw/openclaw.json`, тогда gateway грузит его из рабочей папки:

```jsonc
{
  "plugins": {
    "entries": { "openclaw-max-plus": { "enabled": true } },
    "load": { "paths": ["/путь/к/openclaw-max-plus"] }
  }
}
```

### 3. Настроить канал

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

```jsonc
{
  "channels": {
    "max": {
      "enabled": true,

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

      // Политика личных сообщений (по умолчанию "pairing"):
      //   "pairing"   — новый контакт проходит pairing-код
      //   "allowlist" — только user_id из allowFrom
      //   "open"      — любой (требует allowFrom: ["*"])
      "dmPolicy": "allowlist",

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

      // Режим стриминга ответа: "off" | "partial" | "block"
      "streamMode": "partial"
    }
  }
}
```

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

```bash
openclaw gateway restart
```

> Можно проверить регистрацию канала: `openclaw plugins inspect max --runtime`.

## Индикатор «печатает…» (typing)

MAX гасит индикатор «печатает…» через несколько секунд, поэтому плагин
переотправляет его весь ход ответа через keepalive хоста. Частота
переотправки задаётся **глобальным** параметром `session.typingIntervalSeconds`
(по умолчанию 6с). Одиночный `typing_on` в MAX живёт ~5–6с, поэтому значение по
умолчанию (6с) даёт разрывы. **Обязательно** выставьте **4** — иначе индикатор
будет мигать и обрываться:

```bash
openclaw config set session.typingIntervalSeconds 4
openclaw gateway restart
```

> Параметр общий для всех каналов (затронет и Telegram — для него 4с тоже
> безопасно). Индикатор «печатает…» бота отображается **в мобильном клиенте
> MAX**; веб-версия его показывает ненадёжно — это особенность клиента MAX.

## Команды бота

Меню команд бота задаётся полем `commands` в конфиге канала и регистрируется в
MAX при старте провайдера (через `PATCH /me`). Каждая команда — `{ name,
description }` (`name` 1–64 симв., `description` до 128, максимум 32 команды):

```jsonc
{
  "channels": {
    "max": {
      "commands": [
        { "name": "status",  "description": "Статус и лимиты подписки" },
        { "name": "new",     "description": "Начать новую сессию" },
        { "name": "stop",    "description": "Прервать текущую задачу" },
        { 

... (truncated)

channels