基于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版本。在服务器上，我推荐使用nvm（Node 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 \ libstdc++6 \ 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_KEY="sk-xxx1,sk-xxx2,sk-xxx3" BASE_URL="https://your-proxy.com/v1" GPT_MODEL="gpt-4o-mini" PROMPT="你是一个专业的IT技术助手，回答问题时力求准确、简洁。如果不知道，就明确说不知道，不要编造信息。" WECHATY_PUPPET="wechaty-puppet-wechat"

• OPEN_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

这个命令会执行以下操作：

1. 根据Dockerfile构建一个包含Node.js环境、项目依赖和Chromium的Docker镜像。
2. 启动两个容器：一个运行微信机器人应用，一个运行Redis数据库。
3. 将容器放入后台运行。

步骤三：查看日志并扫码登录

机器人启动后，最关键的一步是让微信“登录”。由于需要扫码，我们必须查看容器的日志输出。

# 持续查看应用容器的日志，--tail 100 显示最后100行，--follow 持续跟踪 docker-compose logs --tail 100 --follow wechat-chatgpt

当你在日志中看到类似“Scan QR Code with your WeChat: https://...”的链接或一个巨大的二维码字符画时，说明程序正在等待登录。

登录操作实操要点：

1. 谁扫？：用一个准备用作机器人的、不常用的微信小号来扫码。强烈不建议使用主力微信号，因为有极小概率被腾讯检测为异常登录的风险。
2. 怎么扫？：将日志里的链接复制到浏览器打开，会出现二维码。或者，如果服务器有桌面环境，可以直接查看终端显示的字符二维码（但可能不清晰）。用微信小号扫描这个二维码。
3. 确认登录：扫描后，手机微信上会提示“登录网页版微信”，点击确认登录。
4. 登录成功：当日志中输出“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账号中获取以下三个信息：

1. MJ_SALAI_TOKEN：你的Discord用户Token。
2. MJ_SERVER_ID：你所在的Midjourney Discord服务器ID。
3. 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_REGION=oss-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_PUPPET="wechaty-puppet-wechat" # 启用企业微信Puppet Service WECHATY_PUPPET="wechaty-puppet-service" WECHATY_PUPPET_SERVICE_TOKEN="你的puppet_service_token"

这里的WECHATY_PUPPET_SERVICE_TOKEN需要从Wechaty的官方服务商或自建的Puppet Service服务获取。企业微信的协议比个人微信更稳定，但通常需要付费购买Token或自行搭建复杂的协议服务器。对于大多数个人用户，使用个人微信Puppet（wechaty-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的日志驱动。重点关注以下几种日志：

1. 登录状态：定期检查是否有掉线重连的日志。
2. API调用错误：如OpenAI返回429（限速）、401（密钥无效）等错误。
3. 消息处理异常：某些特殊格式消息可能导致处理逻辑出错。

7. 常见问题排查与稳定性优化

在实际运行中，你肯定会遇到各种问题。下面是我总结的一些典型问题及其解决方案。

7.1 登录与连接问题

7.2 ChatGPT API 相关错误

7.3 功能与行为异常

7.4 稳定性优化建议

1. 密钥轮询与降级：务必配置至少2-3个OpenAI API Key。当一个Key达到限额时，系统能自动切换，保障服务不中断。
2. 精细化访问控制：充分利用enableGroup、enablePrivate、groupPrefix、privatePrefix，将机器人的响应范围控制在最小必要范围，减少无效调用和潜在骚扰。
3. 监控与告警：简单的监控可以通过pm2 logs或docker logs定期查看。更进阶的做法是，将日志中出现的“Error”、“failed”等关键字，通过脚本监控并发送到你的邮箱或钉钉/飞书群。
4. 定期更新：关注项目GitHub仓库的更新，定期拉取新代码。特别是修复安全漏洞和适配微信协议变化的更新。
5. 备份配置：你的.env和config.ts文件是核心资产。特别是经过复杂调试的正则表达式和提示词，建议进行版本管理或定期备份。

这个项目就像一个功能强大的乐高套装，提供了基础模块和连接器，让你能快速搭建出一个可用的微信AI助手。它的价值在于整合与简化，省去了你从零研究协议对接、会话管理、异步处理等复杂环节的麻烦。然而，它也不是一个开箱即用就高枕无忧的产品，其稳定性高度依赖于外部服务（OpenAI、微信、Midjourney）和你的运维配置。最适合它的场景是小范围的、可控的技术探索或内部工具使用，比如作为一个技术问答助手存在于某个小团队群，或者作为个人娱乐和学习的伴侣。在部署和使用过程中，保持耐心，仔细阅读日志，善用社区资源，你就能更好地驾驭这个工具，让它为你的工作或生活增添一份智能的乐趣。