QQ Bot Channel Plugin for OpenClaw

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

简体中文 | 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.

🎙️ Voice Messages (STT) — AI understands voice messages, auto-transcribes speech to 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

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

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! 🐱

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

You: Tell me a joke in voice

QQBot: (sends a voice message)

📎 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)

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

You: Send me a demo video

QQBot: (sends a video)

For a deep dive into rich media capabilities, see the Media Guide.

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

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.

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

# Via OpenClaw CLI (recommended)
openclaw plugins install @sliverp/qqbot@latest

# Or from source
git clone https://github.com/sliverp/qqbot.git && cd qqbot
openclaw plugins install .

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

openclaw gateway

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

For installations via openclaw plugins install

openclaw plugins upgrade @sliverp/qqbot@latest

npx -y @sliverp/qqbot@latest upgrade

bash ./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 ./upgrade-and-run.sh --appid YOUR_APPID --secret YOUR_SECRET

bash ./pull-latest.sh

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

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

• Rich Media Guide — images, voice, video, files
• Command Reference — OpenClaw CLI commands
• Changelog — release notes (latest: 1.5.4)