QQ Bot Channel Plugin for OpenClaw

Connect your AI assistant to QQ — private chat, group chat, and rich media, all in one plugin.

🚀 Current Version: v1.6.4

简体中文 | English

Scan to join the QQ group chat

Note: This plugin serves as a message channel only — it relays messages between QQ and OpenClaw. Capabilities like image understanding, voice transcription, drawing, etc. depend on the AI model you configure and the skills installed in OpenClaw, not on this plugin itself.

QQ quote events carry index keys (e.g. REFIDX_xxx) instead of full original message body. The plugin now resolves these indices from a local persistent store and injects quote context into AI input, so replies better understand “which message is being quoted”.

• Inbound and outbound messages with ref_idx are automatically indexed.
• Store path: ~/.openclaw/qqbot/data/ref-index.jsonl (survives gateway restart).
• Quote body may include text + media summary (image/voice/video/file).

With STT configured, the plugin automatically transcribes voice messages to text before passing them to AI. The whole process is transparent to the user — sending voice feels as natural as sending text.

You: (send a voice message) "What's the weather like tomorrow in Shenzhen?"

QQBot: Tomorrow (March 7, Saturday) Shenzhen weather forecast 🌤️ ...

Send any file to the bot — novels, reports, spreadsheets — AI automatically recognizes the content and gives an intelligent reply.

You: (send a TXT file of "War and Peace")

QQBot: Got it! You uploaded the Chinese version of "War and Peace" by Leo Tolstoy. This appears to be the opening of Chapter 1...

If your main model supports vision (e.g. Tencent Hunyuan hunyuan-vision), AI can understand images too. This is a general multimodal capability, not plugin-specific.

You: (send an image)

QQBot: Haha, so cute! Is that a QQ penguin in a lobster costume? 🦞🐧 ...

You: Draw me a cat

QQBot: Here you go! 🐱

AI can send images directly. Supports local paths and URLs. Formats: jpg/png/gif/webp/bmp.

You: Tell me a joke in voice

QQBot: (sends a voice message)

AI can send voice messages directly. Formats: mp3/wav/silk/ogg. No ffmpeg required.

You: Remind me to eat in 5 minutes

QQBot: confirms the reminder first, then proactively sends a voice + text reminder when time is up

This capability depends on OpenClaw cron scheduling and proactive messaging. If no reminder arrives, a common reason is QQ-side interception of bot proactive messages.

You: Extract chapter 1 of War and Peace and send it as a file

QQBot: (sends a .txt file)

AI can send files directly. Any format, up to 20MB.

You: Send me a demo video

QQBot: (sends a video)

AI can send videos directly. Supports local files and URLs.

Under the hood: Upload dedup caching, ordered queue delivery, and multi-layer audio format fallback.

The plugin provides built-in slash commands that are intercepted before reaching the AI queue, giving instant responses for diagnostics and management.

You: /bot-ping

QQBot: ✅ pong！⏱ Latency: 602ms (network: 602ms, plugin: 0ms)

Measures end-to-end latency from QQ server push to plugin response, broken down into network transport and plugin processing time.

You: /bot-version

QQBot: 🦞 Framework: OpenClaw 2026.3.13 (61d171a) / 🤖 Plugin: v1.6.3 / 🌟 GitHub repo

Shows framework version, plugin version, and a direct link to the official repository.

You: /bot-help

QQBot: Lists all available slash commands with clickable shortcuts.

You: /bot-upgrade

QQBot: 📌 Current: v1.6.3 / ✅ New version v1.6.4 available / Click button below to confirm

Credentials are automatically backed up before upgrade. Version existence is verified against npm before proceeding. Auto-recovery on failure.

⚠️ Hot upgrade is currently not supported on Windows. Sending /bot-upgrade on Windows will return a manual upgrade guide instead.

You: /bot-logs

QQBot: 📋 Logs packaged (~2000 lines), sending file... (sends a .txt file)

Exports the last ~2000 lines of gateway logs as a file for quick troubleshooting.

All commands support a ? suffix to show usage:

You: /bot-upgrade ?

QQBot: 📖 /bot-upgrade usage: …

1. Go to the QQ Open Platform and scan the QR code with your phone QQ to register / log in. If you haven't registered before, scanning will automatically complete the registration and bind your QQ account.

2. After scanning, tap Agree on your phone — you'll land on the bot configuration page.
3. Click Create Bot to create a new QQ bot.

⚠️ The bot will automatically appear in your QQ message list and send a first message. However, it will reply "The bot has gone to Mars" until you complete the configuration steps below.

4. Find AppID and AppSecret on the bot's page, click Copy for each, and save them somewhere safe (e.g., a notepad). AppSecret is not stored in plaintext — if you leave the page without saving it, you'll have to regenerate a new one.

For a step-by-step walkthrough with screenshots, see the official guide.

Option A: Remote One-Liner (Easiest, no clone required)

curl -fsSL https://raw.githubusercontent.com/tencent-connect/openclaw-qqbot/main/scripts/upgrade-via-npm.sh \ | bash -s -- --appid YOUR_APPID --secret YOUR_SECRET

One command does it all: download script → cleanup old plugins → install → configure channel → restart service. Once done, open QQ and start chatting!

--appid and --secret are required for first-time install. For subsequent upgrades:

curl -fsSL https://raw.githubusercontent.com/tencent-connect/openclaw-qqbot/main/scripts/upgrade-via-npm.sh | bash

Option B: Local Script (if you've cloned the repo)

# Via npm bash ./scripts/upgrade-via-npm.sh --appid YOUR_APPID --secret YOUR_SECRET # Or via source bash ./scripts/upgrade-via-source.sh --appid YOUR_APPID --secret YOUR_SECRET

Common flags:

Environment variables QQBOT_APPID / QQBOT_SECRET are also supported.

Option C: Manual Install / Upgrade

# Uninstall old plugins (skip if first install) openclaw plugins uninstall qqbot openclaw plugins uninstall openclaw-qqbot # Install latest openclaw plugins install @tencent-connect/openclaw-qqbot@latest # Configure channel (first install only) openclaw channels add --channel qqbot --token "AppID:AppSecret" # Start / restart openclaw gateway restart

Open QQ, find your bot, and send a message!

Run multiple QQ bots under a single OpenClaw instance.

Edit ~/.openclaw/openclaw.json and add an accounts field under channels.qqbot:

{ "channels": { "qqbot": { "enabled": true, "appId": "111111111", "clientSecret": "secret-of-bot-1", "accounts": { "bot2": { "enabled": true, "appId": "222222222", "clientSecret": "secret-of-bot-2" }, "bot3": { "enabled": true, "appId": "333333333", "clientSecret": "secret-of-bot-3" } } } } }

Notes:

• The top-level appId / clientSecret is the default account (accountId = "default")
• Each key under accounts (e.g. bot2, bot3) is the accountId for that bot
• Each account can independently configure enabled, name, allowFrom, systemPrompt, etc.
• You may also skip the top-level default account and only configure bots inside accounts

Add a second bot via CLI (if the framework supports the --account parameter):

openclaw channels add --channel qqbot --account bot2 --token "222222222:secret-of-bot-2"

When using openclaw message send, specify which bot to use with the --account parameter:

# Send with the default bot (no --account = uses "default") openclaw message send --channel "qqbot" \ --target "qqbot:c2c:OPENID" \ --message "hello from default bot" # Send with bot2 openclaw message send --channel "qqbot" \ --account bot2 \ --target "qqbot:c2c:OPENID" \ --message "hello from bot2"

Target Formats:

⚠️ Important: Each bot has its own set of user OpenIDs. An OpenID received by Bot A cannot be used to send messages via Bot B — this will result in a 500 error. Always use the matching bot's accountId to send messages to its users.

• When openclaw gateway starts, all accounts with enabled: true launch their own WebSocket connections
• Each account maintains an independent Token cache (isolated by appId), preventing cross-contamination
• Incoming message logs are prefixed with [qqbot:accountId] for easy debugging

STT supports two-level configuration with priority fallback:

{ "channels": { "qqbot": { "stt": { "provider": "your-provider", "model": "your-stt-model" } } } }

• provider — references a key in models.providers to inherit baseUrl and apiKey
• Set enabled: false to disable
• When configured, incoming voice messages are automatically converted (SILK→WAV) and transcribed

{ "channels": { "qqbot": { "tts": { "provider": "your-provider", "model": "your-tts-model", "voice": "your-voice" } } } }

• provider — references a key in models.providers to inherit baseUrl and apiKey
• voice — voice variant
• Set enabled: false to disable (default: true)
• When configured, AI can generate and send voice messages

• Upgrade Guide — full upgrade paths and migration notes
• Command Reference — OpenClaw CLI commands
• Changelog — release notes

Thanks to all the developers who have contributed to this project!

Special thanks to @sliverp for outstanding contributions to the project!

Thanks to Tencent Cloud Lighthouse for the deep collaboration. For raising crawfish, choose Tencent Cloud Lighthouse!