DOCSEARCHbyAlgolia
Submit Docs

OpenClaw QQ Bot Channel Plugin

repository·main·Indexed 23 days ago

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

A channel plugin for the OpenClaw framework that connects AI assistants to QQ. It supports private and group chats, rich media (text, images, voice, video, and files), and dual transport modes via WebSocket or Webhook. Key features include built-in slash commands for bot management, command execution approval policies, multi-account support, and integrated STT/TTS capabilities.

Tokens
33.6K
Snippets
72
Records
174
Agent score
80%

What's inside @tencent-connect/openclaw-qqbot

  1. Overview of QQ Bot OpenClaw Channel Plugin

    main

    The @tencent-connect/openclaw-qqbot plugin acts as a message channel between QQ and the OpenClaw framework. It enables AI assistants to interact via QQ through private chats (C2C) and group chats.

    Key Capabilities:

    • Multi-mode Group Chat: Supports both @mention trigger mode and autonomous speaking mode.
    • Rich Media Support: Handles images, voice (STT/TTS), video, and files.
    • Dual Transmission Modes: Supports WebSocket (default) or Webhook (HTTP callback).
    • Advanced Features: Quoted message context parsing, scheduled reminders (proactive messages), command execution approval via buttons, and one-click hot updates.

    Important Note: This plugin is strictly a message channel. Capabilities like image understanding, voice transcription (STT), or AI image generation depend on your configured AI models and the skills installed in OpenClaw, not the plugin itself.

  2. Overview of QQ Bot Channel Plugin for OpenClaw

    main

    The @tencent-connect/openclaw-qqbot plugin acts as a message channel that connects an OpenClaw AI assistant to QQ. It enables private (C2C) and group chats with support for rich media, including text, images, voice, video, and files.

    Key Capabilities:

    • Multi-Scene Support: Handles both private chats and group chats (with configurable @mention or autonomous modes).
    • Rich Media Handling: Supports sending and receiving images, voice (with STT/TTS), video, and files (up to 100MB).
    • Dual Transport: Supports both WebSocket (default) and Webhook (HTTP callback) modes.
    • Command Integration: Integrates native OpenClaw commands and provides built-in slash commands for management.
    • Safety & Control: Includes command execution approval via interactive buttons and per-group trigger rules.

  3. General usage of the QQ Bot Channel API

    main

    The QQ Bot Channel API is accessed via the qqbot_channel_api tool, which automatically handles authentication.

    Base URL

    https://api.sgroup.qq.com

    Authentication

    The tool automatically injects the following headers, so you do not need to set them manually:

    • Authorization: QQBot {access_token}
    • Content-Type: application/json

    Error Format

    Errors are returned in the following JSON format:

    {
  "message": "error description",
  "code": error_code
}

  4. Configure and manage multiple bot accounts

    main

    Since version 1.5.4, the plugin supports multi-account concurrency by isolating Token caches per appId. This prevents 11255 invalid request errors when running multiple bots simultaneously.

    Key behaviors for multi-account setups:

    • Token Isolation: Tokens are managed in a Map keyed by appId. Methods like clearTokenCache() and stopBackgroundTokenRefresh() now accept an appId parameter to target a specific account.
    • Message Sending: When using the openclaw message send command, you must specify the --account flag. If omitted, the system defaults to the "default" account ID, which will cause 500 errors when attempting to message users associated with other bot instances.

  5. Use unified media tags for rich media messages

    main

    As of version 1.6.0, individual media tags have been unified. Instead of using specific tags for images, voice, files, or videos, use the <qqmedia> tag. The system will automatically identify the correct media type based on the file extension.

    Deprecated tags (use <qqmedia> instead):

    • <qqimg>
    • <qqvoice>
    • <qqfile>
    • <qqvideo>

  7. Understand quoted message context (REFIDX)

    main

    Starting in version 1.5.7, the bot supports advanced message referencing using QQ's REFIDX_* mechanism. This allows the agent to understand the context of a quoted message.

    How it works:

    1. Parsing: The bot parses the reference index from incoming events.
    2. Caching: It caches summaries of both incoming and outgoing messages.
    3. Injection: The quoted content (including structured summaries for images, voice, video, or files) is injected into the agent's context.
    4. Persistence: Reference indices are stored in ~/.openclaw/qqbot/data/ref-index.jsonl using a memory cache + JSONL append-only strategy. This data has a 7-day TTL and supports compaction.

  8. Handle voice input and ASR fallback

    main

    Version 1.5.6 improved voice processing. If a dedicated STT (Speech-to-Text) service is not configured or if transcription fails, the bot provides a fallback mechanism using the asr_refer_text strategy, which utilizes the built-in ASR text provided by the QQ platform.

    Metadata passed to Agent: When voice is used, the following metadata is injected into the agent context:

    • QQVoiceAsrReferTexts
    • QQVoiceTranscriptSources
    • QQVoiceInputStrategy

  9. Understand the QQ Channel (Guild/Channel) hierarchy

    main

    QQ Channels follow a hierarchical structure similar to Discord:

    LevelNameEnglishAPI PathID Format
    Top Level频道Guild/guilds/{guild_id}Pure numeric (e.g., 123456)
    Secondary子频道Channel/channels/{channel_id}Pure numeric (e.g., 789012)

    Key Characteristics:

    • A Guild contains multiple Channels (text, voice, forum, live, etc.).
    • Members are managed via /guilds/{guild_id}/members.
    • All IDs are pure numeric strings.

  10. Upgrade the plugin using npm-upgrade.sh

    main

    Version 1.5.5 introduced the npm-upgrade.sh script, which automates the installation and upgrading of the plugin via npm. This script handles channel configuration backups, cleans up old plugin versions (such as qqbot, @sliverp/qqbot, openclaw-qqbot, and @tencent-connect/openclaw-qqbot), and restarts the gateway.

    Usage: Run the script with the following options:

    • --tag: Specify the npm tag (defaults to @alpha).
    • --version: Specify a specific version to install.

    Note: The script is compatible with multiple CLIs (openclaw, clawdbot, or moltbot) by automatically detecting the configuration path.

  11. Install or upgrade the QQ Bot plugin via local scripts

    main

    If you have cloned the repository locally, you can use the provided scripts.

    Using npm script:

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

    Using source script:

    bash ./scripts/upgrade-via-source.sh --appid YOUR_APPID --secret YOUR_SECRET
    # 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

  12. Use the cron tool as a fallback for QQ Bot reminders

    main

    If the qqbot_remind tool is unavailable, you can use the cron tool directly. This requires strict adherence to specific field values to ensure messages are actually delivered to the user via the QQ channel.

    Mandatory Fields

    • payload.kind: Must be "agentTurn". Using "systemEvent" will result in the message being injected into the AI session only, and the user will not receive a QQ message.
    • delivery.mode: Must be "announce".
    • delivery.channel: Must be "qqbot".
    • delivery.to: The user's openid (retrieved from the To field).
    • sessionTarget: Must be "isolated" to avoid session pollution.
    • delivery.accountId: Must be the current session's account ID to ensure the correct bot account sends the message.

    One-time Reminders (schedule.kind = "at")

    • schedule.atMs: Must be an absolute millisecond timestamp (e.g., current_timestamp_ms + delay_ms). Relative strings like "5m" are not supported here.
    • deleteAfterRun: Set to true for one-time tasks.

    Periodic Reminders (schedule.kind = "cron")

    • schedule.expr: A valid cron expression.
    • schedule.tz: Must include "Asia/Shanghai".
    • deleteAfterRun: Do not include this field for periodic tasks.
    • Group Chat Target: For group chats, the delivery.to format is "qqbot:group:{group_openid}".
    // Example: One-time reminder (schedule.kind = "at")
{
  "action": "add",
  "job": {
    "name": "Task Name",
    "schedule": { "kind": "at", "atMs": 1770733800000 },
    "sessionTarget": "isolated",
    "wakeMode": "now",
    "deleteAfterRun": true,
    "payload": {
      "kind": "agentTurn",
      "message": "Reminder content here..."
    },
    "delivery": {
      "mode": "announce",
      "channel": "qqbot",
      "to": "{openid}",
      "accountId": "{accountId}"
    }
  }
}