--- url: /docs/install.md --- # 一、环境配置和安装 ## 一、环境配置 :::warning 技术边界 wxauto 基于 Windows UI Automation 与用户本人已经正常登录的桌面应用界面交互。 项目不提供协议破解、DLL 注入、内存修改、身份验证或验证码绕过、风险控制或登录限制规避、自动换号、账号养号以及未经授权的数据访问能力。如果目标软件限制某项操作，wxauto 不承诺通过其他技术手段突破该限制。 ::: | 环境 | 版本 | | :----: | :----------------------------------------: | | Python | 3.9、3.10、3.11、3.12、3.13 | | OS | Windows10、11, Windows Server2016、2019、2022 | | 微信 | 4.1 | ## 二、安装&激活 :::info 文档中，方法名前标注“✨”的为plus专用方法。 ::: ### 免费版 ```shell pip install wxauto4 ``` ::: warning ⚠️ 仅支持 python 3.9-3.12 ::: ::: warning 免费版版本兼容 最新支持到客户端 [4.1.8.107](https://github.com/SiverKing/wechat4.0-windows-versions/releases/tag/v4.1.8.107)版本 ::: ### Plus版 ```shell pip install wxautox4 ``` ::: warning ⚠️ 仅支持 python 3.9-3.13 ::: 激活： ```shell wxautox4 auth activate 激活码 ``` :::tip 获取激活码 在[Du'sAPI](https://dusapi.com/register)注册账号，用该账号登录[wxauto](https://wxauto.org/purchase)，即可购买。[关于激活码](/docs/issues.md#激活码有时间限制吗) ::: :::warning 请勿在沙箱环境中激活，否则可能无法作用于计算机正式环境 ！！！ ::: ## 三、测试运行 :::warning 使用边界 请仅在本人有权控制的设备、账号和会话中测试，并优先使用“文件传输助手”。不得将接口用于批量营销、陌生用户触达或规避平台治理。详见[可接受使用政策](/legal/acceptable-use.md)。 ::: ```python title="demo.py" from wxauto4 import WeChat # 免费版 from wxautox4 import WeChat # Plus版 # 初始化微信实例 wx = WeChat() # 切换到文件传输助手 target = "文件传输助手" wx.ChatWith(target) # 查看当前窗口信息 chatinfo = wx.ChatInfo() print(f"当前窗口信息：{chatinfo}") # 发送消息 if chatinfo.get('chat_name') == target: # 先判断是否为要发送的人 wx.SendMsg("你好") # 获取当前聊天窗口消息 msgs = wx.GetAllMessage() for msg in msgs: print(msg.raw) ``` :::tip ✅ 如果测试运行成功，恭喜您，环境配置完成！ ::: --- url: /agreement.md --- # 用户协议 最后更新日期：2026年08月28日 本协议适用于 wxauto 开源组件及 wxautox Plus 商业开发工具（合称“本项目”）。使用、下载、安装或购买前，请仔细阅读本协议、[可接受使用政策](/legal/acceptable-use.md)、[隐私政策](/privacy.md)及适用的授权说明。 ## 1. 项目性质 wxauto 是基于 Windows UI Automation 的本地桌面辅助自动化开发库，目前包含微信桌面客户端适配模块。本项目由独立第三方开发，与腾讯、微信及其他目标软件权利人不存在隶属、合作、官方认证或授权关系。 ## 2. 开源组件 wxauto 开源组件主要用于 Windows UI Automation 的学习、研究和个人开发。具体许可范围以项目随附的开源许可证为准。开源许可证不替代第三方软件的服务协议，也不授予用户访问或使用任何第三方数据的权利。 ## 3. Plus 商业工具 wxautox Plus 为本地桌面自动化开发者提供商业开发工具和技术支持。购买商业授权不代表获得任何第三方软件厂商的授权、许可或认可。授权设备、期限、更新、分发、集成及技术支持范围以[商业授权条款](/legal/commercial-license.md)和购买页面展示的信息为准。 ## 4. 用户义务 - 仅操作本人有权控制的设备、账号、会话和数据； - 遵守适用法律法规、第三方软件服务协议和平台规则； - 对自动化操作设置合理频率、人工确认和异常停止机制； - 在处理他人信息前取得必要授权，并履行告知、保护和删除义务； - 遵守[可接受使用政策](/legal/acceptable-use.md)列明的用途限制。 ## 5. 风险提示 第三方软件的版本、界面、账号状态、服务规则或风险控制机制可能随时变化。本项目无法保证持续兼容，也无法保证使用过程中不会发生操作失败、数据损失、功能限制、账号限制或其他平台处置。用户应在测试环境和小范围对象中验证，并对重要数据进行备份。 ## 6. 违规处置 如有合理依据认为商业授权被用于可接受使用政策禁止的用途，项目方可在法律允许及合同约定范围内拒绝新授权、续费、定制开发或技术支持。项目方不会以本条款为由远程删除用户软件或用户数据。 ## 7. 联系 重大变更将通过项目页面或其他适当方式通知。合规或协议问题请联系 [help@wxauto.org](mailto:help@wxauto.org)。 --- url: /blog/A9dYFme8.md --- # 从 3.9 到 4.x 适配机制的变化 4.x 版本做了更严格的限制，几乎所有方法都需要进行重构。很多人在问，这里说明这些变化的原因。 ## UI 渲染机制 ### 3.9 版本：预加载 在 3.9 客户端，当一个聊天窗口被打开时，系统会**预先加载约 30 条消息的 UI 信息到内存中**。即使这些消息并未显示在当前屏幕的可视区域内，它们依然是可见且可被程序获取的。 ```mermaid graph LR %% 定义样式类，只使用最兼容的属性 %% 包含了圆角 classDef default fill:#f8f9fa,stroke:#d0d7de,color:#1d1d1f,rx:12,ry:12; classDef highlight fill:#ffffff,stroke:#007aff,color:#1d1d1f,rx:12,ry:12; classDef decision fill:#e9ecef,stroke:#6c757d,color:#1d1d1f,rx:8,ry:8; A[打开聊天窗口] B[加载~30条消息] C{获取消息} D[直接获取] E[滚动至可视区操作] F[直接操作] A --> B B --> C C -- "在可视区" --> D C -- "不在可视区" --> D D -- "在可视区" --> F D -- "不在可视区" --> E class A,B,C,D,E,F highlight; ``` ### 4.x 版本：实时渲染 现在 4.x 版本，UI 加载逻辑变为 **“实时渲染”** ，只有那些真正出现在屏幕可见范围内的消息，其 UI 信息才会被加载到内存中。 ```mermaid graph LR classDef default fill:#f8f9fa,stroke:#d0d7de,color:#1d1d1f,rx:12,ry:12; classDef highlight fill:#ffffff,stroke:#007aff,color:#1d1d1f,rx:12,ry:12; classDef decision fill:#e9ecef,stroke:#6c757d,color:#1d1d1f,rx:8,ry:8; A[打开聊天窗口] B[仅加载可见区消息UI] C{滚动窗口} D[新消息进入可见区, UI被加载] E[旧消息离开可见区, UI被卸载] F[可操作] G[不可操作] A --> B B --> C C --> D C --> E D --> F E --> G class A,B,C,D,E,F,G highlight; ``` #### 所以可能存在：新版本监听失效的问题 如果窗口尺寸过小，或者一瞬间涌入大量消息，导致新消息一闪而过，那么这条新消息的 UI 会立即被加载然后又被卸载。用于判断是否有新消息的 UI 锚点也会被顶到消息窗口外，导致消息监听功能彻底失效 。 为了解决这个问题，给 4.x 版本做了**自动调整窗口尺寸**的机制。在执行监控任务时，程序会自动将聊天窗口的纵向高度拉至最大，以确保在单屏内可以加载尽可能多的消息 UI，从而最大限度地保留新消息的判断锚点。 ![短尺寸示意图](/images/blog_short_msgbox.png?text=短尺寸示意图)短尺寸示意图 容纳更少的消息 ![长尺寸示意图](/images/blog_long_msgbox.png?text=长尺寸示意图)长尺寸示意图 容纳更多的消息 :::tip 有些系统因显示器的不同导致最大分辨率上限很小，即使设置到最大尺寸也显示不了几条消息，所以在可能的情况下，如果有一个竖向显示器会比较好; 我后续会找一下有没有不用显示器自定义尺寸的可能 ::: ## `GetNextNewMessage`方法的变化 由于上述 UI 渲染机制的根本性改变，`GetNextNewMessage` 方法也不得不进行重大调整。 ### 主要变化 - **引入 `callback` 回调参数**：方法不再返回可持久操作的消息对象。 - **获取后关闭窗口**：方法执行完毕后，会自动关闭当前聊天窗口。 ### 原因 - **3.9 版本**：当用户滚动聊天记录，一条消息滚出可视范围再滚回来时，它的 UI 对象**依然有效**，可以被程序持续操作。 - **4.x 版本**：任何消息一旦滚出可视范围，其 UI 对象就会被立刻销毁。当它再次滚回可视区时，系统会为它**重新生成一个新的运行时 ID 的 UI 对象**。 `GetNextNewMessage` 方法无法像 3.9 版本一样返回消息对象后，再利用这个对象去进行“引用”、“下载图片”等后续操作。因为当拿到这个对象时，它可能已经因为的滚动而失效了。 **为什么给`GetNextNewMessage`添加 `callback`参数** 目前采用了**回调**模式。所有需要对该消息进行的操作，都必须在 `callback` 函数中完成，例如下载图片、文件、语音转文字等。这样可以确保所有操作都在该消息 UI 对象“存活”的极短窗口期内执行。 :::warning 不能在 `callback` 函数中调用`发送`、`引用`等操作，因为这些操作会将窗口重置到新消息位置，导致后续获取历史消息的操作无法继续进行。 ::: **为什么`GetNextMessage`方法会关闭当前窗口** 在 3.9 版本中，可以先向上滚动获取历史消息，再滚动回底部，因为新消息的判断锚点始终存在。但在 4.x 版本，一旦向上滚动，底部的最新消息 UI 就会被卸载，也就丢失了“最新消息”的判断锚点。此时，没办法判断新消息。 所以目前的“变通方案”是：**获取完消息后直接关闭窗口**。这样，该会话在主列表的“未读”计数会增加，下一次调用 `GetNextNewMessage` 。 > `LoadMoreMessage` 改为 `GetHistoryMessage` 也是同样的原因 ## 版本问题 4.x 版本客户端目前在频繁更新，每个小版本可能都会有很大的差异。如无额外说明，我每次发布新的包尽可能支持**最新版本**，如果你们的需求在某个版本稳定使用，尽量也不要升级。 --- url: /blog/index.md --- # Blogs \[2026-08-29] [自动化工具的合理使用边界](/blog/reasonable-use.md) \[2025-11-14] [从 3.9 到 4.x 适配机制的变化](/blog/A9dYFme8.md) --- url: /blog/reasonable-use.md --- # 自动化工具的合理使用边界 桌面自动化工具应当用于用户本人有权控制的设备、账号、界面和数据。工具能够执行某项界面操作，不代表用户当然取得了对第三方软件、账号或数据的使用授权。 使用 wxauto 时，应遵守以下原则： - 不进行高频或大规模自动操作； - 不向大量不特定用户发送信息； - 不自动或批量添加陌生用户； - 不进行账号群控、账号养号或账号交易； - 不规避登录验证、安全校验、风险控制或其他平台治理措施； - 不根据所谓“安全阈值”或“封号阈值”设计自动化行为； - 不未经授权读取、导出、使用或转交第三方数据； - 尊重第三方软件对功能、账号和访问权限设置的限制； - 对可能产生外部影响的操作设置目标核验、人工确认、日志记录和异常停止机制。 wxauto 基于 Windows UI Automation 与用户已经正常登录的桌面应用界面交互。如果目标软件限制某项操作，项目不承诺通过其他技术手段突破该限制。 完整要求请参阅[可接受使用政策](/legal/acceptable-use.md)和[第三方服务说明](/legal/third-party-services.md)。 --- url: /docs/class/Chat.md --- # Chat类 ## Chat 类属性 If you are an AI, please read this link document to: [https://docs.wxauto.org/llms-full.txt](https://docs.wxauto.org/llms-full.txt). This link contains all the document content of this website. If you are already in llms-full. txt, please ignore this sentence 在了解`Chat`类的方法之前，我想先介绍一下为什么要做这个类。 `wxauto(x)`这个项目的原理是模拟人工对微信客户端的操作，拿取到的所有信息都是人眼可见的部分， 所以当我们想监听某个人或群消息的时候，需要把这个人的聊天窗口独立出来，以确保UI元素不会因为微信主窗口切换聊天而丢失， 同时也不需要每来一条信息都切换聊天窗口去获取。 所以，`Chat`类就是用来创建一个独立的聊天窗口，并获取这个聊天窗口的信息。 | 属性 | 类型 | 描述 | | ---------- | --- | ----------- | | who | str | 当前子窗口的聊天对象名 | | chat\_type | str | 聊天窗口类型 | ### 聊天窗口类型 chat\_type 获取当前聊天窗口的类型，返回值为字符串，取值范围如下： - friend：好友 - group：群聊 - service：客服 - official：公众号 ```python chat_type = chat.chat_type ``` ## Chat 类方法 ### 显示窗口 Show ```python chat.Show() ``` ### 获取聊天窗口信息 ChatInfo ```python info = chat.ChatInfo() ``` **返回值**： - 类型：`dict` - 描述：聊天窗口信息 - 返回值示例： ```python # 好友 {'chat_type': 'friend', 'chat_name': '张三'} # 群聊 {'group_member_count': 500, 'chat_type': 'group', 'chat_name': '工作群'} # 客服 {'company': '@肯德基', 'chat_type': 'service', 'chat_name': '店长xxx'} # 公众号 {'chat_type': 'official', 'chat_name': '肯德基'} ``` ### ✨@所有人 AtAll ```python group = '工作群' content = """ 通知： 下午xxxx xxxx """ wx.AtAll(content, group) ``` msg (str): 发送的消息 ​ who (str, optional): 发送给谁. Defaults to None. ​ exact (bool, optional): 是否精确匹配. Defaults to False. **参数**： | 参数 | 类型 | 默认值 | 描述 | | ----- | ---- | ----- | ------ | | msg | str | None | 发送的消息 | | who | str | None | 发送给谁 | | exact | bool | False | 是否精确匹配 | **返回值**： - 类型：[`WxResponse`](/docs/class/other/#wxresponse) - 描述：是否发送成功 ### 发送消息 SendMsg :::warning 🟡 自动交互接口 该接口用于用户本人控制对象中的低频辅助操作。请勿用于批量营销、垃圾信息、骚扰或向大量不特定用户发送信息。 ::: ```python wx.SendMsg(msg="你好", who="文件传输助手", clear=True, exact=True) ``` **参数**： | 参数 | 类型 | 默认值 | 描述 | | ----- | ----------------------- | ----- | ---------------------------------- | | msg | str | 必填 | 消息内容 | | who | str | None | 发送对象，不指定则发送给当前聊天对象，**当子窗口时，该参数无效** | | clear | bool | True | 发送后是否清空编辑框 | | at | Union\[str, List\[str]] | None | @对象，不指定则不@任何人 | | exact | bool | False | 搜索who好友时是否精确匹配，**当子窗口时，该参数无效** | **返回值**： - 类型：[`WxResponse`](/docs/class/other/#wxresponse) - 描述：是否发送成功 ### 发送文件 SendFiles ```python wx.SendFiles(filepath="C:/文件.txt", who="文件传输助手", exact=True) ``` **参数**： | 参数 | 类型 | 默认值 | 描述 | | -------- | --------- | ----- | ---------------------------------- | | filepath | str\|list | 必填 | 要复制文件的绝对路径 | | who | str | None | 发送对象，不指定则发送给当前聊天对象，**当子窗口时，该参数无效** | | exact | bool | False | 搜索who好友时是否精确匹配，**当子窗口时，该参数无效** | **返回值**： - 类型：[`WxResponse`](/docs/class/other/#wxresponse) - 描述：是否发送成功 ### ✨发送语音 SendAudio \[Beta] 发送语音条消息 ```python wx.SendAudio(filepath="C:/audio.mp3", duration=5) ``` :::warning 该方法为Beta功能，需最新4.1.9+版本客户端，以及需要[额外配置](/read/audio_settings.md)，可能暂不稳定 ::: **参数**： | 参数 | 类型 | 默认值 | 描述 | | ------------ | --------- | ----- | ---------------------------------- | | filepath | str\|list | 必填 | 音频文件的路径 | | duration | int | None | 要发送的时长（秒），例如原文件有10秒，可指定只发3秒 | | start | int | 0 | 从第几秒开始发送 | | who | str | None | 发送对象，不指定则发送给当前聊天对象，**当子窗口时，该参数无效** | | exact | bool | False | 搜索who好友时是否精确匹配，**当子窗口时，该参数无效** | | max\_retries | int | 3 | 最大重试次数 | **返回值**： - 类型：[`WxResponse`](/docs/class/other/#wxresponse) - 描述：是否发送成功 ### 获取当前聊天窗口的所有消息 GetAllMessage ```python messages = wx.GetAllMessage() ``` **返回值**： - 类型：List\[[Message](#message-类方法)] - 描述：当前聊天窗口的所有消息 ### ✨添加群成员 AddGroupMembers ```python wx.ChatWith('工作群') wx.AddGroupMembers(members=["张三", "李四"]) ``` **参数**： | 参数 | 类型 | 默认值 | 描述 | | ------- | ----------------------- | ---- | --------- | | members | Union\[str, List\[str]] | None | 成员名或成员名列表 | **返回值**： - 类型：[`WxResponse`](/docs/class/other/#wxresponse) - 描述：是否添加成功 :::tip 注意 该方法与3.9版本参数做出了一些变动，3.9支持传入`group`参数来切换，现在改为配合`ChatWith`方法来切换后再添加 ::: ### ✨修改群聊名称 SetGroupName ```python chat.SetGroupName(value="新群名") ``` **参数**： | 参数 | 类型 | 默认值 | 描述 | | ----- | --- | --- | ------ | | value | str | 必填 | 新的群聊名称 | **返回值**： - 类型：[`WxResponse`](/docs/class/other/#wxresponse) - 描述：是否修改成功 ### ✨修改群聊备注 SetGroupRemark ```python chat.SetGroupRemark(value="群备注") ``` **参数**： | 参数 | 类型 | 默认值 | 描述 | | ----- | --- | --- | ------ | | value | str | 必填 | 新的群聊备注 | **返回值**： - 类型：[`WxResponse`](/docs/class/other/#wxresponse) - 描述：是否修改成功 ### ✨修改群公告 SetGroupAnnouncement ```python chat.SetGroupAnnouncement(value="群公告内容") ``` **参数**： | 参数 | 类型 | 默认值 | 描述 | | ----- | --- | --- | ------- | | value | str | 必填 | 新的群公告内容 | **返回值**： - 类型：[`WxResponse`](/docs/class/other/#wxresponse) - 描述：是否修改成功 ### ✨修改我在群里的昵称 SetGroupMyNickname ```python chat.SetGroupMyNickname(value="我的群昵称") ``` **参数**： | 参数 | 类型 | 默认值 | 描述 | | ----- | --- | --- | ------ | | value | str | 必填 | 新的群内昵称 | **返回值**： - 类型：[`WxResponse`](/docs/class/other/#wxresponse) - 描述：是否修改成功 ### 关闭窗口 Close ```python wx.Close() ``` --- url: /docs/class/Message.md --- # Message类 :::warning 接口使用边界 联系人、好友申请和消息操作仅限本人有权处理的对象。请勿用于批量处理、陌生人营销、未经授权的数据收集或其他[可接受使用政策](/legal/acceptable-use.md)禁止的用途。 ::: 消息类中，有两个固定属性： - **`attr`**：消息属性，即消息的来源属性 - system：系统消息 - self：自己发送的消息 - friend：好友消息 - other：其他消息 - **`type`**：消息类型，即消息的内容属性 - time：时间消息 - text：文本消息 - quote：引用消息 - voice：语音消息 - image：图片消息 - video：视频消息 - file：文件消息 - location：位置消息 - link：链接消息 - emotion：表情消息 - merge：合并转发消息 - personal\_card：个人名片消息 - note: 笔记消息 - other：其他消息 而`self`和`friend`又可以跟消息类型所组合，所以所有消息类别如下： | | [自己发送的消息`SelfMessage`](#selfmessage) | [对方发来的消息`FriendMessage`](#friendmessage) | | :------------------------------------------------: | :----------------------------------: | :--------------------------------------: | | [✨文本消息`TextMessage`](#textmessage) | SelfTextMessage | FriendTextMessage | | [✨引用消息`QuoteMessage`](#quotemessage) | SelfQuoteMessage | FriendQuoteMessage | | [✨语音消息`VoiceMessage`](#voicemessage) | SelfVoiceMessage | FriendVoiceMessage | | [✨图片消息`ImageMessage`](#imagemessage) | SelfImageMessage | FriendImageMessage | | [✨视频消息`VideoMessage`](#videomessage) | SelfVideoMessage | FriendVideoMessage | | [✨文件消息`FileMessage`](#filemessage) | SelfFileMessage | FriendFileMessage | | [✨位置消息`LocationMessage`](#locationmessage) | SelfLocationMessage | FriendLocationMessage | | [✨链接消息`LinkMessage`](#linkmessage) | SelfLinkMessage | FriendLinkMessage | | [✨表情消息`EmotionMessage`](#emotionmessage) | SelfEmotionMessage | FriendEmotionMessage | | [✨合并消息`MergeMessage`](#mergemessage) | SelfMergeMessage | FriendMergeMessage | | [✨名片消息`PersonalCardMessage`](#personalcardmessage) | SelfPersonalCardMessage | FriendPersonalCardMessage | | [✨笔记消息`NoteMessage`](#notemessage) | SelfNoteMessage | FriendNoteMessage | | [✨其他消息`OtherMessage`](#othermessage) | SelfOtherMessage | FriendOtherMessage | 简单的使用示例： ```python from wxautox4.msgs import * ... # 省略获取消息对象的过程 # 假设你获取到了一个消息对象 msg = ... # 当消息为好友消息时，回复收到 # 方法一： if msg.attr == 'friend': msg.reply('收到') # 方法二： if isinstance(msg, FriendMessage): msg.reply('收到') ``` ## Message 消息基类，所有消息类型都继承自该类 **属性**（所有消息类型都包含以下属性）： | 属性名 | 类型 | 描述 | | :-----: | :--: | --------------------- | | type | str | 消息内容类型 | | attr | str | 消息来源类型 | | info | Dict | 消息的详细信息 | | id | str | 消息UI ID（不重复，切换UI后会变） | | ✨hash | str | 消息hash值（可能重复，切换UI后不变） | | sender | str | 消息发送者 | | content | str | 消息内容 | ### chat\_info 获取该消息所属聊天窗口的信息 ```python chat_info = msg.chat_info() ``` **返回值**： - 类型：`dict` - 描述：聊天窗口信息 - 返回值示例： ```python # 好友 {'chat_type': 'friend', 'chat_name': '张三'} # 群聊 {'group_member_count': 500, 'chat_type': 'group', 'chat_name': '工作群'} # 客服 {'company': '@肯德基', 'chat_type': 'service', 'chat_name': '店长xxx'} # 公众号 {'chat_type': 'official', 'chat_name': '肯德基'} ``` **返回值**： - 类型：List\[str] ### roll\_into\_view 将消息滚动到视野内 ```python msg.roll_into_view() ``` ## SystemMessage 系统消息，没有特殊用法 固定属性： | 属性名 | 类型 | 属性值 | 描述 | | ---- | --- | ------ | ---- | | attr | str | system | 消息属性 | ## TimeMessage 时间消息，继承系统消息 固定属性： | 属性名 | 类型 | 属性值 | 描述 | | ---- | --- | ------------------- | ---------------------- | | attr | str | system | 消息属性 | | type | str | time | 消息类别 | | time | str | yyyy-hh-mm HH:MM:SS | 时间，yyyy-hh-mm HH:MM:SS | ```python from wxautox4.msgs import TimeMessage msg = ... if isinstance(msg, TimeMessage): print(msg.time) # 2026-01-01 12:30:00 ``` ## HumanMessage 人发送的消息，即自己或好友、群友发送的消息 固定属性： | 属性名 | 类型 | 属性值 | 描述 | | ---- | --- | ------ | ---- | | attr | str | friend | 消息属性 | 特有属性： | 属性 | 类型 | 描述 | | ------ | --- | -------------------- | | sender | str | **群消息**中，该消息发送人显示的名称 | ### click 点击该消息，一般特殊消息才会有作用，比如图片消息、视频消息等 ```python msg.click() ``` ### select\_option 右键该消息，弹出右键菜单，并选择指定选项 ```python msg.select_option("复制") ``` **返回值**： - 类型：[`WxResponse`](/docs/class/other/#wxresponse) - 描述：操作结果 ### quote 引用该消息，并回复 ```python msg.quote("回复内容") ``` **参数**： | 参数名 | 类型 | 默认值 | 描述 | | ------- | ----------------------- | --- | --------- | | text | str | 无 | 引用内容 | | at | Union\[List\[str], str] | 无 | @用户列表 | | timeout | int | 3 | 超时时间，单位为秒 | **返回值**： - 类型：[`WxResponse`](/docs/class/other/#wxresponse) - 描述：操作结果 ### forward 转发该消息 ```python # 开源版 msg.forward("张三") # ✨附带消息message参数仅plus版本有效 msg.forward("张三", message="转发会议材料给你，请查收") ``` **参数**： | 参数名 | 类型 | 默认值 | 描述 | | ------- | ----------------------- | ---- | --------- | | targets | Union\[List\[str], str] | 无 | 转发对象名称 | | message | str | None | 要附加的消息 | | timeout | int | 3 | 超时时间，单位为秒 | **返回值**： - 类型：[`WxResponse`](/docs/class/other/#wxresponse) - 描述：操作结果 ### tickle 拍一拍该消息发送人 ```python msg.tickle() ``` **返回值**： - 类型：[`WxResponse`](/docs/class/other/#wxresponse) - 描述：操作结果 ### ✨download\_head\_image 下载该消息发送人的头像 ```python msg.download_head_image() ``` ### ✨edit\_info 编辑该消息发送人的备注和标签 ```python msg.edit_info(add_tags=['同事', '北京'], remove_tags=['老同学'], remark='张三（北京）') ``` **参数**： | 参数名 | 类型 | 默认值 | 描述 | | ------------ | ---------- | ---- | ------------------ | | add\_tags | List\[str] | None | 要添加的标签列表 | | remove\_tags | List\[str] | None | 要移除的标签列表 | | remark | str | None | 要设置的备注，传入空字符串可清除备注 | **返回值**： - 类型：[`WxResponse`](/docs/class/other/#wxresponse) - 描述：操作结果 **说明**： `add_tags`、`remove_tags`、`remark` 三个参数不能同时为 `None`，否则返回失败 ## FriendMessage 好友、群友发送的消息，即聊天页面中，左侧人员发送的消息。继承自[HumanMessage](#humanmessage) ### sender\_info 获取发送人信息 ```python msg.sender_info() ``` **返回值**： - 类型：Dict\[str, str] ### ✨delete\_friend 删除该消息发送人（联系人） ```python msg.delete_friend() # 删除联系人但不清除聊天记录 msg.delete_friend(clear=False) ``` **参数**： | 参数名 | 类型 | 默认值 | 描述 | | ----- | ---- | ---- | ---------- | | clear | bool | True | 是否同时清除聊天记录 | **返回值**： - 类型：[`WxResponse`](/docs/class/other/#wxresponse) - 描述：操作结果 ### ✨add\_friend :::warning 🟠 高风险接口 仅可在用户已主动提交申请、您有权处理且经过人工确认时使用。不得用于自动或批量添加陌生联系人、营销获客或规避平台限制。 ::: 添加该消息发送人为好友（适用于群聊中尚未添加的成员） ```python msg.add_friend(addmsg='已在线下确认身份', remark='已确认联系人', tags=['已确认'], permission='仅聊天') ``` **参数**： | 参数名 | 类型 | 默认值 | 描述 | | ---------- | ---------------------- | ----- | ---------- | | addmsg | str | None | 添加好友时的附加消息 | | remark | str | None | 添加好友后的备注 | | tags | List\[str] | None | 添加好友后的标签 | | permission | Literal\['朋友圈', '仅聊天'] | '朋友圈' | 朋友圈权限 | **返回值**： - 类型：[`WxResponse`](/docs/class/other/#wxresponse) - 描述：操作结果 自己发送的消息，即聊天页面中，右侧自己发送的消息。继承自[HumanMessage](#humanmessage) 固定属性： | 属性名 | 类型 | 属性值 | 描述 | | ---- | --- | ---- | ---- | | attr | str | self | 消息属性 | ## TextMessage 文本消息。继承自[HumanMessage](#humanmessage) 固定属性： | 属性名 | 类型 | 属性值 | 描述 | | ---- | --- | ---- | ---- | | type | str | text | 消息属性 | ## QuoteMessage 引用消息。继承自[HumanMessage](#humanmessage) 固定属性： | 属性名 | 类型 | 属性值 | 描述 | | ---- | --- | ----- | ---- | | type | str | quote | 消息属性 | 特有属性： | 属性名 | 类型 | 属性值 | 描述 | | --------------- | --- | ---------- | ---------- | | quote\_content | str | 被引用消息内容 | 被引用消息内容 | | quote\_nickname | str | 被引用消息发送人昵称 | 被引用消息发送人昵称 | ### ✨download\_quote\_image 下载引用消息中的图片或视频 ```python msg.download_quote_image() ``` **参数**： | 参数名 | 类型 | 默认值 | 描述 | | --------- | ----------------- | ---- | --------------------------------------------------------------------- | | dir\_path | Union\[str, Path] | None | 下载目录，不填则默认[WxParam.DEFAULT\_SAVE\_PATH](/docs/class/other/#wxparam-类) | | timeout | int | 10 | 下载超时时间，单位为秒 | **返回值**： - Path: 文件路径，成功时返回该类型 - None: 引用内容不是图片或视频时返回该类型 **说明**： 仅当引用内容为图片或视频时可下载，其他类型返回 None ## ImageMessage 图片消息。继承自[HumanMessage](#humanmessage) 固定属性： | 属性名 | 类型 | 属性值 | 描述 | | ---- | --- | ----- | ---- | | type | str | image | 消息属性 | ### download 下载图片，返回图片路径 ```python msg.download() ``` **参数**： | 参数名 | 类型 | 默认值 | 描述 | | --------- | ----------------- | ----- | ------------------------------------------------------ | | dir\_path | Union\[str, Path] | None | 下载图片的目录，不填则默认[WxParam.DEFAULT\_SAVE\_PATH](#wxparam-类) | | original | bool | False | 是否下载原图片，默认否 | **返回值**： - Path: 图片路径，成功时返回该类型 - [`WxResponse`](/docs/class/other/#wxresponse): 下载结果，失败时返回该类型 ### ocr 提取图片中的文字 ```python text = msg.ocr(timeout=3) ``` **参数**： | 参数名 | 类型 | 默认值 | 描述 | | ------- | --- | --- | --------- | | timeout | int | 3 | 超时时间，单位为秒 | ## VideoMessage 视频消息。继承自[HumanMessage](#humanmessage) 固定属性： | 属性名 | 类型 | 属性值 | 描述 | | ---- | --- | ----- | ---- | | type | str | video | 消息属性 | ### download 下载视频，返回视频路径 ```python msg.download() ``` **参数**： | 参数名 | 类型 | 默认值 | 描述 | | --------- | ----------------- | ----- | ------------------------------------------------------ | | dir\_path | Union\[str, Path] | None | 下载视频的目录，不填则默认[WxParam.DEFAULT\_SAVE\_PATH](#wxparam-类) | | original | bool | False | 是否下载原视频，默认否 | | timeout | int | 10 | 下载超时时间 | **返回值**： - Path: 视频路径，成功时返回该类型 - [`WxResponse`](/docs/class/other/#wxresponse): 下载结果，失败时返回该类型 ## VoiceMessage 语音消息。继承自[HumanMessage](#humanmessage) 固定属性： | 属性名 | 类型 | 属性值 | 描述 | | ---- | --- | ----- | ---- | | type | str | voice | 消息属性 | ### to\_text 将语音消息转换为文本，返回文本内容 ```python msg.to_text() ``` ## FileMessage 文件消息。继承自[HumanMessage](#humanmessage) 固定属性： | 属性名 | 类型 | 属性值 | 描述 | | ---- | --- | ---- | ---- | | type | str | file | 消息属性 | ### ✨download 下载文件，返回文件路径 ```python msg.download() ``` **参数**： | 参数名 | 类型 | 默认值 | 描述 | | ------------ | ----------------- | ----- | ------------------------------------------------------ | | dir\_path | Union\[str, Path] | None | 下载文件的目录，不填则默认[WxParam.DEFAULT\_SAVE\_PATH](#wxparam-类) | | force\_click | bool | False | 是否强制点击文件消息（当自动下载不可用时指定，否则会打开该文件） | | timeout | int | 10 | 下载超时时间 | **返回值**： - Path: 文件路径，成功时返回该类型 - [`WxResponse`](/docs/class/other/#wxresponse): 下载结果，失败时返回该类型 ## ✨LocationMessage 位置消息。继承自[HumanMessage](#humanmessage) 固定属性： | 属性名 | 类型 | 属性值 | 描述 | | ---- | --- | -------- | ---- | | type | str | location | 消息属性 | ## ✨LinkMessage 链接消息。继承自[HumanMessage](#humanmessage) 固定属性： | 属性名 | 类型 | 属性值 | 描述 | | ---- | --- | ---- | ---- | | type | str | link | 消息属性 | ### ✨get\_url 获取链接地址 ```python msg.get_url() ``` | 参数名 | 类型 | 默认值 | 描述 | | ------- | --- | --- | ------ | | timeout | int | 10 | 下载超时时间 | **返回值**： - str: 链接地址 ## ✨EmotionMessage 表情消息。继承自[HumanMessage](#humanmessage) 固定属性： | 属性名 | 类型 | 属性值 | 描述 | | ---- | --- | ------- | ---- | | type | str | emotion | 消息属性 | ## ✨MergeMessage 合并消息。继承自[HumanMessage](#humanmessage) 固定属性： | 属性名 | 类型 | 属性值 | 描述 | | ---- | --- | ----- | ---- | | type | str | merge | 消息属性 | ## ✨PersonalCardMessage 名片消息。继承自[HumanMessage](#humanmessage) 固定属性： | 属性名 | 类型 | 属性值 | 描述 | | ---- | --- | -------------- | ---- | | type | str | personal\_card | 消息属性 | ### ✨add\_friend :::warning 🟠 高风险接口 调用前应人工确认联系人身份和授权。不得自动循环调用或用于陌生人触达。 ::: 添加好友 ```python msg.add_friend() ``` | 参数名 | 类型 | 默认值 | 描述 | | ---------- | ---------------------- | ----- | ---------- | | addmsg | str | None | 添加好友时的附加消息 | | remark | str | None | 添加好友后的备注 | | tags | List\[str] | None | 添加好友后的标签 | | permission | Literal\['朋友圈', '仅聊天'] | '朋友圈' | 添加好友后的权限 | | timeout | int | 3 | 搜索好友的超时时间 | **返回值**： - [`WxResponse`](/docs/class/other/#wxresponse): 是否添加成功 ## ✨NoteMessage 笔记消息。继承自[HumanMessage](#humanmessage) 固定属性： | 属性名 | 类型 | 属性值 | 描述 | | ---- | --- | ---- | ---- | | type | str | note | 消息属性 | ### ✨get\_content 获取笔记内容 ```python from pathlib import Path note_content_list = msg.get_content() for content in note_content_list: if isinstance(content, str): # 文本内容 print(content) elif isinstance(content, Path): # 文件路径，文件、视频、图片等 print('文件路径：', content) ``` ### ✨save\_files 保存笔记中的文件 ```python msg.save_files() ``` | 参数名 | 类型 | 默认值 | 描述 | | --------- | ----------------- | ---- | ---- | | dir\_path | Union\[str, Path] | None | 保存路径 | **返回值**： - [`WxResponse`](/docs/class/other/#wxresponse): 是否保存成功，若成功则data为保存的文件路径列表 ### ✨to\_markdown 将笔记转换为Markdown格式 ```python msg.to_markdown() ``` | 参数名 | 类型 | 默认值 | 描述 | | --------- | ----------------- | ---- | ---- | | dir\_path | Union\[str, Path] | None | 保存路径 | **返回值**： - Path: markdown文件路径 ## OtherMessage 其他暂未支持解析的消息类型 --- url: /docs/class/Moment.md --- # ✨朋友圈类 ## MomentsWnd **朋友圈窗口**对象，即的是朋友圈的窗口对象，提供对朋友圈窗口的各种操作，如获取朋友圈内容、刷新、关闭等功能。 ![Moments](/images/moment_wnd.png) ```python from wxautox4 import WeChat wx = WeChat() pyq = wx.Moments() # 打开朋友圈并获取朋友圈窗口对象（如果为None则说明你没开启朋友圈，需要在手机端设置） ``` ### ✨GetMoments **获取朋友圈内容** ```python # 获取当前页面的朋友圈内容 moments = pyq.GetMoments() # 通过`next_page`参数获取下一页的朋友圈内容 moments = pyq.GetMoments(next_page=True) ``` **参数**： | 参数 | 类型 | 默认值 | 说明 | | :--------: | :--: | :---: | :-----------------------------------: | | next\_page | bool | False | 是否翻页后再获取 | | speed1 | int | 3 | 翻页时的滚动速度，根据自己的情况进行调整，建议3-10自行调整 | | speed2 | int | 1 | 翻页最后时的速度，避免翻页过多导致遗漏所以一般比speed1慢，建议1-3 | **返回值**：List\[[Moments](#Moments)] ### ✨Refresh **刷新朋友圈** ```python pyq.Refresh() ``` ### ✨close **关闭朋友圈** ```python pyq.Close() ``` ### ✨Publish **发表朋友圈** **参数**： | 参数 | 类型 | 默认值 | 说明 | | :-------------: | :--: | :--: | :-----------------------: | | text | str | 必填 | 朋友圈内容 | | media\_files | list | None | 图片/视频文件路径列表，为None时只发表文字内容 | | privacy\_config | dict | None | 是否翻页后再获取 | ```python text = '''oh 今天天气真好 适合出去走走 嘿嘿~ ''' media_files = [ r"D:\Images\Pictures\1.png", r"D:\Images\Pictures\2.png", r"D:\Images\Pictures\3.png", ] privacy_config = { 'privacy': '白名单', # 设置为黑名单模式 'tags': ['家人','朋友'] # 白名单为仅这些标签能看，黑名单为屏蔽这些标签的人 } # privacy_config = {} # 公开发布，没有任何权限设置 pyq.Publish(text, media_files, privacy_config) ``` ## Moments **朋友圈内容**对象，即的是朋友圈的内容对象，提供对朋友圈的各种操作，如获取朋友圈内容、点赞、评论等功能。 ![Moments](/images/moment.png) ```python # 获取朋友圈对象 moments = pyq.GetMoments() # 获取第一条朋友圈 moment = moments[0] ``` ### ✨获取朋友圈内容 ```python # 获取朋友圈内容 moment.content ``` ### ✨Like **点赞朋友圈** **参数**： | 参数 | 类型 | 默认值 | 说明 | | :--: | :--: | :--: | :-------------: | | like | bool | True | True点赞，False取消赞 | ```python # 点赞 moment.Like() # 取消赞 moment.Like(False) ``` **返回值**：无 ### ✨Comment **评论朋友圈** **参数**： | 参数 | 类型 | 默认值 | 说明 | | :--: | :-: | :-: | :--: | | text | str | 必填 | 评论内容 | ```python # 评论 moment.Comment('评论内容') ``` **返回值**：无 --- url: /docs/class/Other.md --- # 其他类（方法） ### WxResponse 该类用于该项目多个方法的返回值 ```python # 这里假设result为某个方法的WxResponse类型返回值 result: WxResponse = ... # 判断是否成功 if result: data = result['data'] # 成功，获取返回数据，大多数情况下为None else: print(result['message']) # 该方法调用失败，打印错误信息 ``` ### WxParam 该类用于该项目的一些参数，在获取`WeChat`实例前，可以通过修改该类的属性来修改默认参数 | 属性 | 类型 | 默认值 | 描述 | | ------------------------ | ----------------------------- | ---------------------------------- | ---------------------------------------------------------------------------------------------- | | LANGUAGE | Literal\['cn', 'cn\_t', 'en'] | 'cn' | 语言设置，简体中文/繁体中文/英文 | | ENABLE\_FILE\_LOGGER | bool | True | 是否启用日志文件 | | DEFAULT\_SAVE\_PATH | str | ./wxautox | 下载文件/图片默认保存路径 | | ✨MESSAGE\_HASH | bool | False | 是否启用消息哈希值用于辅助判断消息，开启后会稍微影响性能 | | DEFAULT\_MESSAGE\_XBIAS | int | 51 | 头像到消息X偏移量，用于消息定位，点击消息等操作 | | DEFAULT\_MESSAGE\_YBIAS | int | 30 | 头像到消息Y偏移量，用于消息定位，点击消息等操作 | | FORCE\_MESSAGE\_XBIAS | bool | False | 是否强制重新自动获取X偏移量，如果设置为True，则每次启动都会重新获取 | | LISTEN\_INTERVAL | int | 1 | 监听消息时间间隔，单位秒 | | SEARCH\_CHAT\_TIMEOUT | int | 2 | 搜索聊天对象超时时间，单位秒 | | ✨NOTE\_LOAD\_TIMEOUT | int | 30 | 微信笔记加载超时时间，单位秒 | | SEND\_FILE\_TIMEOUT | int | 10 | 发送文件超时时间，单位秒 | | CHAT\_WINDOW\_SIZE | tuple | (800, 6000) | 监听尺寸，由于4.x版本客户端UI机制是显示的部分才注册UIA控件，所以尽可能拉大窗口显示更多消息来提高判断容错 | | SEND\_CONTENT\_RATIO | float | 0.9 | 输入内容相似度，用于判断输入框中的内容是否是要发送的内容，避免发送错误内容。因为存在特殊符号转码问题，可能编辑框内容无法100%与实际传入的字符串相等，所以达到相似度即通过校验，才触发发送 | | GET\_NEXT\_MAX\_QUANTITY | int | 30 | GetNextNewMessage方法最大获取数量 | | GET\_NEXT\_MAX\_RUNTIME | int | 10 | GetNextNewMessage方法最长获取时间，单位秒 | | SPECIAL\_SESSION\_NAME | list | \['公众号', '折叠的聊天', 'QQ邮箱提醒', '服务号'] | 特殊聊天会话名称列表 | | ✨DEFAULT\_STICKERS | list | 见下方列表 | 默认聊天表情列表，包含常用的微信表情符号 | | CALLBACK\_STOP\_SIGN | str | 'stop' | 回调函数结束标识 | | INPUT\_AT\_INTERVAL | float | 0.5 | @成员输入间隔时间，单位秒 | #### DEFAULT\_STICKERS 默认表情列表 WxParam.DEFAULT\_STICKERS 包含了微信的默认表情列表，共计 128 个表情符号： ```python DEFAULT_STICKERS = [ # 基础表情 '[微笑]', '[撇嘴]', '[色]', '[发呆]', '[得意]', '[流泪]', '[害羞]', '[闭嘴]', '[睡]', '[大哭]', '[尴尬]', '[发怒]', '[调皮]', '[呲牙]', '[惊讶]', '[难过]', '[囧]', '[抓狂]', '[吐]', '[偷笑]', '[愉快]', '[白眼]', '[傲慢]', '[困]', '[惊恐]', '[憨笑]', '[悠闲]', '[咒骂]', '[疑问]', '[嘘]', '[晕]', '[衰]', '[骷髅]', '[敲打]', '[再见]', '[擦汗]', '[抠鼻]', '[鼓掌]', '[坏笑]', '[右哼哼]', # 表情和手势 '[鄙视]', '[委屈]', '[快哭了]', '[阴险]', '[亲亲]', '[可怜]', '[笑脸]', '[生病]', '[脸红]', '[破涕为笑]', '[恐惧]', '[失望]', '[无语]', '[嘿哈]', '[捂脸]', '[奸笑]', '[机智]', '[皱眉]', '[耶]', '[吃瓜]', '[加油]', '[汗]', '[天啊]', '[Emm]', '[社会社会]', '[旺柴]', '[好的]', '[打脸]', '[哇]', '[翻白眼]', # 符号和物品 '[666]', '[让我看看]', '[叹气]', '[苦涩]', '[裂开]', '[嘴唇]', '[爱心]', '[心碎]', '[拥抱]', '[强]', '[弱]', '[握手]', '[胜利]', '[抱拳]', '[勾引]', '[拳头]', '[OK]', '[合十]', '[啤酒]', '[咖啡]', # 庆祝和节日 '[蛋糕]', '[玫瑰]', '[凋谢]', '[菜刀]', '[炸弹]', '[便便]', '[月亮]', '[太阳]', '[庆祝]', '[礼物]', '[红包]', '[發]', '[福]', '[烟花]', '[爆竹]', '[猪头]', '[跳跳]', '[发抖]', '[转圈]', '[天啊]', # 其他 '[强]', '[汗]', '[握手]', ] ``` 这些表情可以在发送消息时使用，例如： ```python from wxautox4 import WeChat wx = WeChat() msg_list = wx.ChatWith('文件传输助手') # 发送表情 msg_list.SendMsg('[微笑][拥抱][爱心]') ``` 示例： ```python from wxautox4.param import WxParam # 设置搜索聊天超时时间为10秒 WxParam.SEARCH_CHAT_TIMEOUT = 10 # 自定义表情列表（添加自定义表情） WxParam.DEFAULT_STICKERS = [ '[微笑]', '[撇嘴]', '[色]', # ... 添加更多表情 ] ``` ### WeChatImage ```python from wxautox4.ui.component import WeChatImage imgwnd = WeChatImage() ``` 微信图片/视频**窗口**类，用于处理微信图片或图片窗口的各种操作 ![wxauto\_image\_wnd](/images/wxauto_image_wnd.png) #### save **保存图片/视频** 参数： | 参数名 | 类型 | 默认值 | 说明 | | :-------- | :-- | :--- | :--------------------- | | dir\_path | str | None | 保存的目录路径，None即本地路径下自动生成 | | timeout | int | 10 | 保存超时时间 | 返回值：Path，保存的文件路径 #### close **关闭图片/视频窗口** 参数：无 返回值：无 --- url: /docs/class/Session.md --- # Session类 ## Session 类方法 ```python ... # 此处省略wx对象的初始化 sessionbox = wx.SessionBox ``` ### ✨search **仅用于触发搜索**，返回搜索结果，不会进行下一步的动作，可自行处理搜索结果 **示例**： ```python search_result = sessionbox.search('张三') for item in search_result: print(f"type: {item.type}, text: {item.text}") ``` **参数**： | 参数 | 类型 | 默认值 | 说明 | | :---------: | :----------------: | :---: | :----------------: | | keywords | str | False | 搜索关键词 | | force | bool | False | 是否强制等待，避免未搜索到就返回结果 | | force\_wait | Union\[float, int] | 0.5 | 强制等待时间，秒 | **返回值**： List\[[SearchResultElement](#searchresultelement)] ### go\_top 回到会话列表顶部 **参数**：无 **返回值**：无 ### roll\_up 向上滚动会话列表 **参数**： | 参数 | 类型 | 默认值 | 说明 | | :-: | :-: | :-: | :-----------: | | n | int | 5 | 滚动次数，自行调节滚动幅度 | **返回值**：无 ### roll\_down 向下滚动会话列表 **参数**： | 参数 | 类型 | 默认值 | 说明 | | :-: | :-: | :-: | :-----------: | | n | int | 5 | 滚动次数，自行调节滚动幅度 | **返回值**：无 ## SessionElement ![SessionElement](/images/session_element.png) | 属性 | 类型 | 描述（以上图为例） | | ---------- | --------------- | -------------------- | | name | str | 会话名（wxauto三群） | | time | str | 时间（2025-05-14 14:41） | | content | str | 消息内容（\[10条]天道酬勤：这..） | | ismute | bool | 是否消息免打扰（True） | | isnew | bool | 是否有新消息（True） | | new\_count | int | 新消息数量（10） | | info | Dict\[str, Any] | 会话信息（包含了上述所有属性的dict） | ```python from wxautox4 import WeChat wx = WeChat() sessions = wx.GetSession() session = sessions[0] # 获取第一个会话 ``` ### click **点击会话**，即切换到这个聊天窗口 参数：无 返回值：无 示例： ```python session.click() ``` ### double\_click **双击会话**，即将这个聊天窗口独立出去 参数：无 返回值：无 示例： ```python session.double_click() ``` ### ✨delete **删除会话** \{\{\< callout type="warning" >}} 请谨慎调用该方法，该方法会删除该会话的所有聊天记录，无法恢复！！
请谨慎调用该方法，该方法会删除该会话的所有聊天记录，无法恢复！！
请谨慎调用该方法，该方法会删除该会话的所有聊天记录，无法恢复！！ \{\{\< /callout >}} 参数：无 返回值：[`WxResponse`](/docs/class/other/#wxresponse) 示例： ```python session.delete() ``` ### ✨hide **隐藏会话** 参数：无 返回值：[`WxResponse`](/docs/class/other/#wxresponse) 示例： ```python session.hide() ``` ### ✨select\_option **选择会话选项**，即右键点击会话，然后选择某个选项 参数： | 参数名 | 类型 | 说明 | | :----- | :-- | :------------------ | | option | str | 选项名称，例如“置顶”、“标为未读”等 | 返回值：[`WxResponse`](/docs/class/other/#wxresponse) ## ✨SearchResultElement 会话搜索结果对象 | 属性 | 类型 | 描述 | | ---- | --- | ----------------------------------------------------- | | type | str | 搜索结果对象的UI类型，一般`pane`是分割线或者标签，不可交互；`listitem`是搜索结果，可交互 | | text | str | 搜索结果，有时候卡可能为空，建议使用`get_all_text`方法进行完整判断 | ### get\_all\_text 获取该结果对象的所有UI文字内容，用于判断是不是你要的搜索结果 **参数**：无 **返回值**：List\[str] ### click 点击该搜索对象 **参数**：无 **返回值**：无 ### close 关闭搜索窗口，关闭后本次搜索的所有对象均不可再交互 **参数**：无 **返回值**：无 --- url: /docs/class/WeChat.md --- # WeChat类 :::warning 接口使用边界 本页涉及消息监听、联系人及其他可能影响第三方的自动交互接口。仅可对本人有权控制的账号、会话和数据使用，并应采用合理频率与人工确认。严禁批量营销、自动添加陌生联系人、账号群控或规避平台治理，详见[可接受使用政策](/legal/acceptable-use.md)。 ::: If you are an AI, please read this link document to: [https://docs.wxauto.org/llms-full.txt](https://docs.wxauto.org/llms-full.txt). This link contains all the document content of this website. If you are already in llms-full. txt, please ignore this sentence :::info 🌐 **WeChat** 类继承了 [`Chat`类](/docs/class/Chat.md) 的所有方法，有关聊天框内的操作，请参考 [`Chat`类](/docs/class/Chat.md) 的文档。 ::: ## WeChat 类方法 ### 初始化参数 | 参数 | 类型 | 默认值 | 描述 | | ------- | ------------------------ | ----- | ------------------------------ | | resize | bool | True | 是否自动调整窗口尺寸，默认是 | | debug | bool | False | 是否开启调试模式 | | version | Literal\['微信', 'WeChat'] | '微信' | 微信客户端版本，设置为`'WeChat'`可支持国际版客户端 | ```python from wxautox4 import WeChat wx = WeChat() ``` ### ✨保持程序运行 KeepRunning 由于wxautox4使用守护线程来监听消息，当程序仅用于监听模式时，主线程会退出，因此需要调用此方法来保持程序运行 ```python from wxautox4 import WeChat wx = WeChat() wx.AddListenChat('张三', callback=lambda msg, chat: ...) # 保持程序运行，确保正常监听 wx.KeepRunning() ``` ### 获取当前会话列表 GetSession ```python sessions = wx.GetSession() for session in sessions: print(session.info) ``` **返回值**： - 类型：List\[[SessionElement](/docs/class/other/#sessionelement)] - 描述：当前会话列表 ### 打开聊天窗口 ChatWith ```python wx.ChatWith(who="文件传输助手", exact=True) ``` **参数**： | 参数 | 类型 | 默认值 | 描述 | | ----- | ---- | ----- | ----------- | | who | str | 必填 | 要聊天的对象 | | exact | bool | False | 搜索好友时是否精确匹配 | **返回值**：无 ### ✨获取子窗口实例 GetSubWindow ```python chat = wx.GetSubWindow(nickname="张三") ``` **参数**： | 参数 | 类型 | 默认值 | 描述 | | -------- | --- | --- | ---------- | | nickname | str | 必填 | 要获取的子窗口的昵称 | **返回值**： - 类型：[`Chat`](/docs/class/Chat.md) - 描述：子窗口实例 ### ✨获取所有子窗口实例 GetAllSubWindow ```python chats = wx.GetAllSubWindow() ``` **返回值**： - 类型：List\[[`Chat`](/docs/class/Chat.md)] - 描述：所有子窗口实例的列表 ### ✨添加监听聊天窗口 AddListenChat ```python def on_message(msg, chat): print(f"收到来自 {chat} 的消息: {msg.content}") wx.AddListenChat(nickname="张三", callback=on_message) ``` **参数**： | 参数 | 类型 | 默认值 | 描述 | | -------- | ------------------------------------------------------------------------------ | --- | ------------------------------------------------------------------------ | | nickname | str | 必填 | 要监听的聊天对象 | | callback | Callable\[\[[Message](/docs/class/message/), [Chat](/docs/class/chat/)], None] | 必填 | 回调函数，参数为([Message](/docs/class/message/)对象, [Chat](/docs/class/chat/)对象) | **返回值**： - 成功时： - 类型：[Chat](/docs/class/chat/) - 描述：该监的听子窗口实例 - 失败时： - 类型：[`WxResponse`](/docs/class/other/#wxresponse) - 描述：执行结果，成功时包含监听名称 ### ✨移除监听聊天 RemoveListenChat ```python wx.RemoveListenChat(nickname="张三") ``` **参数**： | 参数 | 类型 | 默认值 | 描述 | | -------- | --- | --- | ---------- | | nickname | str | 必填 | 要移除的监听聊天对象 | **返回值**： - 类型：[`WxResponse`](/docs/class/other/#wxresponse) - 描述：执行结果 ### ✨开始监听 StartListening ```python wx.StartListening() ``` **参数**：无 **返回值**：无 ### ✨停止监听 StopListening ```python wx.StopListening() ``` **参数**： | 参数 | 类型 | 默认值 | 描述 | | ------ | ---- | ---- | --------- | | remove | bool | True | 是否移出所有子窗口 | **返回值**：无 ### 切换到聊天页面 SwitchToChat ```python wx.SwitchToChat() ``` **返回值**：无 ### 切换到联系人页面 SwitchToContact ```python wx.SwitchToContact() ``` **返回值**：无 ### ✨进入朋友圈 Moments ```python moments = wx.Moments(timeout=3) ``` **参数**： | 参数 | 类型 | 默认值 | 描述 | | ------- | --- | --- | ------- | | timeout | int | 3 | 等待时间（秒） | **返回值**： - 类型：[`MomentsWnd`](/docs/class/moment) - 描述：朋友圈窗口实例 ### ✨发送朋友圈 PublishMoment ```python text = '''oh 今天天气真好 适合出去走走 嘿嘿~ ''' media_files = [ r"D:\Images\Pictures\1.png", r"D:\Images\Pictures\2.png", r"D:\Images\Pictures\3.png", ] privacy_config = { 'privacy': '白名单', # 设置为黑名单模式 'tags': ['家人','朋友'] # 白名单为仅这些标签能看，黑名单为屏蔽这些标签的人 } # privacy_config = {} # 公开发布，没有任何权限设置 wx.PublishMoment(text, media_files, privacy_config) ``` ### ✨获取好友申请 GetNewFriends ```python newfriends = wx.GetNewFriends(acceptable=True) for new in newfriends: print(f"{new.name} ： {new.msg}") new.accept(remark='备注名', tags='朋友') # 自动接受好友请求，并添加备注和标签 wx.SwitchToChat() # 操作完成后切换回聊天页面 ``` **参数**： | 参数 | 类型 | 默认值 | 描述 | | ----------- | ---- | ---- | --------------------------- | | acceptable | bool | True | 是否过滤掉已接受的好友申请 | | roll\_times | int | 0 | 向下滚动的次数，为了加载更多好友请求，一般情况下用不到 | **返回值**： - 类型：List\[[`NewFriendElement`](/docs/class/other/#newfriendelement)] - 描述：新的好友申请列表 **示例**： ```python newfriends = wx.GetNewFriends(acceptable=True) tags = ['标签1', '标签2'] for friend in newfriends: remark = f'备注{friend.name}' friend.accept(remark=remark, tags=tags) # 接受好友请求，并设置备注和标签 ``` ### ✨添加新的好友 AddNewFriend ```python wx.AddNewFriend(keywords="张三", addmsg="我是小明", remark="老张", tags=["同学"], permission="朋友圈", timeout=5) ``` **参数**： | 参数 | 类型 | 默认值 | 描述 | | | ---------- | ---------------------- | ----- | -------------------- | ------------- | | keywords | str | 必填 | 搜索关键词，可以是昵称、微信号、手机号等 | | | addmsg | str | None | 添加好友时的附加消息 | | | remark | str | None | 添加好友后的备注 | | | tags | List\[str] | None | 添加好友后的标签 | | | permission | Literal\['朋友圈', '仅聊天'] | '朋友圈' | 添加好友后的权限 | | | timeout | int | float | 5 | 查找好友超时时间，默认5秒 | **返回值**： - 类型：[`WxResponse`](/docs/class/other/#wxresponse) - 描述：添加好友的结果 ### ✨修改好友信息 EditFriendInfo 修改好友的备注和标签 ```python wx.EditFriendInfo(add_tags=['同事', '北京'], remove_tags=['老同学'], remark='张三（北京）') ``` **参数**： | 参数名 | 类型 | 默认值 | 描述 | | ------------ | ---------- | ---- | ------------------ | | add\_tags | List\[str] | None | 要添加的标签列表 | | remove\_tags | List\[str] | None | 要移除的标签列表 | | remark | str | None | 要设置的备注，传入空字符串可清除备注 | | tag\_wait | float | 0.2 | 标签操作等待时间（秒） | **返回值**： - 类型：[`WxResponse`](/docs/class/other/#wxresponse) - 描述：操作结果 **说明**： `add_tags`、`remove_tags`、`remark` 三个参数不能同时为 `None`，否则返回失败 ### ✨获取下一个聊天窗口新消息 GetNextNewMessage ```python def callback(msg): if msg.type == 'image': msg.download() wx.GetNextNewMessage(callback=callback) ``` **参数**： | 参数 | 类型 | 默认值 | 描述 | | ------------ | --------------------------------------------------- | ----- | ------------------------------------------------ | | filter\_mute | bool | False | 是否过滤消息免打扰 | | callback | Callable\[\[[Message](/docs/class/message/)], None] | None | 获取消息时的操作，**不要在此处执行发送消息等操作，会使消息窗口重置，无法正常获取到所有消息** | **返回值**： - 类型：Dict\[str, List\[[Message](/docs/class/message/)]] - 描述：消息列表，键为聊天名称，值为消息列表 - 示例： ```python {'chat_name': 'wxauto交流', 'chat_type': 'group', 'remark': '群备注名', # 仅当有备注名时存在 'msg': [ , , , , ... ] } ``` ### ✨获取最近群聊名称列表 GetAllRecentGroups ```python groups = wx.GetAllRecentGroups() if groups: print(groups) else: print('获取失败') ``` **返回值**： - 类型：WxResponse | List\[str]: 失败时返回WxResponse，成功时返回所有最近群聊列表 ### ✨发送链接卡片 SendUrlCard ```python wx.SendUrlCard(url="https://example.com", friends="张三", timeout=10) ``` **参数**： | 参数 | 类型 | 默认值 | 描述 | | ------- | ----------------------- | ---- | ------------------- | | url | str | 必填 | 链接地址 | | friends | Union\[str, List\[str]] | None | 发送对象，可以是单个用户名或用户名列表 | | message | str | None | 附加消息，默认不发送 | | timeout | int | 10 | 等待时间（秒） | **返回值**： - 类型：[`WxResponse`](/docs/class/other/#wxresponse) - 描述：发送结果 ### ✨获取历史消息 GetHistoryMessage **参数**： | 参数 | 类型 | 默认值 | 描述 | | -------- | --------------------------------------------------- | ---- | --------------- | | n | int | 必填 | 获取数量 | | callback | Callable\[\[[Message](/docs/class/message/)], None] | None | 消息回调函数 | | interval | float | 0.2 | 滚动间隔时间 | | speed | int | 1 | 滚动速度 | | goback | bool | True | 获取结束后是否返回最新消息位置 | ```python def callback(msg): if msg.type == 'image': msg.download() wx.ChatWith('工作群') # 先切换到要获取记录的聊天窗口 msgs = wx.GetHistoryMessage(n=50, callback=callback) # 获取50条消息 ``` callback函数支持设置停止条件，当回调函数返回值为 `WxParam.CALLBACK_STOP_SIGN` 时停止 ```python from wxautox4 import WxParam from wxautox4.msgs import TimeMessage # v40.1.9及以上版本支持TimeMessage对象 # 示例：如果找到带有“通知”字眼的消息则停止获取 def history_callback(msg): # 当消息内容里包含特定字词时停止 if '通知' in msg.content: print('获取到包含“通知”的消息，停止获取历史消息') return WxParam.CALLBACK_STOP_SIGN # 当消息时间超过特定时间时停止 # v40.1.9及以上版本支持TimeMessage对象 if isinstance(msg, TimeMessage) and msg.time < '2026-02-01': print('获取到早于2026年2月1日的消息，停止获取历史消息') return WxParam.CALLBACK_STOP_SIGN wx.GetHistoryMessage(n=100, callback=history_callback) ``` > \[!info] > > 1. v40.1.8及以上版本支持CALLBACK\_STOP\_SIGN作为停止条件 > 2. v40.1.9及以上版本支持TimeMessage对象 **返回值**: - 类型：List\[[Message](/docs/class/message/)] ### ✨获取好友列表 GetFriendDetails ```python # 获取前10个好友详情信息 messages = wx.GetFriendDetails(n=10) ``` **参数**： | 参数 | 类型 | 默认值 | 描述 | | ----------------- | ----------------------- | ------- | ------------------------------------------------------- | | n | int | None | 获取前n个好友详情信息，None表示获取所有好友 | | timeout | int | 0xFFFFF | 获取超时时间（秒），超过该时间则直接返回结果 | | save\_head\_image | bool | False | 是否保存头像图片 | | save\_head\_wait | int | 0 | 保存头像等待时间 | | interval | int | 0 | 获取间隔时间 | | callback | Callable\[\[str], bool] | None | 回调函数，参数为好友昵称，用于定位开始获取的位置，返回True表示从该好友开始获取，返回False表示继续查找 | | speed | int | 3 | 滚动速度 | | max\_repeat | int | 10 | 最大重复次数 | **返回值**： - 类型：List\[dict] - 描述：所有好友详情信息 ```python # 案例 {'头像': 'D:\\myproject\\wxautox文件下载\\头像\\202511210038064171.png', '昵称': '张三', '微信号': 'zhangsan', '标签': 'wxauto', '共同群聊': '3个', '个性签名': '天道酬勤', '来源': '通过扫一扫添加'} ``` **callback 示例**： ```python # 示例1：从昵称为"陈"开头的好友开始获取 def callback(name): if name.startswith('陈'): return True wx.GetFriendDetails(callback=callback) ``` ```python # 示例2：使用re实现更复杂的定位逻辑 import re def callback(name): # 从张三或者李四开始 if re.match(r'张三｜李四', name): return True wx.GetFriendDetails(callback=callback) ``` ```python # 示例3：使用匿名函数，从“陈”开头的好友开始获取 wx.GetFriendDetails(10, callback=lambda name: name.startswith('李')) ``` > \[!warning] > 该方法运行时间较长，约0.3\~0.5秒一个好友的速度，好友多的话可将n设置为一个较小的值，先测试一下 ### ✨创建群聊 CreateGroup ```python wx.CreateGroup(contacts=["张三", "李四", "王五"]) ``` **参数**： | 参数 | 类型 | 默认值 | 描述 | | -------- | ---------- | --- | ----- | | contacts | List\[str] | 必填 | 联系人列表 | **返回值**： - 类型：[`WxResponse`](/docs/class/other/#wxresponse) - 描述：是否创建成功 ### ✨是否在线 IsOnline ```python wx.IsOnline() ``` **返回值**： - 类型：bool ### ✨获取我的信息 GetMyInfo 获取自己的微信号等信息 ```python wx.GetMyInfo() ``` **返回值**： - 类型：Dict\[str, str] ### ✨获取对话框 GetDialog 获取当前窗口的对话框 ```python dialog = wx.GetDialog(wait=3) ``` **参数**： | 参数 | 类型 | 默认值 | 描述 | | ---- | --- | --- | --------- | | wait | int | 3 | 隐性等待时间（秒） | **返回值**： - 类型：`WeChatDialog` - 描述：对话框对象，可对其进行相应处理 --- url: /docs/cli/commands.md --- # CLI 命令参考 本页记录由用户按次发起的 CLI 用法。 ## 基础命令 | 命令 | 用途 | | ---------- | --------------- | | `auth` | 激活、导出和检查授权 | | `status` | 查看当前账号信息与在线状态 | | `switch` | 切换聊天或通讯录页面 | | `sessions` | 查看最近会话 | | `chat` | 打开并读取用户指定的会话 | | `message` | 查询消息或执行低频消息辅助操作 | ## 授权与状态 ```powershell wxautox4 auth check --json wxautox4 status --json ``` ## 页面与会话 ```powershell wxautox4 switch chat wxautox4 switch contact wxautox4 sessions list --json wxautox4 chat open "文件传输助手" wxautox4 chat info --chat "文件传输助手" --json ``` ## 消息查询 ```powershell wxautox4 message list --chat "文件传输助手" --json wxautox4 message new --chat "文件传输助手" --json ``` 读取结果可能包含个人信息。请遵循最小必要原则，不得未经授权收集、导出或转交他人的消息和联系人数据。 ## 低频消息辅助 ```powershell wxautox4 message send "CLI 测试" --chat "文件传输助手" wxautox4 message send-file "C:\\Temp\\report.pdf" --chat "文件传输助手" ``` :::warning 🟡 自动交互命令 发送前必须核对目标、内容和文件。不得用于批量营销、垃圾信息、骚扰或向大量不特定用户发送信息。 ::: ## 输出与退出码 - `--json` 用于输出便于程序读取的 JSON； - 退出码 `0` 表示命令完成； - 其他退出码表示参数、运行或接口失败，应停止后续操作并人工检查； - 不应仅依据终端文本推断外部操作已经成功，应同时核对返回结果和目标界面。 --- url: /docs/cli/index.md --- # CLI 命令行工具 wxautox4 CLI 是 Python API 的命令行入口，用于在当前 Windows 交互桌面中按次执行状态查询、页面切换、会话读取和低频消息辅助操作。 CLI 不能绕过目标软件的登录、页面加载、安全校验或访问权限。 :::warning 技术边界 wxauto 基于 Windows UI Automation 与用户本人已经正常登录的桌面应用界面交互。 项目不提供协议破解、DLL 注入、内存修改、身份验证或验证码绕过、风险控制或登录限制规避、自动换号、账号养号以及未经授权的数据访问能力。如果目标软件限制某项操作，wxauto 不承诺通过其他技术手段突破该限制。 ::: :::warning 使用边界 CLI 会触发真实的桌面操作。请仅操作本人有权控制的设备、账号、会话和数据，优先使用“文件传输助手”测试，并遵守[可接受使用政策](/legal/acceptable-use.md)。 ::: ## 运行条件 - Windows 交互桌面可用； - 微信桌面客户端已由用户本人正常登录； - 当前 Python 环境已安装并激活 wxautox4； - 执行期间由用户保持对桌面和操作结果的监督。 ## 快速开始 ```powershell # 查看帮助和版本 wxautox4 --help wxautox4 --version # 查看当前账号和授权状态 wxautox4 status wxautox4 auth check # 在本人控制的文件传输助手中测试 wxautox4 message send "CLI 测试" --chat "文件传输助手" # 获取最近会话 wxautox4 sessions list --json ``` CLI 命令应在用户发起后按次执行。涉及发送、删除或修改的操作，请在执行前核对目标，并检查命令退出码和返回结果。 ## 文档导航 - [命令参考](/docs/cli/commands.md)：查看公开保留的低风险命令与示例。 - [可接受使用政策](/legal/acceptable-use.md)：查看允许用途、禁止用途和操作要求。 --- url: /docs/concepts.md --- # 三、核心类概念 ## Chat \{\{\< cards >}} \{\{\< card link="/docs/class/chat" title="👉查看Chat类文档" tag="点击跳转" tagType="info" >}} \{\{\< /cards >}} `Chat` 类代表一个微信聊天窗口实例，提供了与聊天相关的操作方法，用于对**微信聊天窗口**进行各种操作，后续文档以变量名`chat`作为该类对象。 image-20250513092208146 ## WeChat \{\{\< cards >}} \{\{\< card link="/docs/class/wechat" title="👉查看WeChat类文档" tag="点击跳转" tagType="info" >}} \{\{\< /cards >}} `WeChat` 类是本项目的主要入口点，它继承自 `Chat` 类，代表微信主窗口实例，用于对**微信主窗口**进行各种操作，后续文档以变量名`wx`作为该类对象。 ### 初始化参数 | 参数 | 类型 | 默认值 | 描述 | | -------- | ---- | ----- | ---------------- | | nickname | str | None | 微信昵称，用于定位特定的微信窗口 | | debug | bool | False | 是否开启调试模式 | ```python wx = WeChat(nickname="张三") ``` image-20250513092208146 ## Message \{\{\< cards >}} \{\{\< card link="/docs/class/message" title="👉查看Message类文档" tag="点击跳转" tagType="info" >}} \{\{\< /cards >}} `Message`类代表微信聊天中的消息，分为两个概念： - 消息**内容**类型（`type`）：文本消息、图片消息、文件消息、语音消息、卡片消息等等 - 消息**来源**类型（`attr`）：系统消息、时间消息、自己发送的消息、对方发来的消息 ```python # 导入你想要的消息类型 from wxautox4.msgs import ( TextMessage, FriendMessage, FriendTextMessage, ... ) # 假设你获取到了一个消息对象 msg: Message = ... # 如果是对方发来的消息，则回复收到 if isinstance(msg, FriendMessage): msg.reply("收到") ``` | type↓ attr→ | 自己的消息`SelfMessage` | 对方的消息`FriendMessage` | | :-----------------------: | :-----------------------: | :-------------------------: | | 文本消息`TextMessage` | `SelfTextMessage` | `FriendTextMessage` | | 引用消息`QuoteMessage` | `SelfQuoteMessage` | `FriendQuoteMessage` | | 语音消息`VoiceMessage` | `SelfVoiceMessage` | `FriendVoiceMessage` | | 图片消息`ImageMessage` | `SelfImageMessage` | `FriendImageMessage` | | 视频消息`VideoMessage` | `SelfVideoMessage` | `FriendVideoMessage` | | 文件消息`FileMessage` | `SelfFileMessage` | `FriendFileMessage` | | 位置消息`LocationMessage` | `SelfLocationMessage` | `FriendLocationMessage` | | 链接消息`LinkMessage` | `SelfLinkMessage` | `FriendLinkMessage` | | 表情消息`EmotionMessage` | `SelfEmotionMessage` | `FriendEmotionMessage` | | 合并消息`MergeMessage` | `SelfMergeMessage` | `FriendMergeMessage` | | 名片消息`PersonalCardMessage` | `SelfPersonalCardMessage` | `FriendPersonalCardMessage` | | 其他消息`OtherMessage` | `SelfOtherMessage` | `FriendOtherMessage` | ## WxResponse 该类用于该项目多个方法的返回值 ```python # 这里假设result为某个方法的WxResponse类型返回值 result: WxResponse = ... # 判断是否成功 if result: data = result['data'] # 成功，获取返回数据，大多数情况下为None else: print(result['message']) # 该方法调用失败，打印错误信息 ``` ## WxParam - **ENABLE\_FILE\_LOGGER** ( bool ) ：是否启用日志文件，默认True - **DEFAULT\_SAVE\_PATH** ( str ) ：下载文件/图片默认保存路径，默认为当前工作目录下的`wxautox`文件下载文件夹 - **✨MESSAGE\_HASH** ( bool ) ：是否启用消息哈希值用于辅助判断消息，开启后会稍微影响性能，默认False - **DEFAULT\_MESSAGE\_XBIAS** ( int ) ：头像到消息X偏移量，用于消息定位，点击消息等操作，默认51 - **FORCE\_MESSAGE\_XBIAS** ( bool ) ：是否强制重新自动获取X偏移量，如果设置为True，则每次启动都会重新获取，默认False - **LISTEN\_INTERVAL** ( int ) ：监听消息时间间隔，单位秒，默认1 - **SEARCH\_CHAT\_TIMEOUT** ( int ) ：搜索聊天对象超时时间，单位秒，默认5 ```python from wxautox import WxParam ... ``` --- url: /docs/example.md --- # 五、使用示例 :::warning 使用边界 以下示例仅用于本人控制对象中的低频测试。涉及消息、联系人或公开内容的操作应设置目标核验、人工确认和合理频率，并遵守[可接受使用政策](/legal/acceptable-use.md)。 ::: ### 1. 基本使用 ```python title="demo.py" from wxautox4 import WeChat # 初始化微信实例 wx = WeChat() # 切换到文件传输助手 target = "文件传输助手" wx.ChatWith(target) # 查看当前窗口信息 chatinfo = wx.ChatInfo() print(f"当前窗口信息：{chatinfo}") # 发送消息 if chatinfo.get('chat_name') == target: # 先判断是否为要发送的人 wx.SendMsg("你好") # 获取当前聊天窗口消息 msgs = wx.GetAllMessage() for msg in msgs: print(f"消息内容: {msg.content}, 消息类型: {msg.type}") ``` ### 2. 监听消息 ```python from wxautox4 import WeChat from wxautox4.msgs import FriendMessage import time wx = WeChat() # 消息处理函数 def on_message(msg, chat): """消息回调函数""" print(f'收到来自 {chat} 的消息: {msg.content}', flush=True) # 仅处理用户预先明确选择的测试会话，并过滤自己的消息 if isinstance(msg, FriendMessage): chat.SendMsg('收到') # 添加消息监听 wx.AddListenChat('文件传输助手', on_message) # 保持运行 wx.KeepRunning() ``` ```python # ... 程序运行一段时间后 ... # 移除监听 wx.RemoveListenChat(nickname="文件传输助手") ``` ### 3. ✨处理好友申请 仅处理用户主动提交且您有权确认的好友申请；请勿将本接口用于批量处理、营销或陌生人触达。 ```python title="accept_new_friend.py" from wxautox4 import WeChat wx = WeChat() # 获取新的好友申请 newfriends = wx.GetNewFriends(acceptable=True) # 处理好友申请 tags = ['同学', '技术群'] for new in newfriends: message = new.content new.accept(tags=tags) # 接受好友请求，并设置备注和标签 ``` ### 4. ✨发送朋友圈 :::warning ⚠️ 请谨慎使用，不建议频繁发送朋友圈，此行为可能会被认定过度营销而触发帐号风控！ ::: ```python title="send_moment.py" from wxautox4 import WeChat wx = WeChat() text = '''oh 今天天气真好 适合出去走走 嘿嘿~ ''' media_files = [ r"D:\Images\Pictures\1.png", r"D:\Images\Pictures\2.png", r"D:\Images\Pictures\3.png", ] privacy_config = { 'privacy': '白名单', # 设置为黑名单模式 'tags': ['家人','朋友'] # 白名单为仅这些标签能看，黑名单为屏蔽这些标签的人 } # privacy_config = {} # 公开发布，没有任何权限设置 wx.PublishMoment(text, media_files, privacy_config) ``` --- url: /docs/index.md --- # Overview --- url: /docs/issues.md --- # 六、常见问题 :::warning 技术边界 wxauto 基于 Windows UI Automation 与用户本人已经正常登录的桌面应用界面交互。 项目不提供协议破解、DLL 注入、内存修改、身份验证或验证码绕过、风险控制或登录限制规避、自动换号、账号养号以及未经授权的数据访问能力。如果目标软件限制某项操作，wxauto 不承诺通过其他技术手段突破该限制。 ::: ## 账号及平台风险 wxauto 是第三方开发的桌面自动化工具，并非腾讯或微信官方提供、授权或认可的软件。 使用第三方自动化工具操作微信可能受到软件版本、账号状态、平台规则及风险控制机制影响。本项目无法保证不会发生功能限制、账号限制或其他平台处置。使用者应自行阅读并遵守微信现行服务协议及账号使用规范。 wxauto 不提供、也不承诺任何规避安全机制、风险控制、账号限制或平台治理措施的能力。详见[第三方服务说明](/legal/third-party-services.md)和[可接受使用政策](/legal/acceptable-use.md)。 ## 支持Linux/Mac吗 不支持，基于windows官方API开发，只支持windows系统 ## 激活码有时间限制吗？ 一年内可激活，激活后提供一年更新，使用没有时间限制，更新过期后，已获取的版本仍可继续使用。 ## 激活码能用几次 一个激活码只能用于一台电脑，不可解绑，如遇问题可联系 [help@wxauto.org](mailto:help@wxauto.org?subject=遇到激活问题：\&body=请详细描述您的问题，如果有报错截图就更好了😊) ## 支持自动接收红包/转账吗？ 不支持，以后也不会支持，涉及金钱类的都不会支持 ## 为什么安装成功但是无法导入 检查下安装wxautox的环境与你运行环境是否同一个python环境。 PyCharm默认会给你的项目创建一个虚拟环境，需要在虚拟环境中安装才可以调用 > 如果不清楚如何使用虚拟环境安装，可问 AI “怎么用pycharm的虚拟环境安装本地离线whl包” ## 支持企业微信吗 目前项目仅维护已公开列明的兼容范围，暂不支持企业微信。项目不会针对未列入支持范围的软件提供适配承诺。 ![image-20250322214731403](/images/issues_wecom.png) ## 有什么限制 开源版与 Plus 的授权范围不同，请分别查看[用户协议](/agreement.md)及[商业授权条款](/legal/commercial-license.md)。所有版本均须遵守[可接受使用政策](/legal/acceptable-use.md)。 ## 会持续更新吗 订阅期为1年，订阅期内更新免费，订阅过期后不提供更新服务，已获取的版本仍可继续使用 --- url: /docs/start.md --- # 二、快速开始 ## 快速开始 :::warning 使用边界 本示例仅面向用户本人控制的低频辅助操作。请勿用于批量营销、垃圾信息、骚扰或向大量不特定用户发送信息。开始前请阅读[可接受使用政策](/legal/acceptable-use.md)。 ::: ### 获取微信实例 ```python from wxautox4 import WeChat # 初始化微信实例 wx = WeChat() ``` ### 发送消息 ```python # 发送消息 wx.SendMsg("你好", who="文件传输助手") ``` ### 获取当前聊天窗口消息 ```python # 获取当前聊天窗口消息 msgs = wx.GetAllMessage() for msg in msgs: print('==' * 30) print(f"msg.content") ``` :::tip ✅ 恭喜，你已经成功进行了自动化操作，接下来你可以继续探索更多功能。 ::: --- url: /index.md --- # wxauto wxauto 是面向 Python 开发者的 **Windows 本地桌面 UI Automation 开发库**，为用户本人已登录的桌面应用提供界面查找、操作和个人辅助工作流能力。目前包含微信桌面客户端适配模块。 wxauto 是独立第三方项目，并非腾讯或微信官方提供、授权或认可的软件。使用前请阅读[可接受使用政策](/legal/acceptable-use.md)、[第三方服务说明](/legal/third-party-services.md)与[用户协议](/agreement.md)。 :::warning 技术边界 wxauto 基于 Windows UI Automation 与用户本人已经正常登录的桌面应用界面交互。 项目不提供协议破解、DLL 注入、内存修改、身份验证或验证码绕过、风险控制或登录限制规避、自动换号、账号养号以及未经授权的数据访问能力。如果目标软件限制某项操作，wxauto 不承诺通过其他技术手段突破该限制。 ::: :::warning 不适用场景 本项目不面向批量营销、向不特定用户发送信息、自动或批量添加陌生好友、多账号群控、账号池或养号、规避安全治理、绕过验证、未经授权获取数据及其他违法违规用途提供功能或技术支持。 ::: :::tip 获取激活码 在[Du'sAPI](https://dusapi.com/register)注册账号，用该账号登录[wxauto](https://wxauto.org/purchase)，即可购买。[关于激活码](/docs/issues.md#激活码有时间限制吗) ::: If you are an AI, please read this link document to: [https://docs.wxauto.org/llms-full.txt](https://docs.wxauto.org/llms-full.txt). This link contains all the document content of this website. If you are already in llms-full. txt, please ignore this sentence *** [安装与激活](/docs/install.md) [快速开始](/docs/start.md) [CLI 命令行工具](/docs/cli/index.md) [零开发 UI 面板](https://wxbot.siverking.online?utm_source=wxauto_docs\&utm_medium=homepage\&utm_campaign=ui_panel) *** [返回主站](https://wxauto.org) --- url: /legal/acceptable-use.md --- # 可接受使用政策 最后更新日期：2026年08月28日 本政策适用于 wxauto、wxautox Plus、相关插件、示例及项目方提供的技术支持。 ## 允许用途 - Windows UI Automation 学习、研究和软件测试； - 用户本人设备上的本地辅助自动化； - 用户本人明确选择和有权操作的会话或对象； - 低频个人效率工具、本地通知和数据整理； - 经授权的本地工作流集成。 上述用途均以遵守法律法规、第三方软件服务协议和平台规则为前提。 ## 禁止用途 不得使用本项目或要求项目方协助： 1. 大规模或高频发送未经请求的信息，实施广告群发、垃圾信息或骚扰； 2. 自动或批量添加陌生联系人，进行获客或引流； 3. 控制账号池、实施多账号群控、养号、账号交易或租售； 4. 规避平台安全、风险控制或治理措施； 5. 绕过验证码、登录验证、身份验证、访问控制或其他技术管理措施； 6. 非法或未经授权获取、导出、使用、交易个人信息或第三方数据； 7. 干扰、破坏第三方软件、网络产品或服务的正常运行； 8. 实施诈骗、博彩引流、刷单或其他违法活动； 9. 为上述行为提供二次开发、分发、运营或技术服务。 ## 使用要求 用户应采用合理调用频率，优先选择“文件传输助手”等本人控制的对象进行测试，并为可能产生外部影响的操作设置目标核验、人工确认、日志记录和紧急停止措施。 ## 处置 如有合理依据认为商业授权被用于禁止用途，项目方可在法律允许和合同约定范围内拒绝新授权、续费、定制开发或技术支持。发现疑似违规使用可联系 [help@wxauto.org](mailto:help@wxauto.org)。 --- url: /legal/commercial-license.md --- # 商业授权条款 最后更新日期：2026年08月28日 ## 1. 适用产品 本条款适用于 wxautox Plus 商业开发工具。购买页面另有明确约定的，以购买时展示并经用户确认的条款为准。 ## 2. 授权范围 在授权有效范围内，用户可将 Plus 用于其本人或所属组织内部、合法合规的本地桌面自动化开发、测试和辅助工作流。授权设备数量、更新期限及技术支持范围以购买页面和授权记录为准。 未经另行书面授权，不得公开传播、转售、出租、共享授权凭证，或将 Plus 本身作为面向不特定第三方的软件服务、SDK 或商业软件组件进行分发。 ## 3. 用途限制 商业授权不扩大用户对第三方软件、账号或数据的权利，也不代表获得第三方软件厂商的许可。用户必须遵守[可接受使用政策](/legal/acceptable-use.md)，不得将 Plus 用于批量营销、陌生用户触达、账号群控、规避平台治理或未经授权的数据处理。 ## 4. 更新与支持 订阅期内提供对应版本更新和约定范围内的开发者支持；订阅到期后，已合法获取版本的继续使用及兼容情况以购买页面说明和技术条件为准。第三方软件更新可能导致部分功能不可用，项目方不承诺永久兼容。 ## 5. 违规处置 如有合理依据认为授权被用于禁止用途，项目方可在法律允许和合同约定范围内拒绝新授权、续费、定制开发或技术支持。涉及授权范围或企业集成需求，请在使用前联系 [help@wxauto.org](mailto:help@wxauto.org)确认。 --- url: /legal/third-party-services.md --- # 第三方服务说明 最后更新日期：2026年08月28日 wxauto 是独立第三方项目，与深圳市腾讯计算机系统有限公司、腾讯、微信及其他目标软件权利人不存在隶属、合作、官方认证或授权关系。 “微信”“WeChat”“腾讯”及相关名称、商标、图标和软件归其各自权利人所有；本站仅为说明兼容对象而作必要指称，不表示任何赞助、认可或许可。 本项目不声称用户通过 wxauto 操作微信已经取得腾讯许可。用户须自行阅读并遵守目标软件现行的服务协议、隐私规则、账号规范和其他适用政策。 第三方软件的界面、版本、规则及技术措施可能变化。本项目不保证持续兼容，不提供规避登录验证、安全校验、风险控制、账号限制或平台治理措施的能力。 --- url: /privacy.md --- # 隐私政策 最后更新日期：2026年08月28日 ## 1. 适用范围 本政策说明 wxauto 与 wxautox Plus 在软件激活、更新和技术支持过程中如何处理信息。第三方软件自身的数据处理不受本政策控制，请同时查阅相应第三方的隐私规则。 ## 2. 我们处理的信息 Plus 激活时可能处理设备硬件标识、授权码、激活时间、软件版本及必要的请求日志，用于许可证验证、防止授权滥用和故障排查。技术支持过程中，仅在用户主动提交时处理其联系方式、问题描述、日志或截图。 请在提交日志或截图前遮盖聊天内容、联系人、账号标识及其他不必要的个人信息。 ## 3. 本地数据 桌面 UI 自动化操作原则上在用户本地设备执行。项目默认不要求用户向项目方上传聊天记录、联系人或消息内容。部分由用户自行安装、配置或调用的插件、AI 服务、HTTP 服务及第三方集成可能另行传输数据，其处理规则由相应服务提供方和用户配置决定。 ## 4. 使用目的与保护 相关信息仅用于授权验证、提供更新与支持、维护安全和履行法定义务。项目方采取与风险相适应的措施限制访问和保存范围，不会将激活信息用于批量营销或出售个人信息。 ## 5. 保存、查询与删除 信息将在实现上述目的所需期限及法律要求的期限内保存。用户可通过 [help@wxauto.org](mailto:help@wxauto.org)咨询其信息处理情况，或在适用法律允许范围内申请更正、删除。 ## 6. 政策更新 重大变更将通过项目页面或其他适当方式通知。继续使用前，请查看最新版本及更新日期。 --- url: /read/audio_settings.md --- # 语音条消息前置配置 官方4.1.9+客户端支持了语音条消息的发送，40.1.13+版本的wxautox4可使用 [`SendAudio`](/docs/class/chat#发送语音-sendaudio) 方法发送语音条消息，但需要以下前置配置。 ## 配置步骤 ### 安装 ffmpeg 首先确认自己电脑有没有 ffmpeg ### 安装虚拟麦克风 下载虚拟麦克风驱动：[audio\_driver.zip](/files/audio_driver.zip) 解压后双击 `VBCABLE_Setup_x64.exe` 点击安装即可 ![安装驱动](/images/install_audio_driver.png) 安装成功 ![安装成功](/images/install_audio_driver_success.png) *** ### 配置虚拟麦克风 打开Windows系统设置，系统 - 声音 - 输入，将输入设备改为刚刚安装的虚拟麦克风驱动 `CABLE Output` ![修改输入设备](/images/set_microphone.png) 至此，所有配置均配置完成 *** ### 测试发送语音条消息 ```python from wxautox4 import WeChat wx = WeChat() audio = 'D:/xxx.mp3' wx.ChatWith('文件传输助手') wx.SendAudio(audio, duration=3) # 发送3秒测试 ``` *** ## 远程桌面额外配置 :::tip 如果经过上述配置可正常发送语音消息，则不需要看此部分 ::: 如果使用的是远程桌面，可能在系统声音设置中，不可设置输入设备，这是因为远程桌面默认使用控制端主机的音频输入，可在连接前设置： **[object Object]** ![远程桌面设置](/images/audio_rdp_setting.png) **[object Object]** ![远程桌面设置](/images/audio_rdp_setting-macos.png)