openclaw/extensions/qqbot

QQ Bot Channel Plugin for Moltbot

A Moltbot channel plugin for the official QQ Robot API, supporting C2C private chats, Group @mentions, and Guild messages.

Features

• Multi-Scenario Support: C2C one-on-one chats, QQ Group @mentions, Guild public messages, and Guild direct messages (DMs).
• Auto-Reconnection: Automatically reconnects after WebSocket disconnection and supports Session Resume.
• Message Deduplication: Automatically manages msg_seq and supports multiple replies to the same message.
• System Prompts: Configurable custom system prompts injected into AI requests.
• Error Notifications: Automatically notifies the user to check the configuration if the AI fails to respond.

Usage Example

Installation

Run the following command in the plugin directory:

clawdbot plugins install .

Configuration

1. Obtain QQ Robot Credentials

1. Visit the QQ Open Platform.
2. Create a Robot Application.
3. Get the AppID and AppSecret (ClientSecret).
4. The Token format is AppID:AppSecret, for example: 102146862:Xjv7JVhu7KXkxANbp3HVjxCRgvAPeuAQ.

2. Add Configuration

Method 1: Interactive Configuration

clawdbot channels add
# Select 'qqbot' and enter the Token as prompted

Method 2: Command Line Configuration

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

Example:

clawdbot channels add --channel qqbot --token "102146862:xxxxxxxx"

3. Manual Configuration (Optional)

You can also directly edit ~/.clawdbot/clawdbot.json:

{
  "channels": {
    "qqbot": {
      "enabled": true,
      "appId": "YourAppID",
      "clientSecret": "YourAppSecret",
      "systemPrompt": "You are a friendly assistant"
    }
  }
}

Configuration Options

Option	Type	Required	Description
appId	string	Yes	QQ Robot AppID
clientSecret	string	Yes*	AppSecret. Choose either this or clientSecretFile.
clientSecretFile	string	Yes*	Path to the AppSecret file.
enabled	boolean	No	Whether to enable the plugin. Default is true.
name	string	No	Account display name.
systemPrompt	string	No	Custom system prompt.

Supported Message Types

Event Type	Description	Intent
C2C_MESSAGE_CREATE	C2C One-on-One Message	1 << 25
GROUP_AT_MESSAGE_CREATE	Group Chat @Robot Message	1 << 25
AT_MESSAGE_CREATE	Guild @Robot Message	1 << 30
DIRECT_MESSAGE_CREATE	Guild Direct Message (DM)	1 << 12

Usage

Startup

Start in background:

clawdbot gateway restart

Start in foreground (convenient for viewing logs):

clawdbot gateway --port 18789 --verbose

CLI Configuration Wizard

clawdbot onboard
# Select QQ Bot for interactive configuration

Important Notes

1. Reply Limitations: The official QQ API limits replies to a maximum of 5 per message, with a 60-minute timeout.
2. URL Restrictions: The QQ platform does not allow URLs in messages; the plugin has built-in prompts to restrict this.
3. Group Messages: The robot must be @mentioned in the group to trigger a reply.
4. Sandbox Mode: Newly created robots are in sandbox mode by default and require test users to be added.

Upgrading

If you need to upgrade the plugin, run the upgrade script to clean up the old version first:

# Run the upgrade script (cleans up old version and config)
./scripts/upgrade.sh

# Reinstall the plugin
clawdbot plugins install .

# Reconfigure
clawdbot channels add --channel qqbot --token "AppID:AppSecret"

# Restart the gateway
clawdbot gateway restart

The upgrade script will automatically:

• Delete the ~/.clawdbot/extensions/qqbot directory.
• Clean up qqbot related configurations in clawdbot.json.

Development

# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run dev

File Structure

qqbot/
├── index.ts          # Entry file
├── src/
│   ├── api.ts        # QQ Bot API wrapper
│   ├── channel.ts    # Channel Plugin definition
│   ├── config.ts     # Configuration parsing
│   ├── gateway.ts    # WebSocket gateway
│   ├── onboarding.ts # CLI configuration wizard
│   ├── outbound.ts   # Outbound message handling
│   ├── runtime.ts    # Runtime state
│   └── types.ts      # Type definitions
├── scripts/
│   └── upgrade.sh    # Upgrade script
├── package.json
└── tsconfig.json

Related Links

• QQ Robot Official Documentation
• QQ Open Platform
• API v2 Documentation

License

MIT