QQ Commands

QQ Commands

Commands are registered through nonebot-plugin-alconna with command start tokens and separators enabled by default. Command trigger words are locale-exclusive: Chinese locales enable Chinese triggers, English locales enable short hyphenated English triggers. The two trigger languages are not enabled at the same time.

Menu

Primary command:

菜单

English command when LINGCHU_LOCALE / lc_locale / locale selects English:

menu

The menu command is an index entry. It lists the available submenu commands instead of expanding every feature into one long message. Submenus are code-driven and filtered by the selected platform, protocol, and implementation.

Default submenu commands:

• member-management / 成员管理: kick, block/unblock, set member card, set member title, set/unset admin.
• speech-management / 发言管理: mute/unmute member, enable/disable whole-group mute, recall recent messages.
• group-chat-management / 群聊管理: set group name, set group avatar (when supported), send group announcement (when supported), leave current group.
• remote-management / 远程管理: cross-group mute/unmute, whole-group mute/unmute, kick, block/unblock, send announcement, mass announcement.
• system-management / 系统管理: silence/speak (silent mode), boot/shutdown (handle gate), application operation commands such as protocol endpoint restart.

Member mute

禁言 @用户 [时长秒数] [原因]
mute @user [duration seconds] [reason]

• Duration default: 60 seconds.
• Reason default: 违反群规「默认」.

Member unmute

解禁 @用户
unmute @user

Whole-group mute

全员禁言
mute-all

Whole-group unmute

全体解禁
unmute-all

Message recall

撤回 [@用户] [数量]
recall [@user] [count]

• Count default: recall_message_default_count from config.json5 (default 10).
• A single numeric argument is treated as the count: 撤回 20.
• To target a user, mention them first: 撤回 @用户 20.
• The command reads recent current-group message records from the message store, skips the triggering command message, verifies each candidate through OneBot V11 get_msg, then recalls it through delete_msg.
• The bot skips messages from the operator, itself, group admins/owner, and protected users configured through protected_subject_feature_keys.

OneBot V11 blocklist

Blocklist and whitelist commands are available on OneBot V11 only. Blocking stores the user in the group or global blocklist, kicks the user from the current group, and rejects future group join requests while the block is active. Whitelisting stores the user as a protected subject; only repository-backed SUPERUSERS can add or remove whitelist entries.

拉黑 @用户 [时长秒数] [原因]
全局拉黑 @用户 [时长秒数] [原因]
删黑 @用户 [原因]
全局删黑 @用户 [原因]
清空黑名单 [原因]
全局清空黑名单 [reason]
拉白 @用户 [原因]
全局拉白 @用户 [原因]
删白 @用户 [原因]
全局删白 @用户 [原因]

English: block, global-block, unblock, global-unblock, clear-blocklist, global-clear-blocklist, protect, global-protect, unprotect, global-unprotect.

• Duration default: permanent.
• Block reason default: 违反群规「默认」.
• Unblock/clear/whitelist reason default: 管理员操作「默认」.

清空黑名单 only clears the current group blocklist. Use 全局清空黑名单 to clear global entries. 拉白 and 删白 only affect the current group whitelist. Use the global variants for protected users across groups.

Group settings and operations

The announcement and group avatar commands accept UniImage values from nonebot-plugin-alconna. Quote names, announcements, cards, or titles that contain spaces so command separators do not split them.

Remote management (OneBot V11 only)

Remote commands operate on a target group other than the current one. The <群号或群名称> argument accepts:

• An integer group ID (e.g., 123456789).
• A numeric string that can be parsed as an integer.
• A non-numeric string that triggers fuzzy matching against the bot's joined groups via get_group_list. Exact name match takes priority; otherwise, substring containment is used. Multiple matches cause the bot to ask for a more precise name or group ID.

Mass announcement uses the command key / feature name mass announcement / 群发公告. The content argument comes first. If the target list is omitted, the bot sends to all groups it has joined. To target multiple groups, separate group IDs or group names with ,, ，, 、, ;, or ；. Use 全部群 or all to explicitly target all joined groups.

Error feedback

Group management commands return readable error messages for covered adapter network errors and rejected operations. Unknown exceptions are still raised outward so developers can find uncovered cases.

Feedback text and command trigger language use LINGCHU_LOCALE, lc_locale, or locale from the current NoneBot configuration. See Internationalization.

System Management

重启协议端 restarts the current QQ OneBot V11 protocol endpoint when the platform argument is omitted. After the protocol endpoint reconnects, Lingchu sends a confirmation message to the group where the command was issued.

silence
闭嘴

Enable silent mode: commands still execute (mute, kick, etc. take effect) but no response messages are sent.

speak
说话

Disable silent mode: resume sending command response messages.

boot
开机

Boot: enable all command handlers. All commands respond normally when booted.

shutdown
关机

Shutdown: disable all command handlers (except boot/shutdown themselves). No commands execute or respond. Only boot/shutdown commands work when shut down.