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 plugin. Direct messages, group chats, guild channels, and media are supported. Reactions and threads are not supported.

Bundled plugin

Current OpenClaw releases bundle QQ Bot, so normal packaged builds do not need a separate

step.

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.

4. Add the channel:

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

5. Restart the Gateway.

Interactive setup paths:

bash
Copy
openclaw channels add
openclaw configure --section channels

Configure

Minimal config:

json5
Copy
{
  channels: {
    qqbot: {
      enabled: true,
      appId: "YOUR_APP_ID",
      clientSecret: "YOUR_APP_SECRET",
    },
  },
}

Default-account env vars:

• text

  Copy

  QQBOT_APP_ID
• text

  Copy

  QQBOT_CLIENT_SECRET

File-backed AppSecret:

json5
Copy
{
  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.
• text

  Copy

  openclaw channels add --channel qqbot --token-file ...
  provides the AppSecret only; the AppID must already be set in config or
  text

  Copy

  QQBOT_APP_ID
  .
• text

  Copy

  clientSecret
  also accepts SecretRef input, not just a plaintext string.

Multi-account setup

Run multiple QQ bots under a single OpenClaw instance:

json5
Copy
{
  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

).

Add a second bot via CLI:

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

Group chats

QQ Bot group chat support uses QQ group OpenIDs, not display names. Add the bot to a group, then mention it or configure the group to run without a mention.

json5
Copy
{
  channels: {
    qqbot: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["member_openid"],
      groups: {
        "*": {
          requireMention: true,
          historyLimit: 50,
          toolPolicy: "restricted",
        },
        GROUP_OPENID: {
          name: "Release room",
          requireMention: false,
          ignoreOtherMentions: true,
          historyLimit: 20,
          prompt: "Keep replies short and operational.",
        },
      },
    },
  },
}

sets defaults for every group, and a concrete entry overrides those defaults for one group. Group settings include:

• text

  Copy

  requireMention
  : require an @mention before the bot replies. Default:
  text

  Copy

  true
  .
• text

  Copy

  ignoreOtherMentions
  : drop messages that mention someone else but not the bot.
• text

  Copy

  historyLimit
  : keep recent non-mention group messages as context for the next mentioned turn. Set
  text

  Copy

  0
  to disable.
• text

  Copy

  toolPolicy
  :
  text

  Copy

  full
  ,
  text

  Copy

  restricted
  , or
  text

  Copy

  none
  for group-scoped tools.
• text

  Copy

  name
  : friendly label used in logs and group context.
• text

  Copy

  prompt
  : per-group behavior prompt appended to the agent context.

Activation modes are

and . maps to ; maps to . A session-level activation override, when present, wins over config.

The inbound queue is per peer. Group peers get a larger queue cap, keep human messages ahead of bot-authored chatter when full, and merge bursts of normal group messages into one attributed turn. Slash commands still run one by one.

Voice (STT / TTS)

STT and TTS support two-level configuration with priority fallback:

json5
Copy
{
  channels: {
    qqbot: {
      stt: {
        provider: "your-provider",
        model: "your-stt-model",
      },
      tts: {
        provider: "your-provider",
        model: "your-tts-model",
        voice: "your-voice",
      },
      accounts: {
        qq-main: {
          tts: {
            providers: {
              openai: { voice: "shimmer" },
            },
          },
        },
      },
    },
  },
}

Set

on either to disable. Account-level TTS overrides use the same shape as and deep-merge over the channel/global TTS config.

Inbound QQ voice attachments are exposed to agents as audio media metadata while keeping raw voice files out of generic

. plain text replies synthesize TTS and send a native QQ voice message when TTS is configured.

Outbound audio upload/transcode behavior can also be tuned with

:

• text

  Copy

  sttDirectFormats
• text

  Copy

  uploadDirectFormats
• text

  Copy

  transcodeEnabled

Target formats

Slash commands

Built-in commands intercepted before the AI queue:

Append

to any command for usage help (for example ).

Admin commands (

, , , , , ) are direct-message-only and require the sender's openid in an explicit non-wildcard list. A wildcard permits chat but does not grant admin command access. Group messages match against first and fall back to . Running an admin command in a group returns a hint rather than silently dropping.

Engine architecture

QQ Bot ships as a self-contained engine inside the plugin:

• Each account owns an isolated resource stack (WebSocket connection, API client, token cache, media storage root) keyed by
  text

  Copy

  appId
  . Accounts never share inbound/outbound state.
• The multi-account logger tags log lines with the owning account so diagnostics stay separable when you run several bots under one gateway.
• Inbound, outbound, and gateway bridge paths share a single media payload root under
  text

  Copy

  ~/.openclaw/media
  , so uploads, downloads, and transcode caches land under one guarded directory instead of a per-subsystem tree.
• Rich media delivery goes through one
  text

  Copy

  sendMedia
  path for C2C and group targets. Local files and buffers above the large-file threshold use QQ's chunked upload endpoints, while smaller payloads use the one-shot media API.
• Credentials can be backed up and restored as part of standard OpenClaw credential snapshots; the engine re-attaches each account's resource stack on restore without requiring a fresh QR-code pair.

QR-code onboarding

As an alternative to pasting

manually, the engine supports a QR-code onboarding flow for linking a QQ Bot to OpenClaw:

1. Run the QQ Bot setup path (for example
   text

   Copy

   openclaw channels add --channel qqbot
   ) and pick the QR-code flow when prompted.
2. Scan the generated QR code with the phone app tied to the target QQ Bot.
3. Approve the pairing on the phone. OpenClaw persists the returned credentials into
   text

   Copy

   credentials/
   under the right account scope.

Approval prompts generated by the bot itself (for example, "allow this action?" flows exposed by the QQ Bot API) surface as native OpenClaw prompts that you can accept with

rather than replying through the raw QQ client.

Troubleshooting

• Bot replies "gone to Mars": credentials not configured or Gateway not started.
• No inbound messages: verify
  text

  Copy

  appId
  and
  text

  Copy

  clientSecret
  are correct, and the bot is enabled on the QQ Open Platform.
• Repeated self-replies: OpenClaw records QQ outbound ref indexes as bot-authored and ignores inbound events whose current
  text

  Copy

  msgIdx
  matches that same bot account. This prevents platform echo loops while still allowing users to quote or reply to previous bot messages.
• Setup with
  text

  Copy

  --token-file
  still shows unconfigured:
  text

  Copy

  --token-file
  only sets the AppSecret. You still need
  text

  Copy

  appId
  in config or
  text

  Copy

  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.

Related

• Pairing
• Groups
• Channel troubleshooting