Skip to main content

​
QQ Bot

QQ Bot connects to OpenClaw via the official QQ Bot API (WebSocket gateway). The plugin supports C2C private chat, group @messages, and guild channel messages with rich media (images, voice, video, files). Status: bundled channel plugin. Direct messages, group chats, guild channels, and media are supported. Reactions and threads are not supported.

​
Bundled with OpenClaw

Current OpenClaw installs bundle QQ Bot. You do not need a separate openclaw plugins install step for normal setup.

​
Setup

  1. Go to the QQ Open Platform and scan the QR code with your phone QQ to register / log in.
  2. Click Create Bot to create a new QQ bot.
  3. Find AppID and AppSecret on the bot’s settings page and copy them.
AppSecret is not stored in plaintext — if you leave the page without saving it, you’ll have to regenerate a new one.
  1. Add the channel:
openclaw channels add --channel qqbot --token "AppID:AppSecret"
  1. Restart the Gateway.
Interactive setup paths: 
openclaw channels add
openclaw configure --section channels

​
Configure

Minimal config: 
{
  channels: {
    qqbot: {
      enabled: true,
      appId: "YOUR_APP_ID",
      clientSecret: "YOUR_APP_SECRET",
    },
  },
}
Default-account env vars:
  • QQBOT_APP_ID
  • QQBOT_CLIENT_SECRET
File-backed AppSecret: 
{
  channels: {
    qqbot: {
      enabled: true,
      appId: "YOUR_APP_ID",
      clientSecretFile: "/path/to/qqbot-secret.txt",
    },
  },
}
Notes:
  • Env fallback applies to the default QQ Bot account only.
  • openclaw channels add --channel qqbot --token-file ... provides the AppSecret only; the AppID must already be set in config or QQBOT_APP_ID.
  • clientSecret also accepts SecretRef input, not just a plaintext string.

​
Multi-account setup

Run multiple QQ bots under a single OpenClaw instance: 
{
  channels: {
    qqbot: {
      enabled: true,
      appId: "111111111",
      clientSecret: "secret-of-bot-1",
      accounts: {
        bot2: {
          enabled: true,
          appId: "222222222",
          clientSecret: "secret-of-bot-2",
        },
      },
    },
  },
}
Each account launches its own WebSocket connection and maintains an independent token cache (isolated by appId). Add a second bot via CLI: 
openclaw channels add --channel qqbot --account bot2 --token "222222222:secret-of-bot-2"

​
Voice (STT / TTS)

STT and TTS support two-level configuration with priority fallback:
SettingPlugin-specificFramework fallback
STTchannels.qqbot.stttools.media.audio.models[0]
TTSchannels.qqbot.ttsmessages.tts
{
  channels: {
    qqbot: {
      stt: {
        provider: "your-provider",
        model: "your-stt-model",
      },
      tts: {
        provider: "your-provider",
        model: "your-tts-model",
        voice: "your-voice",
      },
    },
  },
}
Set enabled: false on either to disable. Outbound audio upload/transcode behavior can also be tuned with channels.qqbot.audioFormatPolicy:
  • sttDirectFormats
  • uploadDirectFormats
  • transcodeEnabled

​
Target formats

FormatDescription
qqbot:c2c:OPENIDPrivate chat (C2C)
qqbot:group:GROUP_OPENIDGroup chat
qqbot:channel:CHANNEL_IDGuild channel
Each bot has its own set of user OpenIDs. An OpenID received by Bot A cannot be used to send messages via Bot B.

​
Slash commands

Built-in commands intercepted before the AI queue:
CommandDescription
/bot-pingLatency test
/bot-versionShow the OpenClaw framework version
/bot-helpList all commands
/bot-upgradeShow the QQBot upgrade guide link
/bot-logsExport recent gateway logs as a file
Append ? to any command for usage help (for example /bot-upgrade ?).

​
Troubleshooting

  • Bot replies “gone to Mars”: credentials not configured or Gateway not started.
  • No inbound messages: verify appId and clientSecret are correct, and the bot is enabled on the QQ Open Platform.
  • Setup with --token-file still shows unconfigured: --token-file only sets the AppSecret. You still need appId in config or QQBOT_APP_ID.
  • Proactive messages not arriving: QQ may intercept bot-initiated messages if the user hasn’t interacted recently.
  • Voice not transcribed: ensure STT is configured and the provider is reachable.