How to Connect OpenClaw to QQ Bot - AppID and AppSecret Setup

QQ Bot is one of the richer Asia-focused integrations in the OpenClaw docs. The channel connects through the official QQ Bot API and supports private chat, group @ messages, guild channel messages, and rich media. That gives you a lot of room to work without needing to bolt on a separate gateway of your own.

What the official docs support

The official page documents QQ Bot as bundled in current releases, with direct messages, group chats, guild channels, and media support. Reactions and threads are not currently part of the documented surface, but built-in slash commands, voice configuration hooks, and multi-account support are all covered directly in the docs.

This is a good channel when you want one OpenClaw instance to serve more than a simple DM bot. The docs describe isolated account stacks keyed by appId, native bot commands, and a shared media payload root under the OpenClaw state directory, which makes the integration feel operationally thought through.

What you need first

• A QQ Open Platform bot with AppID and AppSecret
• A working OpenClaw gateway you can restart after setup
• A decision on whether you need one bot account or several
• Optional STT and TTS provider settings if voice matters

Recommended setup flow

The clean baseline is AppID plus AppSecret first, then voice or multi-account options later.

1. Log into the QQ Open Platform, create the bot, and copy the AppID plus AppSecret. The docs point out that AppSecret is not stored in plaintext on the platform page, so if you leave before saving it you may need to regenerate a fresh secret.
2. Add the channel with openclaw channels add --channel qqbot --token "AppID:AppSecret" or use the interactive channels add flow. Restart the gateway once the credentials are saved.
3. If you prefer config, set channels.qqbot.appId and clientSecret directly, or use QQBOT_APP_ID and QQBOT_CLIENT_SECRET for the default account. The docs also support a file-backed clientSecretFile path when you want to keep the secret out of inline JSON.
4. Enable multi-account only if you need it. The docs show channels.qqbot.accounts with separate appId and clientSecret values, and every account gets its own WebSocket connection plus isolated token cache.
5. Add STT or TTS settings only when you are ready to test voice. The docs document plugin-specific channels.qqbot.stt and channels.qqbot.tts keys that can fall back to framework-wide audio model settings if you do not override them.

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

Access, safety, and operational notes

QQ Bot target formats are explicit, which is a gift when you are debugging. The docs distinguish c2c private chat, group chat, and guild channel targets, and they remind you that an OpenID received by one bot account cannot be reused to send messages through another account. That is exactly the kind of isolation you want.

The built-in slash commands are worth remembering because they give you quick operational checks without waiting on the model. Commands like /bot-ping, /bot-version, /bot-help, and /bot-logs are intercepted before the AI queue, which is handy during outages or rollout testing.

How to verify it is working

After restart, test one private message and one group or guild path that should already be allowed on the QQ side. If voice is in scope, test it last so you separate plain channel connectivity issues from STT or TTS provider issues.

Common gotchas

• AppSecret is easy to lose on the platform page if you leave before saving it
• token-file only supplies AppSecret, you still need AppID in config or env
• Each bot account keeps its own token cache and user identity space

If you want the operator version with tighter rollout checklists, safer defaults, and more production patterns, The OpenClaw Playbook is the easiest shortcut.