wechat-bot

环境要求

• Node.js >= v18.0（推荐 LTS 版本，低版本可能运行失败）
• 已安装 npm，可正常访问 npm 源（国内可切换淘宝镜像）
• 一个可扫码登录的微信账号（Web 协议存在账号风险）
• 如需使用云模型，终端网络需能访问对应模型服务（必要时配置代理）
• 如需 Docker 部署，需本地已安装 Docker

安装与启动步骤

1. 1安装依赖

   在项目根目录执行安装，国内网络慢可先切换淘宝镜像；建议安装时不要同时设置 npm 代理镜像。

   npm i

   复制

2. 2生成配置文件

   复制示例环境变量文件为 .env，后续所有白名单和模型参数都在这里修改。

   cp .env.example .env

   复制

3. 3填写白名单配置

   编辑 .env，至少填写机器人昵称、私聊白名单和群白名单，否则收到消息不会触发回复。

4. 4链接全局命令

   执行 npm link 把项目注册为全局命令，之后才能在任意位置使用 wb 命令启动。

   npm link

   复制

5. 5启动微信机器人

   执行后终端会出现二维码，用微信扫码登录，登录成功后机器人开始按白名单规则自动回复。

   wb agent --im wechat --agent pi

   复制

6. 6Docker 部署(可选)

   先构建镜像再挂载 .env 启动容器，适合不想在宿主机装 Node 依赖的场景。

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

   复制

关键配置

如何确认成功

运行 node ./cli.js --help 和 npm run test:analysis 均正常；启动后终端出现二维码，扫码登录成功即代表跑通。

常见问题

注意事项

• 微信 Web 协议存在账号风险，可能被警告或封禁，请仅在明确接受风险的账号和场景下使用。
• 务必把白名单和使用范围控制得尽量小，避免机器人回复不相关内容。
• 非文本消息（图片、文件等）不会自动送入回复管线，需要自行扩展。
• Docker 构建时若 Node 反复超时，可先拉取本地 Node 镜像并修改 Dockerfile 中的 node:19 版本。