1. 项目概述与核心价值最近在折腾一个挺有意思的东西一个能跑在微信和企业微信里的AI助手。简单来说就是给你的微信挂上一个“外挂大脑”让它能像真人一样在群里聊天、私聊回复背后驱动的正是ChatGPT和Midjourney这类大模型。这玩意儿不是简单的消息转发它集成了负载均衡、场景模式、群聊控制等一系列实用功能让你能在一个熟悉的社交环境里低成本地体验和部署AI能力。我最初接触这个项目是想解决几个实际痛点。比如技术群里总有人问重复的基础问题手动回答效率太低又或者想给个人微信号增加一个“智能秘书”自动处理一些简单的咨询。市面上的方案要么太贵要么部署复杂而这个基于Node.js和Wechaty框架的开源项目提供了一个相对轻量且可控的解决方案。它把AI能力封装成了一个24小时在线的微信联系人你可以通过配置决定它在哪个群发言、响应哪些关键词、甚至扮演什么专业角色比如翻译官或面试官。对于开发者、社群运营者或者单纯想玩转AI的个人来说这个项目的价值在于“集成”和“可控”。你不需要从零开始研究微信协议和AI API的对接它已经帮你做好了桥梁。更重要的是它提供了精细化的控制策略比如通过正则表达式精准控制机器人的活动范围避免在无关的群里“乱说话”造成打扰。通过配置多个OpenAI API Key实现负载均衡也能有效缓解单个Key的速率限制问题提升服务的稳定性。接下来我会详细拆解从环境准备到高级配置的每一个环节分享我在部署和调试过程中积累的一手经验。2. 环境准备与前期避坑指南动手之前先把地基打牢。这个项目对运行环境有明确要求忽略细节很容易在第一步就卡住。2.1 核心环境要求解析项目明确要求Node.js 18。这并非随意设定Wechaty框架及其部分依赖特别是涉及浏览器自动化操作的puppeteer对高版本Node.js的特性有依赖。我实测在Node.js 16环境下安装过程就可能出现兼容性问题运行时也可能产生难以预料的错误。因此第一步就是检查并升级你的Node.js版本。在服务器上我推荐使用nvmNode Version Manager来管理多版本切换起来非常方便。# 使用nvm安装并切换至Node.js 18或以上版本 nvm install 18 nvm use 18另一个硬性条件是“服务器非ARM架构”。这是因为项目底层依赖的wechaty-puppet-wechat默认的微信协议实现所使用的Puppeteer一个控制Headless Chrome的工具在ARM架构例如苹果M系列芯片、树莓派上其预置的Chrome二进制文件可能存在兼容性问题或直接无法运行。如果你只有ARM架构的服务器比如一些轻量应用服务器尝试运行可能会在启动时卡在浏览器初始化阶段。一个可能的替代方案是尝试使用其他协议的Puppeteer即修改WECHATY_PUPPET环境变量但这超出了本项目默认支持的范围需要自行探索稳定性无法保证。因此最稳妥的方案仍然是选择x86_64架构的云服务器如常见的Ubuntu 22.04 LTS系统。2.2 关键依赖与系统包安装项目启动时需要启动一个无头浏览器来模拟微信Web端的登录和操作。因此我们需要安装一系列Chromium所依赖的系统库。官方步骤里给出的apt install命令列表很长但在不同的Linux发行版或纯净系统上可能会缺少某个依赖。这里分享一个更稳妥的实操心得与其记忆一长串包名不如先尝试运行如果报错缺少某个库再针对性安装。不过为了最大程度避免问题你可以直接安装puppeteer本身在Linux上推荐的依赖集合。以下命令在Ubuntu/Debian上通常能覆盖所有需求sudo apt-get update sudo apt-get install -y \ ca-certificates \ fonts-liberation \ libappindicator3-1 \ libasound2 \ libatk-bridge2.0-0 \ libatk1.0-0 \ libc6 \ libcairo2 \ libcups2 \ libdbus-1-3 \ libexpat1 \ libfontconfig1 \ libgbm1 \ libgcc1 \ libglib2.0-0 \ libgtk-3-0 \ libnspr4 \ libnss3 \ libpango-1.0-0 \ libpangocairo-1.0-0 \ libstdc6 \ libx11-6 \ libx11-xcb1 \ libxcb1 \ libxcomposite1 \ libxcursor1 \ libxdamage1 \ libxext6 \ libxfixes3 \ libxi6 \ libxrandr2 \ libxrender1 \ libxss1 \ libxtst6 \ lsb-release \ wget \ xdg-utils安装完这些基本上就为Puppeteer扫清了系统层面的障碍。接下来是项目本身的Node.js依赖使用pnpm安装速度更快、磁盘空间更省。如果没安装pnpm可以用npm i -g pnpm先进行全局安装。注意在服务器上安装系统包时务必确保apt-get update成功否则可能找不到最新的软件包源。如果是在国内服务器建议先配置好阿里云或腾讯云的镜像源以加速下载过程。3. 核心配置详解与个性化定制配置文件是机器人的“大脑”和“行为准则”理解每一项配置的作用才能让它按照你的意愿行事。核心配置主要在./config.ts和.env环境变量文件中。3.1 基础身份与连接配置首先看.env文件这里存放了最敏感的密钥和基础服务地址。# .env 示例 OPEN_API_KEYsk-xxx1,sk-xxx2,sk-xxx3 BASE_URLhttps://your-proxy.com/v1 GPT_MODELgpt-4o-mini PROMPT你是一个专业的IT技术助手回答问题时力求准确、简洁。如果不知道就明确说不知道不要编造信息。 WECHATY_PUPPETwechaty-puppet-wechatOPEN_API_KEY这是OpenAI API的密钥。项目支持负载均衡你可以用英文逗号分隔多个Key。当第一个Key达到速率限制RPM时会自动尝试下一个。实操心得不建议一次性填入太多Key比如超过5个因为轮询逻辑可能让问题排查变复杂。可以先填1-2个稳定后再增加。确保每个Key都有足够的余额和正确的权限。BASE_URL这是最关键的一项配置尤其对于国内服务器。由于网络限制直接访问api.openai.com是不通的。你需要一个能稳定访问的反向代理地址。这个地址需要能转发OpenAI官方API的请求。你可以使用一些公开的代理服务注意其稳定性和隐私政策或者自己在海外服务器搭建一个反向代理例如用Nginx配置proxy_pass。务必确保你填入的URL路径包含/v1因为OpenAI的API端点是以/v1开头的。GPT_MODEL指定使用的模型。gpt-3.5-turbo性价比高响应快gpt-4或gpt-4o系列能力更强但更贵、更慢。根据你的使用场景和预算选择。PROMPT系统提示词用于定义机器人的“人设”。这是塑造机器人性格和专业领域的关键。例如设置为“你是一位资深中医用通俗易懂的语言解答健康疑问并提醒用户严重时需就医”那么机器人就会以中医口吻回答问题。提示词可以写得很长用\n换行。3.2 行为控制与场景配置接下来是./config.ts它控制机器人在何处、以何种方式响应。export default { // 自动通过好友请求的条件 acceptText: /ChatGPT|AI助手/, // 判断在哪里开启机器人 // 群聊开关true为所有群开启正则表达式则匹配群名 enableGroup: /^(技术群|产品交流|AI探索)$/, // enableGroup: true, // 慎用可能会在所有群发言包括家人群、工作群。 // 私聊开关true为对所有好友开启正则表达式则匹配好友备注或昵称 enablePrivate: /(同事|合作伙伴)/, // enablePrivate: true, // 慎用可能会回复所有私聊消息。 // 群聊触发前缀在群里只有机器人或者消息以这个前缀开头才会触发回复 groupPrefix: ChatGPT助手 , // 例如在群里发送“ChatGPT助手 今天天气如何” // 私聊触发前缀在私聊中消息需要以这个前缀开头才会触发回复 privatePrefix: , // 如果为空则私聊所有消息都会触发。设为“问”则需发送“问什么是API” // 其他配置... model: process.env.GPT_MODEL || gpt-3.5-turbo, prompt: process.env.PROMPT || , };enableGroup 与 enablePrivate这是最重要的访问控制。我强烈建议不要直接设为true尤其是在初期。我曾因为设为true导致机器人在一个完全无关的“家庭买菜群”里接话场面一度非常尴尬。最佳实践是使用正则表达式精确匹配群名或好友备注。例如/^(技术群|产品交流|AI探索)$/表示只在这三个群生效。正则的写法需要一些JavaScript基础^代表开头$代表结尾|代表“或”。groupPrefix 与 privatePrefix这两个配置提供了第二层控制。groupPrefix通常设置为“机器人昵称 ”注意空格这样只有在群里明确机器人时它才会响应避免刷屏。privatePrefix如果设置为空那么私聊窗口的每一条消息都会触发AI回复这可能消耗大量Token。我建议设置为一个简短的前缀比如“ai”或“问”这样用户需要主动使用这个前缀才能调用机器人更可控。acceptText自动通过好友请求的规则。当有人申请添加机器人好友时如果验证信息匹配这个正则就会自动通过。可以设为你的项目名或机器人名称方便管理。重要提示修改config.ts后需要重启机器人进程才能生效。如果是Docker部署需要重建容器。4. 部署实战从零到一的启动流程配置妥当后我们进入部署启动环节。这里以最常见的Ubuntu 22.04服务器 Docker部署为例这是最推荐也是问题最少的方案。4.1 使用Docker Compose一键部署项目提供了docker-compose.yml文件它能帮你把机器人应用和它依赖的Redis服务一起管理起来。步骤一获取代码并配置环境# 1. 克隆项目代码 git clone https://github.com/shfshanyue/wechat-chatgpt.git cd wechat-chatgpt # 2. 复制环境变量模板文件 cp .example.env .env # 3. 编辑 .env 文件填入你的 OpenAI API Key、反向代理地址等如上节所述 vim .env # 或使用 nano 等编辑器 # 4. 可选但推荐编辑 config.ts配置群聊和私聊规则 vim src/config.ts步骤二启动Docker服务# 使用 docker-compose 构建镜像并启动服务-d 表示后台运行 docker-compose up -d --build这个命令会执行以下操作根据Dockerfile构建一个包含Node.js环境、项目依赖和Chromium的Docker镜像。启动两个容器一个运行微信机器人应用一个运行Redis数据库。将容器放入后台运行。步骤三查看日志并扫码登录机器人启动后最关键的一步是让微信“登录”。由于需要扫码我们必须查看容器的日志输出。# 持续查看应用容器的日志--tail 100 显示最后100行--follow 持续跟踪 docker-compose logs --tail 100 --follow wechat-chatgpt当你在日志中看到类似“Scan QR Code with your WeChat: https://...”的链接或一个巨大的二维码字符画时说明程序正在等待登录。登录操作实操要点谁扫用一个准备用作机器人的、不常用的微信小号来扫码。强烈不建议使用主力微信号因为有极小概率被腾讯检测为异常登录的风险。怎么扫将日志里的链接复制到浏览器打开会出现二维码。或者如果服务器有桌面环境可以直接查看终端显示的字符二维码但可能不清晰。用微信小号扫描这个二维码。确认登录扫描后手机微信上会提示“登录网页版微信”点击确认登录。登录成功当日志中输出“Wechaty login success!”或类似的成功信息并且停止打印二维码时表示登录成功。此时你的微信小号在网页端已经上线机器人就绪。4.2 本地或服务器直接部署非Docker如果你不想用Docker或者需要在开发环境调试可以按照以下步骤操作。步骤一安装并启动Redis机器人用Redis来存储会话上下文、用户使用次数等数据必须启动。# 安装Redis sudo apt update sudo apt install redis-server -y # 启动Redis服务并设置开机自启 sudo systemctl start redis-server sudo systemctl enable redis-server # 检查Redis是否运行 sudo systemctl status redis-server项目代码中默认尝试连接redis这个主机名。为了让应用能连接到本机的Redis我们需要修改系统的hosts文件将redis指向本地回环地址。echo 127.0.0.1 redis | sudo tee -a /etc/hosts步骤二安装项目依赖并启动# 1. 安装pnpm如果未安装 npm install -g pnpm # 2. 安装项目依赖使用国内镜像源可加速 pnpm config set registry https://registry.npmmirror.com/ pnpm install # 3. 生成Prisma客户端项目使用了Prisma ORM npx prisma generate # 4. 启动机器人开发模式代码变动会自动重启 pnpm start # 或者编译TypeScript代码后以生产模式启动 pnpm build pnpm start:prod之后的扫码登录步骤与Docker方式相同。避坑指南在服务器直接部署时最常见的两个问题是1.Redis连接失败。请确保Redis服务已启动并且/etc/hosts文件已正确添加127.0.0.1 redis。你也可以直接修改项目源码中lib/redis.ts里的连接配置将host改为127.0.0.1。2.Chromium启动失败。这通常是因为缺少我们之前安装的那些系统依赖库。请务必确保所有依赖都已安装成功。5. 高级功能配置Midjourney与次数限制基础聊天功能跑通后可以探索更高级的功能比如让机器人画画Midjourney和管理使用频率。5.1 Midjourney绘图功能集成这个功能让机器人能响应“画一个...”之类的指令调用Midjourney生成图片。其原理是机器人模拟用户向Discord频道发送指令并监听返回的图片结果。配置起来稍显复杂且稳定性受Midjourney官方反爬策略影响。第一步获取必要的Discord凭证你需要从用于Midjourney的Discord账号中获取以下三个信息MJ_SALAI_TOKEN你的Discord用户Token。MJ_SERVER_ID你所在的Midjourney Discord服务器ID。MJ_CHANNEL_ID你授权机器人发送和监听消息的频道ID。获取这些信息需要一定的技术操作通常通过浏览器开发者工具获取网络请求中的信息且涉及Discord账号安全务必使用小号进行操作并注意Token的保密。网上有相关教程但请注意方法可能随时失效。第二步配置环境变量在.env文件中补充以下配置MJ_SALAI_TOKEN你的Discord用户Token MJ_SERVER_ID你的Discord服务器ID MJ_CHANNEL_ID你的Discord频道ID # 可选配置阿里云OSS用于存储生成的图片并返回可访问的URL OSS_REGIONoss-cn-hangzhou OSS_ACCESS_KEY_ID你的AccessKeyId OSS_ACCESS_KEY_SECRET你的AccessKeySecret OSS_BUCKET你的Bucket名称如果不配置OSS机器人会尝试直接发送Discord的图片链接但这个链接可能不稳定或无法在微信中直接预览。配置OSS后图片会被下载并上传到你的OSS返回一个稳定的国内可访问链接体验更好。第三步使用与限制配置成功后在已开启机器人的聊天场景中发送以“画”或“draw”开头的指令具体触发词可在代码中搜索midjourney相关逻辑查看机器人就会尝试调用Midjourney。例如“画一只在星空下奔跑的柴犬”。重要警告Midjourney功能是最不稳定的环节。因为项目通过模拟浏览器请求与Discord交互这违反了Discord的使用条款Midjourney官方会持续更新反爬机制。可能导致功能突然失效甚至Discord账号被封禁。请谨慎使用并做好功能随时不可用的心理准备。建议仅作为实验性功能。5.2 使用次数限制与积分系统为了避免API被刷爆导致高额账单项目内置了一个简单的每日次数限制系统。配置通过环境变量DEFAULT_FREE_CREDIT设置每个用户微信ID每天可用的免费点数默认是30点。消耗规则每次向ChatGPT提问消耗1点。每次使用Midjourney绘图文生图或图生图消耗5点。机制用户点数用尽后机器人将不再响应其请求。项目还预留了“通过红包解锁次数”的接口但具体实现需要自行开发或参考相关代码。这个功能对于管理一个小范围的、可控的机器人非常有用。你可以在.env中根据你的API预算调整这个数值。例如如果你有10个用户每个用户每天30点全部用来问ChatGPT那么每天最多消耗300次请求结合你的OpenAI API定价就能估算出每日成本上限。6. 企业微信支持与运维管理除了个人微信项目也支持企业微信作为机器人载体更适合办公场景。6.1 切换至企业微信机器人要将机器人挂载到企业微信上你需要更改Puppet协议实现。在.env文件中进行如下配置# 注释掉或删除原来的微信配置 # WECHATY_PUPPETwechaty-puppet-wechat # 启用企业微信Puppet Service WECHATY_PUPPETwechaty-puppet-service WECHATY_PUPPET_SERVICE_TOKEN你的puppet_service_token这里的WECHATY_PUPPET_SERVICE_TOKEN需要从Wechaty的官方服务商或自建的Puppet Service服务获取。企业微信的协议比个人微信更稳定但通常需要付费购买Token或自行搭建复杂的协议服务器。对于大多数个人用户使用个人微信Puppetwechaty-puppet-wechat是更简单直接的选择。6.2 进程守护与日志查看对于长期运行的机器人我们需要确保它异常退出后能自动重启。Docker方式Docker Compose默认的restart: unless-stopped策略已经可以满足基本需求。如果容器异常退出Docker会尝试重启它。服务器直接部署方式需要使用进程守护工具。最常用的是pm2。# 全局安装pm2 pnpm add -g pm2 # 使用pm2启动你的应用假设生产模式启动命令是 npm run start:prod pm2 start npm --name wechat-chatgpt -- run start:prod # 设置开机自启 pm2 startup pm2 save # 查看日志 pm2 logs wechat-chatgpt日志管理心得机器人运行日志对于排查问题至关重要。建议将日志输出到文件并定期归档。可以在pm2配置中指定日志路径或者使用Docker的日志驱动。重点关注以下几种日志登录状态定期检查是否有掉线重连的日志。API调用错误如OpenAI返回429限速、401密钥无效等错误。消息处理异常某些特殊格式消息可能导致处理逻辑出错。7. 常见问题排查与稳定性优化在实际运行中你肯定会遇到各种问题。下面是我总结的一些典型问题及其解决方案。7.1 登录与连接问题问题现象可能原因解决方案扫码后提示“登录失败”或二维码反复刷新1. 网络不稳定无法连接微信服务器。2. 使用的微信账号不活跃或存在安全风险。3. 服务器IP被微信限制。1. 确保服务器网络通畅尝试更换服务器地区。2. 使用一个活跃的、常登录的微信小号并先在手机端确认登录。3. 这个IP可能被微信风控尝试更换服务器IP。登录成功一段时间后自动掉线微信网页版长时间无操作会强制下线属于正常现象。项目本身有断线重连机制。检查日志确认是否在尝试重连。确保运行环境稳定避免频繁重启。Docker日志中看不到二维码可能是Puppeteer在Docker容器中启动Chromium失败。确保Docker镜像正确构建了所有依赖。尝试在docker-compose.yml中为服务添加privileged: true有安全风险仅测试用或调整shm_size。更根本的方法是检查构建日志确认系统依赖包已安装。7.2 ChatGPT API 相关错误问题现象可能原因解决方案机器人不回复日志显示429 Too Many RequestsOpenAI API 速率限制RPM每分钟请求数。单个Key的免费用户或初代付费用户限制较严。1.配置多个API Key在.env的OPEN_API_KEY中用逗号分隔多个Key项目会自动轮询。2.降低使用频率通过privatePrefix和enableGroup严格限制触发条件减少非必要请求。3.升级API套餐考虑升级到更高限速的付费计划。回复内容为“抱歉我还没有学会回答这个问题…”或直接报错1.BASE_URL配置的反向代理不可用或错误。2. API Key无效或余额不足。3. 请求的模型GPT_MODEL不存在或无权访问。1.测试代理用curl命令测试你的BASE_URL是否能通例如curl https://your-proxy.com/v1/models需带API Key头。2.检查Key登录OpenAI平台确认Key有效且有余额。3.核对模型名确认GPT_MODEL名称拼写正确如gpt-3.5-turbo。回复速度非常慢1. 反向代理网络延迟高。2. 使用了响应慢的模型如GPT-4。3. 服务器到代理或OpenAI网络不佳。1. 更换一个延迟更低、更稳定的反向代理服务。2. 对于实时聊天优先使用gpt-3.5-turbo或gpt-4o-mini。3. 考虑将机器人部署在海外服务器直连OpenAI API。7.3 功能与行为异常问题现象可能原因解决方案在指定的群里机器人不回复1.config.ts中的enableGroup正则未匹配该群名。2.groupPrefix配置有误或时格式不对。1. 检查群聊名称是否完全匹配正则表达式。注意群名可能包含不可见字符。2. 默认groupPrefix可能为空尝试在群里发送“机器人昵称 你好”测试。确保的是机器人的微信昵称。私聊每句话都回复想加前缀控制config.ts中的privatePrefix配置为空字符串。将privatePrefix设置为一个特定前缀如/ai。这样只有发送“/ai 今天天气怎么样”才会触发回复。Midjourney功能一直提示“正在绘画请稍候”然后失败1. Discord Token或频道ID配置错误。2. Midjourney反爬策略更新依赖的midjourney-api库失效。3. 网络无法访问Discord。1. 重新检查并获取正确的MJ_SALAI_TOKEN、MJ_SERVER_ID、MJ_CHANNEL_ID。2. 查看项目GitHub的Issue或midjourney-api库的更新尝试升级相关依赖。3. 确认服务器网络能访问Discord。这是一个高维护成本功能要有随时失效的预期。7.4 稳定性优化建议密钥轮询与降级务必配置至少2-3个OpenAI API Key。当一个Key达到限额时系统能自动切换保障服务不中断。精细化访问控制充分利用enableGroup、enablePrivate、groupPrefix、privatePrefix将机器人的响应范围控制在最小必要范围减少无效调用和潜在骚扰。监控与告警简单的监控可以通过pm2 logs或docker logs定期查看。更进阶的做法是将日志中出现的“Error”、“failed”等关键字通过脚本监控并发送到你的邮箱或钉钉/飞书群。定期更新关注项目GitHub仓库的更新定期拉取新代码。特别是修复安全漏洞和适配微信协议变化的更新。备份配置你的.env和config.ts文件是核心资产。特别是经过复杂调试的正则表达式和提示词建议进行版本管理或定期备份。这个项目就像一个功能强大的乐高套装提供了基础模块和连接器让你能快速搭建出一个可用的微信AI助手。它的价值在于整合与简化省去了你从零研究协议对接、会话管理、异步处理等复杂环节的麻烦。然而它也不是一个开箱即用就高枕无忧的产品其稳定性高度依赖于外部服务OpenAI、微信、Midjourney和你的运维配置。最适合它的场景是小范围的、可控的技术探索或内部工具使用比如作为一个技术问答助手存在于某个小团队群或者作为个人娱乐和学习的伴侣。在部署和使用过程中保持耐心仔细阅读日志善用社区资源你就能更好地驾驭这个工具让它为你的工作或生活增添一份智能的乐趣。
基于Node.js与Wechaty的微信AI助手部署与配置实战
1. 项目概述与核心价值最近在折腾一个挺有意思的东西一个能跑在微信和企业微信里的AI助手。简单来说就是给你的微信挂上一个“外挂大脑”让它能像真人一样在群里聊天、私聊回复背后驱动的正是ChatGPT和Midjourney这类大模型。这玩意儿不是简单的消息转发它集成了负载均衡、场景模式、群聊控制等一系列实用功能让你能在一个熟悉的社交环境里低成本地体验和部署AI能力。我最初接触这个项目是想解决几个实际痛点。比如技术群里总有人问重复的基础问题手动回答效率太低又或者想给个人微信号增加一个“智能秘书”自动处理一些简单的咨询。市面上的方案要么太贵要么部署复杂而这个基于Node.js和Wechaty框架的开源项目提供了一个相对轻量且可控的解决方案。它把AI能力封装成了一个24小时在线的微信联系人你可以通过配置决定它在哪个群发言、响应哪些关键词、甚至扮演什么专业角色比如翻译官或面试官。对于开发者、社群运营者或者单纯想玩转AI的个人来说这个项目的价值在于“集成”和“可控”。你不需要从零开始研究微信协议和AI API的对接它已经帮你做好了桥梁。更重要的是它提供了精细化的控制策略比如通过正则表达式精准控制机器人的活动范围避免在无关的群里“乱说话”造成打扰。通过配置多个OpenAI API Key实现负载均衡也能有效缓解单个Key的速率限制问题提升服务的稳定性。接下来我会详细拆解从环境准备到高级配置的每一个环节分享我在部署和调试过程中积累的一手经验。2. 环境准备与前期避坑指南动手之前先把地基打牢。这个项目对运行环境有明确要求忽略细节很容易在第一步就卡住。2.1 核心环境要求解析项目明确要求Node.js 18。这并非随意设定Wechaty框架及其部分依赖特别是涉及浏览器自动化操作的puppeteer对高版本Node.js的特性有依赖。我实测在Node.js 16环境下安装过程就可能出现兼容性问题运行时也可能产生难以预料的错误。因此第一步就是检查并升级你的Node.js版本。在服务器上我推荐使用nvmNode Version Manager来管理多版本切换起来非常方便。# 使用nvm安装并切换至Node.js 18或以上版本 nvm install 18 nvm use 18另一个硬性条件是“服务器非ARM架构”。这是因为项目底层依赖的wechaty-puppet-wechat默认的微信协议实现所使用的Puppeteer一个控制Headless Chrome的工具在ARM架构例如苹果M系列芯片、树莓派上其预置的Chrome二进制文件可能存在兼容性问题或直接无法运行。如果你只有ARM架构的服务器比如一些轻量应用服务器尝试运行可能会在启动时卡在浏览器初始化阶段。一个可能的替代方案是尝试使用其他协议的Puppeteer即修改WECHATY_PUPPET环境变量但这超出了本项目默认支持的范围需要自行探索稳定性无法保证。因此最稳妥的方案仍然是选择x86_64架构的云服务器如常见的Ubuntu 22.04 LTS系统。2.2 关键依赖与系统包安装项目启动时需要启动一个无头浏览器来模拟微信Web端的登录和操作。因此我们需要安装一系列Chromium所依赖的系统库。官方步骤里给出的apt install命令列表很长但在不同的Linux发行版或纯净系统上可能会缺少某个依赖。这里分享一个更稳妥的实操心得与其记忆一长串包名不如先尝试运行如果报错缺少某个库再针对性安装。不过为了最大程度避免问题你可以直接安装puppeteer本身在Linux上推荐的依赖集合。以下命令在Ubuntu/Debian上通常能覆盖所有需求sudo apt-get update sudo apt-get install -y \ ca-certificates \ fonts-liberation \ libappindicator3-1 \ libasound2 \ libatk-bridge2.0-0 \ libatk1.0-0 \ libc6 \ libcairo2 \ libcups2 \ libdbus-1-3 \ libexpat1 \ libfontconfig1 \ libgbm1 \ libgcc1 \ libglib2.0-0 \ libgtk-3-0 \ libnspr4 \ libnss3 \ libpango-1.0-0 \ libpangocairo-1.0-0 \ libstdc6 \ libx11-6 \ libx11-xcb1 \ libxcb1 \ libxcomposite1 \ libxcursor1 \ libxdamage1 \ libxext6 \ libxfixes3 \ libxi6 \ libxrandr2 \ libxrender1 \ libxss1 \ libxtst6 \ lsb-release \ wget \ xdg-utils安装完这些基本上就为Puppeteer扫清了系统层面的障碍。接下来是项目本身的Node.js依赖使用pnpm安装速度更快、磁盘空间更省。如果没安装pnpm可以用npm i -g pnpm先进行全局安装。注意在服务器上安装系统包时务必确保apt-get update成功否则可能找不到最新的软件包源。如果是在国内服务器建议先配置好阿里云或腾讯云的镜像源以加速下载过程。3. 核心配置详解与个性化定制配置文件是机器人的“大脑”和“行为准则”理解每一项配置的作用才能让它按照你的意愿行事。核心配置主要在./config.ts和.env环境变量文件中。3.1 基础身份与连接配置首先看.env文件这里存放了最敏感的密钥和基础服务地址。# .env 示例 OPEN_API_KEYsk-xxx1,sk-xxx2,sk-xxx3 BASE_URLhttps://your-proxy.com/v1 GPT_MODELgpt-4o-mini PROMPT你是一个专业的IT技术助手回答问题时力求准确、简洁。如果不知道就明确说不知道不要编造信息。 WECHATY_PUPPETwechaty-puppet-wechatOPEN_API_KEY这是OpenAI API的密钥。项目支持负载均衡你可以用英文逗号分隔多个Key。当第一个Key达到速率限制RPM时会自动尝试下一个。实操心得不建议一次性填入太多Key比如超过5个因为轮询逻辑可能让问题排查变复杂。可以先填1-2个稳定后再增加。确保每个Key都有足够的余额和正确的权限。BASE_URL这是最关键的一项配置尤其对于国内服务器。由于网络限制直接访问api.openai.com是不通的。你需要一个能稳定访问的反向代理地址。这个地址需要能转发OpenAI官方API的请求。你可以使用一些公开的代理服务注意其稳定性和隐私政策或者自己在海外服务器搭建一个反向代理例如用Nginx配置proxy_pass。务必确保你填入的URL路径包含/v1因为OpenAI的API端点是以/v1开头的。GPT_MODEL指定使用的模型。gpt-3.5-turbo性价比高响应快gpt-4或gpt-4o系列能力更强但更贵、更慢。根据你的使用场景和预算选择。PROMPT系统提示词用于定义机器人的“人设”。这是塑造机器人性格和专业领域的关键。例如设置为“你是一位资深中医用通俗易懂的语言解答健康疑问并提醒用户严重时需就医”那么机器人就会以中医口吻回答问题。提示词可以写得很长用\n换行。3.2 行为控制与场景配置接下来是./config.ts它控制机器人在何处、以何种方式响应。export default { // 自动通过好友请求的条件 acceptText: /ChatGPT|AI助手/, // 判断在哪里开启机器人 // 群聊开关true为所有群开启正则表达式则匹配群名 enableGroup: /^(技术群|产品交流|AI探索)$/, // enableGroup: true, // 慎用可能会在所有群发言包括家人群、工作群。 // 私聊开关true为对所有好友开启正则表达式则匹配好友备注或昵称 enablePrivate: /(同事|合作伙伴)/, // enablePrivate: true, // 慎用可能会回复所有私聊消息。 // 群聊触发前缀在群里只有机器人或者消息以这个前缀开头才会触发回复 groupPrefix: ChatGPT助手 , // 例如在群里发送“ChatGPT助手 今天天气如何” // 私聊触发前缀在私聊中消息需要以这个前缀开头才会触发回复 privatePrefix: , // 如果为空则私聊所有消息都会触发。设为“问”则需发送“问什么是API” // 其他配置... model: process.env.GPT_MODEL || gpt-3.5-turbo, prompt: process.env.PROMPT || , };enableGroup 与 enablePrivate这是最重要的访问控制。我强烈建议不要直接设为true尤其是在初期。我曾因为设为true导致机器人在一个完全无关的“家庭买菜群”里接话场面一度非常尴尬。最佳实践是使用正则表达式精确匹配群名或好友备注。例如/^(技术群|产品交流|AI探索)$/表示只在这三个群生效。正则的写法需要一些JavaScript基础^代表开头$代表结尾|代表“或”。groupPrefix 与 privatePrefix这两个配置提供了第二层控制。groupPrefix通常设置为“机器人昵称 ”注意空格这样只有在群里明确机器人时它才会响应避免刷屏。privatePrefix如果设置为空那么私聊窗口的每一条消息都会触发AI回复这可能消耗大量Token。我建议设置为一个简短的前缀比如“ai”或“问”这样用户需要主动使用这个前缀才能调用机器人更可控。acceptText自动通过好友请求的规则。当有人申请添加机器人好友时如果验证信息匹配这个正则就会自动通过。可以设为你的项目名或机器人名称方便管理。重要提示修改config.ts后需要重启机器人进程才能生效。如果是Docker部署需要重建容器。4. 部署实战从零到一的启动流程配置妥当后我们进入部署启动环节。这里以最常见的Ubuntu 22.04服务器 Docker部署为例这是最推荐也是问题最少的方案。4.1 使用Docker Compose一键部署项目提供了docker-compose.yml文件它能帮你把机器人应用和它依赖的Redis服务一起管理起来。步骤一获取代码并配置环境# 1. 克隆项目代码 git clone https://github.com/shfshanyue/wechat-chatgpt.git cd wechat-chatgpt # 2. 复制环境变量模板文件 cp .example.env .env # 3. 编辑 .env 文件填入你的 OpenAI API Key、反向代理地址等如上节所述 vim .env # 或使用 nano 等编辑器 # 4. 可选但推荐编辑 config.ts配置群聊和私聊规则 vim src/config.ts步骤二启动Docker服务# 使用 docker-compose 构建镜像并启动服务-d 表示后台运行 docker-compose up -d --build这个命令会执行以下操作根据Dockerfile构建一个包含Node.js环境、项目依赖和Chromium的Docker镜像。启动两个容器一个运行微信机器人应用一个运行Redis数据库。将容器放入后台运行。步骤三查看日志并扫码登录机器人启动后最关键的一步是让微信“登录”。由于需要扫码我们必须查看容器的日志输出。# 持续查看应用容器的日志--tail 100 显示最后100行--follow 持续跟踪 docker-compose logs --tail 100 --follow wechat-chatgpt当你在日志中看到类似“Scan QR Code with your WeChat: https://...”的链接或一个巨大的二维码字符画时说明程序正在等待登录。登录操作实操要点谁扫用一个准备用作机器人的、不常用的微信小号来扫码。强烈不建议使用主力微信号因为有极小概率被腾讯检测为异常登录的风险。怎么扫将日志里的链接复制到浏览器打开会出现二维码。或者如果服务器有桌面环境可以直接查看终端显示的字符二维码但可能不清晰。用微信小号扫描这个二维码。确认登录扫描后手机微信上会提示“登录网页版微信”点击确认登录。登录成功当日志中输出“Wechaty login success!”或类似的成功信息并且停止打印二维码时表示登录成功。此时你的微信小号在网页端已经上线机器人就绪。4.2 本地或服务器直接部署非Docker如果你不想用Docker或者需要在开发环境调试可以按照以下步骤操作。步骤一安装并启动Redis机器人用Redis来存储会话上下文、用户使用次数等数据必须启动。# 安装Redis sudo apt update sudo apt install redis-server -y # 启动Redis服务并设置开机自启 sudo systemctl start redis-server sudo systemctl enable redis-server # 检查Redis是否运行 sudo systemctl status redis-server项目代码中默认尝试连接redis这个主机名。为了让应用能连接到本机的Redis我们需要修改系统的hosts文件将redis指向本地回环地址。echo 127.0.0.1 redis | sudo tee -a /etc/hosts步骤二安装项目依赖并启动# 1. 安装pnpm如果未安装 npm install -g pnpm # 2. 安装项目依赖使用国内镜像源可加速 pnpm config set registry https://registry.npmmirror.com/ pnpm install # 3. 生成Prisma客户端项目使用了Prisma ORM npx prisma generate # 4. 启动机器人开发模式代码变动会自动重启 pnpm start # 或者编译TypeScript代码后以生产模式启动 pnpm build pnpm start:prod之后的扫码登录步骤与Docker方式相同。避坑指南在服务器直接部署时最常见的两个问题是1.Redis连接失败。请确保Redis服务已启动并且/etc/hosts文件已正确添加127.0.0.1 redis。你也可以直接修改项目源码中lib/redis.ts里的连接配置将host改为127.0.0.1。2.Chromium启动失败。这通常是因为缺少我们之前安装的那些系统依赖库。请务必确保所有依赖都已安装成功。5. 高级功能配置Midjourney与次数限制基础聊天功能跑通后可以探索更高级的功能比如让机器人画画Midjourney和管理使用频率。5.1 Midjourney绘图功能集成这个功能让机器人能响应“画一个...”之类的指令调用Midjourney生成图片。其原理是机器人模拟用户向Discord频道发送指令并监听返回的图片结果。配置起来稍显复杂且稳定性受Midjourney官方反爬策略影响。第一步获取必要的Discord凭证你需要从用于Midjourney的Discord账号中获取以下三个信息MJ_SALAI_TOKEN你的Discord用户Token。MJ_SERVER_ID你所在的Midjourney Discord服务器ID。MJ_CHANNEL_ID你授权机器人发送和监听消息的频道ID。获取这些信息需要一定的技术操作通常通过浏览器开发者工具获取网络请求中的信息且涉及Discord账号安全务必使用小号进行操作并注意Token的保密。网上有相关教程但请注意方法可能随时失效。第二步配置环境变量在.env文件中补充以下配置MJ_SALAI_TOKEN你的Discord用户Token MJ_SERVER_ID你的Discord服务器ID MJ_CHANNEL_ID你的Discord频道ID # 可选配置阿里云OSS用于存储生成的图片并返回可访问的URL OSS_REGIONoss-cn-hangzhou OSS_ACCESS_KEY_ID你的AccessKeyId OSS_ACCESS_KEY_SECRET你的AccessKeySecret OSS_BUCKET你的Bucket名称如果不配置OSS机器人会尝试直接发送Discord的图片链接但这个链接可能不稳定或无法在微信中直接预览。配置OSS后图片会被下载并上传到你的OSS返回一个稳定的国内可访问链接体验更好。第三步使用与限制配置成功后在已开启机器人的聊天场景中发送以“画”或“draw”开头的指令具体触发词可在代码中搜索midjourney相关逻辑查看机器人就会尝试调用Midjourney。例如“画一只在星空下奔跑的柴犬”。重要警告Midjourney功能是最不稳定的环节。因为项目通过模拟浏览器请求与Discord交互这违反了Discord的使用条款Midjourney官方会持续更新反爬机制。可能导致功能突然失效甚至Discord账号被封禁。请谨慎使用并做好功能随时不可用的心理准备。建议仅作为实验性功能。5.2 使用次数限制与积分系统为了避免API被刷爆导致高额账单项目内置了一个简单的每日次数限制系统。配置通过环境变量DEFAULT_FREE_CREDIT设置每个用户微信ID每天可用的免费点数默认是30点。消耗规则每次向ChatGPT提问消耗1点。每次使用Midjourney绘图文生图或图生图消耗5点。机制用户点数用尽后机器人将不再响应其请求。项目还预留了“通过红包解锁次数”的接口但具体实现需要自行开发或参考相关代码。这个功能对于管理一个小范围的、可控的机器人非常有用。你可以在.env中根据你的API预算调整这个数值。例如如果你有10个用户每个用户每天30点全部用来问ChatGPT那么每天最多消耗300次请求结合你的OpenAI API定价就能估算出每日成本上限。6. 企业微信支持与运维管理除了个人微信项目也支持企业微信作为机器人载体更适合办公场景。6.1 切换至企业微信机器人要将机器人挂载到企业微信上你需要更改Puppet协议实现。在.env文件中进行如下配置# 注释掉或删除原来的微信配置 # WECHATY_PUPPETwechaty-puppet-wechat # 启用企业微信Puppet Service WECHATY_PUPPETwechaty-puppet-service WECHATY_PUPPET_SERVICE_TOKEN你的puppet_service_token这里的WECHATY_PUPPET_SERVICE_TOKEN需要从Wechaty的官方服务商或自建的Puppet Service服务获取。企业微信的协议比个人微信更稳定但通常需要付费购买Token或自行搭建复杂的协议服务器。对于大多数个人用户使用个人微信Puppetwechaty-puppet-wechat是更简单直接的选择。6.2 进程守护与日志查看对于长期运行的机器人我们需要确保它异常退出后能自动重启。Docker方式Docker Compose默认的restart: unless-stopped策略已经可以满足基本需求。如果容器异常退出Docker会尝试重启它。服务器直接部署方式需要使用进程守护工具。最常用的是pm2。# 全局安装pm2 pnpm add -g pm2 # 使用pm2启动你的应用假设生产模式启动命令是 npm run start:prod pm2 start npm --name wechat-chatgpt -- run start:prod # 设置开机自启 pm2 startup pm2 save # 查看日志 pm2 logs wechat-chatgpt日志管理心得机器人运行日志对于排查问题至关重要。建议将日志输出到文件并定期归档。可以在pm2配置中指定日志路径或者使用Docker的日志驱动。重点关注以下几种日志登录状态定期检查是否有掉线重连的日志。API调用错误如OpenAI返回429限速、401密钥无效等错误。消息处理异常某些特殊格式消息可能导致处理逻辑出错。7. 常见问题排查与稳定性优化在实际运行中你肯定会遇到各种问题。下面是我总结的一些典型问题及其解决方案。7.1 登录与连接问题问题现象可能原因解决方案扫码后提示“登录失败”或二维码反复刷新1. 网络不稳定无法连接微信服务器。2. 使用的微信账号不活跃或存在安全风险。3. 服务器IP被微信限制。1. 确保服务器网络通畅尝试更换服务器地区。2. 使用一个活跃的、常登录的微信小号并先在手机端确认登录。3. 这个IP可能被微信风控尝试更换服务器IP。登录成功一段时间后自动掉线微信网页版长时间无操作会强制下线属于正常现象。项目本身有断线重连机制。检查日志确认是否在尝试重连。确保运行环境稳定避免频繁重启。Docker日志中看不到二维码可能是Puppeteer在Docker容器中启动Chromium失败。确保Docker镜像正确构建了所有依赖。尝试在docker-compose.yml中为服务添加privileged: true有安全风险仅测试用或调整shm_size。更根本的方法是检查构建日志确认系统依赖包已安装。7.2 ChatGPT API 相关错误问题现象可能原因解决方案机器人不回复日志显示429 Too Many RequestsOpenAI API 速率限制RPM每分钟请求数。单个Key的免费用户或初代付费用户限制较严。1.配置多个API Key在.env的OPEN_API_KEY中用逗号分隔多个Key项目会自动轮询。2.降低使用频率通过privatePrefix和enableGroup严格限制触发条件减少非必要请求。3.升级API套餐考虑升级到更高限速的付费计划。回复内容为“抱歉我还没有学会回答这个问题…”或直接报错1.BASE_URL配置的反向代理不可用或错误。2. API Key无效或余额不足。3. 请求的模型GPT_MODEL不存在或无权访问。1.测试代理用curl命令测试你的BASE_URL是否能通例如curl https://your-proxy.com/v1/models需带API Key头。2.检查Key登录OpenAI平台确认Key有效且有余额。3.核对模型名确认GPT_MODEL名称拼写正确如gpt-3.5-turbo。回复速度非常慢1. 反向代理网络延迟高。2. 使用了响应慢的模型如GPT-4。3. 服务器到代理或OpenAI网络不佳。1. 更换一个延迟更低、更稳定的反向代理服务。2. 对于实时聊天优先使用gpt-3.5-turbo或gpt-4o-mini。3. 考虑将机器人部署在海外服务器直连OpenAI API。7.3 功能与行为异常问题现象可能原因解决方案在指定的群里机器人不回复1.config.ts中的enableGroup正则未匹配该群名。2.groupPrefix配置有误或时格式不对。1. 检查群聊名称是否完全匹配正则表达式。注意群名可能包含不可见字符。2. 默认groupPrefix可能为空尝试在群里发送“机器人昵称 你好”测试。确保的是机器人的微信昵称。私聊每句话都回复想加前缀控制config.ts中的privatePrefix配置为空字符串。将privatePrefix设置为一个特定前缀如/ai。这样只有发送“/ai 今天天气怎么样”才会触发回复。Midjourney功能一直提示“正在绘画请稍候”然后失败1. Discord Token或频道ID配置错误。2. Midjourney反爬策略更新依赖的midjourney-api库失效。3. 网络无法访问Discord。1. 重新检查并获取正确的MJ_SALAI_TOKEN、MJ_SERVER_ID、MJ_CHANNEL_ID。2. 查看项目GitHub的Issue或midjourney-api库的更新尝试升级相关依赖。3. 确认服务器网络能访问Discord。这是一个高维护成本功能要有随时失效的预期。7.4 稳定性优化建议密钥轮询与降级务必配置至少2-3个OpenAI API Key。当一个Key达到限额时系统能自动切换保障服务不中断。精细化访问控制充分利用enableGroup、enablePrivate、groupPrefix、privatePrefix将机器人的响应范围控制在最小必要范围减少无效调用和潜在骚扰。监控与告警简单的监控可以通过pm2 logs或docker logs定期查看。更进阶的做法是将日志中出现的“Error”、“failed”等关键字通过脚本监控并发送到你的邮箱或钉钉/飞书群。定期更新关注项目GitHub仓库的更新定期拉取新代码。特别是修复安全漏洞和适配微信协议变化的更新。备份配置你的.env和config.ts文件是核心资产。特别是经过复杂调试的正则表达式和提示词建议进行版本管理或定期备份。这个项目就像一个功能强大的乐高套装提供了基础模块和连接器让你能快速搭建出一个可用的微信AI助手。它的价值在于整合与简化省去了你从零研究协议对接、会话管理、异步处理等复杂环节的麻烦。然而它也不是一个开箱即用就高枕无忧的产品其稳定性高度依赖于外部服务OpenAI、微信、Midjourney和你的运维配置。最适合它的场景是小范围的、可控的技术探索或内部工具使用比如作为一个技术问答助手存在于某个小团队群或者作为个人娱乐和学习的伴侣。在部署和使用过程中保持耐心仔细阅读日志善用社区资源你就能更好地驾驭这个工具让它为你的工作或生活增添一份智能的乐趣。
