OpenClaw QQ Bot Channel

OpenClaw connects to QQ through the QQ Open Platform's WebSocket-based event gateway. The Gateway establishes an outbound WebSocket connection to QQ's servers and receives real-time event pushes including messages, reactions, and member updates. The message flow is: User sends a message in QQ → QQ Open Platform → WebSocket push to your Gateway → OpenClaw processes with AI → reply via QQ Bot API → message delivered in QQ. QQ's bot architecture distinguishes between three messaging contexts: direct messages (C2C, one-on-one), group chats (standard QQ groups), and channels (QQ Guild/channel system similar to Discord). Each context has its own set of intents and permissions, and can be enabled or disabled independently in OpenClaw. The @openclaw-china/qqbot plugin uses QQ's official Bot SDK and handles connection lifecycle, heartbeats, reconnection, and session resumption automatically.

There are two plugin options for QQ integration: **@openclaw-china/qqbot** (3.2k stars) — The primary recommended plugin by BytePioneer-AI with the largest community. Supports QQ along with other Chinese platforms (Feishu, DingTalk, WeCom, personal WeChat) in a bundled package. Includes the 'openclaw china setup' wizard for guided configuration. Install with 'openclaw plugins install @openclaw-china/qqbot' or install the full bundle with 'openclaw plugins install @openclaw-china/channels'. **@sliverp/qqbot** (186 stars) — A lighter, dedicated QQ-only plugin. A good choice if you only need QQ support and prefer a minimal installation. Recommendation: use @openclaw-china/qqbot for most deployments — it has the larger community, more features, and the convenient setup wizard.

# Install primary recommended plugin
openclaw plugins install @openclaw-china/qqbot

# Or install bundled China channels package
openclaw plugins install @openclaw-china/channels

# Alternative: dedicated QQ-only plugin
openclaw plugins install @sliverp/qqbot

Setting up QQ bot integration requires creating a bot application on the QQ Open Platform: 1. Visit q.qq.com and log in with your QQ account. Developer identity verification is required and may take 1-2 business days. 2. In the Bot Management console, click 'Create Bot' and fill in the required information: bot name, avatar, description, and category. 3. After creation, go to 'Development Settings' → 'Credentials' to find your **AppID** (numeric identifier) and **ClientSecret** (secret key). Copy both. 4. Under 'Development Settings' → 'Intents', configure which events your bot subscribes to: - **GUILDS** — Guild (server) join/leave events - **GUILD_MESSAGES** — Messages in guild channels - **DIRECT_MESSAGE** — Direct messages within guilds - **GROUP_AND_C2C_EVENT** — Group chat and private chat messages (requires approval) - **INTERACTION** — Button click interactions 5. Some intents (especially GROUP_AND_C2C_EVENT) require submitting a request to Tencent for approval. This typically takes 1-3 business days. 6. Use the setup wizard 'openclaw china setup' for guided configuration, or manually add credentials to your config.

# Recommended: interactive setup wizard
openclaw china setup

# Or quick setup via CLI
openclaw channels add --channel qqbot --token "AppID:ClientSecret"

# Or via environment variables
export QQ_APP_ID="your_app_id"
export QQ_CLIENT_SECRET="your_client_secret"

QQ's bot platform supports three distinct messaging contexts, each independently configurable: **Direct Messages (C2C):** One-on-one conversations between a user and the bot. Users can find and message your bot directly through QQ search or the bot's profile page. **Group Chats:** Standard QQ groups where the bot is added as a member. In groups, the bot responds only when @mentioned to avoid noise. Group chat access requires the GROUP_AND_C2C_EVENT intent, which needs Tencent approval. **Channel Messages (QQ Guilds):** QQ Guilds are similar to Discord servers with text and voice channels. The bot can participate in guild text channels and guild direct messages. Channel access uses the GUILD_MESSAGES and DIRECT_MESSAGE intents. Each context maintains its own conversation history. Context resets automatically after a configurable inactivity period.

{
  "channels": {
    "qqbot": {
      "enabled": true,
      "appId": "your-app-id",
      "clientSecret": "your-client-secret"
    }
  }
}

The @openclaw-china/qqbot plugin supports configurable Markdown delivery for C2C (direct) messages via the c2cMarkdownDeliveryMode setting: **passive** — Only sends Markdown in passive replies (within the response window). This is the safest mode and does not consume active message quota. **proactive-table-only** — Sends Markdown proactively only when the message contains tables. Regular text is sent as plain text. This balances formatting quality with active message quota usage. **proactive-all** — Always sends Markdown proactively for all messages. Provides the best formatting experience but consumes active message quota. The c2cMarkdownChunkStrategy setting controls how long Markdown messages are split: - **markdown-block** — Splits at Markdown block boundaries (paragraphs, code blocks, lists). Preserves formatting integrity. Set autoSendLocalPathMedia to true if you want the plugin to automatically upload and send local file paths referenced in AI responses.

{
  "channels": {
    "qqbot": {
      "markdownSupport": true,
      "c2cMarkdownDeliveryMode": "proactive-all",
      "c2cMarkdownChunkStrategy": "markdown-block",
      "autoSendLocalPathMedia": false
    }
  }
}

The QQ bot plugin supports a wide range of media types and message features: **Inbound (receive):** - Text messages with full Unicode support - Images (PNG, JPG, GIF) - Audio messages (voice-to-text requires Tencent Cloud ASR configuration) - Video messages - File attachments - Quote/reply context (the plugin includes the quoted message for AI context) **Outbound (send):** - Plain text - Markdown formatted messages (with headings, lists, code blocks) - Images and files - Keyboard templates (interactive button menus) - Ark messages (rich card templates) **Voice-to-Text (ASR):** Audio message transcription is NOT automatic — it requires configuring Tencent Cloud ASR (Automatic Speech Recognition). You need a Tencent Cloud account with ASR service enabled, then add the ASR configuration block to your qqbot channel config with your Tencent Cloud appId, secretId, and secretKey. **Other Features:** - **Quote Context:** When a user replies to a previous message, the quoted content is included in the AI prompt. - **Scheduled Messages:** Messages can be scheduled for future delivery. - **Markdown Support:** Responses support QQ's Markdown subset for formatted replies.

{
  "channels": {
    "qqbot": {
      "asr": {
        "enabled": true,
        "appId": "tencent-cloud-app-id",
        "secretId": "tencent-cloud-secret-id",
        "secretKey": "tencent-cloud-secret-key"
      }
    }
  }
}

QQ's bot platform has specific rules around active vs. passive messages: **Passive Messages:** Replies to user-initiated messages within a response window. The window length depends on the context: groups and channels have a 5-minute window, while C2C/DM has a 60-minute window with a maximum of 5 replies per message. **Active Messages:** Messages sent by the bot without a user trigger (proactive notifications, scheduled messages). These are subject to strict monthly/daily quotas: - **C2C/DM:** 4 active messages per user per month - **Group:** 4 active messages per group per month - **Channel:** 20 messages per sub-channel per day, limited to 2 sub-channels per day - **Guild DM:** 2 per user per day, 200 total per day QQ enforces rate limits on bot API calls. The default limits vary by bot tier: - Standard bots: ~20 messages per second - Verified bots: Higher limits based on usage To handle rate limiting gracefully, the plugin implements automatic retry with exponential backoff.

OpenClaw provides several commands for managing your QQ bot: - openclaw china setup — Interactive setup wizard for @openclaw-china/qqbot (recommended for first-time setup) - openclaw channels add --channel qqbot --token "AppID:ClientSecret" — Quick channel setup via CLI - openclaw gateway status — Check Gateway connection status and active sessions - openclaw gateway restart — Restart the Gateway service and reconnect to QQ - openclaw logs --follow — View real-time logs for debugging - openclaw plugins list — List installed plugins and versions - openclaw plugins update @openclaw-china/qqbot — Update the QQ plugin to the latest version - openclaw doctor — Run a comprehensive diagnostic check - openclaw channels test qqbot — Send a test message to verify QQ connectivity