wechat-bot Documentation

Technical Documentation: wangrongding/wechat-bot

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

WeChat Bot

English | Simplified Chinese

A WeChat / IM agent project based on Wechaty.

It can route IM 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. It can also use OpenCLI wx-cli to access local WeChat chats, contacts, group members, favorites, and Moments cache, then run statistics or AI analysis for a group chat or a specific friend.

If you want to use Pi as the project agent and WeChat, Lark, Telegram, or WhatsApp as the external communication channel, start with Pi Agent + IM Guide.

Sponsors Copy Chapter

Feature Overview Copy Chapter

Quick Start: Pi + WeChat IM Copy Chapter

npm i
cp .env.example .env
npm link

Configure at least the following 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 message -> local JSONL capture -> Pi agent reply -> WeChat IM sends reply

Trigger rules:

• Private chats: the sender alias or nickname must be in ALIAS_WHITELIST.
• Group chats: the group name must be in ROOM_WHITELIST, and the message must mention @BOT_NAME.
• Non-text messages are not automatically sent to the reply pipeline.

Note: WeChat Web protocols carry account risk, including warnings or bans. Use this only with accounts and scenarios where you explicitly accept the risk. Keep allowlists and usage scope narrow.

Contributors Copy Chapter

PRs for more AI services, better integrations, and stronger implementations are welcome.

Important WeChat Protocol Warning Copy Chapter

WeChat has recently become very strict about this type of usage. The default protocol can trigger WeChat warnings or account bans. Use it carefully. The author of the padlocal protocol is no longer maintaining it, so switch to a more stable protocol yourself if needed.

Supported Reply / Agent Services Copy Chapter

If you only use wb wx ... to access local WeChat data, or only use wb lark ... to operate Lark IM, you do not need to configure an LLM.

If you want automatic WeChat replies or wb analyze deep analysis, choose a --serve service. Current options include ChatGPT, doubao, deepseek, Kimi, Xunfei, deepseek-free, 302AI, dify, ollama, tongyi, claude, and pi.

• pi

  Pi is suitable as the project agent and can communicate through WeChat, Lark, Telegram, or WhatsApp IM:

  env Copy

  PI_BIN='pi'
  PI_NPM_PACKAGE='@earendil-works/pi-coding-agent'
  PI_AGENT_ARGS='--print --no-session'

  If your machine does not have a global pi command, leave PI_BIN empty. The project will start Pi through npx --yes @earendil-works/pi-coding-agent.

• deepseek

  Get your api key from the DeepSeek platform, then put it in .env:

  env Copy

  DEEPSEEK_FREE_TOKEN='your key'

• ChatGPT

  Get your api key from OpenAI API keys.

  This is a paid service. If requests fail, make sure your terminal proxy works and your OpenAI account has billing available.

  sh Copy

  # Copy .env.example to .env
  cp .env.example .env
  # Fill in .env
  OPENAI_API_KEY='your key'

• Doubao

  Doubao Seed 1.6 supports image input and deep thinking. After registering and logging in to Volcano Engine, select a Doubao model, choose API access, and get an API key.

  sh Copy

  # Copy .env.example to .env
  cp .env.example .env
  # Fill in .env
  DOUBAO_API_KEY='your key'
  # Test whether the API works
  node src/doubao/__test__.js

• Tongyi Qianwen

  Tongyi Qianwen is an AI service from Alibaba Cloud. After getting your API key, fill in .env:

  sh Copy

  # Copy .env.example to .env
  cp .env.example .env
  # Fill in .env
  # Tongyi URL, including the URI path
  TONGYI_URL = "https://dashscope.aliyuncs.com/compatible-mode/v1"
  # Tongyi API key
  TONGYI_API_KEY = ''
  # Tongyi model
  TONGYI_MODEL='qwen-plus'

• Xunfei

  Apply for a key from Xunfei. Be careful not to mix up the several Xunfei configuration keys. For service errors, see issues/170 and issues/180.

• Kimi

  Get a key from Kimi API keys. Kimi is currently integrated at a basic level. PRs for file upload and other improvements are welcome.

• dify

  Create an app at dify, get your API key, and fill in .env. Self-hosted Dify deployments are also supported.

  sh Copy

  # Copy .env.example to .env
  cp .env.example .env
  # Fill in .env
  DIFY_API_KEY='your key'
  # For self-hosted Dify, update the following value in .env
  # DIFY_URL='https://[your self-hosted URL]'

• ollama

  Ollama is a local AI service. Its API is close to OpenAI's API, but configuration differs from cloud services.

  sh Copy

  # Copy .env.example to .env
  cp .env.example .env
  # Fill 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.'

• 302.AI

  302.AI is an AI aggregation platform. Add an API from 302.AI APIs, then configure the API key in .env:

  env Copy

  _302AI_API_KEY = 'xxxx'
  _302AI_MODEL= 'gpt-4o-mini'

  You can choose the model yourself. Users should evaluate platform cost, payment flow, and service quality before using it.

• claude

  Register on the Anthropic Console, get an API key, then configure:

  bash Copy

  # Copy .env.example to .env if it does not already exist
  cp .env.example .env
  
  # Edit .env and add Claude settings
  CLAUDE_API_VERSION = '2023-06-01'
  CLAUDE_API_KEY = 'your API key'
  CLAUDE_MODEL = 'claude-3-5-sonnet-latest'
  # System prompt
  CLAUDE_SYSTEM = ''

• Other

  In theory, APIs compatible with OpenAI's format can be used by configuring the corresponding API key, model, and proxy URL in .env.

API Resources / Platforms Copy Chapter

• gpt4free
• chatanywhere

Development / Usage Copy Chapter

Make sure your development environment has nodejs installed. The required version is Node.js >= v18.0. Older versions can fail at runtime. An LTS version is recommended.

1. Install dependencies Copy Section

For users in mainland China, switching to the Taobao npm mirror before installing dependencies may help: npm config set registry https://registry.npmmirror.com For flexible registry switching, you can use prm-cli.

npm i

# Optional: register wb as a local command
npm link

If you do not want to run npm link, replace every wb ... command below with:

npm run start -- ...

2. Configure `.env` Copy Section

cp .env.example .env

Minimum usable configuration:

BOT_NAME='@Your WeChat nickname'
ALIAS_WHITELIST='Friend alias 1,Friend nickname 2'
ROOM_WHITELIST='Group name 1,Group name 2'
AUTO_REPLY_PREFIX=''

WECHAT_DATA_DIR='.data/wechat'
WECHAT_STORE_MESSAGES='true'

PI_BIN='pi'
PI_AGENT_ARGS='--print --no-session'

3. Start WeChat IM Copy Section

Pi agent mode:

wb agent --im wechat --agent pi

Equivalent commands:

wb start --serve pi
npm run agent
npm run start -- start --serve pi

Traditional model reply mode:

wb start --serve ollama
wb start --serve ChatGPT
wb start --serve deepseek

After startup, a QR code appears in the terminal. Scan it to log in to WeChat. After login, received WeChat messages are appended to:

.data/wechat/messages.jsonl

4. Local WeChat Data and Moments Copy Section

OpenCLI wx-cli is passed through by wb wx ... and is used to access local WeChat cache:

wb wx init
wb wx sessions
wb wx history
wb wx search
wb wx contacts
wb wx members
wb wx stats
wb wx favorites
wb wx sns-feed
wb wx sns-search
wb wx sns-notifications
wb wx help

Common flows:

# Initialize local WeChat data access
wb wx init

# View recent sessions and chat history
wb wx sessions
wb wx history

# View group members and chat statistics
wb wx members
wb wx stats

# View Moments cache and search Moments text
wb wx sns-feed
wb wx sns-search

5. Group / Friend Analysis Copy Section

Command-line analysis:

# Local statistics only, without calling AI
wb analyze --room "Group name" --stats-only
wb analyze --friend "Friend alias" --stats-only

# Call a selected service for deep analysis
wb analyze --room "Group name" --serve pi
wb analyze --friend "Friend alias" --serve ollama

Built-in commands in WeChat chats only work for allowlisted contacts or allowlisted groups by default:

/stats group GroupName
/analyze friend FriendAlias

/stats only reads local JSONL and does not call AI. /analyze sends recent message samples to the current serve service or agent. For private chats, prefer a local model or local Pi configuration.

6. Lark IM Copy Section

Lark IM is integrated through lark-cli:

# Generate a device-flow authorization link / QR-code info
wb lark login --no-wait

# Check authorization status
wb lark status

# Read / search / send messages
wb lark messages --chat-id oc_xxx
wb lark search --query "keyword"
wb lark send --chat-id oc_xxx --text "hello"

To let Pi or another provider reply to Lark messages through the event stream, configure:

LARK_AGENT_IDENTITY='bot'
LARK_AGENT_EVENT_KEY='im.message.receive_v1'
LARK_AGENT_CHAT_TYPES='p2p,group'
LARK_AGENT_MESSAGE_TYPES='text,post'
LARK_AGENT_CHAT_WHITELIST=''
LARK_AGENT_USER_WHITELIST=''
LARK_AGENT_REPLY_PREFIX=''
LARK_AGENT_GROUP_MENTION_NAME=''
LARK_AGENT_GROUP_AUTO_REPLY='false'

Then start:

wb agent --im lark --agent pi
# or
wb lark agent --agent pi

The Lark event path uses lark-cli event consume im.message.receive_v1 --as bot. Private chats are replied to by default unless you set a chat or user allowlist. Group chats require LARK_AGENT_CHAT_WHITELIST and one of these triggers: LARK_AGENT_REPLY_PREFIX, LARK_AGENT_GROUP_MENTION_NAME, or LARK_AGENT_GROUP_AUTO_REPLY=true.

Before using event replies, make sure the Lark app has enabled the im.message.receive_v1 event in the developer console and has the required IM scopes.

7. Telegram Bot API Copy Section

Telegram uses the official Bot API with long polling:

TELEGRAM_BOT_TOKEN='123456:bot-token'
TELEGRAM_AGENT_CHAT_TYPES='private,group,supergroup'
TELEGRAM_AGENT_CHAT_WHITELIST=''
TELEGRAM_AGENT_USER_WHITELIST=''
TELEGRAM_AGENT_REPLY_PREFIX=''
TELEGRAM_AGENT_GROUP_MENTION_NAME='@your_bot'
TELEGRAM_AGENT_GROUP_AUTO_REPLY='false'

Start:

wb agent --im telegram --agent pi
# or
wb telegram agent --agent pi

Private chats are replied to by default unless you set a chat or user allowlist. Group and supergroup chats require a chat allowlist and one of these triggers: reply prefix, bot mention name, or TELEGRAM_AGENT_GROUP_AUTO_REPLY=true.

You can send a test message with:

wb telegram send --chat-id 123456 --text "hello"

8. WhatsApp Cloud API Copy Section

WhatsApp uses the official Cloud API. Incoming messages are received through a webhook, so the local server must be reachable from Meta through a public HTTPS URL.

WHATSAPP_ACCESS_TOKEN='your access token'
WHATSAPP_PHONE_NUMBER_ID='your phone_number_id'
WHATSAPP_VERIFY_TOKEN='your webhook verify token'
WHATSAPP_GRAPH_API_VERSION='v23.0'
WHATSAPP_WEBHOOK_PORT='3000'
WHATSAPP_WEBHOOK_PATH='/webhook/whatsapp'
WHATSAPP_AGENT_REPLY_PREFIX=''

Start the webhook server:

wb agent --im whatsapp --agent pi
# or
wb whatsapp agent --agent pi

Configure the webhook callback URL in Meta as:

https://your-public-domain.example/webhook/whatsapp

Use the same WHATSAPP_VERIFY_TOKEN value in Meta's webhook verification form. WhatsApp replies only support inbound text messages by default.

You can send a test message with:

wb whatsapp send --to 15551234567 --text "hello"

9. Pi / OpenCLI Passthrough Copy Section

wb pi -- --help
wb pi -- --print "Analyze the current project structure"

wb opencli -- --help
wb opencli -- wx-cli help

10. Tests Copy Section

npm run test:analysis
node ./cli.js --help
node ./cli.js wx help
node ./cli.js pi -- --help

If you use cloud services such as OpenAI, Claude, or Kimi, make sure the corresponding API key, balance, and network proxy are available.

What You Need to Customize Copy Chapter

Many users assume the bot should automatically send and receive every message after startup. It does not. To avoid replying to every incoming message, the project intentionally has trigger restrictions.

Customize the following values:

• BOT_NAME: the WeChat nickname of the bot account, in a format similar to @Cola.
• ALIAS_WHITELIST: friend aliases or nicknames allowed for auto-reply.
• ROOM_WHITELIST: group chat names allowed for auto-reply.
• AUTO_REPLY_PREFIX: optional. Auto-reply is triggered only when the message matches this prefix.
• PI_AGENT_ARGS: arguments used when Pi runs as the IM agent. The default is --print --no-session.
• For deeper business logic, see src/wechaty/sendMessage.js and src/platforms/wechat/commandRouter.js.

Edit these values in .env. Example:

# Allowlist configuration
# Define the bot name. This avoids replying to too many group messages.
# Keep the @ prefix and append the WeChat nickname of the bot account.
BOT_NAME=@Cola
# Contact allowlist
ALIAS_WHITELIST=WeChatName1,Alias2
# Group chat allowlist
ROOM_WHITELIST=Group1,Group2
# Auto-reply prefix matching. For text messages, auto-reply is triggered only
# when the specified prefix matches. Empty or unset values disable this setting.
# Matching rule: group messages remove ${BOT_NAME} and trim before prefix matching;
# private messages are trimmed directly before prefix matching.
AUTO_REPLY_PREFIX=''

# Pi agent
PI_BIN='pi'
PI_AGENT_ARGS='--print --no-session'

Auto-reply is no longer limited to chatgpt. Use --serve to choose different services, such as pi, ollama, deepseek, claude, or ChatGPT.

Notes Copy Chapter

Recent WeChat review is strict. Many users have reported plugin warnings. Because the project uses a free Web protocol by default, WeChat can detect it easily. Consider using a pad protocol or buying an enterprise protocol yourself to reduce account-ban risk.

Reference change: https://github.com/wangrongding/wechat-bot/pull/263/files

Pad protocol channel shared by Wechaty, purchase carefully: http://pad-local.com

The underlying wechaty dependency itself is not actively maintained. Community feedback says the pad protocol can currently work, but frequent login/logout can still trigger warnings. Avoid buying a very long subscription at once.

FAQ Copy Chapter

The following are the author's WeChat and group QR codes. Please describe your purpose clearly when adding the author.

Runtime errors Copy Section

First check the following:

• Pull the latest code and reinstall dependencies. If necessary, delete the lock file and node_modules.

• It is usually better not to set an npm mirror while installing dependencies.

• If Puppeteer installation fails, set the environment variable:

  sh Copy

  # Mac
  export PUPPETEER_SKIP_DOWNLOAD='true'
  
  # Windows
  SET PUPPETEER_SKIP_DOWNLOAD='true'

• If you use a cloud model, make sure the terminal network can access the corresponding model service. Enable a global proxy or configure a terminal proxy manually.

  sh Copy

  # Set proxy
  export https_proxy=http://127.0.0.1:your_proxy_port;export http_proxy=http://127.0.0.1:your_proxy_port;export all_proxy=socks5://127.0.0.1:your_proxy_port
  # Then run a service test, or first check whether the CLI works
  node ./cli.js --help

• If you use OpenAI / Claude / Kimi or another cloud model, confirm that the API key, account balance, model name, and proxy settings are correct.

• Configure .env, especially BOT_NAME, allowlists, and parameters required by the current --serve service.

• Run npm run test:analysis to verify the local analysis module. Run node ./cli.js --help to verify the CLI.

• Run wb agent --im wechat --agent pi or wb start --serve <service> to start WeChat QR-code login.

• Run wb agent --im lark --agent pi or wb lark agent --agent pi to start Lark event-based replies.

You can also refer to this issue.

• How to use it? After customization, when someone mentions you in an allowlisted group, or an allowlisted private contact sends you a message, auto-reply is triggered.
• Runtime error? Check whether the Node version meets the requirement. If not, upgrade Node. Check whether dependencies are fully installed. Users in mainland China can switch npm mirrors and reinstall dependencies. prm-cli can switch registries quickly.
• How to adjust conversation mode? Prefer switching services with --serve. For custom business logic, see sendMessage.js, commandRouter.js, and the corresponding provider implementation.

Docker Deployment Copy Chapter

docker build . -t wechat-bot

docker run -d --rm --name wechat-bot -v $(pwd)/.env:/app/.env wechat-bot

• If Node repeatedly times out during docker build, download a Node.js image to your local image registry first, then change node:19 in Dockerfile to your local Node.js image version.

Star History Chart Copy Chapter

This project became No. 1 on GitHub Trending on 2023-02-13.

License Copy Chapter

MIT.

Pi Im Agent (`docs/pi-im-agent.md`) Copy Section

Pi Agent + IM Guide

English | Simplified Chinese

This document explains how to use this project as a runtime shell for a Pi agent, with IM as the external communication channel.

Target Pipeline Copy Chapter

External IM message -> wechat-bot -> Pi agent -> IM reply

Currently implemented:

• WeChat IM: receive and reply to messages after QR-code login.
• Pi agent: handles WeChat, Lark, Telegram, and WhatsApp messages as a serve type.
• Local WeChat data: access chats, group members, statistics, and Moments cache through OpenCLI wx-cli.
• Lark IM: login, send messages, read messages, search messages, and consume message events through lark-cli.
• Telegram IM: receive messages through Bot API long polling and send replies through Bot API.
• WhatsApp IM: receive messages through WhatsApp Cloud API webhooks and send replies through Cloud API.

Installation Command Copy Chapter

If you want to use the wb command directly, run this in the project root:

npm link

You can also skip wb and use:

npm run start -- <command>

Environment Configuration Copy Chapter

Copy and edit .env:

cp .env.example .env

Recommended WeChat + Pi configuration:

BOT_NAME='@Your WeChat nickname'
ALIAS_WHITELIST='Friend alias allowed for private chat'
ROOM_WHITELIST='Group name allowed for access'
AUTO_REPLY_PREFIX=''

WECHAT_DATA_DIR='.data/wechat'
WECHAT_STORE_MESSAGES='true'

PI_BIN='pi'
PI_NPM_PACKAGE='@earendil-works/pi-coding-agent'
PI_AGENT_ARGS='--print --no-session'

If your machine does not have a global pi command, leave it empty:

PI_BIN=''

The project will start Pi through npx --yes @earendil-works/pi-coding-agent, but each cold start will be slower.

Connect Pi Through WeChat QR-code Login Copy Chapter

Recommended command:

wb agent --im wechat --agent pi

Equivalent command:

wb start --serve pi

Or use npm:

npm run agent
npm run start -- start --serve pi

After startup, the terminal shows a WeChat QR code. Once login succeeds, the pipeline is:

WeChat QR-code login -> Wechaty receives message -> local JSONL capture -> Pi single-turn agent reply -> WeChat IM sends reply

Trigger rules:

• Private chats: the sender must be in ALIAS_WHITELIST.
• Group chats: the group name must be in ROOM_WHITELIST, and the message must mention @bot nickname.
• Non-text messages are not sent to the Pi reply pipeline.

Built-in WeChat Analysis Commands Copy Chapter

You can send commands directly in WeChat chats:

/stats group GroupName
/analyze group GroupName
/stats friend FriendAlias
/analyze friend FriendAlias

Notes:

• /stats only reads local JSONL and does not call AI.
• /analyze calls the current agent or AI service and sends recent message samples to the model.
• For private chats, prefer a local model or local Pi configuration.

Local WeChat Data and Moments Copy Chapter

OpenCLI wx-cli can access local WeChat cache data:

wb wx init
wb wx sessions
wb wx history
wb wx search
wb wx contacts
wb wx members
wb wx stats
wb wx favorites
wb wx sns-feed
wb wx sns-search
wb wx sns-notifications

Run this first before initial use:

wb wx init

View the full command list supported by wx-cli:

wb wx help

Lark IM Copy Chapter

Lark can log in, read and write messages, search messages, and run an event-based agent:

wb lark login --no-wait
wb lark status
wb lark messages --chat-id oc_xxx
wb lark search --query "keyword"
wb lark send --chat-id oc_xxx --text "hello"

--no-wait returns a device-flow authorization link / QR-code information. After you complete authorization, run the read/write commands.

To let Pi reply to Lark messages, configure the event agent:

LARK_AGENT_IDENTITY='bot'
LARK_AGENT_EVENT_KEY='im.message.receive_v1'
LARK_AGENT_CHAT_TYPES='p2p,group'
LARK_AGENT_MESSAGE_TYPES='text,post'
LARK_AGENT_CHAT_WHITELIST=''
LARK_AGENT_USER_WHITELIST=''
LARK_AGENT_REPLY_PREFIX=''
LARK_AGENT_GROUP_MENTION_NAME=''
LARK_AGENT_GROUP_AUTO_REPLY='false'

Start:

wb agent --im lark --agent pi
# or
wb lark agent --agent pi

The Lark agent consumes im.message.receive_v1 through lark-cli event consume. Private chats are replied to by default unless a chat or user allowlist is configured. Group chats require LARK_AGENT_CHAT_WHITELIST and one of these triggers: reply prefix, group mention name, or LARK_AGENT_GROUP_AUTO_REPLY=true.

Before using this path, enable the im.message.receive_v1 event in the Lark developer console and make sure the app has the required IM scopes.

Telegram IM Copy Chapter

Telegram uses Bot API long polling:

TELEGRAM_BOT_TOKEN='123456:bot-token'
TELEGRAM_AGENT_CHAT_WHITELIST=''
TELEGRAM_AGENT_USER_WHITELIST=''
TELEGRAM_AGENT_REPLY_PREFIX=''
TELEGRAM_AGENT_GROUP_MENTION_NAME='@your_bot'
TELEGRAM_AGENT_GROUP_AUTO_REPLY='false'

Start:

wb agent --im telegram --agent pi
wb telegram agent --agent pi

Private chats are replied to by default. Group chats require a chat allowlist and a trigger: reply prefix, bot mention name, or TELEGRAM_AGENT_GROUP_AUTO_REPLY=true.

WhatsApp IM Copy Chapter

WhatsApp uses the official Cloud API and receives inbound messages through a webhook:

WHATSAPP_ACCESS_TOKEN='your access token'
WHATSAPP_PHONE_NUMBER_ID='your phone_number_id'
WHATSAPP_VERIFY_TOKEN='your webhook verify token'
WHATSAPP_WEBHOOK_PORT='3000'
WHATSAPP_WEBHOOK_PATH='/webhook/whatsapp'
WHATSAPP_AGENT_REPLY_PREFIX=''

Start:

wb agent --im whatsapp --agent pi
wb whatsapp agent --agent pi

Configure Meta's webhook callback URL to point to your public HTTPS endpoint, for example https://your-public-domain.example/webhook/whatsapp, and use the same verify token configured in WHATSAPP_VERIFY_TOKEN.

Pi Passthrough Commands Copy Chapter

Call Pi directly:

wb pi -- --help
wb pi -- --print "Analyze the current project structure"

PI_AGENT_ARGS controls the arguments used when Pi runs as the IM reply agent. Default:

PI_AGENT_ARGS='--print --no-session'

This means each IM message is handled as a single-turn non-interactive reply. If you want to reuse a session, remove --no-session, but note that context and private data may be saved in the Pi session.

FAQ Copy Chapter

No reply after QR-code login Copy Section

Check:

• Whether the private chat sender alias is in ALIAS_WHITELIST.
• Whether the group name is in ROOM_WHITELIST.
• Whether the group chat really mentioned BOT_NAME.
• Whether BOT_NAME in .env has the form @Your WeChat nickname.
• Whether the current message is a text message.

Pi replies slowly Copy Section

Configure local Pi:

PI_BIN='pi'

If this is left empty, the project starts Pi through npx. First runs and cold starts will be slower.

Analyze only, without auto-reply Copy Section

Use command-line analysis:

wb analyze --room "Group name" --stats-only
wb analyze --friend "Friend alias" --stats-only

Or call AI for deep analysis:

wb analyze --room "Group name" --serve pi

Safety Boundary Copy Section

• The project only processes data visible to the locally logged-in account.
• WeChat auto-reply is controlled by allowlists.
• OpenCLI remote execution is disabled by default.
• /analyze sends message samples to the current model or agent. Confirm where the model runs and how it is configured before processing private data.

Pi Im Agent.Zh CN (`docs/pi-im-agent.zh-CN.md`) Copy Section

Pi Agent + IM 使用说明

English | 简体中文

这份文档说明如何把当前项目作为 Pi agent 的运行壳，用 IM 作为外部通信渠道。

目标链路 Copy Chapter

外部 IM 消息 -> wechat-bot -> Pi agent -> IM 回复

当前已实现：

• 微信 IM：扫码登录后接收/回复消息。
• Pi agent：作为 serve 类型处理微信、飞书、Telegram 和 WhatsApp 消息。
• 本地微信数据：通过 OpenCLI wx-cli 访问聊天、群成员、统计和朋友圈缓存。
• 飞书 IM：通过 lark-cli 登录、发消息、读消息、搜索消息和消费消息事件。
• Telegram IM：通过 Bot API long polling 接收消息，并通过 Bot API 发送回复。
• WhatsApp IM：通过 WhatsApp Cloud API webhook 接收消息，并通过 Cloud API 发送回复。

安装命令 Copy Chapter

如果希望直接使用 wb 命令，在项目根目录执行：

npm link

也可以不用 wb，直接使用：

npm run start -- <command>

环境配置 Copy Chapter

复制并编辑 .env：

cp .env.example .env

微信 + Pi 推荐配置：

BOT_NAME='@你的微信昵称'
ALIAS_WHITELIST='允许私聊你的好友备注'
ROOM_WHITELIST='允许接入的群名'
AUTO_REPLY_PREFIX=''

WECHAT_DATA_DIR='.data/wechat'
WECHAT_STORE_MESSAGES='true'

PI_BIN='pi'
PI_NPM_PACKAGE='@earendil-works/pi-coding-agent'
PI_AGENT_ARGS='--print --no-session'

如果本机没有全局 pi 命令，可以先留空：

PI_BIN=''

项目会通过 npx --yes @earendil-works/pi-coding-agent 调起 Pi，但每次冷启动会慢一些。

微信扫码接入 Pi Copy Chapter

推荐命令：

wb agent --im wechat --agent pi

等价命令：

wb start --serve pi

或使用 npm：

npm run agent
npm run start -- start --serve pi

启动后终端会展示微信二维码。扫码登录成功后，链路如下：

微信扫码登录 -> Wechaty 收消息 -> 本地 JSONL 捕获 -> Pi 单轮 agent 回复 -> 微信 IM 发回

触发规则：

• 私聊：发消息人必须在 ALIAS_WHITELIST 中。
• 群聊：群名必须在 ROOM_WHITELIST 中，并且消息里需要 @机器人昵称。
• 非文本消息不会进入 Pi 回复链路。

微信内置分析命令 Copy Chapter

微信聊天中可以直接发命令：

/统计 群 XX群1
/分析 群 XX群1
/统计 好友 好友备注
/分析 好友 好友备注

说明：

• /统计 只读取本地 JSONL，不调用 AI。
• /分析 会调用当前 agent 或 AI 服务，并把最近消息样本发给模型。
• 隐私聊天建议优先使用本地模型或本地 Pi 配置。

本地微信数据与朋友圈 Copy Chapter

OpenCLI 的 wx-cli 可访问本机微信缓存数据：

wb wx init
wb wx sessions
wb wx history
wb wx search
wb wx contacts
wb wx members
wb wx stats
wb wx favorites
wb wx sns-feed
wb wx sns-search
wb wx sns-notifications

首次使用先执行：

wb wx init

查看 wx-cli 支持的完整命令：

wb wx help

飞书 IM Copy Chapter

飞书可登录、读写、搜索消息，也可以启动事件驱动 agent：

wb lark login --no-wait
wb lark status
wb lark messages --chat-id oc_xxx
wb lark search --query "关键词"
wb lark send --chat-id oc_xxx --text "hello"

--no-wait 会返回 device-flow 授权链接/扫码信息。你完成授权后，再运行读写命令。

要让 Pi 回复飞书消息，配置事件 agent：

LARK_AGENT_IDENTITY='bot'
LARK_AGENT_EVENT_KEY='im.message.receive_v1'
LARK_AGENT_CHAT_TYPES='p2p,group'
LARK_AGENT_MESSAGE_TYPES='text,post'
LARK_AGENT_CHAT_WHITELIST=''
LARK_AGENT_USER_WHITELIST=''
LARK_AGENT_REPLY_PREFIX=''
LARK_AGENT_GROUP_MENTION_NAME=''
LARK_AGENT_GROUP_AUTO_REPLY='false'

启动：

wb agent --im lark --agent pi
# 或
wb lark agent --agent pi

飞书 agent 通过 lark-cli event consume 消费 im.message.receive_v1。私聊默认回复；如果配置 chat 或 user 白名单，则只回复白名单。群聊需要配置 LARK_AGENT_CHAT_WHITELIST，并命中回复前缀、群提及名，或显式设置 LARK_AGENT_GROUP_AUTO_REPLY=true。

使用这条链路前，需要在飞书开发者后台启用 im.message.receive_v1 事件，并确认应用已开通所需 IM 权限。

Telegram IM Copy Chapter

Telegram 使用 Bot API long polling：

TELEGRAM_BOT_TOKEN='123456:bot-token'
TELEGRAM_AGENT_CHAT_WHITELIST=''
TELEGRAM_AGENT_USER_WHITELIST=''
TELEGRAM_AGENT_REPLY_PREFIX=''
TELEGRAM_AGENT_GROUP_MENTION_NAME='@your_bot'
TELEGRAM_AGENT_GROUP_AUTO_REPLY='false'

启动：

wb agent --im telegram --agent pi
wb telegram agent --agent pi

私聊默认回复。群聊需要配置 chat 白名单，并命中回复前缀、机器人提及名，或显式设置 TELEGRAM_AGENT_GROUP_AUTO_REPLY=true。

WhatsApp IM Copy Chapter

WhatsApp 使用官方 Cloud API，通过 webhook 接收消息：

WHATSAPP_ACCESS_TOKEN='your access token'
WHATSAPP_PHONE_NUMBER_ID='your phone_number_id'
WHATSAPP_VERIFY_TOKEN='your webhook verify token'
WHATSAPP_WEBHOOK_PORT='3000'
WHATSAPP_WEBHOOK_PATH='/webhook/whatsapp'
WHATSAPP_AGENT_REPLY_PREFIX=''

启动：

wb agent --im whatsapp --agent pi
wb whatsapp agent --agent pi

在 Meta 后台把 webhook callback URL 配置为公开 HTTPS 地址，例如 https://your-public-domain.example/webhook/whatsapp，verify token 和 WHATSAPP_VERIFY_TOKEN 保持一致。

Pi 透传命令 Copy Chapter

直接调用 Pi：

wb pi -- --help
wb pi -- --print "分析当前项目结构"

PI_AGENT_ARGS 控制 Pi 作为 IM 回复 agent 时的参数。默认：

PI_AGENT_ARGS='--print --no-session'

这表示每条 IM 消息都是单轮非交互回复。如果希望沿用会话，可以去掉 --no-session，但要注意上下文和隐私数据会被 Pi session 保存。

常见问题 Copy Chapter

扫码后没有回复 Copy Section

检查：

• 私聊好友备注是否在 ALIAS_WHITELIST。
• 群名是否在 ROOM_WHITELIST。
• 群聊是否真的 @ 了 BOT_NAME。
• .env 中 BOT_NAME 是否形如 @你的微信昵称。
• 当前消息是否为文本消息。

Pi 回复慢 Copy Section

建议配置本机 Pi：

PI_BIN='pi'

如果留空，项目会通过 npx 调起 Pi，首次执行和冷启动都会更慢。

如何只分析，不自动回复 Copy Section

使用命令行：

wb analyze --room "群名" --stats-only
wb analyze --friend "好友备注" --stats-only

或调用 AI 深度分析：

wb analyze --room "群名" --serve pi

安全边界 Copy Section

• 项目只处理本机已登录账号可见的数据。
• 微信自动回复受白名单控制。
• OpenCLI 远程执行默认关闭。
• /分析 会把消息样本交给当前模型或 agent，处理隐私数据前请确认模型运行位置和配置。

--- METRICS ---

• Files Extracted: 3
• Estimated Token Budget: ~8151 tokens
• Canonical Reference: https://codewiki.google/github.com/wangrongding/wechat-bot