What You’ll Build Today
You will create a fully functional QQ bot that leverages OpenClaw’s autonomous AI agent capabilities through Tencent’s official one-click integration. This bot connects to QQ groups and direct messages, processes natural language queries using OpenClaw’s reasoning engine, and executes tasks like web scraping, file management, and API calls directly within the QQ ecosystem. By the end of this guide, you’ll have a production-ready bot running on Tencent’s infrastructure, bound to your QQ Open Platform account, capable of handling concurrent conversations across multiple groups with sub-second latency. The entire setup takes approximately 15 minutes from registration to first message, utilizing Tencent’s native support for OpenClaw rather than unofficial third-party adapters that frequently break during protocol updates. This integration allows up to 5 bots per account with sub-minute binding times, giving you scalable AI agent deployment within China’s largest messaging platform. Your bot will handle image recognition, long-context conversations, and tool execution while complying with Tencent’s rate limits and content policies. The OpenClaw framework, combined with Tencent’s robust infrastructure, provides a powerful platform for developing intelligent and interactive QQ bots for various applications, from customer service to entertainment.
Prerequisites and System Requirements
Before touching the QQ Open Platform, verify your setup meets baseline requirements. You need a Tencent QQ account in good standing, verified with a mainland China phone number (+86) or international passport for foreign developers. The OpenClaw integration requires OpenClaw version 0.25.0 or higher installed locally or on Tencent Cloud. If self-hosting, ensure Python 3.10+, Node.js 18+, and 4GB RAM minimum with 10GB free disk space for model caching. For cloud deployment, Tencent Cloud Lighthouse instances with 2 cores and 4GB RAM suffice for handling 100 concurrent group chats. You’ll also need the QQ mobile app installed for administrator verification during bot creation and real-time testing. Git is required for cloning the OpenClaw QQ adapter from the official repository. Finally, prepare a dedicated directory for bot configuration files at /opt/openclaw-qq/ and ensure firewall rules allow HTTPS traffic on port 443 for webhook callbacks from Tencent’s servers. No prior QQ bot development experience is necessary, but familiarity with OpenClaw’s config.yaml structure and JSON webhooks accelerates the process significantly. It’s also beneficial to have a basic understanding of API keys and environment variables for secure credential management.
How Tencent’s OpenClaw Integration Works
Tencent’s integration isn’t a fork or clone of OpenClaw. It’s official platform support that exposes QQ’s Bot API to OpenClaw through a certified adapter maintained by both communities. When you bind your bot, Tencent generates a unique AppID and AppSecret pair that OpenClaw uses to authenticate with QQ’s messaging gateway using OAuth 2.0 with PKCE. The architecture uses webhook-based event pushing rather than inefficient polling: QQ servers send JSON payloads to your OpenClaw instance when messages arrive, and your agent responds via POST requests to Tencent’s API endpoints at https://api.sgroupqq.com/. This differs from legacy polling architectures by reducing latency to under 200ms for most operations. The one-click creation process provisions a bot sandbox with pre-configured rate limits: 20 messages per second for group chats, 5 messages per second for direct messages, and 50 file uploads per hour. Your OpenClaw instance maintains persistent WebSocket connections to Tencent’s gateway, handling reconnection logic automatically during network interruptions without dropping conversation context. This robust integration ensures high availability and responsiveness for your QQ bots.
Setting Up Your QQ Open Platform Developer Account
Navigate to bot.q.qq.com and sign in with your QQ credentials, preferably using the mobile app’s QR code scan for security. Complete real-name verification if prompted—this requires your Chinese ID card for mainland users or passport for international developers, plus facial recognition via the QQ app. Once inside the console, select “Create Bot” from the dashboard’s blue button. Choose “OpenClaw Integration” from the framework dropdown menu; this flags your account for the one-click binding feature and unlocks specialized documentation. Fill in basic bot information: name (max 20 characters), description (max 500 characters), and avatar (128x128 PNG under 500KB). Select “Personal” or “Enterprise” as the entity type. Personal accounts allow immediate deployment but limit concurrent group memberships to 500 and daily messages to 10,000. Enterprise accounts require business license verification but unlock unlimited groups, priority API quotas, and dedicated support channels. Submit the application; approval typically takes 2 minutes for personal accounts, instantly activating your bot credentials and showing the AppID. This initial setup is crucial for accessing the necessary API resources.
Creating a QQ Bot via the One-Click Interface
With your developer account active, locate the “OpenClaw Quick Deploy” card in the console’s main dashboard. Click “Create Bot Instance” to trigger the one-click workflow that automates credential generation. The system auto-generates your Bot AppID (18-digit numeric string) and AppSecret (32-character alphanumeric with mixed case). Copy these immediately into a password manager—they display only once and cannot be retrieved later, only regenerated. The interface presents a configuration URL: https://open.qq.com/bind?appid=YOUR_ID&framework=openclaw×tamp=UNIX_TIME. This link encapsulates your bot’s authentication parameters and expires in 24 hours. Do not share this URL in public repositories or chat logs. The console also provides a QR code for mobile binding that persists for 7 days. At this stage, select your bot’s visibility: “Public” allows any QQ user to add it via search, while “Private” restricts invites to specific QQ numbers you whitelist in the console. Choose message encryption: AES-256-CBC is mandatory for group chats, optional but recommended for DMs. These settings determine how users interact with your bot and the security level of communications.
Configuring Bot Permissions and Message Scopes
Your bot needs explicit permissions to function beyond basic presence. In the QQ Open Platform console, navigate to “Feature Management” for your specific bot. Enable “Group Message Reception” to allow your OpenClaw agent to read group chats and parse @mentions. Enable “Direct Message Reception” for private conversations and friend requests. Check “Message Sending” to permit text and image replies. For OpenClaw’s advanced features, enable “File Upload” and “Image Recognition” if your agent handles media analysis or document processing. Each permission requires corresponding scope declaration in your OpenClaw config file under qq.scopes. The critical scope is message.group for group interactions and message.direct for private chats. Avoid enabling “Administrator” scopes like group.manage unless your agent needs to mute users or manage groups—this triggers additional safety review and delays deployment by 24 hours. Save your selections; changes propagate to QQ’s gateway within 30 seconds, though you may need to restart your OpenClaw instance to recognize new permissions. Carefully consider the minimum necessary permissions to enhance security and streamline the approval process.
Deploying OpenClaw on Tencent Cloud Servers
While local hosting works for development, Tencent Cloud offers optimized latency and pre-configured security. From the QQ Open Platform console, click “Deploy on Tencent Cloud” to provision a Lighthouse instance pre-configured with OpenClaw 0.25.0. Select “OpenClaw Standard Image” from the marketplace—this Ubuntu 22.04 image includes Python 3.11, Node.js 20, and the QQ adapter pre-installed. Choose Singapore or Hong Kong regions for best QQ API connectivity with sub-50ms latency. Configure with 2 CPU cores, 4GB RAM, and 50GB SSD for approximately 80 RMB monthly. The instance launches with OpenClaw systemd service enabled and auto-start configured. SSH in using the provided credentials: ssh ubuntu@YOUR_IP. Run claw doctor to verify the installation and check QQ adapter status. The cloud deployment automatically configures security groups to allow QQ webhook IPs: 203.205.219.0/24 and 203.205.220.0/24 on port 443. This bypasses manual firewall configuration and reduces setup time by approximately 10 minutes compared to self-hosting. Leveraging Tencent Cloud streamlines deployment and ensures optimal performance for your QQ bot.
Installing the QQ Bot Adapter Locally
For self-hosted setups or local development, install the official adapter manually from GitHub. Clone the repository:
git clone https://github.com/openclaw/adapter-qq.git /tmp/adapter-qqNavigate into the directory and install Python dependencies:
pip install -r requirements.txtThis command installs cryptography, aiohttp, and qq-botpy. Copy the adapter files to your OpenClaw installation’s adapters directory:
cp -r /tmp/adapter-qq ~/.openclaw/adapters/qq-official/Verify installation by running claw list-adapters—you should see qq-official marked as [installed] in the output. Create a configuration file at ~/.openclaw/adapters/qq/config.yaml from the template:
cp ~/.openClaw/adapters/qq/config.example.yaml ~/.openclaw/adapters/qq/config.yamlThis file requires your AppID, AppSecret, and webhook URL. The adapter handles message parsing, converting QQ’s JSON protocol into OpenClaw’s internal message format, and vice versa. It manages heartbeats every 30 seconds to keep the connection alive and automatically retries failed messages with exponential backoff. This local setup provides flexibility for custom environments and advanced debugging.
Binding Your Bot Using the Official Integration Link
Return to the QQ Open Platform console and copy the binding URL provided during bot creation, which looks like https://open.qq.com/bind?appid=123456789012345678. On your server or local machine with OpenClaw installed, execute:
claw bind-qq --url "https://open.qq.com/bind?appid=123456789012345678&framework=openclaw"This command extracts the AppID, AppSecret, and endpoint configurations, then establishes the authentication handshake with Tencent’s servers. Alternatively, use the QR code method for headless servers: run claw bind-qq --qr and scan the generated ASCII-art or image-based code with your QQ mobile app’s scanner. The binding process takes 30-60 seconds during which the CLI shows a progress spinner. You’ll see confirmation: “Bot 123456789012345678 successfully bound to OpenClaw instance at [timestamp]”. This creates a persistent session file at ~/.openclaw/sessions/qq_session.json containing your access tokens and refresh tokens. The tokens refresh automatically every 24 hours via a background cron job. Verify binding status anytime with claw status --adapter qq which shows connection state and last ping time. Proper binding is essential for your OpenClaw instance to communicate with the QQ platform.
Configuring Webhooks for Real-Time Messaging
QQ requires HTTPS endpoints for message delivery and rejects HTTP for security. In your OpenClaw config.yaml, set the webhook receiver:
webhook:
host: "0.0.0.0"
port: 443
ssl_cert: "/etc/letsencrypt/live/yourdomain.com/fullchain.pem"
ssl_key: "/etc/letsencrypt/live/yourdomain.com/privkey.pem"If using Tencent Cloud, the platform auto-generates Let’s Encrypt certificates via the Lighthouse dashboard. For local development behind NAT, use ngrok: ngrok http 8080, then paste the HTTPS URL (e.g., https://abc123.ngrok.io) into the QQ console’s “Webhook URL” field under Bot Settings. The endpoint must respond to POST requests at /webhook/qq with JSON content type. Your OpenClaw instance listens here for message events containing message ID, sender QQ number, group ID, and content. Configure timeout thresholds carefully: QQ expects a 200 OK response within 5 seconds or it retries delivery. If your agent takes longer to process, implement immediate HTTP 200 acknowledgment followed by async processing using OpenClaw’s task queue. Test the webhook with:
curl -X POST https://your-domain.com/webhook/qq -H "Content-Type: application/json" -H "X-Signature: sha256=computed_hash" -d '{"test":"ping"}'Correct webhook configuration is vital for receiving messages and events from QQ in real time.
Testing Your Bot in QQ Groups and DMs
Start your OpenClaw instance in foreground mode for debugging:
claw run --adapter qq --verboseAdd your bot to a test QQ group using its QQ number (displayed in the console as 18-digit ID) by searching in the QQ app’s “Add Group Member” interface. Send a message mentioning the bot: @123456789012345678 hello world or use the bot’s custom name if configured. Check your terminal logs: you should see JSON payloads arriving with message_type: group and content fields. The bot responds based on your configured skills in skills.yaml. Test direct messages by adding the bot as a friend (requires the bot to enable “Auto-accept friend requests” in console settings). Send /help to trigger the default help skill or @bot help. Verify file handling by uploading a JPG image—the adapter should pass the file URL to OpenClaw’s vision capabilities if image_recognition scope is enabled. Monitor message delivery status in the QQ Open Platform’s “Message Log” section under Statistics, which shows success rates, latency metrics, and failed delivery reasons. Expect 150-300ms response times for text, 500ms for image analysis on standard hardware. Thorough testing ensures your bot functions as expected across different interaction types.
Managing Up to 5 Bots Per Tencent Account
Tencent allows 5 concurrent active bots per verified personal account, tracked in the console’s “Bot Quota” dashboard. From the dashboard, click “Create New Bot” to spawn additional instances for different use cases. Each bot gets unique AppID, AppSecret, and can run different OpenClaw configurations or skill sets. Use case separation: Bot 1 handles customer service for Group A, Bot 2 manages DevOps alerts via direct messages, Bot 3 runs personal productivity tasks in your private groups. To switch between bots in your terminal, use:
claw use-bot --id 123456789012345678This command updates the active context in ~/.openclaw/current_bot. Each bot maintains separate session files and log directories at ~/.openclaw/logs/bot-{appid}/. Manage resources efficiently: 5 bots on a single 4GB RAM instance works for light traffic under 100 messages per minute combined, but separate cloud instances prevent one bot’s CPU spikes from affecting others. Archive unused bots via “Bot Management” > “Disable” to free up quota without deleting configuration data. Re-enable takes 5 minutes and preserves all historical settings. This multi-bot capability allows for specialized and scalable bot deployments.
Securing App IDs and Bot Tokens
Your AppSecret grants full bot access including message history and group management. Never commit it to Git or expose it in client-side code. Store it in environment variables: export QQ_APP_SECRET=your_secret_here added to ~/.bashrc. Reference it in config.yaml as app_secret: ${QQ_APP_SECRET} using OpenClaw’s env var substitution. Rotate secrets every 90 days via the console’s “Security” > “Reset AppSecret” button; this invalidates old tokens within 5 minutes. Enable IP whitelisting in the console: restrict API calls to your server’s public IP or CIDR block. In OpenClaw, enable request signature verification: verify_signatures: true and signature_algorithm: hmac-sha256 in the QQ adapter config. This validates that messages originate from Tencent’s servers using HMAC-SHA256 computed against your AppSecret. Implement rate limiting on your webhook endpoint using nginx or OpenClaw’s built-in limiter to prevent DDoS—QQ sends bursts during viral group activity that can overwhelm unprotected servers. Use fail2ban to block IPs with excessive failed authentication attempts (more than 10 failed signatures per minute). Backup your session files securely to encrypted storage; losing them requires re-binding, which interrupts service for 2-3 minutes while tokens regenerate. Comprehensive security measures are paramount for protecting your bot and user data.
Troubleshooting Connection Failures
If your bot stops responding to @mentions, check the QQ gateway status first:
curl https://api.sgroupqq.com/statusThis should return {"status":"ok"}. If Tencent’s servers are operational, verify your OpenClaw instance health: claw logs --tail 50 shows recent errors. A common error, “Invalid session” or 401 Unauthorized, means your tokens expired; run claw refresh-qq-tokens to force regeneration. Error 403 Forbidden indicates IP restrictions—check your Tencent Cloud security groups allow outbound HTTPS to api.sgroupqq.com on port 443. If webhooks return 404 Not Found, confirm your reverse proxy (nginx/traefik) routes /webhook/qq correctly to the OpenClaw port. For “Message rate limit exceeded” errors (HTTP 429), implement exponential backoff in your OpenClaw skills using time.sleep() or the built-in @rate_limited decorator. When the bot appears offline in groups despite running, force re-bind using claw bind-qq --force --id YOUR_APPID. Check QQ mobile notifications for “Bot suspended” alerts—the platform pauses bots violating spam policies or sending too many unsolicited DMs. Review the “Violation Center” in the console for specific rule breaches. Systematic troubleshooting helps quickly diagnose and resolve issues.
Optimizing for Low-Latency Responses
QQ users expect near-instant replies comparable to human response times. Move your OpenClaw instance to Tencent Cloud’s Hong Kong region for sub-50ms API latency versus 200ms+ from overseas. Enable connection pooling in the QQ adapter config: keep_alive: true and pool_size: 10 maintains persistent HTTP connections to Tencent’s API, eliminating TCP handshake overhead. Pre-warm your LLM by sending a dummy query on startup—this loads the model into GPU memory or keeps the CPU cache hot, reducing first-response time from 3 seconds to under 200ms. Use async processing patterns: acknowledge messages immediately with HTTP 200 via OpenClaw’s immediate_ack: true setting, then process complex tasks in background threads, sending follow-up messages when complete. Cache frequent responses using Redis: claw cache --ttl 3600 stores common answers like help text or status reports. For high-traffic groups with 1000+ members, implement message batching—collect 3 seconds of messages, process them as a single context window to reduce LLM calls, then respond to all queries. Monitor latency percentiles with claw metrics --adapter qq --report, aiming for p95 under 500ms and p99 under 1000ms to maintain user engagement. These optimizations are crucial for a responsive and engaging user experience.
Self-Hosting vs Tencent Cloud: Which Should You Choose?
You face a fundamental deployment decision: run OpenClaw on your own hardware or let Tencent manage the infrastructure. Self-hosting offers complete data sovereignty and zero recurring costs beyond electricity, making it ideal for development, testing, or handling sensitive data that cannot leave your premises. However, you manage SSL certificates, firewall rules, and OS security patches manually. Tencent Cloud provides optimized network routes to QQ’s servers, reducing message latency by 60-80% compared to international self-hosted setups. The managed service includes automatic OpenClaw updates, DDoS protection, and 24/7 monitoring. For production bots serving 1000+ group members, Tencent Cloud’s stability outweighs the monthly cost. For personal automation or experimental agents, self-hosting suffices.
| Feature | Self-Hosted VPS | Tencent Cloud Lighthouse |
|---|---|---|
| Setup Time | 45-60 min (manual configuration) | 8-10 min (pre-configured image) |
| Average Latency | 150-400ms (depending on location and network path) | 20-50ms (optimized routes to QQ servers) |
| SSL Certificates | Manual (Let’s Encrypt, Certbot management) | Auto-managed (integrated with platform) |
| Security Updates | Self-managed (OS, dependencies, OpenClaw updates) | Automatic (platform handles OS and OpenClaw updates) |
| Cost | $5-20/month (VPS cost, electricity) | 50-100 RMB/month (instance cost) |
| QQ API Reliability | Standard (reliant on general internet routing) | Premium routing (dedicated network infrastructure) |
| Data Sovereignty | Full control (data stored on your chosen hardware) | Within Tencent Cloud’s compliance boundaries |
| Scalability | Manual scaling (add more VPS instances) | Easier scaling (cloud features, auto-scaling groups) |
| Maintenance Overhead | High (OS, software, security patches, backups) | Low (platform handles most infrastructure tasks) |
| DDoS Protection | Requires external solutions or advanced configuration | Built-in platform-level DDoS protection |
Choose self-hosting for development and budget constraints. Choose Tencent Cloud for production workloads requiring consistent sub-100ms response times and reduced operational overhead.
Monitoring Bot Health and Debugging Logs
Production bots need constant visibility into performance and errors. Configure OpenClaw’s built-in health checks in config.yaml:
health_check:
interval: 30
endpoint: "/health"Then point Tencent Cloud’s monitoring to http://localhost:8080/health for automated restart on failure. Enable verbose QQ-specific logging: log_level: DEBUG and qq_log_payloads: true in the adapter config to see raw JSON from Tencent. Log files reside at ~/.openclaw/logs/qq-bot.log with rotation handled by logrotate on Linux systems. Set up Prometheus metrics export: metrics: enabled: true, port: 9090, path: "/metrics" exposes counters for messages received, errors, and response times. Track critical metrics: messages per minute, average response time, error rate percentage, and QQ API quota remaining. Use Tencent Cloud’s CLS (Cloud Log Service) integration by installing the CLS agent: sudo install_cls_agent.sh and configuring ~/.cls/config.json to stream logs to their platform for SQL-based analysis (SELECT * FROM logs WHERE error_level = 'ERROR'). Create Grafana dashboards showing bot uptime, memory usage, and QQ API quota consumption to predict when you need to upgrade to higher tiers before hitting limits. Proactive monitoring and logging are indispensable for maintaining a stable and performant QQ bot.
Future Enhancements and Advanced Features
Once your basic QQ bot is operational, consider exploring advanced OpenClaw features and integrations to enhance its capabilities. Implement more sophisticated natural language understanding (NLU) by integrating with external LLMs or fine-tuning local models. Develop custom tools for your OpenClaw agent to interact with other APIs, such as weather services, stock market data, or internal business systems. For instance, you could create a tool that allows your bot to fetch the latest sales reports or manage calendar events directly from QQ. Explore OpenClaw’s multimodal capabilities, enabling your bot to process and generate images, audio, or even short video clips, responding to complex visual cues or creating dynamic content for users. Integrate with Tencent’s AI services, such as Tencent Cloud Vision for advanced image analysis or Tencent Cloud Speech for voice interactions, to further augment your bot’s intelligence. Consider implementing a feedback loop where users can rate bot responses, allowing your OpenClaw agent to learn and improve over time. Finally, explore the possibility of creating a bot marketplace within QQ, where other users can discover and install your OpenClaw-powered bots, expanding their reach and utility. These future enhancements can transform a simple QQ bot into a powerful and versatile AI assistant.
Frequently Asked Questions
How long does the QQ bot binding process take?
The actual binding takes 30 to 60 seconds using Tencent’s one-click integration link. After clicking the binding URL or scanning the QR code, OpenClaw establishes a secure session with QQ’s gateway immediately. However, account verification and initial bot approval add 5 to 10 minutes for personal accounts. Enterprise accounts may face 24-hour delays during business license verification. Once bound, the bot responds instantly to commands.
Can I run OpenClaw QQ bots outside mainland China?
Yes, but with caveats. Tencent Cloud’s Hong Kong and Singapore regions work perfectly and offer lower latency than mainland servers for international users. Self-hosting outside China requires VPN tunneling for stable QQ API connectivity due to intermittent firewall restrictions. The QQ Open Platform accepts foreign passports for verification, though the interface remains Chinese-only. Response times increase by 100-200ms when routing through international connections.
What happens if I exceed the 5-bot limit per account?
Tencent hard-caps personal accounts at 5 active bots. Attempting to create a sixth triggers an error: Quota exceeded for account tier. You must disable or delete an existing bot before creating a new one. Alternatively, upgrade to an Enterprise account, which raises the limit to 50 bots and provides dedicated API quotas. Each disabled bot retains its configuration for 30 days before permanent deletion, allowing quick reactivation if needed.
Do I need to know Chinese to develop QQ bots?
Not necessarily, but it helps. The QQ Open Platform console is Mandarin-only, though browser translation extensions handle basic navigation. QQ user messages arrive in Chinese predominantly, so your OpenClaw agent needs Chinese language capabilities for group chats. Technical documentation for the API exists in English, and the OpenClaw QQ adapter accepts English configuration files. Error messages from Tencent’s servers, however, typically return in Chinese characters.
Is the OpenClaw QQ integration free to use?
Personal accounts incur no fees for the first 10,000 messages per month per bot. Beyond that, Tencent charges 0.01 RMB per 1000 messages. Tencent Cloud server costs apply separately, starting at 50 RMB monthly for the smallest Lighthouse instance. Enterprise accounts negotiate custom pricing based on message volume. The OpenClaw framework itself remains open-source and free. No hidden charges exist for the binding process or basic bot functionality.