Tools
Qqbot Openclaw
By OpenClaw QQBot Plugin - Rich Media Support
Install
openclaw plugins install @sliverp/qqbot@latestREADME
# QQ
QQ is a widely-used instant messaging platform that provides various communication capabilities such as text, voice, images, and files. It supports collaborative scenarios like group chats and channels, making it suitable for both personal communication and team collaboration.
This integration method connects OpenClaw with a QQ Bot. It utilizes the platform's long-connection event subscription mechanism to receive message and event callbacks, enabling stable and secure message exchange and automation capability integration without exposing a public webhook address.
# Step 1: Install the QQ Bot Plugin
Install via the OpenClaw plugins command.
```
openclaw plugins install @sliverp/qqbot@latest
```
Install from source code:
```
git clone https://github.com/sliverp/qqbot.git && cd qqbot
openclaw plugins install .
```
# Step 2: Create a QQ Bot
## 1. Register on the QQ Open Platform
Go to the official website of the Tencent QQ Open Platform. You cannot log in directly with your personal QQ account by default; you need to register a new QQ Open Platform account.
<img width="2140" height="1004" alt="1" src="https://github.com/user-attachments/assets/d76a780c-5040-43fb-ac41-5808f975ae4b" />
After the initial registration, follow the platform's instructions to set up a super administrator.
<img width="2556" height="1744" alt="2" src="https://github.com/user-attachments/assets/ad0a54d5-6997-4f52-ae8f-bea71aa11c30" />
After successfully scanning the QR code with your mobile QQ, proceed to the next step to fill in the relevant entity information.
Using "Individual" as an example here, follow the prompts to enter your name, ID number, phone number, and verification code, then click continue to proceed to the facial recognition step.
<img width="2544" height="1744" alt="3" src="https://github.com/user-attachments/assets/b85c11f8-5627-4e08-b522-b38c4929bcb6" />
Use your mobile QQ to scan the QR code for facial recognition.
<img width="2542" height="1272" alt="4" src="https://github.com/user-attachments/assets/d0db5539-56ef-4189-930f-595348892bef" />
Once the facial recognition review is approved, you can log in to the QQ Open Platform.
<img width="2356" height="1308" alt="5" src="https://github.com/user-attachments/assets/c1875b27-fefc-4a1c-81ef-863da8b15ec6" />
## 2. Create a QQ Bot
On the QQ Open Platform's QQ Bot page, you can create a bot.
<img width="2334" height="1274" alt="6" src="https://github.com/user-attachments/assets/8389c38d-6662-46d0-ae04-92af374b61ef" />
<img width="2316" height="1258" alt="7" src="https://github.com/user-attachments/assets/15cfe57a-0404-4b02-85fe-42a22cf96d01" />
After the QQ Bot is created, you can select it and click to enter the management page.
<img width="3002" height="1536" alt="8" src="https://github.com/user-attachments/assets/7c0c7c69-29db-457f-974a-4aa52ebd7973" />
On the QQ Bot management page, obtain the current bot's AppID and AppSecret, copy them, and save them to your personal notepad or memo (please ensure data security and do not leak them). They will be needed later in "Step 3: Configuring OpenClaw".
Note: For security reasons, the QQ Bot's AppSecret is not stored in plain text. If you view it for the first time or forget it, you need to regenerate it.
<img width="2970" height="1562" alt="9" src="https://github.com/user-attachments/assets/c7fc3094-2840-4780-a202-47b2c2b74e50" />
<img width="1258" height="594" alt="10" src="https://github.com/user-attachments/assets/4445bede-e7d5-4927-9821-039e7ad8f1f5" />
## 3. Sandbox Configuration
On the QQ Bot's "Development Management" page, in the "Sandbox Configuration" section, set up private chat (select "Configure in Message List").
You can configure this according to your own usage scenario, or you can complete the subsequent steps and then return to this step to operate.
⚠️ Note:
The QQ Bot created here does not need to be published and made available to all QQ users. It can be used for personal (sandbox) debugging and experience.
The QQ Open Platform does not support "Configuration in QQ Groups" for bots; it only supports private chat with the QQ Bot.
<img width="1904" height="801" alt="11" src="https://github.com/user-attachments/assets/f3940a87-aae7-4c89-8f9a-c94fb52cd3ea" />
Note: When selecting "Configure in Message List", you need to first add members, and then use the QQ scan code of that member to add the bot.
<img width="2582" height="484" alt="12" src="https://github.com/user-attachments/assets/5631fe76-2205-4b1e-b463-75fa3a397464" />
Note here that after successfully adding a member, you still need to use QQ scan code to add the bot.
<img width="2286" height="1324" alt="13" src="https://github.com/user-attachments/assets/cbf379be-ef6e-4391-8cb1-67c08aad2d43" />
At this point, after adding the bot to your QQ account, you still cannot have a normal conversation with it. You will receive a prompt saying "The bot has gone to Mars, please try again later." This is because the QQ bot has not yet been connected to the OpenClaw application.
You need to proceed with the following steps to configure the QQ bot's AppID and AppSecret for the OpenClaw application.
<img width="872" height="1052" alt="14" src="https://github.com/user-attachments/assets/0c02aaf6-6cf9-419c-a6ab-36398d73c5ba" />
(Optional) You can also add more members by referring to the previous steps: First, add a new member in the member management page, then add the member in the sandbox configuration page. After that, the new member can add this QQ bot by scanning the QR code with QQ.
<img width="3006" height="1504" alt="15" src="https://github.com/user-attachments/assets/cecef3a6-0596-4da0-8b92-8d67b8f3cdca" />
<img width="2902" height="1394" alt="16" src="https://github.com/user-attachments/assets/eb98ffce-490f-402c-8b0c-af7ede1b1303" />
<img width="1306" height="672" alt="17" src="https://github.com/user-attachments/assets/799056e3-82a6-44bc-9e3d-9c840faafa41" />
# Step 3: Configure OpenClaw
## Method 1: Configure via Wizard (Recommended)
Add the qqbot channel and input the AppID and AppSecret obtained in Step 2.
```
openclaw channels add --channel qqbot --token "AppID:AppSecret"
```
## Method 2: Configure via Configuration File
Edit ~/.openclaw/openclaw.json:
``` json
{
"channels": {
"qqbot": {
"enabled": true,
"appId": "Your AppID",
"clientSecret": "Your AppSecret"
}
}
}
```
# Step 4: Start and Test
## 1. Start the gateway
```
openclaw gateway
```
## 2. Chat with the QQbot in QQ
<img width="990" height="984" alt="18" src="https://github.com/user-attachments/assets/b2776c8b-de72-4e37-b34d-e8287ce45de1" />
# Features
## Rich Media Support
This QQ Bot plugin supports receiving and sending various types of media messages, including images, voice, video, and other attachments.
### Receiving Media
When users send media messages to the bot, the plugin will:
- **Images**: Automatically download and provide local file path for AI processing
- Supported formats: JPG, PNG, GIF, WebP, BMP
- **Voice**: Automatically convert SILK/AMR format to WAV for better compatibility
- Supported formats: SILK, AMR, MP3, WAV, OGG (auto-converted to WAV)
- **Video**: Download and provide local file path for AI processing
- Supported formats: MP4, MOV, AVI, MKV, FLV, WMV
- **Other Attachments**: Download and provide file information
### Sending Media
The bot can send media messages using special tags in the response:
#### Send Images
Use `<qqimg>` tag to send images:
```
<qqimg>/path/to/image.jpg</qqimg>
<qqimg>https://example.com/image.png</qqimg>
```
- Local files: Must use absolute path
- Network images: Must be valid HTTP/HTTPS URL
- Supported formats: PNG, JPG, JPEG, GIF, WebP
#### Send Video
Use `<qqvideo>` tag to send videos:
```
<qqvideo>/path/to/video.mp4</qqvideo>
<qqvideo>https://example.com/video.mp4</qqvideo>
```
- Local files: Must use absolute path
- Network videos: Must be valid HTTP/HTTPS URL
- Supported formats: MP4, MOV, AVI
#### Send Voice
Use `<qqvoice>` tag to send voice messages:
```
<qqvoice>/path/to/audio.mp3</qqvoice>
<qqvoice>/path/to/recording.wav</qqvoice>
<qqvoice>https://example.com/audio.mp3</qqvoice>
```
- Local files: Must use absolute path
- Network audio: Must be valid HTTP/HTTPS URL
- Supported formats: MP3, WAV, OGG, FLAC, AAC, M4A, SILK
- **Auto-conversion**: Non-SILK formats are automatically converted to SILK format required by QQ
### Important Notes
1. **File Paths**: Always use absolute paths for local files
2. **Network URLs**: Must be valid and accessible HTTP/HTTPS URLs
3. **Format Conversion**: Voice messages are automatically converted to SILK format
4. **File Size**: Large files may take longer to process
5. **Passive Reply**: All media sending must be done as passive replies (within 5 minutes of receiving a message)
# Upgrade
## Using openclaw/npm(Recommendation)
> only for installed by`openclaw plugins install`
```
openclaw plugins upgrade @sliverp/qqbot@latest
```
## Using npx
```
npx -y @sliverp/qqbot@latest upgrade
```
## Using resource code
```
git clone https://github.com/sliverp/qqbot.git && cd qqbot
# run upgrade script
bash ./scripts/upgrade.sh
# re-install
clawdbot plugins install .
# re-config
clawdbot channels add --channel qqbot --token "AppID:AppSecret"
# restart gateway
clawdbot gateway restart
```
# Other Language README
[简体中文](README.zh.md)
tools
Comments
Sign in to leave a comment