OpenClaw MAX Messenger Plugin

Plugin for connecting OpenClaw to MAX Messenger — Russian messaging platform with 30+ million users. Tested with OpenClaw 2026.5.28

Features

✅ Two-way messaging (receive and send)
✅ Markdown formatting support
✅ Webhook primary + Long Polling fallback
✅ DM security with allowlist
✅ Pairing/approval flow for new contacts
✅ Session persistence
✅ Works with both direct messages and group chats
✅ Media support — handles images, audio, video, and file attachments
✅ Audio transcription — voice messages are transcribed via Groq Whisper API
✅ Message deduplication — prevents duplicate processing from webhook + polling overlap
✅ Typing indicator
✅ PDF document analysis — PDF files are processed via configured PDF model
✅ Image analysis — photos are analyzed via configured image model (multimodal)

Installation

Via ClawHub (Recommended)

openclaw plugins install clawhub:@alexbessarabenko/openclaw-max

Via npm

openclaw plugins install alexbessarabenko-openclaw-max

Via GitHub

openclaw plugins install github:AlexBessarabenko/openclaw-max-plugin

Manual (Development)

cd ~/.openclaw/extensions
git clone https://github.com/AlexBessarabenko/openclaw-max-plugin.git max
cd max
npm install
npm run build

Configuration

Add to your OpenClaw config (~/.openclaw/config.json):

{
  "channels": {
    "max": {
      "token": "YOUR_MAX_BOT_TOKEN",
      "dmPolicy": "allowlist",
      "allowFrom": ["123456789"]
    }
  }
}

Or set environment variable:

export MAX_BOT_TOKEN=***

For audio transcription, also set:

export GROQ_API_KEY=***

Multimodal Models (Images & PDFs)

To enable image and PDF analysis, configure multimodal-capable models in your OpenClaw config:

{
  "agents": {
    "defaults": {
      "imageModel": "kimi/kimi-for-coding",
      "pdfModel": "kimi/kimi-for-coding"
    }
  }
}

Supported models:

kimi/kimi-for-coding — Kimi (Moonshot AI), supports images and PDFs
openrouter/auto — Auto-selected multimodal model via OpenRouter
Other OpenRouter multimodal models

Getting a Bot Token

Go to MAX for Partners
Create a new bot
Copy the token from bot settings

Usage

Once configured, the bot will:

Receive messages from MAX users (text, images, audio, video, files)
Transcribe voice messages to text via Groq Whisper
Analyze images and PDFs via configured multimodal models
Process them through OpenClaw agent
Send replies back to MAX

Webhook Setup (Recommended)

https://your-openclaw-instance/max/webhook

The plugin automatically uses webhook mode if the health check passes
Falls back to Long Polling if webhook is unavailable

Supported Message Types

Type	Incoming	Outgoing	Notes
Text	✅	✅	Markdown formatting
Images	✅	✅	Analyzed via imageModel (multimodal)
Audio/Voice	✅	⚠️	Transcribed via Groq Whisper
Video	✅	⚠️	Received as placeholder
Files	✅	⚠️	PDFs analyzed via pdfModel
Group chats	✅	✅	Basic support

Architecture

MAX User → MAX API → Webhook/Polling → OpenClaw Plugin → Agent → Reply → MAX API → User
                              ↓
                    [Audio] → Groq Whisper → Text
                    [Image] → Image Model (Kimi, etc.)
                    [PDF]   → PDF Model (Kimi, etc.)

API Reference

Webhook Endpoint

Default webhook path: /max/webhook

Configure in MAX bot settings to point to your OpenClaw instance.

Audio Transcription

Voice messages are automatically:

Downloaded from MAX servers
Sent to Groq Whisper API (whisper-large-v3, Russian language)
Transcribed text appended to message as [Voice]: <transcription>

Requires GROQ_API_KEY environment variable.

Image Analysis

Photos are automatically:

Downloaded from MAX servers (via payload.ls[0] or payload.url)
Passed to configured imageModel (e.g., kimi/kimi-for-coding)
Analyzed with prompt "Что изображено на фото?"

PDF Analysis

PDF files are automatically:

Downloaded from MAX servers (via payload.url)
Passed to configured pdfModel (e.g., kimi/kimi-for-coding)
Text extracted and analyzed

Message Deduplication

The plugin maintains an in-memory deduplication cache (5-minute TTL) to prevent processing the same message twice when both webhook and polling are active during fallback transitions.

MAX Attachment Payload Structures

The plugin handles different MAX API payload structures:

Images:

{
  "type": "image",
  "payload": {
    "photo_id": 12345,
    "token": "***",
    "ls": ["https://i.oneme.ru/i?r=..."]
  }
}

Files:

{
  "type": "file",
  "payload": {
    "url": "https://fd.oneme.ru/getfile?sig=...",
    "token": "***",
    "fileId": 12345,
    "filename": "document.pdf",
    "size": 123456
  }
}

Audio:

{
  "type": "audio",
  "payload": {
    "url": "https://...",
    "token": "***"
  }
}

Development

# Watch mode
npm run dev

# Build
npm run build

Troubleshooting

No image/PDF analysis

Check that imageModel and pdfModel are configured in OpenClaw config
Verify the model supports multimodal input (images + text)
Check logs for [tools] image failed: No image model is configured

Audio not transcribed

Verify GROQ_API_KEY is set
Check Groq API limits and availability

Duplicate messages

Deduplication is automatic (5-min TTL)
Check logs for Duplicate message ... ignored

Webhook not working

Ensure webhook URL is accessible from internet
Check firewall/proxy settings
Plugin falls back to polling automatically

Contributing

Fork the repository
Create a feature branch
Make your changes
Submit a pull request

License

MIT License — see LICENSE file.

Support

GitHub Issues: github.com/AlexBessarabenko/openclaw-max-plugin/issues
MAX Developer Community: dev.max.ru

Made with ❤️ for the OpenClaw community

MAX Messenger