nonebot-plugin-avatar-manager

✨ NoneBot2 头像管理插件，支持机器人和群资料的头像/名称立即修改与定时修改 ✨

📖 介绍

nonebot-plugin-avatar-manager 是一个基于 NoneBot2 和 OneBot V11 的资料管理插件，提供机器人头像/昵称、群头像/群名称的立即修改和定时修改能力，并支持任务持久化恢复。

插件目前支持的核心场景：

• 超级管理员在私聊中查看机器人信息和可管理群列表
• 群主或管理员在群聊中直接修改当前群头像或群名称
• 超级管理员修改机器人自身头像或昵称
• 为群资料或机器人资料创建定时修改任务
• 从图床或 COS 的图片直链 / txt 清单中轮换头像与名称
• 群聊中上传头像资源或名称资源到本群独立资源池
• 从本地存储列表中随机切换群头像或群名称
• 分页查看本群本地存储列表中的头像与名称资源
• 按序号删除本群本地存储列表中的头像或名称资源
• 启动时自动恢复已保存任务

💿 安装

使用 nb-cli 安装

在 nonebot2 项目的根目录下打开命令行，输入以下指令即可安装：

nb plugin install nonebot-plugin-avatar-manager

使用包管理器安装

在 nonebot2 项目的插件目录下打开命令行，根据你使用的包管理器，输入相应的安装命令。

pip

pip install nonebot-plugin-avatar-manager

安装完成后，打开 nonebot2 项目根目录下的 pyproject.toml 文件，在 [tool.nonebot] 部分追加写入：

plugins = ["nonebot_plugin_avatar_manager"]

⚙️ 配置

在 nonebot2 项目的 .env 文件中添加下表中的配置项：

配置项	必填	默认值	说明
SUPERUSERS	是	无	NoneBot 超级管理员账号列表，私聊管理机器人资料时必需
ENABLE_SELF_AVATAR	否	true	是否允许修改机器人自身头像与昵称
ENABLE_GROUP_AVATAR	否	true	是否允许修改群头像与群名称

示例：

SUPERUSERS=["123456789"]
ENABLE_SELF_AVATAR=true
ENABLE_GROUP_AVATAR=true

🎉 使用

指令表

指令	权限	需要@	范围	说明
头像帮助	超级管理员 / 群管理员 / 群主	否	私聊 / 群聊	查看插件帮助
头像信息	超级管理员	否	私聊	查看机器人账号、昵称、头像地址与所在群列表
群管	超级管理员	否	私聊	查看机器人在哪些群具备管理权限
修改	群管理员 / 群主	否	群聊	使用本地头像/名称关键字立即修改当前群资料
修改头像	群管理员 / 群主	否	群聊	立即修改当前群头像
修改名称	群管理员 / 群主	否	群聊	立即修改当前群名称
定时修改头像	群管理员 / 群主	否	群聊	为当前群创建头像定时修改任务
定时修改名称	群管理员 / 群主	否	群聊	为当前群创建名称定时修改任务
上传	群管理员 / 群主	否	群聊	接收下一条消息并保存为本群头像资源或名称资源
随机头像	群管理员 / 群主	否	群聊	从本地存储列表中随机更换当前群头像
随机名称	群管理员 / 群主	否	群聊	从本地存储列表中随机更换当前群名称
本地存储列表	群管理员 / 群主	否	群聊	分页查看当前群的本地头像/名称存储列表
使用本地存储项	群管理员 / 群主	否	群聊	按序号立即使用当前群的本地头像或名称资源
删除本地存储项	群管理员 / 群主	否	群聊	按序号删除当前群的本地头像或名称资源
bot修改头像	超级管理员	否	私聊 / 群聊	立即修改机器人头像
bot修改名称	超级管理员	否	私聊 / 群聊	立即修改机器人名称
bot定时修改头像	超级管理员	否	私聊 / 群聊	为机器人自身创建头像定时修改任务
bot定时修改名称	超级管理员	否	私聊 / 群聊	为机器人自身创建名称定时修改任务
定时列表	超级管理员 / 群管理员 / 群主	否	私聊 / 群聊	查看任务列表；群聊中只显示当前群任务
删除定时	超级管理员 / 群管理员 / 群主	否	私聊 / 群聊	删除指定任务；群聊中仅可删除当前群任务

使用示例

修改 本地头像
修改 本地名称 2
修改头像 https://example.com/avatar.jpg
修改头像 https://example.com/avatar_list.txt
修改头像 https://example.com/avatar_list.txt && ./avatars
修改名称 新群名
修改名称 name_list.txt
修改名称 name_list.txt && 备用群名
定时修改头像 0 8 * * * https://example.com/avatar.jpg
定时修改头像 0 8 * * * https://example.com/avatar_list.txt
定时修改头像 0 8 * * * https://example.com/avatar_list.txt && ./avatars
定时修改名称 0 8 * * * 新群名
定时修改名称 0 8 * * * name_list.txt
定时修改名称 0 8 * * * name_list.txt && 备用群名
上传
取消
随机头像
随机名称
本地存储列表
本地存储列表 头像 2
本地存储列表 名称 1
使用本地存储项 头像 3
使用本地存储项 名称 2
删除本地存储项 头像 3
删除本地存储项 名称 2
bot修改头像 https://example.com/avatar.jpg
bot修改名称 新昵称
bot定时修改头像 0 9 * * 1 https://example.com/avatar.jpg
bot定时修改名称 0 9 * * 1 name_list.txt
删除定时 avatar_group_20260409100000

清单规则

• 头像清单使用 txt 文件，每行一个图片直链或本地图片路径
• 名称清单使用 txt 文件，每行一个名称
• 推荐使用英文文件名，例如 avatar_list.txt 和 name_list.txt
• 多个资源来源可使用 && 连接，例如 avatar_list.txt && ./avatars 或 name_list.txt && 备用名称
• 本地头像 和 本地名称 可作为关键字直接调用已上传的本地资源池
• 定时任务执行时会重新读取 txt 清单，并与当前群已上传资源合并
• 上传资源按群隔离存放，不会被 txt 清单覆盖
• 上传图片会保存到 data 目录，并记录到本群本地头像存储列表
• 上传名称会写入本群本地名称存储列表

上传与随机切换

• 发送 上传 后，下一条图片消息会保存为本群头像资源
• 发送 上传 后，下一条文本消息会保存为本群名称资源
• 在上传等待状态中发送 取消 可终止当前上传任务
• 发送 随机头像 会从本群本地头像存储列表中随机选择一项并立即更换
• 发送 随机名称 会从本群本地名称存储列表中随机选择一项并立即更换
• 发送 修改 本地头像 或 修改 本地名称 会立即从本地资源池调用对应资源
• 发送 使用本地存储项 头像 3 或 使用本地存储项 名称 2 可按编号精确调用本地资源
• 发送 本地存储列表 会显示本群头像/名称资源数量摘要
• 发送 本地存储列表 头像 1 或 本地存储列表 名称 1 可分页查看具体内容
• 列表中的编号为全局序号，可直接配合 删除本地存储项 头像 3 或 删除本地存储项 名称 2 使用

Cron 示例

0 8 * * *    每天 8 点执行
0 0 8 * * *  每天 8 点整执行（6 段，包含秒）
0 9 * * 1    每周一 9 点执行
0 0 9 * * 1 2026  2026 年内每周一 9 点整执行（7 段，包含秒和年）
*/30 * * * * 每 30 分钟执行一次

任务存储

• data/avatar_manager/tasks.json：保存定时任务
• data/avatar_manager/temp：保存下载的临时图片