QQ Bot Channel Plugin for OpenClaw

Connect your AI assistant to QQ — private chat, group chat, and rich media, all in one plugin.

🚀 Current Version: `v1.7.1`

![License](./LICENSE) ![QQ Bot](https://bot.q.qq.com/wiki/) ![Platform](https://github.com/tencent-connect/openclaw-qqbot) ![Node.js](https://nodejs.org/) ![TypeScript](https://www.typescriptlang.org/)

<br/>

简体中文 | English

Scan to join the QQ group chat

</div>

---

✨ Features

| Feature | Description | |---------|-------------| | 🔒 Multi-Scene | C2C private chat, group chat (@mention / autonomous dual mode) | | 👥 Group Fine-Tuning | Per-group @trigger rules, tool policies, custom prompts, message filtering | | 🌐 Dual Transport | WebSocket (default) or Webhook (HTTP callback) — switch via config | | 🖼️ Rich Media | Send & receive images, voice, video, and files | | 🎙️ Voice (STT/TTS) | Speech-to-text transcription & text-to-speech replies | | 🔥 One-Click Hot Upgrade | Send /bot-upgrade in private chat to upgrade — no server login needed | | ⏰ Scheduled Push | Proactive message delivery via scheduled tasks | | 🔗 URL Support | Direct URL sending in private chat (no restrictions) | | ⌨️ Typing Indicator | "Bot is typing..." status shown in real-time | | 📝 Markdown | Full Markdown formatting support | | 🛠️ Commands | Native OpenClaw command integration | | 💬 Quoted Context | Parses the original message a user is replying to and injects it into AI context, so the model always knows exactly which message is being referenced | | 📦 Large File Support | Auto chunked upload for large files (parallel upload with retry), up to 100 MB | | 🔐 Command Execution Approval | AI requests approval via Inline Keyboard buttons before executing commands — tap to allow or deny |

---

📸 Feature Showcase

> Note: This plugin serves as a message channel only — it relays messages between QQ and OpenClaw. Capabilities like image understanding, voice transcription, drawing, etc. depend on the AI model you configure and the skills installed in OpenClaw, not on this plugin itself.

💬 Quoted Message Context

When a user quotes a message in QQ, the plugin automatically parses the quoted message content and injects it into the AI context, so the model clearly knows "which message the user is replying to" and gives more accurate responses. Supports text and media messages (image/voice/video/file), and works across devices.

🎙️ Voice Messages (STT)

With STT configured, the plugin automatically transcribes voice messages to text before passing them to AI. The whole process is transparent to the user — sending voice feels as natural as sending text.

> You: (send a voice message) "What's the weather like tomorrow in Shenzhen?" > > QQBot: Tomorrow (March 7, Saturday) Shenzhen weather forecast 🌤️ ...

📄 File Understanding

Send any file to the bot — novels, reports, spreadsheets — AI automatically recognizes the content and gives an intelligent reply.

> You: (send a TXT file of "War and Peace") > > QQBot: Got it! You uploaded the Chinese version of "War and Peace" by Leo Tolstoy. This appears to be the opening of Chapter 1...

🖼️ Image Understanding

If your main model supports vision (e.g. Tencent Hunyuan hunyuan-vision), AI can understand images too. This is a general multimodal capability, not plugin-specific.

> You: (send an image) > > QQBot: Haha, so cute! Is that a QQ penguin in a lobster costume? 🦞🐧 ...

🎨 Image Sending

> You: Draw me a cat > > QQBot: Here you go! 🐱

AI can send images directly. Supports local paths and URLs. Formats: jpg/png/gif/webp/bmp.

🔊 Voice Sending

> You: Tell me a joke in voice > > QQBot: (sends a voice message)

AI can send voice messages directly. Formats: mp3/wav/silk/ogg. No ffmpeg required.

⏰ Scheduled Reminder (Proactive Message)

> You: Remind me to eat in 5 minutes > > QQBot: confirms the reminder first, then proactively sends a voice + text reminder when time is up

This capability depends on OpenClaw cron scheduling and proactive messaging. If no reminder arrives, a common reason is QQ-side interception of bot proactive messages.

📎 File Sending

> You: Extract chapter 1 of War and Peace and send it as a file > > QQBot: (sends a .txt file)

AI can send files directly, in any format.

Since v1.6.6, large file transfer is supported: images up to 20MB, videos up to 30MB, attachments up to 100MB, with a daily transfer limit of 2GB.

🔐 Command Execution Approval

When the AI needs to execute a command, the plugin sends an approval request via QQ message with interactive buttons — tap ✅ Allow Once, ⭐ Always Allow, or ❌ Deny to control whether the command runs.

Use the /bot-approve command to manage the approval mode (allowlist / off / strict).

🎬 Video Sending

> You: Send me a demo video > > QQBot: (sends a video)

AI can send videos directly. Supports local files and URLs.

> Under the hood: Upload dedup caching, ordered queue delivery, and multi-layer audio format fallback.

🛠️ Slash Commands

The plugin provides built-in slash commands that are intercepted before reaching the AI queue, giving instant responses for diagnostics and management.

`/bot-ping` — Latency Test

> You: /bot-ping > > QQBot: ✅ pong！⏱ Latency: 602ms (network: 602ms, plugin: 0ms)

Measures end-to-end latency from QQ server push to plugin response, broken down into network transport and plugin processing time.

`/bot-version` — Version Info

> You: /bot-version > > QQBot: 🦞 Framework: OpenClaw 2026.3.13 (61d171a) / 🤖 Plugin: v1.6.3 / 🌟 GitHub repo

Shows framework version, plugin version, and a direct link to the official repository.

`/bot-help` — Command List

> You: /bot-help > > QQBot: Lists all available slash commands with clickable shortcuts.

`/bot-upgrade` — One-Click Hot Upgrade

> You: /bot-upgrade > > QQBot: 📌 Current: v1.6.3 / ✅ New version v1.6.4 available / Click button below to confirm

Credentials are automatically backed up before upgrade. Version existence is verified against npm before proceeding. Auto-recovery on failure.

> ⚠️ Hot upgrade is currently not supported on Windows. Sending /bot-upgrade on Windows will return a manual upgrade guide instead.

> ⚠️ v1.6.6 and below do not support hot upgrade via /bot-upgrade. Please upgrade using the following command: > ``bash > curl -fsSL https://raw.githubusercontent.com/tencent-connect/openclaw-qqbot/main/scripts/upgrade-via-npm.sh | bash > ``

`/bot-logs` — Log Export

> You: /bot-logs > > QQBot: 📋 Logs packaged (~2000 lines), sending file... (sends a .txt file)

Exports the last ~2000 lines of gateway logs as a file for quick troubleshooting.

Usage Help

All commands support a ? suffix to show usage:

> You: /bot-upgrade ? > > QQBot: 📖 /bot-upgrade usage: …

`/bot-approve` — Approval Configuration

> You: /bot-approve > > QQBot: 🔐 Command Execution Approval — Enable / Disable / Strict mode / Reset / View current config

Manage the AI command execution approval policy. Supported subcommands:

| Subcommand | Description | |------------|-------------| | /bot-approve on | Enable approval (allowlist mode, recommended) | | /bot-approve off | Disable approval — commands execute directly | | /bot-approve always | Strict mode — every execution requires approval | | /bot-approve reset | Restore framework defaults | | /bot-approve status | View current approval config |

`/bot-clear-storage` — Clear files generated through QQBot conversations and downloaded resources (stored on the host running OpenClaw)

/bot-clear-storage lists files generated by the conversation and files in the downloaded resources directory. Use /bot-clear-storage --force to confirm deletion.

`/bot-group-allways` — Group Response Mode Toggle

> You: /bot-group-allways > > QQBot: 🤖 Group autonomous mode: ❌ @mention required

Toggle group @trigger behavior at runtime — changes persist instantly, no restart needed:

| Subcommand | Description | |------------|-------------| | /bot-group-allways on | AI decides when to speak autonomously (no @ needed) | | /bot-group-allways off | Only respond when @mentioned | | /bot-group-allways (no arg) | View current setting |

> ⚠️ This command modifies the account-level defaultRequireMention. It has lower priority than per-group groups.{groupId}.requireMention settings.

---

🚀 Getting Started

Step 1 — Create a QQ Bot on the QQ Open Platform

1. Go to the QQ Open Platform and scan the QR code with your phone QQ to register / log in. If you haven't registered before, scanning will automatically complete the registration and bind your QQ account.

2. After scanning, tap Agree on your phone — you'll land on the bot configuration page. 3. Click Create Bot to create a new QQ bot.

> ⚠️ The bot will automatically appear in your QQ message list and send a first message. However, it will reply "The bot has gone to Mars" until you complete the configuration steps below.

4. Find AppID and AppSecret on the bot's page, click Copy for each, and save them somewhere safe (e.g., a notepad). AppSecret is not stored in plaintext — if you leave the page without saving it, you'll have to regenerate a new one.

> For a step-by-step walkthrough with screenshots, see the official guide.

Step 2 — Install / Upgrade the Plugin

Option A: Remote One-Liner (Easiest, no clone required)

curl -fsSL https://raw.githubusercontent.com/tencent-connect/openclaw-qqbot/main/scripts/upgrade-via-npm.sh \
  | bash -s -- --appid YOUR_APPID --secret YOUR_SECRET

One command does it all: download script → cleanup old plugins → install → configure channel → restart service. Once done, open QQ and start chatting!

> --appid and --secret are required for first-time install. For subsequent upgrades, run the following command to upgrade to the latest version: > ``bash > curl -fsSL https://raw.githubusercontent.com/tencent-connect/openclaw-qqbot/main/scripts/upgrade-via-npm.sh | bash > ``

Option B: Local Script (if you've cloned the repo)

# Via npm
bash ./scripts/upgrade-via-npm.sh --appid YOUR_APPID --secret YOUR_SECRET

# Or via source
bash ./scripts/upgrade-via-source.sh --appid YOUR_APPID --secret YOUR_SECRET

Common flags:

| Flag | Description | |------|-------------| | --appid <id> --secret <secret> | Configure channel (required for first install, or to change credentials) | | --version <version> | Install a specific version (npm script only) | | --self-version | Install the version from local package.json (npm script only) | | -h / --help | Show full usage |

> Environment variables QQBOT_APPID / QQBOT_SECRET are also supported.

Option C: Manual Install / Upgrade

# Uninstall old plugins (skip if first install)
openclaw plugins uninstall qqbot
openclaw plugins uninstall openclaw-qqbot

# Install latest
openclaw plugins install @tencent-connect/openclaw-qqbot@latest

# Configure channel (first install only)
openclaw channels add --channel qqbot --token "AppID:AppSecret"

# Start / restart
openclaw gateway restart

Step 3 — Test

Open QQ, find your bot, and send a message!

---

⚙️ Advanced Configuration

Multi-Account Setup (Multi-Bot)

Run multiple QQ bots under a single OpenClaw instance.

Configuration

Edit ~/.openclaw/openclaw.json and add an accounts field under channels.qqbot:

{
  "channels": {
    "qqbot": {
      "enabled": true,
      "appId": "111111111",
      "clientSecret": "secret-of-bot-1",

      "accounts": {
        "bot2": {
          "enabled": true,
          "appId": "222222222",
          "clientSecret": "secret-of-bot-2"
        },
        "bot3": {
          "enabled": true,
          "appId": "333333333",
          "clientSecret": "secret-of-bot-3"
        }
      }
    }
  }
}

Notes:

The top-level appId / clientSecret is the default account (accountId = "default")
Each key under accounts (e.g. bot2, bot3) is the accountId for that bot
Each account can independently configure enabled, name, allowFrom, systemPrompt, etc.
You may also skip the top-level default account and only configure bots inside accounts

Add a second bot via CLI (if the framework supports the --account parameter):

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

Sending Messages to a Specific Account's Users

When using openclaw message send, specify which bot to use with the --account parameter:

# Send with the default bot (no --account = uses "default")
openclaw message send --channel "qqbot" \
  --target "qqbot:c2c:OPENID" \
  --message "hello from default bot"

# Send with bot2
openclaw message send --channel "qqbot" \
  --account bot2 \
  --target "qqbot:c2c:OPENID" \
  --message "hello from bot2"

Target Formats:

| Format | Description | |--------|-------------| | qqbot:c2c:OPENID | Private chat (C2C) | | qqbot:group:GROUP_OPENID | Group chat | | qqbot:channel:CHANNEL_ID | Guild channel |

> ⚠️ Important: Each bot has its own set of user OpenIDs. An OpenID received by Bot A cannot be used to send messages via Bot B — this will result in a 500 error. Always use the matching bot's accountId to send messages to its users.

How It Works

When openclaw gateway starts, all accounts with enabled: true launch their own connections (WebSocket or Webhook depending on transport config)
Each account maintains an independent Token cache (isolated by appId), preventing cross-contamination
Incoming message logs are prefixed with [qqbot:accountId] for easy debugging

---

Webhook Transport Mode

By default, the plugin connects to QQ via WebSocket (outbound connection, no public IP required). You can switch to Webhook mode where QQ platform POSTs events to your HTTP endpoint.

| | WebSocket (default) | Webhook | |---|---|---| | Connection | Plugin connects to QQ gateway | QQ platform POSTs to your server | | Public IP | Not required | Required | | Use case | Development, single instance | Production, horizontal scaling, Serverless | | Session resume | Supported (RESUME) | Stateless, no resume needed | | Signature | Built-in | Ed25519 auto-verified by plugin |

Configuration

{
  "channels": {
    "qqbot": {
      "appId": "111111111",
      "clientSecret": "your-secret",
      "transport": "webhook",
      "webhook": {
        "path": "/qqbot/webhook"
      }
    }
  }
}

| Field | Default | Description | |-------|---------|-------------| | transport | "websocket" | "websocket" or "webhook" | | webhook.path | "/qqbot/webhook" | HTTP path for receiving callbacks |

Platform Setup

1. Go to QQ Open Platform → Bot Settings → Message Receiving 2. Select HTTP Callback 3. Enter your callback URL: https://your-domain.com/qqbot/webhook 4. The platform sends an op:13 validation request — the plugin handles it automatically 5. Once validated, all events will be POSTed to your endpoint

---

Group Chat Configuration

The plugin provides flexible group chat controls, allowing you to customize trigger rules, tool permissions, and AI behavior per group.

@Mention Trigger Mode (`requireMention`)

By default, the bot only responds when @mentioned in a group. You can configure it to autonomously decide when to speak:

| Mode | Config Value | Behavior | |------|-------------|----------| | @ only | true (default) | Only messages that @mention the bot trigger a reply | | Autonomous | false | AI decides on its own whether each message needs a reply — no @ required |

Priority chain (highest to lowest):

groups.{groupOpenid}.requireMention
  > groups."*".requireMention
    > account-level defaultRequireMention
      > default value true

Example:

{
  "channels": {
    "qqbot": {
      // Account-level default for all groups
      "defaultRequireMention": false,

      "accounts": {
        "default": {
          "groups": {
            "*": {
              // Wildcard fallback for all groups
              "requireMention": false
            },
            "GROUP_OPENID": {
              // Per-group override — this group still requires @
              "requireMention": true
            }
          }
        }
      }
    }
  }
}

> Use cases: > > - Work groups → requireMention: true — avoid AI chiming in on every casual message > - Dedicated AI companion groups → requireMention: false — participate naturally like a real person > - Use /bot-group-allways to toggle account-level defaults at runtime

Additional Group Config Fields

Besides requireMention, each group supports these settings:

| Field | Type | Default | Description | |-------|------|---------|-------------| | ignoreOtherMentions | boolean | false | If enabled, messages that @mention others but not the bot are silently dropped (not recorded, no AI trigger) | | toolPolicy | "full" \| "restricted" \| "none" | "restricted" | Tool scope available to AI in this group. full=all tools; restricted=sensitive tools restricted (e.g., command execution, file ops); none=no tool calls allowed | | prompt | string | built-in default | Group-specific system prompt, appended after global systemPrompt | | historyLimit | number | 50 | Cached group history message count |

Full example with multiple groups:

{
  "channels": {
    "qqbot": {
      "defaultRequireMention": false,
      "accounts": {
        "default": {
          "groups": {
            "*": {
              "requireMention": true,
              "toolPolicy": "restricted",
              "ignoreOtherMentions": true
            },
            "WORK_GROUP_OPENID": {
              "requireMention": true,
              "toolPolicy": "none",
              "prompt": "You are a work assistant. Only answer work-related questions."
            },
            "FRIEND_GROUP_OPENID": {
              "requireMention": false,
              "toolPolicy": "full",
              "prompt": "You are a friend in the group. Chat casually and naturally."
            }
          }
        }
      }
    }
  }
}

Group Access Control (`groupPolicy`)

Control which groups are allowed via groupPolicy:

| Policy | Description | |--------|-------------| | "open" (default) | All groups are allowed | | "allowlist" | Only groups in groupAllowFrom are allowed | | "disabled" | Group chats are disabled entirely |

{
  "channels": {
    "qqbot": {
      "groupPolicy": "allowlist",
      "groupAllowFrom": ["ALLOWED_GROUP_OPENID_1", "ALLOWED_GROUP_OPENID_2"]
    }
  }
}

> You can also use /bot-group-allways to toggle account-level defaults at runtime without restarting.

---

STT (Speech-to-Text) — Transcribe Incoming Voice Messages

STT supports two-level configuration with priority fallback:

| Priority | Config Path | Scope | |----------|------------|-------| | 1 (highest) | channels.qqbot.stt | Plugin-specific | | 2 (fallback) | tools.media.audio.models[0] | Framework-level |

{
  "channels": {
    "qqbot": {
      "stt": {
        "provider": "your-provider",
        "model": "your-stt-model"
      }
    }
  }
}

provider — references a key in models.providers to inherit baseUrl and apiKey
Set enabled: false to disable
When configured, incoming voice messages are automatically converted (SILK→WAV) and transcribed

TTS (Text-to-Speech) — Send Voice Messages

| Priority | Config Path | Scope | |----------|------------|-------| | 1 (highest) | channels.qqbot.tts | Plugin-specific | | 2 (fallback) | messages.tts | Framework-level |

{
  "channels": {
    "qqbot": {
      "tts": {
        "provider": "your-provider",
        "model": "your-tts-model",
        "voice": "your-voice"
      }
    }
  }
}

provider — references a key in models.providers to inherit baseUrl and apiKey
voice — voice variant
Set enabled: false to disable (default: true)
When configured, AI can generate and send voice messages

---

📚 Documentation & Links

Upgrade Guide — full upgrade paths and migration notes
Command Reference — OpenClaw CLI commands
Changelog — release notes

🤝 Contributors

Thanks to all the developers who have contributed to this project!

💖 Acknowledgements

Special thanks to @sliverp for outstanding contributions to the project!

Thanks to Tencent Cloud Lighthouse for the deep collaboration. For raising crawfish, choose Tencent Cloud Lighthouse!

⭐ Star History

![Star History Chart](https://www.star-history.com/#tencent-connect/openclaw-qqbot&type=date&legend=top-left)

</div>

openclaw-qqbot

Summary

Install to Claude Code

QQ Bot Channel Plugin for OpenClaw

🚀 Current Version: v1.7.1

✨ Features

📸 Feature Showcase

💬 Quoted Message Context

🎙️ Voice Messages (STT)

📄 File Understanding

🖼️ Image Understanding

🎨 Image Sending

🔊 Voice Sending

⏰ Scheduled Reminder (Proactive Message)

📎 File Sending

🔐 Command Execution Approval

🎬 Video Sending

🛠️ Slash Commands

/bot-ping — Latency Test

/bot-version — Version Info

/bot-help — Command List

/bot-upgrade — One-Click Hot Upgrade

/bot-logs — Log Export

Usage Help

/bot-approve — Approval Configuration

/bot-clear-storage — Clear files generated through QQBot conversations and downloaded resources (stored on the host running OpenClaw)

/bot-group-allways — Group Response Mode Toggle

🚀 Getting Started

Step 1 — Create a QQ Bot on the QQ Open Platform

Step 2 — Install / Upgrade the Plugin

Step 3 — Test

⚙️ Advanced Configuration

Multi-Account Setup (Multi-Bot)

Configuration

Sending Messages to a Specific Account's Users

How It Works

Webhook Transport Mode

Configuration

Platform Setup

Group Chat Configuration

@Mention Trigger Mode (requireMention)

Additional Group Config Fields

Group Access Control (groupPolicy)

STT (Speech-to-Text) — Transcribe Incoming Voice Messages

TTS (Text-to-Speech) — Send Voice Messages

📚 Documentation & Links

🤝 Contributors

💖 Acknowledgements

⭐ Star History

Related plugins

Plugins by category

🚀 Current Version: `v1.7.1`

`/bot-ping` — Latency Test

`/bot-version` — Version Info

`/bot-help` — Command List

`/bot-upgrade` — One-Click Hot Upgrade

`/bot-logs` — Log Export

`/bot-approve` — Approval Configuration

`/bot-clear-storage` — Clear files generated through QQBot conversations and downloaded resources (stored on the host running OpenClaw)

`/bot-group-allways` — Group Response Mode Toggle

@Mention Trigger Mode (`requireMention`)

Group Access Control (`groupPolicy`)