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 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.
• entertainment / 娱乐功能: Chat with AI.

Remote management

远程管理 / remote-management is a top-level menu entry that lists all remote (cross-group) commands. Remote commands accept a group ID (int) or group name (str). When a non-int string is provided, the bot falls back to fuzzy matching group names via the OneBot V11 get_group_list API.

Member mute

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

When the duration or reason is omitted, Lingchu uses the corresponding member_mute.toml handle default. Administrators can update all supported handle defaults at runtime with set-handle-default <handle> <field> <value>. Use set-default-mute <seconds> as the member-mute shortcut.

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

Member unmute

解禁 @用户
unmute @user

Permission pre-checks and audit

The unmute command runs permission pre-checks before executing: check_target_privilege() verifies the target user is not an admin/owner (unless the operator is the group owner or a superuser), and check_bot_privilege() verifies the bot has admin/owner role in the group. After execution, record_command_audit() writes a command-level audit log entry.

Unmuting your own account is allowed — 解禁 / unmute is a restorative action, so the operator’s own QQ is not rejected (only the bot itself is excluded).

Whole-group mute

全员禁言
mute-all

Whole-group unmute

全体解禁
unmute-all

Message recall

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

• Count default: LINGCHU_RECALL_MESSAGE_DEFAULT_COUNT from the NoneBot environment or .env (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.

Blocking yourself or the bot is rejected: 拉黑 / block (and the remote variants) refuse targets that are the operator’s own account or the bot itself.

Group settings and operations

Capability	Chinese command	English command
Set group name	设置群名称 <新群名称>	set-group-name <new group name>
Set group avatar	设置群头像 <图片>	set-group-avatar <image>
Set member card	设置群名片 @用户 <名片>	set-member-card @user <card>
Set member special title	设置群头衔 @用户 <头衔>	set-member-title @user <title>
Set member admin	设置群管理员 @用户 [true/false]	set-member-admin @user [true/false]
Unset member admin	取消群管理员 @用户	unset-member-admin @user
Kick member	踢出 <用户ID或@提及> [原因]	kick-member <user_id_or_mention> [reason]
Send announcement	发送群公告 <内容> [图片]	send-announcement <content> [image]
Leave current group	退出群	leave-group

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.

Capability	Chinese command	English command
Remote mute	远程禁言 <群号或群名称> @用户 [时长秒数] [原因]	remote-mute <group_id_or_group_name> @user [duration seconds] [reason]
Remote unmute	远程解禁 <群号或群名称> @用户 [原因]	remote-unmute <group_id_or_group_name> @user [reason]
Remote whole mute	远程全体禁言 <群号或群名称>	remote-mute-all <group_id_or_group_name>
Remote whole unmute	远程全体解禁 <群号或群名称>	remote-unmute-all <group_id_or_group_name>
Remote kick	远程踢出 <群号或群名称> @用户 [原因]	remote-kick <group_id_or_group_name> @user [reason]
Remote block	远程拉黑 <群号或群名称> @用户 [时长秒数] [原因]	remote-block <group_id_or_group_name> @user [duration seconds] [reason]
Remote unblock	远程删黑 <群号或群名称> @用户 [原因]	remote-unblock <group_id_or_group_name> @user [reason]
Remote announcement	远程公告 <群号或群名称> <内容> [图片]	remote-announcement <group_id_or_group_name> <content> [image]
Mass announcement	群发公告 <内容> [群号或群名称列表或全部群] [图片]	mass-announcement <content> [group_ids_or_group_names_or_all] [image]

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.

Remote unmute (远程解禁 / remote-unmute) allows unmuting your own account in the target group. Remote block (远程拉黑 / remote-block) rejects targeting yourself or the bot.

Announcement availability

Remote announcement and mass announcement require NapCat.Onebot >= 4.18.0. Other OneBot V11 implementations cannot send group notices. Announcement menu entries are hidden when the implementation is unsupported.

Remote kick requires blocklist

远程踢出 only works on users already in the blocklist for the target group. Use 远程拉黑 first if the user is not yet blocked.

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 from the current NoneBot configuration. See Internationalization.

System Management

Capability	Chinese command	English command
Restart protocol endpoint	重启协议端 [平台]	restart-protocol-endpoint [platform]
Reset Lingchu config	重置灵初配置	reset-lingchu-config

重启协议端 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.

重置灵初配置 reloads Lingchu runtime configuration from disk: bot state (bot_state.toml), menu, handle config files, and mutable runtime overrides (runtime-overrides.toml). Use it after editing these TOML files by hand so the running bot picks up the changes without a restart. Command trigger overrides still require a restart because matchers are registered at startup.

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.

Shutdown Scope

After shutdown, all group management commands (mute, kick, block, etc.) stop responding. Only the boot command can restore operation. In silent mode, commands still execute — only feedback messages are suppressed.