后端即时通讯【免费下载链接】wxpy微信机器人 / 可能是最优雅的微信个人号 API ✨✨项目地址https://gitcode.com/gh_mirrors/wx/wxpy点击查看免费下载本文以 wxpy 的 Bot 机器人对象文档 为核心脉络系统讲解微信个人号机器人核心对象Bot的初始化登录、聊天对象获取与搜索、加好友与建群、文件上传与多开控制等完整能力。读完本文你将掌握Bot的全部初始化参数与回调用法、puid稳定唯一 ID 的启用方式、基于关键词与属性组合的搜索技巧以及自动接受好友请求、创建群聊等多开实战方案并可从源码层面理解其底层实现原理。Bot对象是 wxpy 的入口可被理解为一个Web 微信客户端。它负责扫码登录、消息收发监听、聊天对象的管理与调度几乎所有 wxpy 功能都从创建一个Bot实例开始。from wxpy import * bot Bot()关于消息的发送可参见 chats 文档关于消息对象与自动处理可参见 messages 文档。本文聚焦Bot本身的初始化、登录、聊天对象管理与相关操作。初始化与登录Bot在初始化时便会执行登录操作需要手机扫描二维码确认登录这一点在 wxpy/api/bot.py 的__init__中直接调用itchat的auto_login()实现扫描的是 Web 微信二维码。构造参数详解Bot.__init__提供多个参数用于控制缓存、二维码显示方式与生命周期回调完整定义见 wxpy/api/bot.py参数默认值作用cache_pathNone会话缓存路径开启后可在短时间内避免重复扫码console_qrFalse在终端中显示登录二维码需安装pillow模块qr_pathNone保存二维码的路径qr_callbackNone获得二维码后的回调函数login_callbackNone登录成功后的回调logout_callbackNone登出时的回调cache_path扫码缓存避免重复登录设为None默认时不开启缓存每次运行都要重新扫码设为True时使用默认缓存路径wxpy.pkl源码中会做cache_path wxpy.pkl的转换见 wxpy/api/bot.py设为具体路径字符串时使用该路径保存登录状态。开启缓存后短时间内再次运行无需扫码缓存失效时会重新要求登录。该缓存最终被透传给itchat的auto_login(hotReload..., statusStorageDir...)并由Bot.dump_login_status()落盘。console_qr无图形界面的终端二维码适用于服务器、树莓派等纯命令行环境登录二维码直接以字符形式打印在终端传True时在内部被当作整数2单元格宽度为 2传正整数表示二维码单元格宽度传负数表示以反色显示二维码适合浅底深字的命令行界面。例如大部分 Linux 终端可设True或2而 macOS Terminal 默认白底配色下应设-2。使用终端二维码需要安装pillow模块pip3 install pillow。若运行环境没有图形界面又未指定console_qr初始化时会因找不到xdg-open而抛出异常源码中专门对此做了提示见 wxpy/api/bot.py。# 在纯命令行环境登录终端打印反色二维码 bot Bot(console_qr-2, cache_pathbot.pkl)回调参数qr_callback获得二维码后的回调接收参数(uuid, status, qrcode)可用于自定义二维码的处理方式如推送到其他设备、转存图片等login_callback登录成功后的回调若不指定wxpy 默认会执行清屏并删除二维码文件logout_callback登出时的回调。自动完成的后台工作初始化除了登录还会自动完成若干准备工作见 wxpy/api/bot.py对底层itchat.Core()的会话连接做增强enhance_connection构建机器人自身聊天对象self与文件传输助手file_helper初始化消息队列messages、注册中心registered启动消息监听线程self.start()并注册进程退出时的清理动作atexit。因此创建Bot()之后即可直接收发消息无需额外启动步骤。登出与生命周期bot.logout()登出当前账号见 wxpy/api/bot.pybot.alive只读属性登录状态为True否则为Falsebot.join()堵塞当前进程直到消息监听结束例如机器人被登出时适合在脚本主流程末尾保持程序运行见 wxpy/api/bot.py。启用 puid稳定唯一的聊天对象 ID微信的user_name、wxid等 ID 属性会因隐私策略、会话变化等原因不可获取或发生改变Chat类文档对此有明确说明见 wxpy/api/chats/chat.py。为此 wxpy 提供了puidwxpy 特有的聊天对象/用户 ID可始终被获取到且具有稳定的唯一性非常适合长期持久化保存。启用方式为调用Bot.enable_puid()可指定映射数据的保存/载入路径见 wxpy/api/bot.pybot Bot(cache_pathTrue) # 启用 puid 属性指定映射数据保存/载入路径 bot.enable_puid(wxpy_puid.pkl) # 指定一个好友 my_friend bot.friends().search(游否)[0] # 查看他的 puid print(my_friend.puid) # edfe8468从源码看enable_puid()会构造一个PuidMap见 wxpy/utils/puid_map.py其中维护 4 个双向映射字典user_name - puid、wxid - puid、remark_name - puid、caption(昵称, 性别, 省份, 城市) - puid。查询某个聊天对象的puid时按顺序用其自身的user_name、wxid、remark_name、caption轮询这 4 个字典命中任一映射则复用已有puid并把其他属性补充进映射全部未命中则为该对象生成新的puid默认取user_name后 8 位。映射数据会在退出时自动pickle落盘、下次启动自动载入。注意puid 映射数据不可跨机器人使用且调用bot.enable_puid()前访问chat.puid会抛出TypeError提示先启用 puid见 wxpy/api/chats/chat.py。相关行为在测试用例TestBot.test_enable_puid中有验证见 tests/api/test_bot.py。获取聊天对象Bot初始化后可通过以下属性与方法获取各类聊天对象。所有“合集”对象好友、群、公众号、全部聊天均为Chats类型——它是list的子类支持搜索、统计与加法合并见 wxpy/api/chats/chats.py。机器人自身与文件传输助手# 机器人账号自身作为一个聊天对象 myself bot.self # 文件传输助手 bot.file_helper.send(Hello from wxpy!)bot.self机器人自身是一个User对象对应源码中的User(self.core.loginInfo[User], self)见 wxpy/api/bot.py。若需要给自己发送消息需先在 Web 微信中把自己加为好友进行一次性的操作# 在 Web 微信中把自己加为好友 bot.self.add() bot.self.accept() # 发送消息给自己 bot.self.send(能收到吗)bot.file_helper文件传输助手常用于调试时快速给自己传文件或文本对应源码中的Chat(wrap_user_name(filehelper), self)。获取好友 / 群聊 / 公众号 / 全部聊天方法返回类型说明bot.friends(updateFalse)ChatsFriend 合集获取所有好友bot.groups(updateFalse, contact_onlyFalse)Groups获取所有群聊bot.mps(updateFalse)ChatsMP 合集获取所有公众号bot.chats(updateFalse)Chats获取全部聊天对象不传参数时从本地缓存itchat 的storageClass读取速度快传updateTrue时强制向服务器同步最新数据。groups()的contact_onlyTrue可只获取保存为联系人的群聊。另外需注意一些不活跃的群可能无法被获取到可通过在群内发言或修改群名称来激活见 wxpy/api/bot.py。bot.chats()内部等价于friends() groups() mps()这一关系在测试TestBot.test_chats中被断言验证见 tests/api/test_bot.py。# 更新并获取所有好友 my_friends bot.friends(updateTrue) # 获取全部聊天对象 all_chats bot.chats()auto_mark_as_read自动消除小红点bot.auto_mark_as_read默认为False设为True后机器人收到新消息时将自动调用mark_as_read()消除手机端的新消息小红点提醒。源码中该逻辑位于消息处理流程_process_message内处理完消息后若auto_mark_as_read为真、消息非系统消息且发送者不是自己则对聊天对象执行mark_as_read()见 wxpy/api/bot.py。底层通过 Web 微信的webwxstatusnotify接口实现见 wxpy/api/chats/chat.py。搜索聊天对象Bot与各类合集Chats、Groups都提供了search()方法用于按关键词与属性组合过滤聊天对象。注意通过.search()获得的搜索结果均为列表Chats对象若希望找到唯一结果应使用ensure_one()。ensure_one()确保列表中仅有一个项并返回该唯一项否则抛出ValueError未找到或找到多个时见 wxpy/utils/tools.py。搜索好友关键词 属性组合# 搜索名称包含 游否 的深圳男性好友 found bot.friends().search(游否, sexMALE, city深圳) # [Friend: 游否] # 确保搜索结果是唯一的并取出唯一结果 youfou ensure_one(found) # Friend: 游否其中sex使用常量MALE值为 1或FEMALE值为 2定义见 wxpy/api/consts.py。搜索群聊成员条件# 搜索名称包含 wxpy且成员中包含 游否 的群聊对象 wxpy_groups bot.groups().search(wxpy, [youfou]) # [Group: wxpy 交流群 1, Group: wxpy 交流群 2]在群聊中搜索成员# 在刚刚找到的第一个群中搜索 group wxpy_groups[0] # 搜索该群中所有浙江的群友 found group.search(province浙江) # [Member: 浙江群友 1, Member: 浙江群友 2, Member: 浙江群友 3 ...]Group.search()实际委托给群成员合集self.members.search()见 wxpy/api/chats/group.py。搜索任何类型的聊天对象# 搜索名称含有 wxpy 的任何聊天对象不包含群内成员 found bot.search(wxpy) # [Friend: wxpy 机器人, Group: wxpy 交流群 1, Group: wxpy 交流群 2]Bot.search()内部等价于self.chats().search(keywords, **attributes)见 wxpy/api/bot.py。搜索匹配规则源码级Chats.search()的实现见 wxpy/api/chats/chats.py其核心是两个匹配函数见 wxpy/utils/misc.py名称匹配match_name不区分大小写关键词可为空白分隔的字符串或多个精准关键词组成的列表要求聊天对象的remark_name备注名、display_name群内显示名、nick_name昵称/群名、wxid中至少有一个属性包含全部关键词属性匹配match_attributes传入的键值对如sexMALE、province浙江、city深圳必须与聊天对象属性或raw数据逐项相等。可用属性键包括sex、province、city、nick_name等。搜索结果会保留source来源Bot或Group测试用例TestBot.test_search验证了搜索返回类型与来源见 tests/api/test_bot.py。此外合集还提供了stats()与stats_text()方法可统计合集内用户按性别、省份、城市等属性的分布情况见 wxpy/api/chats/chats.py。加好友与建群主动添加好友与公众号# 添加用户为好友user 可为用户对象或 user_name bot.add_friend(user, verify_content我是 xxx) # 添加/关注公众号 bot.add_mp(mp)Bot.add_friend(user, verify_content)添加用户为好友verify_content为验证说明信息。底层调用core.add_friend(status2, ...)见 wxpy/api/bot.pyBot.add_mp(user)添加/关注公众号底层调用core.add_friend(status1, ...)见 wxpy/api/bot.py。接受好友请求Bot.accept_friend(user, verify_content)接受用户为好友成功后返回新的好友对象Friend。底层通过core.add_friend(status3, ...)实现见 wxpy/api/bot.py。自动接受好友请求是常见玩法注册好友请求类消息msg_typesFRIENDS在回调中判断验证文本并调用accept_friend# 注册好友请求类消息 bot.register(msg_typesFRIENDS) # 自动接受验证信息中包含 wxpy 的好友请求 def auto_accept_friends(msg): # 判断好友请求中的验证文本 if wxpy in msg.text.lower(): # 接受好友 (msg.card 为该请求的用户对象) new_friend bot.accept_friend(msg.card) # 或 new_friend msg.card.accept() # 向新的好友发送消息 new_friend.send(哈哈我自动接受了你的好友请求)创建群聊# users 为用户列表不含自己至少 2 位topic 为群名称 new_group bot.create_group(users, topicwxpy 交流群)Bot.create_group()的实现见 wxpy/api/bot.py建群前会先通过except_self排除机器人自身再调用core.create_chatroom()成功后返回新的Group对象。建群后还可配合群对象的方法继续操作group.add_members(users, use_invitationFalse)拉人入群use_invitationTrue时改为发送邀请、group.remove_members(members)移出成员、group.rename_group(name)修改群名见 wxpy/api/chats/group.py。TestBot.test_create_group对建群、改名等流程有完整测试见 tests/api/test_bot.py。其他常用操作获取用户详细信息Bot.user_details(user_or_users, chunk_size50)可获取单个或批量获取多个用户的详细信息地区、性别、签名等但不可用于群聊成员。传入列表时按chunk_size目前为 50分批请求见 wxpy/api/bot.py# 获取单个好友的详细信息 details bot.user_details(my_friend)上传文件获取 media_idBot.upload_file(path)上传文件并返回media_id可用于重复发送图片、表情、视频和文件避免每次发送都重复上传。源码会根据扩展名自动判断上传类型.bmp/.png/.jpeg/.jpg/.gif按图片上传、.mp4按视频上传其余按普通文件上传见 wxpy/api/bot.py# 上传一次获取 media_id media_id bot.upload_file(logo.png) # 后续发送给多个好友时直接复用 media_id省略上传过程 friend_a.send_image(logo.png, media_idmedia_id) friend_b.send_image(logo.png, media_idmedia_id)该用法在测试TestBot.test_upload_file中被验证见 tests/api/test_bot.py。控制多个微信多开wxpy 天然支持多开仅需初始化多个Bot对象即可同时控制多个微信bot1 Bot(cache_pathbot1.pkl) bot2 Bot(cache_pathbot2.pkl) # 分别操作两个机器人 bot1.file_helper.send(来自 bot1) bot2.file_helper.send(来自 bot2)每个Bot实例都独立持有自己的itchat.Core()见 wxpy/api/bot.py因此消息监听、聊天对象与缓存互不干扰。多开场景下尤其建议为每个机器人指定独立的cache_path与enable_puid路径便于各自持久化登录状态与 puid 映射注意 puid 映射数据不可跨机器人混用。总结Bot对象是 wxpy 一切能力的起点其核心价值在于初始化即登录通过cache_path、console_qr与各类回调参数覆盖图形环境、纯命令行环境与长期运行场景对象化聊天管理self、file_helper、friends()、groups()、mps()、chats()一应俱全配合Chats合集的搜索与统计能力可灵活定位任意聊天对象puid 稳定 IDenable_puid()提供的 puid 解决了原生 ID 不稳定、不可持久化的问题社交操作闭环加好友、接受好友请求、关注公众号、建群、拉人、移人、改群名配合消息注册机制可实现全自动的账号运营多开支持多个Bot实例互不干扰可同时管理多个微信账号。建议在小号上运行机器人详见 index 文档中的风险提示并关注 Web 微信的接口频率限制避免触发风控。下一阶段可继续阅读 chats 文档 了解各聊天对象的具体方法与群成员管理以及 messages 文档 掌握消息注册与自动回复机制。赞分享后端即时通讯【免费下载链接】wxpy微信机器人 / 可能是最优雅的微信个人号 API ✨✨项目地址https://gitcode.com/gh_mirrors/wx/wxpy点击查看免费下载相关推荐ItChat 通讯录管理全指南好友、公众号、群聊的获取、搜索与 Uin 唯一标识详解ItChat 通讯录管理全指南好友、公众号、群聊的获取、搜索与 Uin 唯一标识详解 在使用个人微信的过程中任何一个基于 ItChat 的机器人程序都绕不开即时通讯后端如何快速上手Nextcloud News Android新手必备的5分钟配置指南如何快速上手Nextcloud News Android新手必备的5分钟配置指南 Nextcloud News Android是一款专为Nextcloud新闻上一篇3个常见风扇控制难题用FanControl轻松解决的实用指南下一篇15分钟实战部署Keep开源AIOps平台构建企业级告警治理体系创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考