---

---

• 🔒 多场景支持 - C2C 私聊、群聊 @消息、频道消息、频道私信
• 🖼️ 富媒体消息 - 支持图片、语音、视频、文件收发
• ⏰ 定时推送 - 支持定时任务到时后主动推送
• 🔗 URL 无限制 - 私聊可直接发送 URL
• ⌨️ 输入状态 - Bot 正在输入中状态提示
• 🔄 热更新 - 支持 npm 方式安装和热更新
• 📝 Markdown - 支持 Markdown 格式
• 📝 Command - 支持Openclaw原生命令

---

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.

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 .

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.

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.

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.

Add the qqbot channel and input the AppID and AppSecret obtained in Step 2.

openclaw channels add --channel qqbot --token "AppID:AppSecret"

Edit ~/.openclaw/openclaw.json:

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

STT supports any provider that implements a compatible transcription API. Add an audio model entry in tools.media.audio.models:

{
  "tools": {
    "media": {
      "audio": {
        "models": [
          {
            "provider": "your-provider",
            "model": "your-stt-model"
          }
        ]
      }
    }
  },
  "models": {
    "providers": {
      "your-provider": {
        "baseUrl": "https://your-provider-api-base-url",
        "apiKey": "your-api-key"
      }
    }
  }
}

• provider — references a key in models.providers to inherit baseUrl and apiKey
• model — STT model name
• 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

Configure TTS under channels.qqbot.tts:

{
  "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
• model — TTS model name
• voice — voice variant
• 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 compatible TTS API

openclaw gateway

only for installed byopenclaw plugins install

openclaw plugins upgrade @sliverp/qqbot@latest

npx -y @sliverp/qqbot@latest upgrade

bash ./upgrade-and-run.sh

When no --appid / --secret is provided, the script reads the existing configuration from ~/.openclaw/openclaw.json (or ~/.clawdbot/clawdbot.json) automatically — no need to re-enter credentials on every upgrade.

To override or set credentials for the first time:

bash ./upgrade-and-run.sh --appid YOUR_APPID --secret YOUR_SECRET

Full options:

Option	Description
--appid <id>	QQ Bot AppID
--secret <secret>	QQ Bot AppSecret
--markdown <yes|no>	Enable Markdown message format (default: no)
-h, --help	Show help

Environment variables QQBOT_APPID, QQBOT_SECRET, QQBOT_TOKEN (AppID:Secret) are also supported.

Pull the latest source code from GitHub, install dependencies and restart:

bash ./pull-latest.sh

If the plugin directory already contains a .git repo, it does an incremental git pull; otherwise it clones from scratch. Existing channel configuration is automatically backed up and restored.

bash ./pull-latest.sh --branch main            # specify branch (default: main)
bash ./pull-latest.sh --force                   # skip prompts, force update
bash ./pull-latest.sh --repo <git-url>          # use a different repo

git clone https://github.com/sliverp/qqbot.git && cd qqbot 

# run upgrade script
bash ./scripts/upgrade.sh

# re-install
openclaw plugins install .

# re-config
openclaw channels add --channel qqbot --token "AppID:AppSecret"

# restart gateway
openclaw gateway restart

简体中文