30分钟跑通微信群聊AI自动回复机器人：从零配置启动到Docker部署-迪斯科星球

30分钟跑通微信群聊AI自动回复机器人：从零配置启动到Docker部署

【免费下载链接】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 让机器人对接大模型，自动回复白名单内的群聊消息，30 分钟跑通本地启动。

技术栈与消息链路全景

技术	版本	职责	替代选项与取舍
Wechaty	^1.20.2	微信机器人框架（微信协议封装，负责扫码登录与收发消息）	itchat：老方案，已停止维护
wechaty-puppet-wechat4u	^1.14.14	Puppet（底层协议驱动，决定机器人通过哪种通道连接微信）	padlocal：稳定性更好但需付费购买
commander	^12.0.0	CLI 命令解析，提供 start、analyze 等入口	yargs：能力相当，生态偏小
dotenv	^16.4.5	加载 .env 环境变量	config：功能更全，对小项目偏重
qrcode-terminal	^0.12.0	在终端直接绘制登录二维码	qrcode：输出图片文件，终端场景不便
axios / openai	^1.6.8 / ^4.52.0	调用各模型服务的 HTTP 客户端	原生 fetch：少一个依赖，但各模型协议需自行适配

消息走单条链路：先写入本地 JSONL 消息库（每行一条 JSON 记录，只追加），再经白名单过滤，通过的消息交给选定的模型服务，回复发回原群聊或私聊。本地消息库同时是群聊统计和 AI 深度分析的数据源，形成「捕获 → 过滤 → 回复 → 分析」闭环。

零配置启动步骤：从克隆到扫码登录

# 环境检查（Node 需 >= v18）并克隆代码 node -v git clone https://gitcode.com/GitHub_Trending/we/wechat-bot && cd wechat-bot

# 安装依赖（国内先切镜像），并生成配置文件 npm config set registry https://registry.npmmirror.com && npm i cp .env.example .env

# 启动机器人，终端出现二维码后用微信扫码登录 npm run start -- --serve ollama

⚠️ 两个高频坑：BOT_NAME 必须带 @ 符号（如 @可乐），漏掉则群聊 @ 触发永远不生效；npm i 卡在 puppeteer 下载时，设置 PUPPETEER_SKIP_DOWNLOAD='true' 重装即可。

消息处理链路：白名单过滤到模型回复

输入是微信的每条消息事件，无论是否回复都会先落入本地消息库。处理环节是白名单过滤：群聊要求群名在 ROOM_WHITELIST 且消息 @ 了机器人，私聊要求发送者在 ALIAS_WHITELIST，非文本消息和机器人自己的消息直接丢弃。输出是模型回复：文本交给 --serve 指定的服务生成答案，回发到原会话；以 / 开头的消息则走命令路由，用于群聊统计或分析。

// defaultMessage 判定链简化骨架 if (!isText || isBotSelf) return // 非文本或机器人自己，不处理 if (isRoom && !roomWhiteList.includes(roomName)) return if (!isRoom && !aliasWhiteList.includes(sender)) return await (room || contact).say(await getServe(serve)(question))

完整逻辑见消息处理模块，消息捕获在消息存储。

环境变量配置速查

参数	含义	示例值	不填的默认行为
BOT_NAME	机器人的微信昵称，群聊 @ 触发标识	@可乐	群聊 @ 触发不生效
ROOM_WHITELIST	允许自动回复的群名，逗号分隔	产品群,内测群	群聊只记录不回复
ALIAS_WHITELIST	允许私聊回复的好友昵称或备注	张三,李四	私聊不自动回复
AUTO_REPLY_PREFIX	消息需以此前缀开头才回复	/问	空串，无前缀限制
WECHAT_STORE_MESSAGES	是否把消息写入本地消息库	true	true，默认存储
WECHAT_DATA_DIR	消息库目录	.data/wechat	.data/wechat
OLLAMA_URL / OLLAMA_MODEL	本地 Ollama 服务地址与模型名	http://127.0.0.1:11434/api/chat	启动时提示缺配置，直接退出
PI_BIN	Pi agent 可执行命令	pi	用 npx 自动拉起，冷启动更慢

易错项一行对比：正确写法BOT_NAME=@可乐，错误写法BOT_NAME=可乐（少了 @，群聊消息里 @ 的字符串永远匹配不上）。

自动回复不生效排错速查

问题一：扫码登录后不回复

症状：群里或私聊发消息，机器人完全无响应
原因：BOT_NAME 与实际昵称不一致，或群名、好友备注不在白名单
解法：核对 .env 中 BOT_NAME 为 @+微信昵称，群名与 ROOM_WHITELIST 完全一致，且群聊消息确实 @ 了机器人

问题二：白名单配置正确仍不回复

症状：@ 机器人后依然没有响应
原因：消息不是文本类型，或设置了 AUTO_REPLY_PREFIX 但消息不匹配
解法：改发纯文本消息，临时把 AUTO_REPLY_PREFIX 设为空串再验证

问题三：npm i 安装失败

症状：卡在 puppeteer 或 chromium 下载报错
原因：浏览器二进制下载超时
解法：设置 PUPPETEER_SKIP_DOWNLOAD='true' 后重装依赖

问题四：云端模型不回复

症状：@ 后超时，控制台出现网络错误
原因：API Key 未填或本机访问不了模型服务
解法：核对 .env 中对应服务的 Key，终端设置 https_proxy 后再跑 node ./cli.js --help 验证

问题五：/统计命令无数据

症状：群里发 /统计群群名，显示消息数为 0
原因：该命令只读本地消息库，还没有捕获过该群的消息
解法：先在群里正常发几条消息，再触发统计

进阶路径：统计、深度分析与本地数据

群聊数据统计与 AI 深度分析：运行wb analyze --room "群名" --serve pi，微信内置 /分析命令的入口逻辑见命令路由。
访问本机微信缓存（会话、群成员、朋友圈）：运行wb wx init && wb wx stats。
把 Pi 接成单轮非交互 agent：参考Pi Agent 使用说明，等价命令wb agent --im wechat --agent pi。

Docker 一行命令上线与云选型

方案	配置	适合场景
轻量服务器 1C2G	Ubuntu 20.04+，预装 Docker	个人试用，成本最低，推荐
云 ECS 2C4G	固定带宽，数据盘可挂载	长期 7x24 运行、需备份消息库
本地常开机器	现有 PC 或树莓派	零成本，但断电断网即停服

# .env 中写入 SERVICE_TYPE=ollama 跳过交互选择，再构建并运行 docker build -t wechat-bot . docker run -d --name wechat-bot -v $(pwd)/.env:/app/.env -v $(pwd)/.data:/app/.data wechat-bot

⚠️ 默认 wechat4u 是微信网页协议，近期风控较严，账号可能收到外挂警告；重要主号不建议使用，请配专用号。

能力边界与下一步

自动回复仅覆盖文本消息和白名单范围，飞书通道只读不实时，网页协议存在风控风险。建议下一步：先对一个群跑wb analyze --stats-only，确认消息捕获正常，再接入云端模型。

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

企业官网建设流程全解析