wechat-bot: A Wechaty-Based IM Agent That Puts an LLM Behind WeChat, Lark, Telegram and WhatsApp

The gap wechat-bot fills: IM clients do not speak to model APIs

The problem is not model access. It is that WeChat, Lark, Telegram and WhatsApp each expose messages through a different transport, and none of them hands you a normalised message object you can forward to an HTTP API. wechat-bot treats those four transports as interchangeable inputs and the model provider as an interchangeable output. The README describes the project as a WeChat / IM agent based on Wechaty that can route messages received from WeChat QR-code login, Lark IM events, Telegram Bot API polling, or WhatsApp Cloud API webhooks to ChatGPT, DeepSeek, Ollama, Claude, Pi and other services. That routing layer is the actual product. The audience is developers who want an LLM to answer inside an existing chat account rather than inside a web app. The secondary audience is narrower and more interesting: people who want to read local WeChat data (sessions, history, group members, Moments cache) without going through an official API at all, using the OpenCLI wx-cli integration that the feature table lists under wb wx sessions, wb wx history, wb wx members, wb wx sns-feed and wb wx sns-search.

Message pipeline: QR login, JSONL capture, agent reply, send

The README gives the pipeline in one line: WeChat QR-code login, then Wechaty receives the message, then a local JSONL capture, then the Pi agent reply, then WeChat IM sends the reply. The JSONL step matters because it decouples capture from generation. WECHAT_STORE_MESSAGES='true' is the switch that turns it on, which means a message can be persisted even when no reply is produced, and the same stored stream is what wb analyze later reads for statistics or AI deep analysis. Triggering is deliberately narrow. Private chats require the sender alias or nickname to appear in ALIAS_WHITELIST. Group chats require the group name to be in ROOM_WHITELIST and the message to mention @BOT_NAME. Non-text messages are not automatically sent to the reply pipeline, so images, files and voice notes pass through capture but not generation. That last rule is a design decision worth noticing: Doubao Seed 1.6 is documented as supporting image input, but the automatic reply path will not forward an image, so the multimodal capability is reachable only if you wire it yourself. The Pi path is described as single-turn non-interactive replies by default, controlled by PI_AGENT_ARGS='--print --no-session'. If you want conversational memory across messages, the material does not show where that state lives.

Getting it running: npm link, .env, and the wb command surface

The quick start is three commands: npm i, cp .env.example .env, npm link. The npm link step is what puts wb on your PATH, and every documented entry point goes through it: wb agent --im wechat --agent pi, wb start --serve pi, wb lark login, wb lark messages, wb lark send, wb lark agent, wb telegram agent, wb telegram send, wb whatsapp agent, wb whatsapp send, and the wb analyze --room "Group name" or wb analyze --friend "Friend alias" forms. The minimum .env for the Pi plus WeChat path is BOT_NAME, ALIAS_WHITELIST, ROOM_WHITELIST, PI_BIN, PI_AGENT_ARGS and WECHAT_STORE_MESSAGES. Provider configuration differs per service. DeepSeek uses DEEPSEEK_FREE_TOKEN. OpenAI uses OPENAI_API_KEY and the README states plainly that it is a paid service and that failures usually mean a terminal proxy problem or an account without billing. Doubao uses DOUBAO_API_KEY with a test script at node src/doubao/__test__.js. Tongyi needs three keys at once: TONGYI_URL, TONGYI_API_KEY and TONGYI_MODEL, with the URL given as https://dashscope.aliyuncs.com/compatible-mode/v1. Xunfei is flagged as easy to misconfigure because it has several keys that are easy to mix up. If pi is not installed globally, leaving PI_BIN empty makes the project fall back to npx --yes @earendil-works/pi-coding-agent, which is a sensible default for a tool you may only run occasionally.

The WeChat protocol risk is the project's own headline warning

The README does not bury this. It states that WeChat has recently become very strict about this type of usage, that the default protocol can trigger WeChat warnings or account bans, and that the author of the padlocal protocol is no longer maintaining it, with a suggestion to switch to a more stable protocol yourself. That last clause is the real limitation. The project hands you a protocol choice and does not make it for you. A ban on a personal WeChat account is not a recoverable deployment error; it is a lost account, and the README's own advice is to keep allowlists and usage scope narrow. There is a second, quieter failure mode: if you only want the wx-cli local data features or the Lark commands, the README says you do not need to configure an LLM at all, which means the project is really two tools sharing a binary. Treating it as one tool and enabling the WeChat reply pipeline by default is how people get into trouble. The wrong-tool case is a business that needs a support bot on a branded WeChat presence. The documented transports are QR-code login, Lark events, Telegram long polling and WhatsApp Cloud API webhooks, and only the first carries this account risk.

Where it sits against a direct Wechaty build or a workflow tool

The obvious alternative is writing your own Wechaty bot. Wechaty gives you the login and message events; what it does not give you is the provider matrix, the allowlist semantics, the JSONL capture, the wb analyze statistics pass over stored history, or the wb wx commands that read local sessions, contacts, group members and the Moments cache through OpenCLI wx-cli. Building those yourself is a few weeks of adapter work across twelve documented providers (ChatGPT, doubao, deepseek, Kimi, Xunfei, deepseek-free, 302AI, dify, ollama, tongyi, claude and pi). The other alternative is a general workflow runner such as n8n or a Dify deployment. Those give you a visual graph, retries and a webhook layer, and dify is in fact one of the providers this project can call. The difference is direction: a workflow tool owns the orchestration and you plug chat transports into it, while wechat-bot owns the chat transport and you plug a model endpoint into it. If your messages already arrive somewhere a webhook can reach, the workflow tool is the cleaner fit. If your messages live inside a WeChat account you log into by QR code, wechat-bot is doing work you would otherwise have to write against Wechaty directly.

Maintenance cost, release cadence and the MIT licence

Two releases are listed: 0.0.2 in March 2024, which added Kimi, and 0.0.1 in December 2022, which added the original OpenAI auto-reply. The repository's last push is dated 2026-09-04, so the code is active even though the version number has not moved past 0.0.2. That combination is worth reading carefully. A 0.0.x version string with a recently updated main branch suggests the maintainer ships changes without cutting tagged releases, which makes it harder to pin a known-good state and harder to read a changelog before upgrading. The upgrade surface is also split across three moving parts: the Wechaty protocol you choose, the OpenCLI wx-cli binary that the wb wx commands depend on, and whichever provider SDK or HTTP shape you configured. A provider changing its request format can break one --serve value without touching the others. The licence is MIT, which is permissive and imposes no copyleft obligation on your own code. That says nothing about the terms of the services you connect: OpenAI, DeepSeek, Kimi, Tongyi, Xunfei, Doubao, Claude and the rest each have their own acceptable-use and data-handling terms, and WeChat's own terms are the reason the ban warning exists. MIT covers the code in this repository, not your account, and not the data you route through it. This is not legal advice; read the provider terms yourself before pointing the bot at real conversations.

What to check before you point it at a real account

Start with the path that carries no account risk. Run npm i, cp .env.example .env and npm link, then try wb wx sessions or wb lark login before you touch the WeChat reply pipeline. The README states that neither of those needs an LLM configured, so a failure there is a setup failure, not a model failure. Once that works, pick one provider, put a single key in .env, and run the Doubao test script if Doubao is your choice, or a single manual wb agent invocation if it is not. Confirm that ALIAS_WHITELIST and ROOM_WHITELIST actually gate traffic by messaging from an account that is not on either list and checking that nothing is sent. Decide which Wechaty protocol you will use before you log in, because the README says the default one is the risky one and padlocal is unmaintained. The features that justify the project are the ones with no equivalent elsewhere in the stack: the four-transport input layer, the twelve-provider output layer, and the wx-cli bridge to local chats, contacts, group members and the Moments cache. If you only need one transport and one provider, a smaller script against Wechaty plus one HTTP call will be easier to reason about than this.

Editorial conclusion

Adopt it if you already have a WeChat account you are willing to risk, need the wx-cli local chat and Moments access, and can keep ALIAS_WHITELIST and ROOM_WHITELIST tight. Do not adopt it as a customer-facing bot on a primary WeChat account, and do not expect the README's WeChat path to be the stable one, since the project itself warns that the default protocol can trigger warnings or bans and that padlocal is unmaintained. Before committing, verify three things on your own machine: that npm link exposes the wb command, that your chosen provider key works in a single manual run, and which Wechaty protocol you will actually use in production.

Official sources

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