https://github.com/tencent-connect/openclaw-qqbot

QQ Bot Channel Plugin for OpenClaw
https://github.com/tencent-connect/openclaw-qqbot
bot-plugin openclaw openclaw-qqbot qqbot
Last synced: 3 months ago
JSON representation
QQ Bot Channel Plugin for OpenClaw
Host: GitHub
URL: https://github.com/tencent-connect/openclaw-qqbot
Owner: tencent-connect
License: mit
Created: 2026-03-09T13:12:58.000Z (3 months ago)
Default Branch: main
Last Pushed: 2026-03-12T05:39:05.000Z (3 months ago)
Last Synced: 2026-03-12T11:31:56.648Z (3 months ago)
Topics: bot-plugin, openclaw, openclaw-qqbot, qqbot
Language: TypeScript
Homepage:
Size: 10.9 MB
Stars: 105
Watchers: 10
Forks: 29
Open Issues: 7
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project

awesome-openclaw - tencent-connect/openclaw-qqbot - connect/openclaw-qqbot?style=social) - QQ bot channel integration for the OpenClaw ecosystem. (🔌 Plugins & Channel Integrations)
awesome-claw-cn - openclaw-qqbot
README

          




# 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.5.7`

[![License](https://img.shields.io/badge/license-MIT-green)](./LICENSE)

[![QQ Bot](https://img.shields.io/badge/QQ_Bot-API_v2-red)](https://bot.q.qq.com/wiki/)

[![Platform](https://img.shields.io/badge/platform-OpenClaw-orange)](https://github.com/tencent-connect/openclaw-qqbot)

[![Node.js](https://img.shields.io/badge/Node.js->=18-339933?logo=node.js&logoColor=white)](https://nodejs.org/)

[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)




**[简体中文](README.zh.md) | English**

Scan to join the QQ group chat





---

## ✨ Features

| Feature | Description |

|---------|-------------|

| 🔒 **Multi-Scene** | C2C private chat, group @messages, channel messages, channel DMs |

| 🖼️ **Rich Media** | Send & receive images, voice, video, and files |

| 🎙️ **Voice (STT/TTS)** | Speech-to-text transcription & text-to-speech replies |

| ⏰ **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 |

| 🔄 **Hot Reload** | Install via npm with seamless hot updates |

| 📝 **Markdown** | Full Markdown formatting support |

| 🛠️ **Commands** | Native OpenClaw command integration |

| 💬 **Quoted Context** | Resolve QQ `REFIDX_*` quoted messages and inject quote body into AI context |

---

## 📸 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 (REFIDX)

QQ quote events carry index keys (e.g. `REFIDX_xxx`) instead of full original message body. The plugin now resolves these indices from a local persistent store and injects quote context into AI input, so replies better understand “which message is being quoted”.

- Inbound and outbound messages with `ref_idx` are automatically indexed.

- Store path: `~/.openclaw/qqbot/data/ref-index.jsonl` (survives gateway restart).

- Quote body may include text + media summary (image/voice/video/file).



### 🎙️ 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 sends images via `path`. 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 sends voice via `path`. 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 sends files via `path`. Any format, up to 20MB.



### 🎬 Video Sending

> **You**: Send me a demo video

>

> **QQBot**: *(sends a video)*

AI sends videos via `path`. Supports local files and URLs. Large files (>5MB) auto-show upload progress.



### Rich Media Tag Reference

| Tag | Direction | Notes |

|-----|-----------|-------|

| `path` | Send | jpg/png/gif/webp/bmp, local path or URL |

| `path` | Send | mp3/wav/silk/ogg, no ffmpeg required |

| `path` | Send | Any format, up to 20MB |

| `path` | Send | Local path or URL |

| Voice / File / Image | Receive | Auto-transcribe (STT), auto-download, or vision analysis |

> **Under the hood:** 30+ tag variant auto-correction, upload dedup caching, ordered queue delivery, and multi-layer audio format fallback.

---

## 🚀 Getting Started

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

1. Go to the [QQ Open Platform](https://q.qq.com/) 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](https://cloud.tencent.com/developer/article/2626045).

### Step 2 — Install / Upgrade the Plugin

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

```bash

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:

> ```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)**

```bash

# 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  --secret ` | Configure channel (required for first install, or to change credentials) |

| `--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**

```bash

# 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`:

```json

{

  "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):

```bash

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:

```bash

# 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 WebSocket connections

- Each account maintains an independent Token cache (isolated by `appId`), preventing cross-contamination

- Incoming message logs are prefixed with `[qqbot:accountId]` for easy debugging

---

### Voice Configuration (STT / TTS)

#### 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 |

```json

{

  "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 |

```json

{

  "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 use `` tags to generate and send voice messages

---

## 📚 Documentation & Links

- [Upgrade Guide](docs/UPGRADE_GUIDE.md) — full upgrade paths and migration notes

- [Command Reference](docs/commands.md) — OpenClaw CLI commands

- [Changelog](CHANGELOG.md) — release notes

## ⭐ Star History



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

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/tencent-connect/openclaw-qqbot

Awesome Lists containing this project

README
