Skip to content
Get packs

Guide · Open source

How to use wechat-bot: setup, config and AI replies

Updated · written with AI from the project's own documentation and checked against our catalogue data

wechat-bot is an open-source, MIT-licensed JavaScript project built on the Wechaty library. It receives messages from WeChat, Lark, Telegram or WhatsApp and passes them to an AI service such as ChatGPT, Claude, DeepSeek or a local Ollama model, then sends the reply back. This guide shows you how to install it, configure your .env file, start the agent and set narrow allowlists so it only answers the people and groups you choose.

wechat-botwangrongding/wechat-bot · ★ 11.5k · MIT

Quick start

  1. 1Check prerequisites. Install Node.js 18.0 or newer and npm, and get an API key or a local Ollama install.
  2. 2Install dependencies. Run npm i in the project folder.
  3. 3Create the config file. Run cp .env.example .env, then edit .env.
  4. 4Register the wb command. Run npm link so the wb command is available.
  5. 5Set allowlists and a reply service. Fill in BOT_NAME, ALIAS_WHITELIST, ROOM_WHITELIST and the values for your chosen AI service.
  6. 6Start the agent. Run wb agent --im wechat --agent pi, then scan the QR code shown in the terminal.

What you need before you install wechat-bot

You need Node.js 18.0 or newer and npm. The README recommends an LTS version of Node.js, since older versions can fail at runtime.

You also need at least one AI option: an API key for a supported cloud service, or a local Ollama install. If you only use the project to read local WeChat data or operate Lark IM, the README says you do not need to configure an LLM.

  • Node.js 18.0 or newer (LTS recommended)
  • npm
  • An API key for at least one AI service, or a local Ollama install

Install wechat-bot and create the config file

Clone the repository, then run the three install commands from the README in the project folder. npm i installs dependencies, cp creates your .env file from the template, and npm link registers the wb command.

Setup involves editing .env, so expect to work in a text editor and a terminal.

npm i cp .env.example .env npm link

Configure .env for WeChat and your allowlists

Set your bot name and the allowlists in .env. The README says private chats are answered only when the sender's alias or nickname is in ALIAS_WHITELIST, and group chats are answered only when the group name is in ROOM_WHITELIST and the message mentions @BOT_NAME. Keep these lists short.

The Pi example also sets PI_BIN, PI_AGENT_ARGS and WECHAT_STORE_MESSAGES. Use the values shown in the README for those settings.

  • BOT_NAME: your WeChat nickname with the @ prefix used in the README example
  • ALIAS_WHITELIST: friend aliases allowed for private chat
  • ROOM_WHITELIST: group names allowed for access
  • Non-text messages are not sent to the reply pipeline automatically
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'

Connect an AI service such as Ollama, DeepSeek or Claude

Pick one reply service and fill in its values in .env. The README lists ChatGPT, doubao, deepseek, Kimi, Xunfei, deepseek-free, 302AI, dify, ollama, tongyi, claude and pi as --serve options. For a local model, Ollama needs a URL and a model name. The README example uses the Ollama chat endpoint on your own machine.

Cloud services need an API key from the provider. The ChatGPT section is marked as a paid service, so check your billing before relying on it.

  • Ollama: set OLLAMA_URL, OLLAMA_MODEL and OLLAMA_SYSTEM_MESSAGE
  • DeepSeek: set DEEPSEEK_FREE_TOKEN with your key from the DeepSeek platform
  • ChatGPT: set OPENAI_API_KEY; this is a paid service
  • Claude: set CLAUDE_API_KEY, CLAUDE_MODEL and related values
  • Other OpenAI-compatible APIs can work by setting their key, model and proxy URL in .env
OLLAMA_URL='http://127.0.0.1:11434/api/chat' OLLAMA_MODEL='qwen2.5:7b' OLLAMA_SYSTEM_MESSAGE='You are a personal assistant.'

Start the agent and log in with a QR code

Run the start command below. When a QR code appears in the terminal, scan it with WeChat. After login, the README describes this pipeline: Wechaty receives the message, the project captures it locally as JSONL, the agent generates a reply, and WeChat sends it.

The Pi example uses --serve Pi through the wb agent command. Other services follow the same pattern through the --serve option listed in the README.

  • Terminal shows a QR code: scan it with WeChat
  • Replies go only to allowlisted private chats and groups
wb agent --im wechat --agent pi

Use local chat analysis for a group or friend

The README says wb analyze can run local statistics and, if a reply service is configured, AI deep analysis. It takes a group name or a friend alias. The README also lists commands for sessions, history and members under wb wx, which read local WeChat data through OpenCLI wx-cli.

Only analyze chats you belong to, and keep the WeChat protocol warning below in mind.

  • Group analysis: wb analyze --room with the group name
  • Friend analysis: wb analyze --friend with the friend alias
  • Local data commands: wb wx sessions, wb wx history, wb wx members
wb analyze --room "Group name" wb analyze --friend "Friend alias"

What people use it for

  • Auto-reply to a short list of WeChat friends using a model you already pay for
  • Route Telegram or WhatsApp messages to an AI model through the same project
  • Answer chat messages with a local Ollama model so no cloud API is called
  • Run statistics or AI analysis on a group chat you belong to
  • Summarise activity for a specific friend using wb analyze --friend

Frequently asked questions

Is wechat-bot free to use?

The project is released under the MIT licence. You still need API access for cloud AI services, and the README notes that ChatGPT is a paid service. A local Ollama setup avoids cloud API fees but requires your own hardware.

What do I need to run wechat-bot?

You need Node.js 18.0 or newer, npm, and either an API key for at least one supported AI service or a local Ollama install. You also need to edit a .env file and run terminal commands.

Is wechat-bot safe to use with my WeChat account?

The README warns that WeChat has become strict about this type of usage and that the default protocol can trigger warnings or account bans. Use it only with accounts and scenarios where you accept that risk, and keep allowlists narrow.

Can wechat-bot use Ollama?

Yes. The README lists ollama as a reply service and gives example OLLAMA_URL, OLLAMA_MODEL and OLLAMA_SYSTEM_MESSAGE values for a local model.

Why does my bot not reply in a group chat?

According to the README, group chats are answered only when the group name is in ROOM_WHITELIST and the message mentions @BOT_NAME. Check both values in .env.

What are the alternatives to wechat-bot?

The project's comparable projects include wechaty, chatgpt-on-wechat and other forks of wechat-bot. wechaty is the library this project is built on, so it is a lower-level option for developers who want to write their own bot.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

wechat-bot suits developers who want an AI auto-reply bot for a small set of WeChat contacts or groups, or who want to route Telegram or WhatsApp messages to a model they already use. It is a poor fit for anyone who needs an officially supported WeChat integration or a polished app with no setup, because it requires .env editing, terminal work and accepts WeChat account risk.

Install options & downloads