How to Connect OpenClaw to QQ

QQ Bot connects OpenClaw to the official QQ Bot API over a WebSocket gateway, which means you get a real channel integration instead of a scraper or sidecar hack. The official docs say the plugin supports C2C private chats, group @messages, guild channel messages, and rich media, so the setup is worth doing carefully once and then leaving alone.

When this is the right move

Use this when your operator workflow or community already lives inside QQ and you want the assistant reachable there without adding another chat app. It is also a good fit when you need one gateway to host more than one QQ bot account but still keep routing and credentials isolated per bot.

The practical workflow

1. Create the bot in the QQ Open Platform, then copy the AppID and AppSecret immediately because the docs warn that the secret is not stored in plaintext for later viewing.
2. Add the channel with the documented CLI token format or place the same values in channels.qqbot config.
3. Restart the Gateway so the bundled plugin can open its WebSocket connection and fetch a token cache for that appId.
4. If you need more than one bot, add accounts under channels.qqbot.accounts rather than reusing the same credentials everywhere.
5. Test a C2C private chat first, then a group @message or guild channel message so you can verify each target shape separately.

Grounded command or config pattern

The docs show both a direct CLI setup and a minimal config block. The quickest documented CLI path is this token form.

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

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

For file-backed secrets, the docs also support clientSecretFile. Multi-account setups sit under channels.qqbot.accounts, and each account keeps an isolated WebSocket stack keyed by its own appId.

Operator notes

QQ target formats differ by surface: private chats use qqbot:c2c:OPENID, groups use qqbot:group:GROUP_OPENID, and guild channels use qqbot:channel:CHANNEL_ID. The docs also call out that OpenIDs are bot-specific, so an OpenID received by one bot cannot be reused to send messages from another bot. Voice STT and TTS are configurable, but reactions and threads are explicitly unsupported today.

Rollout approach

For connecting OpenClaw to QQ, I would start with one bot, one private conversation, and one group test instead of enabling every destination at once. That keeps the first troubleshooting cycle small and makes it obvious whether a failure belongs to credentials, routing, or the target surface itself.

Common mistake

The common mistake is treating the command or config key as the whole feature. The command starts the workflow, but the surrounding state is what keeps it reliable: config validation, auth, pairing, permissions, logs, and one small verification step. If those pieces are skipped, the next failure looks random even when OpenClaw is behaving exactly as configured.

Maintenance rhythm

Once this is working, write down the exact command, config path, or approval decision you used. Future you will not remember the tiny detail that made the setup safe. A short note in the workspace or runbook is cheaper than rediscovering the same behavior during an outage, especially after updates or host changes.

Safety checks

Treat the AppSecret like production infrastructure. If you lose it, regenerate it rather than copying partial screenshots around. If you run multiple QQ bots, keep each account's credentials and delivery targets separate so you do not accidentally mix OpenIDs, token caches, or user expectations across bots.

How to verify it worked

After restart, send a private message to the bot and confirm the reply arrives in the same C2C chat. Then send a group @message and make sure the bot responds only there, not in some unrelated session. If either surface fails, inspect the account-specific config and logs before changing anything about models or memory.

If you want the operator version with sharper checklists, safer defaults, and fewer “why is this broken?” afternoons, The OpenClaw Playbook is the shortcut I would hand to a serious OpenClaw owner.