YuYuWechat V3: a Django and Celery service that drives the desktop WeChat client

Three processes, and the WeChat window is the bottleneck

The architecture is the thing to understand first, because it decides where you have to run things. YuYuWechat is split into three main parts. The YuYuWechatV3_Server runs on the Windows computer where WeChat is installed, receives HTTP requests and performs the UI automation. The YuYuWechatV2_Client is the management interface and the scheduling centre, and it can be deployed on Windows, macOS or Linux. Between them sits the pywechat and pyweixin libraries, which are the WeChat 4.x automation core the V3 server uses, and which must sit in the same repository and at the same directory level as the server when you deploy from source. The reason the server is separate from the client is stated plainly: V3 keeps a global task queue and a mutex on the server, so even if several clients connect to the same server, the WeChat operations still execute in order. Without that, two requests would fight over the same window.

The features are message automation, log watching and red packets

The feature list is unusually concrete. You can send different text messages in bulk, schedule recurring sends with a five-field cron expression down to the minute, and schedule the sending of files from the server's local disk. You can pull chat records and check them for keywords or regular expressions in time blocks, and you can fetch images, videos and temporary download links from a conversation. You can pin or unpin a specific chat. You can claim red packets and collect transfers manually, and you can listen for unread one to one chats and claim them automatically, with an optional thank you message afterwards. The reliability features are the ones that matter for unattended use: client task logs, server request logs, detection of missed executions, and email alerts when something goes wrong. The server serialises its requests so that multiple requests do not grab the WeChat window at the same time, which is the failure mode you get from every naive version of this kind of tool.

WeChat 4.1.8, Simplified Chinese, and an unlocked desktop

The requirements are narrow and they are not negotiable for the V3 line. The README states that V3 currently supports only Windows 10 or 11, WeChat 4.1.8, and the Simplified Chinese interface. If you need to control WeChat 3.x you are told to switch to the V2 branch and use YuYuWechatV2_Server instead. The server side needs Python 3.10 or newer with 3.11 recommended, and the Windows user has to be logged into WeChat already. The last requirement is the one that trips people up: the desktop must stay unlocked, and the machine must not go to sleep or the screen lock during operation. On top of that, WeChat 4.x may hide some UI Automation elements by default, and the documented remedy is unusual enough to be worth repeating. You fully quit WeChat, start the Windows Narrator with Win plus Ctrl plus Enter, start WeChat and log in, keep Narrator running for about five minutes, close Narrator, and then start the YuYuWechat V3 server. The power settings advice is to turn off automatic sleep, screen blanking and screen locking. And if the interface says it cannot locate the WeChat main window, the instruction is to repeat the Narrator procedure rather than edit the UI location code.

Building the server executable on Windows

The recommended way to run the server is to compile a Windows executable from the v3 branch, and the repository ships a batch file that does it so you do not have to install and invoke PyInstaller by hand. Before compiling, the checks are that Python 3.10 or newer is installed, that the repository is fully fetched with pywechat and YuYuWechatV3_Server as sibling directories, that any running server executable has been closed, and that the machine can reach the Python package index because the script installs build dependencies:

git clone -b v3 https://github.com/xieyumc/YuYuWechat.git
cd YuYuWechat\YuYuWechatV3_Server
.\build_pyinstaller_windows.bat

There is a warning about the build script that is worth taking seriously. It deletes the old dist every time it runs, so you must not keep a production database and logs in the source dist directory; back up the db.sqlite3 file and the logs folder before rebuilding, or copy the build output to a separate run directory. The build uses PyInstaller in directory mode, which means the output depends on an _internal directory next to the executable, so you have to copy the whole folder and not just the EXE.

Initialising, then running the server

After a successful build you move into the output directory and initialise the database and an administrator account:

cd dist\YuYuWechatV3_Server
.\YuYuWechatV3_Server.exe migrate
.\YuYuWechatV3_Server.exe createsuperuser

The order of operations on the desktop matters and is stated three times in the documentation, which tells you how often people get it wrong. Every time you start the server you must first fully quit WeChat, then open Narrator, then start and log into WeChat, confirm the login, and only then start the server. Logging into WeChat before opening Narrator is called out as the wrong order. Started without arguments, the server listens on 0.0.0.0:8000 by default, the runtime data is kept in a db.sqlite3 file next to the executable, and rolling logs go to logs/server.log. There is a source-running path too, which uses a virtual environment and manage.py:

cd YuYuWechatV3_Server
py -3.11 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
python manage.py migrate
python manage.py createsuperuser

The server loads pyweixin automatically from the pywechat directory at the repository root, and if you move the directories around it answers with pywechat core library not found.

An HTTP API with no authentication, which is the caveat

The server exposes its functionality as a REST API, and the security note is the most important line in the README. The V3 server interfaces currently have no API token authentication, and the WeChat operation endpoints allow cross-site calls, so the instruction is to deploy only on a trusted LAN, restrict the source IPs with the Windows firewall, and never expose port 8000 to the public internet. The endpoints themselves are a sensible set. There is a health check at GET /wechat/ping/ that returns a pong status, endpoints for sending a message and sending a server-local file, a status check on whether WeChat is running, logged in and reachable, endpoints for fetching the last N chat records and for fetching them in time blocks, an endpoint that returns temporary download links for recent images and videos with the media cache kept for six hours by default, and endpoints for pinning a chat and for claiming a payment with an optional reply. The chat record response keeps the three element structure that older clients expect, so a client written against the V2 API still parses it.

Checking the connection from PowerShell

The documentation shows how to exercise the API directly, which is the quickest way to tell whether the server is alive and whether the WeChat window is reachable. The health check is a single call:

Invoke-RestMethod -Uri http://127.0.0.1:8000/wechat/ping/

Sending a message takes a little more, since the body has to be built as JSON with a name and the text, and posted with an explicit content type. The documentation builds the body with a hash table piped through ConvertTo-Json, then calls Invoke-RestMethod against the send_message path with a Post method and a JSON content type. The name is the chat to send to, and the test in the documentation uses the File Transfer Assistant chat, which is the conversation WeChat always keeps for testing. There is also a Swagger interface at the schema/swagger-ui path and a Redoc view at the schema/redoc path, both on the same port, and the documentation says the full field list and live debugging are best read there. The server home page also exposes the auto-claim status, start and stop buttons, the thank you message and the WeChat window size settings, and saving a window size on that page turns off maximise mode so the single column layout is kept.

Editorial conclusion

YuYuWechat suits a Windows user on a specific WeChat build who needs repeated messages and file sends on a schedule, or who wants keyword alerts from chat logs, and who accepts running an automation server on the machine where WeChat lives. It does not suit a deployment on a server without a WeChat desktop session, and the V3 endpoints carry no token authentication, so the README's own advice to keep it on a trusted LAN behind a firewall is a requirement rather than a suggestion. Before you set it up, confirm your WeChat version is 4.1.8, that the interface language is Simplified Chinese, and that the desktop never sleeps, since a locked screen breaks UI automation.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. README
4. Releases
5. xieyumc/YuYuWechat on GitHub