iuiaoin/wechat-gptbot: a Windows hook WeChat bot that avoids login risk

The account restriction problem wechat-gptbot was built around

Most WeChat bot tutorials start with a QR code. You scan it with your phone, the library registers your account as a logged-in client, and messages flow. The README for wechat-gptbot opens by describing the outcome of that pattern: the author says that with bots based on itchat and wechaty, scanning to log in often risks account restrictions, and links to an issue in another project as the reference point. That is the problem statement. The audience is a Windows user who wants a personal or small-group WeChat assistant and is not willing to put a daily-use account in that position.

The project's answer is to stop pretending to be a WeChat client. It drives a real WeChat installation on the same machine through a Windows hook, so from WeChat's side there is no new device session and no QR login. The README states this as the core claim: implemented on a Windows hook, with no worry about the risk of WeChat account restriction. Treat that as the design intent rather than a guarantee. It removes one class of risk, the login-based one, and replaces it with a different dependency: a specific WeChat build and a DLL that matches it.

How the Windows hook and the bot process fit together

The repository layout separates the moving parts. app.py is the entry point. bot/ holds the conversation logic, channel/ is the transport layer that talks to the hooked client, plugins/ is the extension directory, and config.py plus config.template.json define the settings surface. The README's own framing is that the bot is implemented on a Windows hook, which means the message path runs client to injected DLL to a local WebSocket, then into Python. The dependency list supports that reading: websocket_client==1.5.1 is present in requirements.txt, alongside openai==0.27.8 and litellm==0.1.365.

On the model side, the README says litellm is the abstraction layer, and the badge lists OpenAI, Azure, Anthropic, Palm and Cohere as reachable providers. The features section names GPT-3, GPT-3.5, GPT-4, Claude-2, Claude Instant-1 and Command Nightly as supported models. Configuration decides which one is used: model selects the model ID, use_azure_chatgpt toggles Azure OpenAI, and azure_deployment_id carries the deployment name. Session state is held in memory with a lifetime, session_expired_duration defaults to 3600 seconds, and max_tokens caps the stored context at 1000. In group chats, chat_group_session_independent controls whether each member gets a separate session or the group shares one. That single flag changes the whole feel of a group bot, and it defaults to false.

Installing wechat-gptbot and sending a first message

The README requires Windows and a Python installation, and recommends Python 3.13 or above. The pyproject.toml agrees, setting target-version to py313 for Ruff. Start by cloning and installing the pinned dependencies.

git clone https://github.com/iuiaoin/wechat-gptbot && cd wechat-gptbot
pip install -r requirements.txt

The requirements file is fully pinned, including openai==0.27.8 and litellm==0.1.365, so the install should resolve to the versions the project was written against. Next, copy the template so there is a real config file to edit.

cp config.template.json config.json

Open config.json and at minimum set openai_api_key and, if you are not using the default, model. The template also carries role_desc, the system prompt, which defaults to "You are a helpful assistant.", and temperature, which defaults to 0.9. Before the bot can run, the README requires a separate preparation step: download the assets from the v1.0.0 release, install WeChatSetup-3.2.1.121.exe and log in, run wechat-dll-injectorV1.0.3.exe, select 3.2.1.121-LTS.dll and click inject dll. The README says the injector then prints "Successfully injected: 3.2.1.121-LTS.dll".

With the DLL injected and WeChat logged in, start the bot.

python app.py

In a single chat, the default single_chat_prefix is ["bot", "@bot"], so a message has to begin with one of those to trigger a reply. Setting that list to empty makes the bot answer everything, which the README explicitly notes. The default clear_current_session_command is "#clear session", and query_key_command is "#query key" with recent_days defaulting to 5. Image generation is triggered by the create_image_prefix list, which ships as ["draw", "paint", "imagine"], and create_image_size defaults to 256x256.

The pinned WeChat version is the real constraint

The preparation steps are not incidental setup. They are the architecture. The hook only works against the WeChat build the DLL was compiled for, which is why the README names WeChatSetup-3.2.1.121.exe and 3.2.1.121-LTS.dll rather than saying "install WeChat". If your machine already runs a newer WeChat, you are being asked to install an old client, and the README does not describe what happens if both are present or how to roll back. It also does not document an upgrade path for the DLL when WeChat updates itself.

That is the sharpest trade-off in the project. Login-based bots are portable across operating systems and survive client updates, but they carry the restriction risk the README describes. This one inverts both properties. It is Windows-only, the README says Linux support is a future possibility based on a sandbox approach and is not implemented, and it is tied to one client version at a time. The README's stability claim is about account safety, not about the code running forever unattended. The repository's last push was on 2026-03-22, so the code is not abandoned, but the newest release listed is v1.5.1 from 2023-07-20, and the release assets the setup instructions point at are from v1.0.0. If you cannot control which WeChat version runs on the host, this is the wrong tool.

Plugin system and the tiktok example

The changelog entry for 2023.07.13 introduces a plugin system, described as making gptbot easier to expand, and names one existing plugin: tiktok, in a separate repository. Plugins are configured from the same config.json through a plugins array, where each entry has a name and any additional config keys that plugin needs. The docs for usage and contribution live in plugins/README.md.

This matters for scope. The core bot handles conversation, session memory and image generation. Anything domain-specific, such as fetching media, is expected to be a plugin rather than a pull request into the core. The README does not describe a plugin API surface in the main document, so the practical reference is the plugins directory and the separate plugin repository. If your requirement is not conversation, check whether someone has already written the plugin before assuming you will extend the core.

How it differs from itchat and wechaty style bots

The honest comparison is the one the README makes itself. itchat and wechaty style bots log in as a client, usually by QR code, which the README associates with account restriction risk. wechat-gptbot instead hooks an installed Windows client through an injected DLL. The difference is not cosmetic: one adds a session to your account, the other manipulates a process already running on your machine.

What you give up is portability and update tolerance. A wechaty deployment can move to a server, run in a container, and pick up client changes without repinning a binary. wechat-gptbot cannot, per its own documentation. What you get is the property the author cared about most, stated in the first line of the README. If account safety is not your primary concern, the hook approach buys you nothing and costs you the Windows dependency. If it is, the trade is the entire point of the project.

Licence, maintenance and what an upgrade costs

The project is MIT licensed, and the README repeats that in a badge. MIT is permissive: you can use, modify and redistribute the code, including commercially, provided the licence and copyright notice are preserved. That covers the Python source. It does not automatically cover the third-party binaries the setup steps depend on. The README says WeChatSetup comes from wechat-windows-versions and the injector from wechat-bot, and thanks both owners. Those are separate projects with their own terms, and the README does not state their licences. If you plan to redistribute anything, check those two repositories directly. This is a description of the files, not legal advice.

Upgrade cost is tied to the same binaries. Python dependencies are pinned in requirements.txt, so a deliberate upgrade means editing versions and retesting against openai==0.27.8 era APIs and litellm==0.1.365. The harder cost is the WeChat side: moving to a different client version requires a matching DLL, and the README documents no procedure for that. The repository has a .pre-commit-config.yaml and Ruff settings with target-version py313, so contributions are expected to pass linting, but that says nothing about how a new DLL gets built or who builds it.

Editorial conclusion

Adopt it if you run Windows, can install WeChat 3.2.1.121, and accept that a DLL injection step is the price of avoiding login-based account restrictions. Do not adopt it if you need Linux or macOS, a current WeChat build, or a bot that survives a client update without repinning artifacts. Before anything else, verify that the v1.0.0 release assets still contain WeChatSetup-3.2.1.121.exe and 3.2.1.121-LTS.dll, because the README names those exact files and nothing else.

Frequently asked questions

Official sources

1. Issues
2. iuiaoin/wechat-gptbot on GitHub
3. License: MIT
4. README
5. Releases