SnowLuma Adapter

Updated: 07/09/2026Word count: 0 wordsReading time: 1 min

The SnowLuma Adapter allows MaiBot to connect to the QQ via SnowLuma to send and receive messages, and handle group and private chats.

可用（测试中）

The SnowLuma Adapter is currently in the testing phase. While basic functions are available, there may be uncovered edge cases. If you encounter any issues, please report them via GitHub Issues.

Introduction

The SnowLuma Adapter is a MaiBot plugin that uses WebSockets for bidirectional communication with SnowLuma. Its workflow is simple:

• Inbound: SnowLuma pushes QQ messages to the adapter, which converts them and injects them into MaiBot.
• Outbound: Replies generated by MaiBot are converted by the adapter and sent out via SnowLuma.

Unlike the NapCat adapter, the SnowLuma adapter only supports plugin mode and does not provide a standalone execution method. The adapter runs directly within the MaiBot process, resulting in fewer configurations and simpler deployment.

Message flow: QQ → SnowLuma → Adapter Plugin (inside MaiBot) → MaiBot

Adapter Repository

Source code for the SnowLuma Adapter: Mai-with-u/MaiBot-SnowLuma-Adapter

Installation

Step 1: Get the Adapter

Clone the adapter repository into MaiBot's plugins/ folder:

# 进入 MaiBot 的 plugins 目录
cd MaiBot/plugins

# 克隆仓库
git clone https://github.com/Mai-with-u/MaiBot-SnowLuma-Adapter.git

Alternatively, you can install the plugin via the MaiBot WebUI.

Step 2: Configure SnowLuma Connection

The adapter is already running inside MaiBot; you only need to configure the connection information between the adapter and SnowLuma. Edit the adapter's configuration file plugins/MaiBot-SnowLuma-Adapter/config.toml and fill in the SnowLuma address and port.

Step 3: Configure SnowLuma

Ensure that SnowLuma has the forward WebSocket server enabled. The listening address and port must match luma_client.server and luma_client.port in the adapter configuration.

The default connection address is ws://127.0.0.1:3001. If your SnowLuma is running on the same machine, you can keep the default.

Step 4: Start

Simply start MaiBot, and the adapter will load and connect automatically.

Plugin is Disabled by Default

After installation, the SnowLuma adapter plugin is disabled by default and must be manually enabled to connect.

Method 1: Edit Configuration File (Recommended)

Edit plugins/MaiBot-SnowLuma-Adapter/config.toml and change enabled to true:

[plugin]
enabled = true   # 改为 true
config_version = "1.0.0"

Then restart MaiBot.

Method 2: Enable via WebUI

1. Access http://127.0.0.1:8001 in your browser and log in using your Access Token.
2. Click "Plugin Management" in the left menu.
3. Find "SnowLuma Adapter" and click the enable switch.
4. Save the configuration and restart MaiBot (or wait for the plugin to hot-reload).

Verify Activation: After starting MaiBot, check the logs for prompts indicating that the adapter has loaded and connected successfully. If you see 已在配置中禁用，跳过激活, it means it is not enabled.

Configuration Reference

The adapter's configuration file is located at plugins/MaiBot-SnowLuma-Adapter/config.toml and contains the following four groups.

Plugin Settings ([plugin])

• enabled — Whether to enable the SnowLuma adapter. When disabled, the plugin only registers the message gateway and will not actively connect to SnowLuma. Default: disabled.
• config_version — Current configuration structure version (managed automatically, generally no need to modify manually). Default: "1.0.0"

SnowLuma Connection ([luma_client])

• server — SnowLuma WebSocket service address. Default: "127.0.0.1"
• port — SnowLuma WebSocket service port. Default: 3001
• token — SnowLuma access token (can be left blank). Default: empty
• connection_id — Optional connection identifier used to distinguish between multiple adapter links. Default: empty
• reconnect_delay_sec — Reconnection wait time after disconnection (seconds). Default: 5.0
• action_timeout_sec — Timeout for calling SnowLuma action interfaces (seconds). Default: 10.0

Chat Filtering ([chat])

• enable_chat_list_filter — Whether to enable group and private chat list filtering. When disabled, only ban_user_id rules are kept. Default: enabled.
• show_dropped_chat_list_messages — Whether to log messages discarded due to failing chat list filtering. Default: disabled.
• group_list_type — Group chat list mode. "whitelist" only accepts group chats in the list; "blacklist" ignores group chats in the list. Default: "whitelist"
• group_list — List of group numbers in the group chat list (automatically deduplicated). Default: empty
• private_list_type — Private chat list mode. "whitelist" only accepts private chats in the list; "blacklist" ignores private chats in the list. Default: "whitelist"
• private_list — List of user IDs in the private chat list (automatically deduplicated). Default: empty
• ban_user_id — Global blocked user ID list; messages from these users are discarded before entering MaiBot. Default: empty
• ban_qq_bot — Whether to block official QQ bot messages. Default: disabled.

群聊白名单默认开启

The adapter enables chat list filtering by default, and group chats default to whitelist mode. This means group messages not added to group_list will be discarded. If the connection is successful but the bot does not respond to @ mentions in a group, check here first.

During the testing phase, you can temporarily disable list filtering:

[chat]
enable_chat_list_filter = false

Or add the group numbers you need to test to the whitelist:

[chat]
enable_chat_list_filter = true
group_list_type = "whitelist"
group_list = ["你的QQ群号"]

Message Filtering ([filters])

• ignore_self_message — Whether to ignore messages sent by the bot itself (recommended to keep enabled to avoid the bot processing its own messages). Default: enabled.

Full Configuration Example

[plugin]
enabled = true
config_version = "1.0.0"

[luma_client]
server = "127.0.0.1"
port = 3001
token = ""
connection_id = ""
reconnect_delay_sec = 5.0
action_timeout_sec = 10.0

[chat]
enable_chat_list_filter = true
show_dropped_chat_list_messages = false
group_list_type = "whitelist"
group_list = ["123456789"]
private_list_type = "whitelist"
private_list = []
ban_user_id = []
ban_qq_bot = false

[filters]
ignore_self_message = true

Verification and Troubleshooting

Verify Connection

How do I know it's connected? Check these areas:

1. WebUI Plugin List: You can see that the SnowLuma adapter plugin is loaded.
2. MaiBot Logs: You see the prompt SnowLuma WebSocket 已连接.
3. Message Test: @ the bot in a QQ group and see if it replies.

What if it won't connect?

Check the following:

• Are the SnowLuma address and port correct? Do they match the adapter's luma_client.server / luma_client.port?
• Is the firewall blocking it?
• Are SnowLuma and MaiBot on the same machine?
• Is the access token token correct?
• What error messages are appearing in the logs?

Not receiving messages?

Possible reasons:

• Group chat whitelist is enabled by default; have you added your group number to group_list?
• Is enabled set to true?
• Is SnowLuma itself receiving the messages? Check the SnowLuma logs.
• Is the network connection normal?

Cannot send messages?

Troubleshooting methods:

• Does the bot have permission to speak? (Group chats require permissions)
• Check the MaiBot logs for any error messages.
• Is the action_timeout_sec setting reasonable? It can be increased if network latency is high.

Multi-instance Deployment

If you need a single MaiBot to interface with multiple SnowLuma instances (e.g., multiple QQ accounts), you can configure a different connection_id for each instance to distinguish the links:

[luma_client]
connection_id = "bot-1"