Building a Versatile Chatbot: A Practical Guide to Moltbot and OneBot v11 QQ Plugin Integration

Clawdbot (Moltbot) is a multi-functional intelligent agent, but its basic functionality is merely the starting point. Through a robust plugin system, we can extend its capabilities to a wider range of communication platforms.

The core question this article answers: How can we add QQ channel support to Moltbot using the OneBot v11 protocol to achieve cross-platform messaging?

We will delve into how to leverage open-source plugins to seamlessly connect Moltbot’s powerful core capabilities with QQ, a mainstream social platform. This process involves not only simple installation but also system architecture compatibility, refined configuration, and systematic troubleshooting. Below is an in-depth practical guide based on the official documentation.

Plugin Architecture and OneBot v11 Protocol Integration

Before diving into installation, it is crucial to understand how the Moltbot QQ plugin works. Essentially, this plugin acts as a connector, bridging the Moltbot core system and the QQ client (via the OneBot v11 protocol).

The core question this section answers: How does the Moltbot QQ plugin enable cross-platform communication using the OneBot v11 protocol?

OneBot v11 is a communication protocol widely used in the QQ bot ecosystem, defining standards for message receiving, sending, and event handling. Moltbot implements support for OneBot v11 through this plugin, specifically using WebSocket communication. This means Moltbot does not need to run the QQ client directly; instead, it acts as a client connecting to a server running OneBot v11 (such as NapCat or Go-CQHTTP).

The advantage of this architecture lies in decoupling. Moltbot focuses on business logic and AI processing, while the underlying stability and protocol compatibility of the QQ connection are delegated to mature OneBot implementations.

Application Scenario: Unified Multi-Platform Management

Imagine a scenario where you are running a community and need to handle user messages from Discord, Slack, and QQ simultaneously. With this architecture, Moltbot can serve as the central brain, processing commands from different channels uniformly. The QQ plugin plays a pivotal role here by standardizing the QQ message stream into an event stream that Moltbot can understand, ensuring that core processing logic remains consistent regardless of the message source.

“

Reflection: The Power of Modularity
When examining the design of this plugin, I am struck by the elegance of modular architecture. Moltbot itself does not need to modify its core code to adapt to QQ; it simply needs to load a compliant plugin. This “hot-pluggable” design philosophy not only reduces maintenance costs but also allows developers to focus on the ultimate optimization of a single function. For technical teams, this implies lower coupling and higher system reusability.

---

Environment Setup and Prerequisites

Setting up the environment is the most foundational yet critical step in the entire integration process. Any oversight in details can lead to subsequent connection failures.

The core question this section answers: What components and services are necessary before installing the Moltbot QQ plugin?

To run this plugin, the primary requirement is a running OneBot v11 server. The documentation specifically recommends NapCat because it is a modern implementation and extremely Docker-friendly. Of course, traditional options like Lagrange or Go-CQHTTP are also viable alternatives.

One detail that must be noted when configuring OneBot: you must enable the Forward WebSocket Server. Typically, this service runs on port 3001. A Forward WebSocket means the OneBot server listens on a port, waiting for Moltbot to actively initiate a connection. This differs from Reverse WebSocket (where the server actively pushes), and this plugin utilizes the former.

Component Selection Advice

Choosing the right OneBot implementation is crucial depending on your actual use case:

• 🍂
  
  NapCat: Best for users pursuing modern deployment who are comfortable using Docker containers. It usually updates faster and has more timely support for new protocols.
• 🍂
  
  Lagrange: Suitable for scenarios with specific compatibility requirements for older protocol versions.
• 🍂
  
  Go-CQHTTP: Although a classic, it may be less active than the former two in adapting to the latest versions of QQ.

---

Source Installation: Building the Integration from Scratch

For developers who prefer to control projects via source code, cloning and compiling directly is the best choice. This approach offers the greatest flexibility and control.

The core question this section answers: How can we install the Moltbot QQ plugin via source code and complete the dependency build?

Below is a detailed breakdown of the steps; none should be overlooked:

1. Navigate to the Extensions Directory

First, you need to enter the Moltbot extensions directory. This is because the plugin system requires specific functions to be placed in a designated extensions folder to be correctly recognized.

cd moltbot/extensions

This directory serves as the “toolbox” where Moltbot stores all external plugins. Placing the QQ plugin here is the first step to making it effective.

2. Clone the Plugin Code

Next, clone the plugin code from the GitHub repository. The official advice is to name the directory qq so that referencing it in the configuration file is more intuitive.

git clone https://github.com/constansino/moltbot_qq.git qq

When executing this step, ensure your network environment can access GitHub normally and that Git is installed locally. Once cloning is complete, you should see a folder named qq inside the extensions directory containing all the plugin’s source code.

3. Install Dependencies and Build

Plugins often come with their own dependency libraries. After installing a new plugin, you must update Moltbot’s dependency tree and rebuild the project to ensure all code links correctly.

Return to the Moltbot root directory:

cd ..

Then execute the installation and build commands:

pnpm install
pnpm build

pnpm install reads the package.json files of the project and plugins, downloading all necessary Node.js modules. pnpm build compiles TypeScript or other source code into JavaScript for the Node.js runtime to execute.

4. Restart the Service

The final step is to restart Moltbot. Only upon restart will the core system scan the extensions directory, load the new QQ plugin, and register it within the system.

“

Reflection: The Necessity of the Build Process
Many beginners tend to skip the pnpm build step, running the code only to find the plugin ineffective. This is actually because, in the JavaScript/TypeScript ecosystem, source code often needs to be transpiled and bundled before it can run efficiently in a production environment. This step seems tedious but is essential for guaranteeing code compatibility and execution efficiency.

---

Docker Deployment: Plugin Management in Containers

With the popularity of containerization technology, Docker has become the preferred method for deploying applications. Installing plugins in a Docker environment differs slightly from source installation, primarily involving image rebuilding.

The core question this section answers: How do we integrate the Moltbot QQ plugin in a Docker environment and rebuild the service?

Docker’s design philosophy is “image as build artifact.” To add a plugin into a container, it must be done during the build phase, not simply modified via command line during the runtime phase.

1. File Placement

First, you need to place all moltbot_qq files into the extensions/qq directory within your build context. The “build context” here usually refers to the directory where your docker-compose.yml file is located, or the copy path specified in the Dockerfile.

Ensuring the directory structure is correct is a prerequisite for success. If the copy path defined in the Dockerfile is /app/extensions, you must ensure the files on the host machine are mapped to the correct location.

2. Rebuild the Image

Since the plugin content has changed, the original image is no longer applicable, and it must be rebuilt. Using docker compose can greatly simplify this operation:

docker compose build clawdbot-gateway

This command triggers the Docker daemon to re-execute the build steps according to the Dockerfile. During this process, the files in extensions/qq will be copied into the image, becoming part of the container’s filesystem.

3. Start the Container

Once the build is complete, start the new container with the following command:

docker compose up -d clawdbot-gateway

The -d flag indicates running in the background. At this point, a new Moltbot container has started, and the QQ plugin is already integrated internally.

Application Scenario: CI/CD Automated Deployment

For team collaboration environments, the Docker deployment method is particularly powerful. You can incorporate plugin updates into the CI/CD workflow. Once the source repository updates, the pipeline automatically triggers a build, generating a new image containing the latest plugin, and automatically deploys it to the test or production environment. In this scenario, Docker’s consistency and reproducibility demonstrate immense value.

---

Configuration Guide: Establishing a Stable Communication Link

After installation, correct configuration is the final kick to a successful connection. The configuration file defines how Moltbot finds the OneBot server and verifies its identity.

The core question this section answers: How do we edit clawdbot.json to ensure Moltbot can connect to the OneBot server securely and accurately?

The configuration file is typically located in the user directory: ~/.clawdbot/clawdbot.json. You need to open it with a text editor and modify the JSON structure according to your actual situation.

Core Configuration Items Explained

Below is a standard configuration template:

{
  "channels": {
    "qq": {
      "wsUrl": "ws://<ONEBOT_SERVER_IP>:3001",
      "accessToken": "your_security_token_here"
    }
  },
  "plugins": {
    "entries": {
      "qq": {
        "enabled": true
      }
    }
  }
}

1. Channels

The channels object defines all connected communication channels.

• 🍂
  
  qq: The identifier for the QQ channel.
• 🍂
  
  wsUrl: This is the listening address for the OneBot v11 Forward WebSocket.

  • 🍂
    
    IP Address: If Moltbot and OneBot are running on the same machine (or the same Docker network), you can usually use 127.0.0.1 or localhost. If connecting across machines, you must fill in the actual LAN IP or public IP of the server hosting OneBot.
  • 🍂
    
    Port: Defaults to 3001, but must match exactly what you set in the OneBot configuration file.
• 🍂
  
  accessToken: This is the security verification token. To prevent malicious connections, it is recommended to set an access token in OneBot and fill in the same string here.

2. Plugins

The plugins object controls plugin behavior.

• 🍂
  
  entries: The list of plugin entry points.
• 🍂
  
  qq: Corresponds to the plugin name we installed.
• 🍂
  
  enabled: Must be explicitly set to true. Only when this switch is turned on will Moltbot attempt to load and initialize the QQ connection.

Configuration Validation Tips

After modifying the JSON file, it is advisable to use a JSON validation tool to check the syntax. JSON format is very strict; extra commas or missing quotes will cause file parsing failures, leading to Moltbot failing to start or load configurations.

---

Troubleshooting: Resolving Common Connection and Runtime Obstacles

Even when following the steps, various issues can arise during actual operation. Learning to troubleshoot is an essential skill for every engineer.

The core question this section answers: How can we use logs and the file system to quickly diagnose issues when Moltbot fails to connect or runs abnormally?

Issue 1: 502 Gateway Error

When you try to access the Moltbot web interface or API and see a 502 error, it usually means the Moltbot process itself has crashed.

Diagnosis Method:
The most direct way is to check the Docker container logs. The logs will record stack traces or error messages before the program crashes.

docker logs -f clawdbot-gateway

The -f flag allows you to track log output in real-time. By analyzing the last line of the error in the logs, you can pinpoint whether the configuration file is wrong, the network is unreachable, or if there is a code-level exception.

Issue 2: Session Locked

This is a common problem with Node.js applications. When Moltbot exits abnormally (e.g., forcibly killed, power failure), certain lock files used to manage concurrency or database connections may not be released. Upon the next startup, the system detects the existence of the lock file, mistakenly assuming another instance is running, and thus refuses to start.

Solution:
You need to manually clean up these lock files. You can use the find command to search for and delete all files ending in .lock within the configuration directory:

find . -name "*.lock" -delete

Before executing this command, please ensure that no other Moltbot process is currently running; otherwise, it may lead to data conflicts.

“

Reflection: Thoughts on Robustness Design
The existence of the “Session Locked” problem reminds us that when designing systems, we must consider “non-graceful shutdown” scenarios. While deleting lock files is a simple fix, in the long run, automated lock timeout mechanisms or more robust process managers (like PM2) can significantly reduce the frequency of manual intervention. As an ops engineer or developer, one must not only know how to fix bugs but also think about how to reduce bug occurrence through architectural optimization.

---

Conclusion and Action Checklist

Through the steps above, we have covered the entire process from environment setup, plugin installation, configuration debugging, to troubleshooting. The combination of Moltbot and OneBot v11 provides a solid foundation for building powerful QQ bots.

Practical Summary / Action Checklist

To facilitate rapid deployment, here is a condensed checklist of key steps:

1. Environment Confirmation:

   • 🍂
     
     [ ] OneBot v11 server installed and running (Recommend NapCat).
   • 🍂
     
     [ ] OneBot Forward WebSocket enabled (Port 3001).
   • 🍂
     
     [ ] accessToken obtained (if configured).

2. Install Plugin:

   • 🍂
     
     [ ] Source Install: cd moltbot/extensions -> git clone ... qq -> cd .. -> pnpm install -> pnpm build.
   • 🍂
     
     [ ] Docker Install: Place files in extensions/qq -> docker compose build clawdbot-gateway.

3. Configure Connection:

   • 🍂
     
     [ ] Edit ~/.clawdbot/clawdbot.json.
   • 🍂
     
     [ ] Fill in the correct wsUrl (IP:Port).
   • 🍂
     
     [ ] Fill in the correct accessToken.
   • 🍂
     
     [ ] Set "enabled": true.

4. Startup and Verification:

   • 🍂
     
     [ ] Restart Moltbot or Docker container.
   • 🍂
     
     [ ] Check Docker logs to ensure no errors.
   • 🍂
     
     [ ] Send a test message in QQ to verify bot response.

---

One-page Summary

Phase	Key Action	Command/Config Example	Notes
Prepare	Start OneBot	Configure Forward WS (Port 3001)	NapCat recommended
Install (Source)	Enter dir, clone, build	cd moltbot/extensions && git clone ... pnpm install && pnpm build	Must build from root dir
Install (Docker)	Place files, rebuild	Place files in extensions/qq docker compose build clawdbot-gateway	Ensure build context path is correct
Configure	Edit JSON	"wsUrl": "ws://IP:3001" "accessToken": "token"	IP depends on network environment
Maintain	View logs, delete locks	docker logs -f clawdbot-gateway find . -name "*.lock" -delete	502 error usually requires log check

---

Frequently Asked Questions (FAQ)

Q1: Which OneBot implementations does the Moltbot QQ plugin support?
A: It supports any implementation compatible with the OneBot v11 protocol; the documentation recommends NapCat, Lagrange, or Go-CQHTTP.

Q2: Why is there no response after Moltbot starts?
A: Please check if "enabled" is set to true in clawdbot.json and verify the Docker logs to confirm the WebSocket connection to OneBot was successful.

Q3: What should I fill in for wsUrl in the configuration file?
A: You should fill in a string starting with ws://, followed by the OneBot server’s IP address and port (e.g., 3001). If on the same Docker network, you can use the container name as the hostname.

Q4: What should I do if I encounter a 502 Gateway Error?
A: This usually indicates Moltbot has crashed. Please use docker logs -f clawdbot-gateway to view specific error details for troubleshooting.

Q5: How do I solve the Session Locked issue on startup?
A: Use the command find . -name "*.lock" -delete to delete lock files in the configuration directory, then restart the service.

Q6: Do I need to restart Moltbot after installing the plugin?
A: Yes, whether it is a source installation or a Docker rebuild, you need to restart or recreate the container to load the new plugin.

Q7: Can I hot-reload the plugin without restarting?
A: According to the documentation guide, the installation steps include pnpm build and container rebuilds, which usually implies a process restart is required to apply changes.

---

Note: Images used in this article are sourced from the official project documentation and GitHub assets.