Connect OpenClaw agents to the OneBot protocol for seamless QQ messaging and bot integration.
Install & Download
1. ClawHub CLI
The fastest way to install a skill directly from the registry.
npx clawhub@latest install onebot-adapter
2. Manual Installation
Copy the skill folder to one of these locations
~/.openclaw/skills/ <project>/skills/ Priority: Workspace > Local > Bundled
3. Prompt Installation
Copy this prompt to OpenClaw to install it automatically.
Help me install onebot-adapter using Clawhub. If Clawhub is not installed, install it first (npm i -g clawhub).
Prefer to download?
Get the raw skill files in a ZIP archive.
What is OneBot Adapter?
The OneBot Adapter is a specialized bridge designed to integrate OpenClaw agents with the OneBot protocol, enabling robust QQ bot functionality. By leveraging implementations like NapCat, which is based on NTQQ, developers can empower their Openclaw Skills to interact with users and groups on one of the world's largest communication platforms.
This adapter provides a flexible interface for both real-time event handling via WebSockets and reliable message delivery through standard HTTP APIs. It is built to handle the complexities of the OneBot11 specification, ensuring that your agents can respond to triggers and manage social interactions with high efficiency and low latency.
OneBot Adapter Use Cases
- Building automated customer support or community management bots on QQ.
- Real-time monitoring and notification systems for private and group chats.
- Integrating AI agents into social communities for interactive tasks and games.
- Programmatically managing friend requests and group memberships within Openclaw Skills workflows.
How OneBot Adapter Works
- Configure the connection by defining the OneBot server URL and authentication token in the environment variables.
- Initialize the WebSocket listener to capture incoming messages and system events from the QQ client in real-time.
- Process incoming data payloads to identify message types, sender IDs, and group contexts.
- Execute agent logic to determine the appropriate response or action based on the input.
- Send outgoing private or group messages back through the HTTP API or established WebSocket connection.
OneBot Adapter Setup
To get started, set the OneBot server configuration using environment variables:
export ONEBOT_WS_URL="ws://127.0.0.1:3001"
export ONEBOT_HTTP_URL="http://127.0.0.1:3000"
export ONEBOT_TOKEN="your-token"
Launch the listener to begin receiving events for your Openclaw Skills:
python scripts/onebot_ws_listener.py
OneBot Adapter Data Schema & Taxonomy
The adapter manages connection metadata and message structures through the following parameters:
| Parameter | Description | Requirement |
|---|---|---|
| ONEBOT_WS_URL | WebSocket endpoint for real-time bidirectional events | Required |
| ONEBOT_HTTP_URL | HTTP API endpoint for sending commands | Required |
| ONEBOT_TOKEN | Security token for server-side authentication | Recommended |
| user_id | Unique integer identifier for a QQ user | Required for private msgs |
| group_id | Unique integer identifier for a QQ group | Required for group msgs |
OneBot Adapter Advanced Features
- Support for NapCat/NTQQ implementations to ensure compatibility with modern QQ versions.
- Dual-mode communication allowing developers to choose between WebSocket for speed or HTTP for simple request-response tasks.
- Modular client architecture for granular control over private and group messaging streams.
- Built-in methods for retrieving account information, friend lists, and group lists to enrich agent context within Openclaw Skills.
- Robust error handling for connection timeouts and authentication failures.
SKILL.md
Loading
Related Openclaw Skills
Clawdbot Security Suite
A comprehensive security layer for AI agents providing real-time threat detection and command sanitization as part of the Openclaw Skills ecosystem.
Filesystem Management
A powerful toolset for AI agents to perform advanced file listing, searching, and batch processing with built-in safety checks.
Zown Gemini Governor
A high-fidelity token management and model stabilization skill designed to prevent Gemini TPM rate limits through context pruning and atomic pipelines.
Fish Audio S1 TTS Skill
Transform text into high-quality AI speech and automatically sync audio files to your private NextCloud storage.
Daily Standup Generator
Automate your daily status reports by extracting task progress and blockers from your conversation history and project logs.
aliyun-tts
An Alibaba Cloud-powered Text-to-Speech synthesis skill for generating high-quality audio from text strings.
Featured*
