# wx4py: automating the WeChat 4.x Windows client with Python

> wx4py drives the WeChat 4.x desktop client on Windows through UI automation, so a script can broadcast a notice to a list of group chats, distribute a file to each of them, update group announcements, export chat history to CSV, and run a bot that replies when mentioned. It is AGPL licensed, Windows only, and the README is candid about the account risk of automating a client at all.

**claw-codes/wx4py** — 微信4.x自动化机器人：群聊机器人、批量群发（支持文件）、批量设置群公告、聊天记录导出、群管理 | 5分钟上手

- Repository: https://github.com/claw-codes/wx4py
- Website: https://wx4py.biglongxia.com/
- Stars: 779 · Forks: 210
- Language: Python
- License: AGPL-3.0
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/claw-codes-wx4py

## UI automation against a real client, not an API

wx4py is a Python automation library for WeChat 4.x on Windows, and the mechanism matters more than the feature list.

The dependency list gives it away. pywin32 and comtypes are the Windows UI automation and COM libraries, pyperclip is for the clipboard, and then there is markdown, beautifulsoup4, and Pillow. There is no HTTP client, no protocol implementation, and no reverse engineering of the WeChat network protocol in the dependency tree. The library drives the actual desktop client, the same way a person would, by finding windows and controls and interacting with them.

That is a deliberate trade, and it has clear consequences. It works with whatever the client supports, which is why the README claims support for the latest 4.x releases while the comparison table says most other solutions only support older versions or the Mac client. It also inherits every fragility of UI automation, because a client update that moves a control breaks a selector, and it inherits the requirement that the client be running and logged in.

The environment requirements are explicit: Windows 10 or 11, Python 3.9 or newer, and the WeChat 4.x client, with 4.1.7.59 and 4.1.8.29 listed as tested. The project is Windows only, and the classifiers in the package metadata say so, with the operating system marked as Microsoft Windows and the development status at Alpha.

The install is a single pip command.

```bash
pip install wx4py
```

And the first use is a context manager and a send.

```python
from wx4py import WeChatClient

with WeChatClient() as wx:
```

The WeChatClient object is the entry point to everything else, and it exposes a chat window interface, a group manager interface, and a method for processing several groups at once with a handler.

The licence is AGPL-3.0-or-later, which is a strong copyleft licence and a different proposition from the permissive licences most automation tools carry, so it is worth understanding the obligations before you deploy it somewhere.

## Broadcasting one message to a list of groups

The first capability in the README is the one the project leads with, and it is the one with the clearest motivation: sending the same notice to several group chats by hand is slow and easy to miss a group.

The API is a single call on the chat window interface, batch_send, with a list of target names, the message text, and a target type that distinguishes a group from a contact. The call blocks until the sends are done, and the client context manager closes the connection on the way out.

The README frames this as a notification use case rather than a marketing one, and the examples are internal: a notice about a meeting to the technical, product, and operations groups, and a daily reminder to two development groups to submit their reports. The scheduled version uses the schedule library, with a function that sends the reminder and a call that fires it every day at a given hour.

That scheduling pattern is the one to copy for a recurring internal notice, because it runs the send on a schedule rather than in a loop, and it is easy to add a guard.

The one-line table at the end of the usage section is worth reading in full, because it is the API summary: send to a contact, send to a group, send a file, search for a contact or a group, get and set a group nickname, turn on do not disturb, pin a chat, process several groups with a handler, forward messages between groups, and trigger an AI reply when mentioned.

The search method is the one that makes the rest practical, because you can look up a group by name rather than hard coding an identifier, and the group nickname methods are the ones that let a script tell groups apart by the name you have given them rather than the one the members chose.

## File distribution, announcements, and group administration

Three administrative features follow the same shape as the broadcast, and each one is a small wrapper over a client action.

File distribution is send_file_to, which takes a target, a path, and the target type. The example sends the same weekly report file to three department groups, and the point of the feature is that you do the upload once per group without dragging the file three times.

Announcements are handled by a method on the group manager called modify_announcement_simple, and the example loops over a list of project groups to update each one with this week's focus. Batch updating announcements is a genuine time saver for a team that runs many project groups, and the simple form of the method name suggests there is a more detailed one.

Group administration is the third area, and it is the most invasive in practice, because it changes settings that other people see. There is get_group_members to list the members of a group, and the example prints the count and the names. There is get_group_nickname and set_group_nickname for the local display name, set_do_not_disturb to mute a group, and set_pin_chat to pin one to the top of the list.

Those last two are worth a moment of thought. Muting a group and pinning a group are personal settings for the account running the automation, not settings for the group, so they are the least disruptive of the set. Setting an announcement and renaming a group affect everyone in the group, so a script that does either in a loop should be run deliberately rather than on a schedule, and a typo in the group list is a mistake other people will see.

The chat history export sits in the same family and is the one with a documented limitation, which the next section covers.

## Exporting chat history, and the sender you cannot get

The export feature pulls chat history for a group or a contact and hands it back as data, and the example turns it into a dataframe and writes it to a CSV, then prints the distribution of message types.

The call is get_chat_history on the chat window interface, with a target, the target type, and a since parameter, and the example uses a value of week to get the last week of a project discussion group. The pandas in the example is not a dependency of the library, since the dependencies are pywin32, comtypes, pyperclip, markdown, beautifulsoup4, and Pillow, so you bring your own analysis library and the library simply returns a list of message dictionaries.

The limitation is stated in the FAQ and it is a real one. The WeChat 4.x interface does not expose sender information, so you cannot get the sender of a message, and it is described as a technical limitation that cannot be worked around for now.

That constraint shapes what an export is good for. Counting messages, spotting a spike in activity, extracting dates, and looking at the text of a conversation all work. Attribution does not, which means an export cannot be used for a moderation workflow, for a per person analysis, or for anything where you need to know who said what. For a team that wants to understand where a discussion happened, the export is fine. For anything involving individual performance or dispute, it is not enough.

The FAQ also records that the WeChat window must be in the foreground while the automation runs, and suggests using a dedicated machine or running the task during an idle period. That is the practical cost of the UI automation approach, and it is a scheduling constraint your deployment has to respect.

## The AI reply bot and the forwarding rules

Two features turn wx4py from a batch tool into a listener, and both work the same way: you hand process_groups a list of group names and a list of handlers, and the client blocks while it watches.

The AI bot is the first. The AIConfig carries a base URL, an API format, a model, an API key, and a thinking switch, and the README example points it at an OpenAI compatible completions endpoint with a DeepSeek model. The AIResponder wraps that client with a context size and a reply-on-mention flag, and the AsyncCallbackHandler adds auto_reply.

```python
        base_url="https://api.siliconflow.cn/v1",
        api_format="completions",
        model="Pro/deepseek-ai/DeepSeek-V3.2",
        enable_thinking=False,
```

The reply_on_at flag is what makes this usable in a real group. The README describes the behaviour as listening to several groups, calling the model only when you are mentioned, and leaving ordinary messages alone. It also notes that replies sent by the library are recorded, so the bot does not trigger itself in a loop, which is the failure mode every group bot hits on its first run.

The forwarding rules are the second, and they are the more useful of the two for a working team. A GroupForwardRule names a source group, a list of targets, a target type, and a prefix template, and the ForwardRuleHandler applies a list of them. The examples given are an alert group forwarding to a duty engineer as a contact, and one project group forwarding into another with a prefix identifying the origin.

The prefix template is the detail to notice, because without it a forwarded message is indistinguishable from an original one, and the recipient cannot tell which group it came from. The use cases the README names for this are alert notifications, duty handovers, and cross-group message synchronisation, all of which are internal workflows where a bot is doing the work of a person copying and pasting.

## The skill file, the packaging, and the account risk

The project has a second interface that is worth knowing about, because it is aimed at a different user.

The AI Skill section is a block of instructions to paste into Claude Code or OpenClaw. It asks the assistant to install the library with pip, to install the wx4py skill into the local skills directory and record it in the tool documentation and memory system, to read the skill document, and then to explain how to talk to it. The skill address is a raw file in the repository, at the wx4-skill directory. After that, a plain sentence such as asking it to send a message to a work group is supposed to do the work, with the assistant generating and running the code.

The packaging is conventional: setuptools with a source directory mapped to the package name, the version read dynamically from an attribute in the version module, and a pytest configuration with the test paths and the file naming conventions. The repository carries an examples directory split into groups, inspect, messaging, and sending, and a docs directory with an API guide.

Now the part that should decide whether you use this at all, which the FAQ addresses under the question of whether you will be banned. wx4py simulates real user operations and does not modify the WeChat client. But the README still advises controlling the sending frequency, avoiding large amounts of mass marketing content, and using the client responsibly.

Read that as a warning, not a disclaimer. The mechanism is indistinguishable from a person clicking, which is exactly why it can be flagged, and the account is yours. That is the same argument that applies to any RPA tool aimed at a consumer application, and it is the reason to run this on a dedicated account rather than on the one your personal chats live in.

There is also a terms of service dimension that the README does not discuss, and a business dimension: sending the same message to many groups is the shape of spam, and the difference between an internal notice and unwanted bulk content is entirely in the recipients' consent.

## Conclusion

wx4py fits a Windows team that has moved to WeChat 4.x and needs to send the same notice to several work groups, distribute a weekly report, keep group announcements in sync, or analyse their own group chat history, and who would rather script the client than maintain a server side bot. It does not fit a Linux or macOS developer, since the library is Windows only and depends on pywin32 and comtypes, and it does not fit a case where the sender identity in the exported history matters, because the 4.x interface does not expose it. Verify first that the WeChat client is 4.x and logged in, that the window can stay in the foreground while the automation runs, and that you have read the section on account risk, since the library simulates real user actions and the account carries the consequence.

## FAQ

### What does wx4py automate?

It automates the WeChat 4.x desktop client on Windows through UI automation, using pywin32 and comtypes rather than any network protocol. That lets it work with the current client releases, and it means the client must be running, logged in, and in the foreground while the automation runs.

### How do I send one message to several WeChat groups?

Call batch_send on the chat window interface with a list of group names, the message text, and target_type set to group. The README also shows a scheduled version built on the schedule library that fires the same send every day at a given hour.

### Can wx4py export WeChat chat history with sender names?

It can export the history, through get_chat_history with a target, a target type, and a since value, and the example turns the result into a CSV. It cannot give you the sender, because the WeChat 4.x interface does not expose that information, which the FAQ describes as a technical limitation.

### Will automating WeChat with wx4py get my account banned?

The library simulates real user operations and does not modify the client, but the README still advises controlling the sending frequency, avoiding mass marketing content, and using it responsibly, and it recommends running tasks on a dedicated machine or during idle periods. The account carries the risk, so use a separate account.

### Which platforms and versions does wx4py support?

Windows 10 and 11 with Python 3.9 or newer, and the WeChat 4.x client, with 4.1.7.59 and 4.1.8.29 listed as tested. The package classifiers mark the operating system as Microsoft Windows, the development status as Alpha, and the licence as AGPL-3.0-or-later.

## Sources

- [claw-codes/wx4py on GitHub](https://github.com/claw-codes/wx4py)
- [License: AGPL-3.0](https://github.com/claw-codes/wx4py/blob/main/LICENSE)
- [Project website](https://wx4py.biglongxia.com/)
- [README](https://github.com/claw-codes/wx4py/blob/main/README.md)
- [Releases](https://github.com/claw-codes/wx4py/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/claw-codes-wx4py