Adapter Overview
Adapters are responsible for connecting messaging platforms such as QQ, Telegram, WeChat, and Discord to MaiBot. Different adapters support different platforms, have different runtime methods, and have different maintenance statuses. For your first deployment, it is recommended to prioritize adapters that are actively maintained and have complete documentation.
Choose an Adapter
| Adapter | Supported Platforms | Status | Description |
|---|---|---|---|
| NapCat | Recommended | The QQ adapter officially maintained by MaiBot, supporting both the plugin version and the standalone version. The plugin version is the currently recommended solution. | |
| GoCQ | Available, outdated | QQ adaptation solution based on go-cqhttp / AstralGocq, suitable for existing GoCQ environments or specific needs. | |
| SnowLuma | Available (In testing) | Next-generation QQ adaptation solution | |
| Telegram | Telegram | Community adaptation | Telegram platform adaptation solution |
| Discord | Discord | Community adaptation | Discord platform adaptation solution |
| Desktop Pet Adapter | Desktop Pet | Community adaptation | Integrates MaiBot into desktop pet interaction scenarios. |
| WeChat - wxauto Adapter | Community adaptation | WeChat platform adaptation solution based on wxauto. | |
| More adapters | - | Community adaptation | Follow the MaiBot GitHub Organization or community groups for information on more third-party adapters. |
When deploying for the QQ platform for the first time, it is recommended to use the NapCat plugin version. It runs directly as a MaiBot plugin, requires less configuration, and eliminates the need to maintain the network connection between the adapter and MaiBot separately.
Legacy / Community Adapter List (May not be maintained promptly)
The following adapters are mostly legacy or community projects, and some may not be compatible with the current version of MaiBot. Before using them, it is recommended to check the update time, README, and Issues of the corresponding repository.
注意兼容性
Some community adapters may be legacy projects and are not necessarily compatible with the current MaiBot. Before installing, it is recommended to check the repository's update time, README, and Issues.
Plugin Version Adapters
If an adapter provides a plugin version, it is typically installed following this process:
- Download or clone the adapter project.
- Make sure to switch to the plugin branch required by the adapter.
- Place the adapter directory into MaiBot's
plugins/directory. - Start MaiBot and let the plugin system automatically load the adapter.
Plugin version adapters run inside MaiBot, so typically you only need to configure the "messaging platform to adapter" connection.
Standalone Version Adapters
If an adapter is a standalone version, it is typically installed following this process:
- Download or clone the adapter project.
- Install dependencies according to the adapter's documentation.
- Fill in the adapter's own configuration file.
- Start the adapter process separately.
Standalone version adapters need to connect to both the messaging platform and MaiBot, so when troubleshooting, you need to check both connections separately.
Configure Connections
Adapters typically require configuring two types of connections:
| Connection Direction | Description |
|---|---|
| Messaging Platform → Adapter | For example, NapCat connects to QQ and pushes QQ messages to the adapter. |
| Adapter → MaiBot | Standalone version adapters need to connect to MaiBot; plugin version adapters usually do not require additional configuration for this layer. |
When using a plugin version adapter, primarily confirm that the adapter can correctly connect to the messaging platform.
When using a standalone version adapter, you also need to confirm that the adapter can connect to MaiBot's messaging service address.
If you are unsure what address to fill in, first run it using the default local machine configuration from the corresponding adapter's documentation, and then consider cross-machine or Docker network deployment.
Confirm Successful Connection
Once configuration is complete, send a test message to the corresponding platform.
If you can see the corresponding message logs in the MaiBot backend, and MaiBot can reply normally, it means the adapter has connected successfully.
If no messages are received, check in this order:
- Whether the messaging platform client has successfully logged in.
- Whether the adapter has started normally.
- Whether the adapter has successfully connected to the messaging platform.
- Whether the standalone version adapter has successfully connected to MaiBot.
- Whether MaiBot has completed initialization and is running normally.