wechat-bot: Multi-Platform IM AI Agent for WeChat, Telegram, WhatsApp, and Lark

What wechat-bot Does and Who It Is For

wechat-bot connects messaging platforms to language model APIs. On the input side it supports WeChat (via QR-code login using Wechaty), Lark (via IM event webhooks), Telegram (via Bot API long-polling), and WhatsApp (via Cloud API webhooks). On the output side it supports a broad list of services: ChatGPT, DeepSeek, Kimi, Claude, Doubao, Tongyi Qianwen, Xunfei, dify, Ollama, 302AI, deepseek-free, and Pi.

The project also integrates with OpenCLI `wx-cli` for local WeChat data access: reading chat sessions, message history, group members, Moments cache, and contact lists without going through the web protocol. This is a separate capability from the auto-reply pipeline and does not require an LLM to be configured.

The target users are developers who want to automate replies in a WeChat group or personal chat, run statistical analysis on a group's message history, or build a multi-platform bot that talks to multiple IM services from a single codebase.

The WeChat Protocol Warning

The most important constraint in this project is the WeChat account risk. The README includes two separate warnings. The first, in the quick-start section, states that WeChat Web protocols carry account risk including warnings or bans, and instructs users to use this only with accounts and scenarios where they explicitly accept the risk, keeping allowlists and usage scope narrow.

The second warning notes that WeChat has recently become very strict about this type of usage, that the default protocol can trigger warnings or account bans, and that the author of the `padlocal` protocol is no longer maintaining it. The README advises switching to a more stable protocol, but does not name a replacement.

This risk applies specifically to the WeChat integration. The Telegram, WhatsApp, and Lark integrations use official platform APIs (Bot API, Cloud API, and webhook events respectively) and do not carry the same account risk.

Quick Start with Pi and WeChat

The README's quick-start path uses Pi as the agent and WeChat as the IM channel. Install dependencies and link the CLI:

npm i
cp .env.example .env
npm link

Configure at minimum these values in `.env`:

BOT_NAME='@Your WeChat nickname'
ALIAS_WHITELIST='Friend alias allowed for private chat'
ROOM_WHITELIST='Group name allowed for access'
PI_BIN='pi'
PI_AGENT_ARGS='--print --no-session'
WECHAT_STORE_MESSAGES='true'

Start the agent:

wb agent --im wechat --agent pi

When a QR code appears in the terminal, scan it with WeChat. The message pipeline is: WeChat QR-code login, Wechaty receives the message, local JSONL capture, Pi agent reply, WeChat IM sends the reply. Trigger rules: private chats require the sender alias or nickname to be in `ALIAS_WHITELIST`; group chats require the group name in `ROOM_WHITELIST` and the message to mention `@BOT_NAME`. Non-text messages are not sent to the reply pipeline.

Configuring Other LLM Providers

Each provider requires its own section in `.env`. The DeepSeek integration uses the SiliconFlow API by default:

DEEPSEEK_API_KEY=''
DEEPSEEK_URL="https://api.siliconflow.cn/v1"
DEEPSEEK_MODEL='deepseek-ai/DeepSeek-R1'

The Tongyi Qianwen integration uses the Alibaba Cloud DashScope endpoint:

TONGYI_URL = "https://dashscope.aliyuncs.com/compatible-mode/v1"
TONGYI_API_KEY = ''
TONGYI_MODEL='qwen-plus'

The Doubao integration points to Volcano Engine. The dify integration supports both the hosted dify.ai service and self-hosted Dify deployments by setting `DIFY_URL` to the self-hosted instance URL.

The `wb` CLI binary (registered in `package.json` under `bin.wb`) accepts `--serve` to pick the LLM and `--im` to pick the platform. For Telegram, the command is `wb telegram agent --agent pi`. For WhatsApp, `wb whatsapp agent --agent pi`. For Lark, `wb lark agent --agent pi`.

The Doubao integration points to Volcano Engine. The Doubao Seed 1.6 model supports image input and deep thinking, according to the README. After registering with Volcano Engine, select a Doubao model through API access to obtain a key.

The Xunfei integration uses three credentials: an app ID, an API key, and an API secret from the Xunfei console at https://console.xfyun.cn/services. The model version defaults to v4.0 and is configured through the XUNFEI_MODEL_VERSION environment variable. The README points to specific issues for troubleshooting Xunfei service errors.

The dify integration connects to either the hosted dify.ai service or a self-hosted Dify deployment. For self-hosted deployments, set the DIFY_URL environment variable to the self-hosted instance URL. The pattern of supporting both hosted and self-hosted variants extends the tool's usefulness in environments where external API calls are restricted or where data sovereignty requirements apply.

Local WeChat Data Access with wx-cli

Separate from the auto-reply pipeline, wechat-bot integrates with OpenCLI `wx-cli` for reading local WeChat data. This capability does not send messages or require an LLM. Available commands include `wb wx sessions` for local chat sessions, `wb wx history` for message history, `wb wx members` for group members, `wb wx sns-feed` and `wb wx sns-search` for Moments cache.

The group and friend analysis feature uses these local data sources. `wb analyze --room "Group name"` runs statistics or AI deep analysis on a group's message history. `wb analyze --friend "Friend alias"` does the same for a specific contact.

This part of the project requires OpenCLI `wx-cli` to be installed and connected to a running WeChat installation. The README references OpenCLI `wx-cli` as the integration point but does not include setup instructions for it.

Maintenance and Licence

The last push to the repository was on 2026-09-04. The most recent release is 0.0.2, tagged in March 2024. The project uses MIT licence for the repository itself. The Wechaty dependency, which provides the WeChat QR-code login layer, has its own licence terms that are separate from this repository.

The `package.json` lists `wechaty` among the dependencies along with `axios`, `openai`, `commander`, `dotenv`, and others. The project is maintained by its author and accepts pull requests for new AI services, better integrations, and stronger implementations according to the README.

Docker Deployment for WeChat Bot

A Dockerfile is included in the repository for containerized deployment. The image is built from node:19. The build process installs system packages including chromium, ffmpeg, and git, then installs the Node.js dependencies. The container copies the cli.js and src/ files and starts with npm run dev.

Two Dockerfiles are available: Dockerfile for the full build and Dockerfile.alpine for a smaller Alpine-based image. Both are listed in the package.json files array, so they are included when the package is published.

The Docker image requires the --net=host flag or equivalent network access for WeChat QR-code scanning to function, since the Wechaty library needs to initiate outbound connections to Tencent's servers. The container respects the same .env file configuration as the non-containerized setup: provide the .env file at runtime using Docker's --env-file flag or by mounting it as a volume.

Editorial conclusion

wechat-bot is a practical tool for developers who need to connect one or more IM platforms to a language model for automatic replies or community analysis, and who accept the documented risks of the WeChat Web protocol. It is not suitable for production deployments where account safety is non-negotiable: the README explicitly warns that WeChat has become strict about this type of usage and that the padlocal protocol is no longer maintained. For Telegram, WhatsApp, and Lark integrations, the account risk does not apply. Verify the LLM provider configuration before running, since each service requires its own API key in `.env`.

Frequently asked questions

Official sources

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