30 分钟跑通微信机器人：wechat-bot 实现 AI 自动回复与群聊分析-迪斯科星球

30 分钟跑通微信机器人：wechat-bot 实现 AI 自动回复与群聊分析

【免费下载链接】wechat-bot🤖 Multi-platform IM AI Agent for Telegram, WhatsApp, Lark, and WeChat. Connects ChatGPT / Claude / Kimi / DeepSeek / Ollama / Pi for auto-replies, community analysis, contact management, and inactive-friend detection.项目地址: https://gitcode.com/GitHub_Trending/we/wechat-bot

wechat-bot 是一个基于 Wechaty 的微信 AI 机器人项目：扫码登录微信后，它能用 Ollama、DeepSeek、ChatGPT 等 AI 服务自动回复白名单内的私聊和群聊消息，同时把每条消息捕获成本地记录，供你随时做群聊统计和 AI 深度分析。下面这份教程带你在一台自己的电脑上把完整链路跑通。

先从一个真实场景说起：你运营着一个几百人的产品交流群，用户半夜提问没人接，你想知道本周谁话最多、大家在聊什么，又不想把聊天记录上传到别处。wechat-bot 做的事情就是：机器人账号扫码进群后，被 @ 的消息交给本地或云端的 AI 回答，所有消息同时写进一份本地"账本"，你随时可以查账、出报表。

🏢 一眼看懂 wechat-bot：一家 IM 前台公司

这个项目可以想象成一家 24 小时营业的"IM 前台公司"：Wechaty 是前台，负责登录微信、收发每一条消息；你配置的白名单是门禁名单，只有名单上的人（私聊好友）或群（被 @ 的群聊）才能进入接待流程；messages.jsonl是公司的记账本，每条消息都落一笔；你选择的 AI 服务（Ollama、DeepSeek 等）是后援团队，前台把问题转给后援，后援的回答再由前台发回微信；而wb analyze是记账部门，它只读账本、不打电话，专门输出统计报表和深度分析。

主要技术选型如下：

技术	作用	备选方案
Wechaty + wechaty-puppet-wechat4u	微信协议层，负责扫码登录、收发信	wechaty-puppet-wechat（pad 协议，更稳但需付费）
dotenv	加载`.env`环境变量	直接读 process.env
qrcode-terminal	在终端画出登录二维码	qrcode 图形库
commander	解析`wb`命令行参数	yargs
Ollama	本地模型服务，无需 API Key 和代理	DeepSeek / ChatGPT / Claude 等云端服务

1️⃣ 安装依赖并注册 wb 命令

目的：让项目装好依赖，并把 cli.js 暴露成全局的wb命令。

操作：确认 Node 版本后克隆、安装：

node -v # 必须 >= v18，建议用 LTS 版 git clone https://gitcode.com/GitHub_Trending/we/wechat-bot cd wechat-bot npm i npm link # 注册 wb 命令

国内网络如果npm i卡住，可先执行npm config set registry https://registry.npmmirror.com再重试。

预期结果：执行node ./cli.js --help能看到start、agent、analyze、wx、lark等子命令列表。执行wb --help应有相同输出。

你可能会问：npm link是必须的吗？不是。它只是把wb变成全局命令，图省事而已。跳过它的话，下文所有wb xxx都可以写成npm run start -- xxx。

2️⃣ 配置 .env：设置门禁名单和后援团队

目的：告诉机器人"谁能触发它、谁来回答它"。

操作：复制模板并编辑：

cp .env.example .env

以本地 Ollama 为例（无需 API Key，最适合第一次跑通），最小可用配置：

BOT_NAME='@你的机器人微信昵称' ALIAS_WHITELIST='好友备注1,好友备注2' ROOM_WHITELIST='群名1,群名2' AUTO_REPLY_PREFIX='' WECHAT_DATA_DIR='.data/wechat' WECHAT_STORE_MESSAGES='true' OLLAMA_URL='http://127.0.0.1:11434/api/chat' OLLAMA_MODEL='qwen2.5:7b' OLLAMA_SYSTEM_MESSAGE='You are a personal assistant.'

逐项说明"配错会怎样"：

BOT_NAME→ 机器人账号的微信昵称，必须带@。配错后果：群聊靠@昵称触发，昵称对不上就等于永远无法触发回复。
ALIAS_WHITELIST→ 允许私聊触发的备注或昵称，英文逗号分隔。配错后果：不在名单里的人私聊机器人，消息只记账不回复。
ROOM_WHITELIST→ 允许接入的群名，必须和群名称逐字一致。配错后果：该群所有消息不进入回复链路（但依然记账）。
AUTO_REPLY_PREFIX→ 可选的前缀过滤，空串表示不生效；填了之后只有以该前缀开头的消息才回复，适合"大账号"不想被每条 @ 都触发的场景。
WECHAT_DATA_DIR→ 账本目录。配错后果：wb analyze到错误路径找记录，分析结果为空。
WECHAT_STORE_MESSAGES→false时停止记账，之后的群聊分析将无数据可用，建议保持true。
OLLAMA_URL/OLLAMA_MODEL→ 本地 Ollama 的地址与模型名。配错后果：机器人正常收消息，但 AI 调用报错、不回复。

如果用云端服务，改换对应配置即可，比如 DeepSeek 填DEEPSEEK_API_KEY，ChatGPT 填OPENAI_API_KEY，具体变量名参考 README.md 中"支持的回复 / Agent 服务"一节。

3️⃣ 扫码登录，验证自动回复链路

目的：让"前台 → 账本 → 后援"整条链路转起来。

操作：

wb start --serve ollama

预期结果分三步观察：

终端打印出一枚二维码，用机器人账号的微信扫码；
终端出现has logged in，说明前台已就位；
到白名单群里发一条@你的机器人微信昵称今天天气怎么样，几秒后机器人在群里回复；再让ALIAS_WHITELIST里的朋友私聊发一句，同样收到回复。

此时打开.data/wechat/messages.jsonl，应能看到刚发的消息以 JSON 一行一条追加进去——账本在正常记账。

触发规则只有一条判断标准，记不住就回头看这里：

私聊：发消息人的备注或昵称在ALIAS_WHITELIST中；
群聊：群名在ROOM_WHITELIST中，且消息里真正@了BOT_NAME；
非文本消息（图片、语音等）不进入回复链路，只记账。

一个必须知道的风险提示：默认使用的免费 Web 协议（wechaty-puppet-wechat4u）存在被微信风控甚至封号的可能，README 中有明确警告。请只在自己能接受风险的账号上使用，并保持白名单尽量小。

4️⃣ 查账与出报表：群聊统计和深度分析

目的：确认捕获的数据可用，并生成群聊分析。

操作：统计和分两步走：

# 第一步：纯本地统计，不调用 AI wb analyze --room "群名1" --stats-only # 第二步：交给 AI 做深度分析 wb analyze --room "群名1" --serve ollama

预期结果：终端输出消息总数、文本消息数、平均长度、高频发言者等统计；第二步还会输出结构化的中文分析（关键统计、主要话题、互动模式、风险提醒、建议）。实现细节可以对照 analysis 模块和消息存储模块。

除了在终端查账，机器人还支持在微信里直接下命令（仅对白名单内的人/群生效，前缀/可通过BOT_COMMAND_PREFIX调整）：

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

/统计只读本地账本；/分析会把最近消息样本交给当前--serve指定的服务，处理隐私聊天时建议优先选 Ollama 这类本地模型。

5️⃣ 可选：Docker 部署到服务器

目的：让前台 24 小时在岗。

操作：

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

预期结果：容器后台运行，docker logs -f wechat-bot中能看到登录二维码，扫码后行为与本地完全一致。镜像定义见 Dockerfile。

🔧 三个高频故障：现象 → 原因 → 修复

现象：扫码登录成功，群里 @ 机器人没有任何反应。原因：三个条件缺一不可——BOT_NAME与真实昵称不一致、群名不在ROOM_WHITELIST、消息里没有真正的@（手动打"@xx"不算，必须用微信的 @ 功能）。修复：逐项核对.env，群名做到逐字一致；确认消息里 @ 的对象正是机器人账号。
现象：npm i在 puppeteer 下载 Chromium 阶段长时间卡住或失败。原因：浏览器二进制下载在国内网络下容易超时。修复：设置export PUPPETEER_SKIP_DOWNLOAD=true（Windows 为SET PUPPETEER_SKIP_DOWNLOAD=true）后重新npm i，项目运行本身不依赖这个下载。
现象：机器人正常收消息，但云端服务（DeepSeek、ChatGPT 等）不回复。原因：API Key 未配置、余额不足，或终端无法直连对应服务（需要代理）。修复：先单独验证 Key，例如node ./src/deepseek/__test__.js；确认可达后，为终端设置https_proxy/http_proxy再启动机器人。

🧭 进阶路径

换后援团队：通过--serve在deepseek、claude、dify、ollama、pi等 12 种服务间切换，只需在.env里补齐对应服务的 Key 和模型配置，消息处理链路本身不用改。
读本机微信数据：wb wx init之后可以用wb wx sessions、wb wx history、wb wx sns-search直接访问本机微信的会话、聊天记录和朋友圈缓存（由 OpenCLI 的 wx-cli 透传实现）。
多 IM 渠道：wb lark login、wb lark send、wb lark messages提供了飞书的登录、读、搜、发通道；目前飞书还是 CLI 控制通道，尚未接入实时自动回复。

（完）

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析