3步跑起AI对话微信机器人：智能微秘书部署实战指南-平芜编程栈

3步跑起AI对话微信机器人：智能微秘书部署实战指南

【免费下载链接】wechat-assistant-pro智能微秘书客户端，搭配项目地址: https://gitcode.com/GitHub_Trending/we/wechat-assistant-pro

wechat-assistant-pro（智能微秘书客户端）是基于 Wechaty 框架的微信机器人客户端，它接入个微、企微、公众号协议，承载 AI 对话、定时推送、关键词回复与群消息同步，并由智能微秘书平台的可视化配置驱动。部署客户端并登录后，全部规则在 Web 面板完成，无需改代码。本文给出最小启动路径、能力边界、协议选型与生产运行要点。

项目定位与解决什么问题

填补的空白：自己写微信机器人要处理 Wechaty 协议对接、消息分发、定时调度等底层逻辑；本项目把协议层封装成一个可部署的 Node 客户端（入口 index.js → src/index.js），配置全部上移到智能微秘书 Web 平台，你只负责"部署 + 登录"，不负责写对话逻辑。
适用场景：私域客服（挂 Dify / FastGPT 知识库做问答）、社群运营（定时新闻、问候、签到）、多群管理（跨群消息同步、批量群发）。
不适用：需要在代码层深度改造对话流程并做单元测试的团队。本仓库是协议适配层，对话规则在wechaty-web-panel插件与平台侧，二次开发的对象不是这个仓库。

🚀 快速上手：3 步跑起来并扫码登录

前置条件：一个智能微秘书平台账号（个人中心可取 APIKEY / APISECRET）、Node.js >= 18；若要用定时新闻和天气，还需注册天行数据账号并申请"天行机器人、天气、新闻、垃圾分类"四个接口权限。

git clone https://gitcode.com/GitHub_Trending/we/wechat-assistant-pro cd wechat-assistant-pro npm install # 在 src/index.js 的 WechatyWebPanelPlugin 中填入 APIKEY / APISECRET # 配置协议环境变量，例如企微：export WORK_PRO_TOKEN="你的token" npm run start

成功标志：终端输出所配协议的启动日志（如"读取到环境变量中的企微 token 使用企业微信协议启动"），到平台"小助手配置 → 登录状态"扫码（部分协议终端会直接显示二维码）。登录完成后，给机器人发送关键词更新，收到"已拉取最新配置"的确认即代表链路跑通。

注意：默认免费网页协议 wechat4u 因封号风险在当前版本已关闭（见 src/index.js 末尾的警告），必须配置企微、iPad、matrix 或公众号参数之一才能启动。

核心能力拆解

AI 对话引擎：接入 ChatGPT、Dify、FastGPT 做知识库问答

把任意群或好友变成私域问答入口，无需为每个群写代码。

平台"智能机器人回复"里切换后端：ChatGPT（支持代理地址与第三方兼容 API、自定义 Prompt 设定角色）、Dify / FastGPT / Coze（挂知识库做私域客服）、天行 / 图灵机器人。
支持按好友或群组设置不同角色，关键词触发无需 @，可设对话次数限制并挂文本审核接口。
客户端侧只是挂载wechaty-web-panel插件收发消息并回调平台（src/index.js），协议与对话逻辑解耦，换 AI 后端不用重启客户端。

定时任务与定时推送：新闻和问候按时到群

让机器人不用被 @ 也能主动运营。

每日说：固定时间推送天气 + 随机一句情话/提示。
分类新闻推送：按群配置新闻分类（国内、国际、科技等）、执行时间与结尾备注。
倒计时提醒：为某个未来日期设置每日倒计时。
固定素材发送与对话提醒：定时推文字/图片（提醒下班、打卡），私聊发固定格式内容还能直接创建一次性提醒。
RSS 订阅：源更新时推送到指定群或好友。

群聊管理与消息同步：打破群与群之间的壁垒

多群运营者可以只维护一个入口。

多群消息同步支持一对多、多对一、多对多三种模式，同步内容可选文字和图片转发。
批量群发：同一内容一次发到多个群或好友，并可批量设置群公告。
关键词进群：配置进群关键词与欢迎词，进机器人自动通过并发欢迎语。
群聊列表里在线发送文字、图片、文件、小程序、H5 链接到指定群。

素材中心与开放 API：内容复用并对接外部系统

素材与发送能力被统一管理，避免重复录入。

素材分文字、文件图片、小程序、H5 链接四类，关键词回复、欢迎语、定时推送都引用素材库条目。
开放 API 让任意外部系统调用接口向群和好友发送文字、图片、视频，也可获取全部好友列表与群列表。
回调事件把指定内容转发到你的服务器，由服务器返回回复内容——这是把对话逻辑放到自己后端的钩子。

配置与个性化定制

所有配置都在智能微秘书 Web 面板的"小助手配置"下完成，改完保存后必须给机器人发送更新关键词，客户端才会拉取新配置——这是最容易漏的一步。

关键词回复（小助手配置 → 关键词回复 → 新增规则）：每条规则包含关键词（支持多个）、匹配规则（精准/模糊）、回复内容（文字可混排素材）、是否群中 @ 触发，适合固定问答、产品信息查询、暗号获取。
基础配置：自动通过好友并回复欢迎素材、机器人触发范围（所有群/所有好友/都生效）、敏感词过滤、智能机器人后端选择与 APIKEY。
定时任务：在"定时任务"页签选择目标任务类型、目标群、内容与循环日期。

🐳 部署方案与选型建议

方式	适用场景	核心命令	注意事项
源码运行	调试协议切换、排查启动问题	`npm run start`	Node >= 18；必须配置协议环境变量，否则不启动
Docker 官方镜像	生产环境长期运行	`docker pull aibotk/wechat-assistant`	建议官方镜像源拉取，镜像 < 500M，超过 1G 说明拉错源
公众号部署	服务号/订阅号客服	`docker run -p 8077:8077 ...`	需备案域名映射 8077，容器出口 IP 加入公众号白名单

# 国内网络可在命令前加注释里的镜像源前缀：registry.cn-hangzhou.aliyuncs.com/aibotk/wechat-assistant docker pull aibotk/wechat-assistant docker run -d --name wechatbot \ -e AIBOTK_KEY="微秘书apikey" -e AIBOTK_SECRET="微秘书apiSecret" \ aibotk/wechat-assistant

公众号模式额外注入四个环境变量，端口必须映射到备案域名：

# 认证服务号 OFFICE_IS_PERSON=false；个人订阅号/未认证号=true（3秒内必须响应） docker run -d -p 8077:8077 --name officebot \ -e OFFICE_APPID="appid" -e OFFICE_APPSECRET="secret" \ -e OFFICE_TOKEN="token" -e OFFICE_IS_PERSON="false" \ -e AIBOTK_KEY="apikey" -e AIBOTK_SECRET="apisecret" \ aibotk/wechat-assistant

如果你只选一种，推荐 Docker 官方镜像：依赖在镜像里已装好，拉取即用，且企微、iPad、公众号协议只靠环境变量切换，升级只需换 tag 重跑。

🔌 进阶集成与扩展

把机器人接进你自己的系统有两条路：

开放 API：外部系统向群/好友发消息、拉好友与群列表。请求路径与字段以平台左侧菜单"开放api"页面的文档为准，调用形态如下：

# 路径与字段按平台"开放api"文档替换 curl -X POST "https://your-domain/<api-path>" \ -H "Content-Type: application/json" \ -d '{"content": "来自外部系统的一条消息"}'

回调事件（Webhook）：在平台"回调事件"菜单配置转发规则，命中内容会推送到你的服务器，服务器返回的文本作为机器人回复发出，适合有开发能力、想自写对话逻辑的团队。

扩展入口：src/index.js 是协议选择与插件挂载的唯一入口（WechatyWebPanelPlugin负责平台通信，WechatyMessageCallBackPlugin负责回调转发）；各协议实现分别位于 src/workpro.js（企微）、src/padlocal.js（iPad）、src/matrix.js（matrix）、src/office.js（公众号）、src/wechat4u.js（网页版）。

生产环境注意事项

进程与日志

用 pm2 托管而不是裸node：pm2 start pm2.json，该配置已开启 autorestart、cron_restart每天 00:00 重启、max_restarts100 次；instances固定为 1，微信单账号机器人不能多实例，不要调大。

# 日志落在 ./logs 目录，实时跟踪： pm2 logs wechaty-pro

日志文件为./logs/app-out.log与./logs/app-err.log，建议配置 logrotate 每日切割、保留 7 天，防止长期运行占满磁盘。

时区与协议安全

定时推送精度依赖系统时区：Dockerfile 已把容器时区固定为 Asia/Shanghai，源码运行时用timedatectl检查服务器是否为 UTC+8，否则所有定时任务整体偏移。
默认 wechat4u 协议保持关闭，生产优先企微（WORK_PRO_TOKEN）或 iPad 协议（PAD_LOCAL_TOKEN）；APIKEY、APISECRET 与各类 token 只走环境变量或平台配置，不要提交进代码库。

公众号专项

个人订阅号/未认证服务号走普通消息接口，3 秒内不响应消息发不出去，OFFICE_IS_PERSON必须设为true；认证服务号走客服接口无此限制，设为false。
8077 端口映射到备案域名，且把容器出口 IP 加入公众号"开发配置 → IP 白名单"，二者缺一消息必不通。

高频问题速查

现象	原因	处理动作
启动后只打印封号警告，机器人未启动	未配置任何协议环境变量，默认 wechat4u 已关闭	补`WORK_PRO_TOKEN`/`PAD_LOCAL_TOKEN`/`MATRIX_TOKEN`/`OFFICE_APPID`之一后重启
平台保存了配置，微信里行为不变	未发送更新关键词，客户端未拉取	给机器人发`更新`（或你自定义的更新关键词）
`docker pull`超过 1G 或启动即退出	第三方镜像源拉到旧版本镜像	切官方镜像源重新 pull，正常体积 < 500M
公众号消息调不通	域名未备案或未加入 IP 白名单	8077 映射备案域名，容器出口 IP 加入公众号开发配置白名单
定时新闻、天气推送内容为空	天行数据账号缺失或接口权限未申请	申请天行机器人、天气、新闻、垃圾分类四个接口
FastGPT / Dify 回复无上下文或缺变量	客户端版本低于 5.0.32 / 5.0.43	对照 CHANGELOG.md 升级镜像 tag