@sliverp/qqbot

QQ Bot Channel Plugin for Openclaw(Clawdbot/Moltbot)

QQ 开放平台 Bot API 的 Openclaw 渠道插件，支持 C2C 私聊、群聊 @消息、频道消息。

The Openclaw channel plugin of the Bot API of the QQ Open Platform supports C2C private chats, group chat @ messages, and channel messages.

扫描二维码加入群聊，一起交流

📸 使用示例

✨ 功能特性

• 🔒 多场景支持 - C2C 私聊、群聊 @消息、频道消息、频道私信

• 🖼️ 富媒体消息 - 支持图片收发、文件发送

• ⏰ 定时推送 - 支持定时任务到时后主动推送

• 🔗 URL 无限制 - 私聊可直接发送 URL

• ⌨️ 输入状态 - Bot 正在输入中状态提示

• 🔄 热更新 - 支持 npm 方式安装和热更新

• 📝 Markdown - 支持 Markdown 格式

• 📝 Command - 支持Openclaw原生命令

⭐ Star History

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.

After the initial registration, follow the platform's instructions to set up a super administrator.

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.

Use your mobile QQ to scan the QR code for facial recognition.

Once the facial recognition review is approved, you can log in to the QQ Open Platform.

2. Create a QQ Bot

On the QQ Open Platform's QQ Bot page, you can create a bot.

After the QQ Bot is created, you can select it and click to enter the management page.

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.

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.

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. Note here that after successfully adding a member, you still need to use QQ scan code to add the bot.

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.

(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.

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:

{
  "channels": {
    "qqbot": {
      "enabled": true,
      "appId": "Your AppID",
      "clientSecret": "Your AppSecret"
    }
  }
}

Voice Capabilities (Optional)

STT (Speech-to-Text) — Transcribe incoming voice messages

STT reuses your existing model provider configuration. Add an audio model entry in tools.media.audio.models:

{
  "tools": {
    "media": {
      "audio": {
        "models": [
          {
            "provider": "openai",
            "model": "whisper-1"
          }
        ]
      }
    }
  },
  "models": {
    "providers": {
      "openai": {
        "baseUrl": "https://api.openai.com/v1",
        "apiKey": "sk-xxx"
      }
    }
  }
}

• provider — references a key in models.providers to inherit baseUrl and apiKey (default: "openai")
• model — STT model name (default: "whisper-1")
• You can also set baseUrl / apiKey directly in the audio model entry to override the provider defaults
• When configured, incoming voice messages are automatically converted (SILK→WAV) and transcribed

TTS (Text-to-Speech) — Send voice messages

Configure TTS under channels.qqbot.tts:

{
  "channels": {
    "qqbot": {
      "tts": {
        "provider": "openai",
        "model": "tts-1",
        "voice": "alloy"
      }
    }
  }
}

• provider — references a key in models.providers to inherit baseUrl and apiKey (default: "openai")
• model — TTS model name (default: "tts-1")
• voice — voice variant (default: "alloy")
• baseUrl / apiKey — optional overrides for the provider defaults
• enabled — set to false to disable (default: true)
• When configured, the AI can use <qqvoice> tags to generate and send voice messages via OpenAI-compatible TTS API

Step 4: Start and Test

1. Start the gateway

openclaw gateway

2. Chat with the QQbot in QQ

Upgrade

Using openclaw/npm(Recommendation)

only for installed byopenclaw 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

简体中文