QQ Bot Channel Plugin for OpenClaw

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

Scan to join the QQ group chat

✨ Features

Feature	Description
🔒 Multi-Scene	C2C private chat, group @messages, channel messages, channel DMs
🖼️ Rich Media	Send & receive images, voice, video, and files
🎙️ Voice (STT/TTS)	Speech-to-text transcription & text-to-speech replies
⏰ Scheduled Push	Proactive message delivery via scheduled tasks
🔗 URL Support	Direct URL sending in private chat (no restrictions)
⌨️ Typing Indicator	"Bot is typing..." status shown in real-time
🔄 Hot Reload	Install via npm with seamless hot updates
📝 Markdown	Full Markdown formatting support
🛠️ Commands	Native OpenClaw command integration

📸 Feature Showcase

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.

🎙️ Voice Messages (STT) — AI understands voice messages, auto-transcribes speech to text

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 🌤️ ...

📄 File Understanding — Send any file, AI reads and understands it

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...

🖼️ Image Understanding — Vision-capable models can see and describe images

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? 🦞🐧 ...

🎨 Image Generation — Ask the bot to draw, it sends the result back

You: Draw me a cat

QQBot: Here you go! 🐱

AI uses the <qqimg> tag to send images. Both local file paths and URLs are supported. Formats: jpg/png/gif/webp/bmp.

<qqimg>~/.openclaw/qqbot/images/cute-cat.png</qqimg>

🔊 Voice Reply (TTS) — Bot replies with voice messages

You: Tell me a joke in voice

QQBot: (sends a voice message)

AI uses the <qqvoice> tag to send voice messages. Formats: mp3/wav/silk/ogg. Works without ffmpeg.

<qqvoice>~/.openclaw/qqbot/tts/joke.silk</qqvoice>

📎 File Sending — Generate and send files of any format (up to 20MB)

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

QQBot: (sends a .txt file)

AI uses the <qqfile> tag to send files. PDF, Excel, ZIP, TXT — any format, up to 20MB.

<qqfile>~/.openclaw/qqbot/downloads/war-and-peace-ch1.txt</qqfile>

🎬 Video Sending — Send videos, large files auto-show upload progress

You: Send me a demo video

QQBot: (sends a video)

AI uses the <qqvideo> tag to send videos. Both local files and URLs are supported. Large files (>5MB) auto-show "uploading..." status.

<qqvideo>~/.openclaw/qqbot/downloads/demo.mp4</qqvideo>

Rich Media Tag Reference

Tag	Direction	Usage	Notes
`<qqimg>path</qqimg>`	Send	Image	Local path or URL, jpg/png/gif/webp/bmp
`<qqvoice>path</qqvoice>`	Send	Voice	mp3/wav/silk/ogg, no ffmpeg required
`<qqfile>path</qqfile>`	Send	File	Any format, up to 20MB
`<qqvideo>path</qqvideo>`	Send	Video	Local path or URL
Voice message	Receive	STT	Auto-transcribe with configured STT model
File attachment	Receive	File	Auto-download and feed content to AI
Image attachment	Receive	Vision	Requires vision-capable model

Try It Yourself

Direction	You say	AI does
Receive voice	Send a voice message asking about weather	STT auto-transcribes, AI replies with text
Receive file	Send a file to the bot	AI reads file content, gives intelligent reply
Send image	"Draw me a cat"	Calls drawing tool, sends image back
Send voice	"Tell me a joke in voice"	TTS generates voice, sends voice message
Send file	"Generate a file for me"	Creates file, sends via `<qqfile>`
Send video	"Send me a video"	Sends video via `<qqvideo>`

Under the hood: Tag variant auto-correction (30+ variants like <qq_img>, <image>, ＜qqimg＞ are all recognized), upload caching (dedup within short windows), ordered queue delivery, and multi-layer audio format fallback.

⭐ Star History

🚀 Getting Started

Step 1 — Create a QQ Bot on the QQ Open Platform

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 bindyour QQ account.

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

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.

⚠️ 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.

Step 2 — Install the Plugin

Option A: One-Click Install & Run (Recommended)

git clone https://github.com/tencent-connect/openclaw-qqbot.git && cd openclaw-qqbot
bash ./scripts/upgrade-and-run.sh --appid YOUR_APPID --secret YOUR_SECRET

The script handles everything: cleanup old plugins → install deps → register plugin → configure channel → start service. Once done, skip to Step 4.

Option B: Manual Step-by-Step

git clone https://github.com/tencent-connect/openclaw-qqbot.git && cd openclaw-qqbot
npm install --omit=dev
openclaw plugins install .

Step 3 — Configure OpenClaw

Option 1: CLI Wizard (Recommended)

openclaw channels add --channel qqbot --token "AppID:AppSecret"

Option 2: Edit Config File

Edit ~/.openclaw/openclaw.json:

{
  "channels": {
    "qqbot": {
      "enabled": true,
      "appId": "Your AppID",
      "clientSecret": "Your AppSecret"
    }
  }
}

Step 4 — Start & Test

openclaw gateway

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

🤖 Multi-Account Setup (Multi-Bot)

Run multiple QQ bots under a single OpenClaw instance.

Configuration

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"

Sending Messages to a Specific Account's Users

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:

Format	Description
`qqbot:c2c:OPENID`	Private chat (C2C)
`qqbot:group:GROUP_OPENID`	Group chat
`qqbot:channel:CHANNEL_ID`	Guild channel

⚠️ 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.

How It Works

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

🎙️ Voice Configuration (Optional)

STT (Speech-to-Text) — Transcribe Incoming Voice Messages

STT supports two-level configuration with priority fallback:

Priority	Config Path	Scope
1 (highest)	`channels.qqbot.stt`	Plugin-specific
2 (fallback)	`tools.media.audio.models[0]`	Framework-level

{
  "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

TTS (Text-to-Speech) — Send Voice Messages

Priority	Config Path	Scope
1 (highest)	`channels.qqbot.tts`	Plugin-specific
2 (fallback)	`messages.tts`	Framework-level

{
  "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 use <qqvoice> tags to generate and send voice messages

🔄 Upgrade

Via OpenClaw / npm

npm package coming soon. Once published, you can install and upgrade via:
openclaw plugins install openclaw-qqbot@latest
openclaw plugins upgrade openclaw-qqbot@latest

Via upgrade-and-run.sh (One-Click)

bash ./scripts/upgrade-and-run.sh

When no --appid / --secret is provided, the script reads existing config from ~/.openclaw/openclaw.json automatically.

# First-time or override credentials
bash ./scripts/upgrade-and-run.sh --appid YOUR_APPID --secret YOUR_SECRET

Full Options

Option	Description
`--appid <id>`	QQ Bot AppID
`--secret <secret>`	QQ Bot AppSecret
`--markdown <yes\|no>`	Enable Markdown format (default: no)
`-h, --help`	Show help

Environment variables QQBOT_APPID, QQBOT_SECRET, QQBOT_TOKEN (AppID:Secret) are also supported.

Via pull-latest.sh (Git Source)

bash ./scripts/pull-latest.sh

Options

bash ./scripts/pull-latest.sh --branch main            # specify branch (default: main)
bash ./scripts/pull-latest.sh --force                   # skip prompts, force update
bash ./scripts/pull-latest.sh --repo <git-url>          # use a different repo

From Source

git clone https://github.com/tencent-connect/openclaw-qqbot.git && cd openclaw-qqbot
npm install --omit=dev
bash ./scripts/upgrade.sh
openclaw plugins install .
openclaw channels add --channel qqbot --token "AppID:AppSecret"
openclaw gateway restart

📚 Documentation

Rich Media Guide — detailed STT/TTS config examples and tag usage
Command Reference — OpenClaw CLI commands
Changelog — release notes (latest: 1.5.4)

Name		Name	Last commit message	Last commit date
Latest commit History 253 Commits
bin		bin
docs		docs
scripts		scripts
skills		skills
src		src
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
README.zh.md		README.zh.md
clawdbot.plugin.json		clawdbot.plugin.json
index.ts		index.ts
moltbot.plugin.json		moltbot.plugin.json
openclaw.plugin.json		openclaw.plugin.json
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

QQ Bot Channel Plugin for OpenClaw

✨ Features

📸 Feature Showcase

Rich Media Tag Reference

Try It Yourself

⭐ Star History

🚀 Getting Started

Step 1 — Create a QQ Bot on the QQ Open Platform

Step 2 — Install the Plugin

Step 3 — Configure OpenClaw

Step 4 — Start & Test

🤖 Multi-Account Setup (Multi-Bot)

Configuration

Sending Messages to a Specific Account's Users

How It Works

🎙️ Voice Configuration (Optional)

STT (Speech-to-Text) — Transcribe Incoming Voice Messages

TTS (Text-to-Speech) — Send Voice Messages

🔄 Upgrade

Via OpenClaw / npm

Via upgrade-and-run.sh (One-Click)

Via pull-latest.sh (Git Source)

From Source

📚 Documentation

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

QQ Bot Channel Plugin for OpenClaw

✨ Features

📸 Feature Showcase

Rich Media Tag Reference

Try It Yourself

⭐ Star History

🚀 Getting Started

Step 1 — Create a QQ Bot on the QQ Open Platform

Step 2 — Install the Plugin

Step 3 — Configure OpenClaw

Step 4 — Start & Test

🤖 Multi-Account Setup (Multi-Bot)

Configuration

Sending Messages to a Specific Account's Users

How It Works

🎙️ Voice Configuration (Optional)

STT (Speech-to-Text) — Transcribe Incoming Voice Messages

TTS (Text-to-Speech) — Send Voice Messages

🔄 Upgrade

Via OpenClaw / npm

Via upgrade-and-run.sh (One-Click)

Via pull-latest.sh (Git Source)

From Source

📚 Documentation

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages