折腾微信 AI 机器人这件事前前后后花了我差不多两个月。中间踩过不少坑也推翻过好几版方案最后才落成一个“消息进来 - 大模型理解 - 自动回复”的稳定闭环。这篇文章就从需求、架构、代码到上线部署完整复盘一下我最终的实现方案。文章会包含可直接运行的代码、微信公众号接入方式、企业微信群机器人接入方式以及个人微信自动化方案的合规风险说明。不管你是刚开始接触 AI 应用开发还是已经在折腾微信机器人都可以把这份笔记当作一套落地参考。1. 为什么我想做一个微信 AI 聊天机器人先说说原始需求。我希望有一个随时能聊天的 AI 伙伴不只是网页对话框里问一句答一句而是能融入日常聊天习惯微信收到消息机器人自动回复能记住上下文能按不同人设聊天也能在群里被 时回答问题。这个场景听起来简单真正落地时要拆成几块微信侧消息怎么接收消息怎么转给大模型大模型回复后怎么发回微信多轮对话上下文怎么保存私聊、群聊怎么区分并发消息来了会不会乱账号会不会有安全风险前两周我基本都在处理后面这些“非 AI”的问题。真正调大模型接口反而是最快的一步因为大模型平台基本都提供了 OpenAI 兼容接口封装一下就能用。1.1 这个机器人适合做什么一个稳定的微信 AI 机器人可以承担很多角色私人助手查资料、写文案、翻译、总结网页内容。群聊问答机器人被 时回答技术问题或日常问题。内容创作助手接收关键词自动生成短文、日报。学习陪伴设定角色人设比如英语陪练、编程老师。信息助理对接企业内部知识库做员工问答。本质上它就是“微信消息通道 大模型能力 业务逻辑”的组合。你不需要重新训练模型只需要做好消息接入、上下文管理和提示词设计。1.2 微信生态接入方案对比做微信机器人第一个要决策的不是模型而是“从哪个微信入口接入”。我自己对比下来主要分三条路接入方案消息接收消息发送风险适合场景个人微信号自动化可以可以违反微信用户协议可能封号仅个人学习高危微信公众号回调消息被动/客服消息低官方支持个人或企业对外服务企业微信回调/机器人应用消息/群机器人低官方支持企业内部助理、团队机器人一开始我也盯着个人微信号的方案研究了一段时间后放弃了两个点一是稳定性差登录、消息同步都可能失效二是账号风险不可控一旦被限制很麻烦。最终我把重心放在“官方支持的通道”上也就是微信公众号和企业微信。这个判断很重要。如果你的机器人要长期使用、甚至要做成产品一定要优先选官方渠道。2. 整体架构与核心流程我的最终架构没有用复杂框架核心就是一条消息管道。2.1 消息处理链路微信用户发消息 ↓ 微信服务器 ↓ 我们的回调服务接收消息 ↓ 消息预处理类型判断 / 群聊判断 / 敏感词过滤 ↓ 会话管理器取出历史上下文 ↓ 大模型 API生成回复 ↓ 保存本轮对话记录 ↓ 返回回复内容给微信整条链路是同步的收到微信消息 - 处理 - 返回回复。微信服务器在等待响应时对耗时有限制所以单次大模型调用不能太慢否则会超时。这里有两种思路同步返回适合大模型响应快、业务简单的场景。先回复“收到”再异步处理适合生成耗时长的场景。我第一版用的同步方案因为大模型接口响应普遍在 1 到 3 秒左右微信公众号 5 秒超时限制内勉强能完成。但如果你的提示词很长、历史上下文很多响应可能变慢那就需要考虑异步化。2.2 模块划分代码结构我拆成了几层通道层负责对接微信把微信消息转成统一的消息对象。业务层负责判断是否回复、调用大模型、维护会话。模型层封装大模型客户端方便切换不同平台。会话层保存和管理多轮对话历史。分层的好处是以后换微信入口或换大模型平台只需要改对应层不用动整套逻辑。2.3 为什么用 FastAPI 和 OpenAI 兼容接口服务端用的是 Python 和 FastAPI原因是开发效率高异步支持好接收微信 XML 回调、返回响应都很方便。大模型这块我用了 OpenAI 兼容接口。现在很多国内大模型平台都提供这种协议一种接入方式可以适配多家模型只需要改base_url、api_key、model三个配置。如果以后想从 A 平台切到 B 平台业务代码基本不用动。3. 环境准备与项目初始化下面进入实操环节。这套代码需要的环境不复杂重点是把项目结构和依赖梳理清楚。3.1 运行环境建议使用 Python 3.9 或更高版本我在本地和服务器上都验证过。依赖主要是fastapi提供 HTTP 服务。uvicorn启动 FastAPI 应用。openai通过 OpenAI 兼容接口调用大模型。requests企业微信机器人发送消息时使用。python-dotenv加载环境变量。关于openai库代码按 1.x 版本的 SDK 写法实现接口名是chat.completions.create老版本0.x的ChatCompletion.create写法已经废弃注意区分。3.2 安装依赖在项目目录下创建requirements.txtfastapi0.115.6 uvicorn0.34.0 openai1.59.6 requests2.32.3 python-dotenv1.8.1版本号按你当前环境可以调整不用完全一致。安装命令pip install -r requirements.txt如果你希望版本更宽松也可以直接安装最新版pip install fastapi uvicorn openai requests python-dotenv3.3 项目目录结构我最终的项目结构是这样的wechat-ai-bot/ ├── .env ├── requirements.txt ├── llm_client.py ├── session_manager.py ├── service.py ├── wechat_server.py ├── wecom_notify.py └── simulate_test.py每个文件职责如下文件职责llm_client.py封装大模型 API 调用session_manager.py管理多轮对话历史service.py消息处理核心业务逻辑wechat_server.py微信公众号回调接入wecom_notify.py企业微信群机器人发送消息simulate_test.py本地命令行模拟测试4. 核心代码实现下面逐个文件说明并解释关键设计原因。4.1 大模型客户端封装文件llm_client.py# llm_client.py import os from openai import OpenAI class LLMClient: 统一封装大模型调用兼容 OpenAI API 格式。 def __init__(self, api_keyNone, base_urlNone, modelNone): self.api_key api_key or os.getenv(LLM_API_KEY) self.base_url base_url or os.getenv(LLM_BASE_URL) self.model model or os.getenv(LLM_MODEL, deepseek-chat) self.client OpenAI(api_keyself.api_key, base_urlself.base_url) def chat(self, messages, temperature0.7): 传入 messages 列表返回模型生成的文本。 resp self.client.chat.completions.create( modelself.model, messagesmessages, temperaturetemperature, ) return resp.choices[0].message.content为什么单独封装一层第一业务代码不需要关心具体平台。第二以后加日志、加超时重试、统计 token 消耗都可以集中在这个类里改。第三切换模型时只改.env配置即可。在.env里配置LLM_API_KEYsk-你的密钥 LLM_BASE_URLhttps://api.deepseek.com/v1 LLM_MODELdeepseek-chat不同平台的base_url和model参数以平台官方文档为准。这里以 DeepSeek 为例因为它的 API 兼容 OpenAI 格式国内网络环境可以直接访问不需要额外处理。4.2 多轮会话管理文件session_manager.py大模型接口本身不记忆历史。每次调用只看到你传给它的messages。所以机器人要支持多轮对话必须自己保存聊天记录下次请求时一起传给大模型。# session_manager.py import time from collections import defaultdict, deque class SessionManager: 保存每个用户的对话历史支持过期清理。 def __init__(self, max_history12, expire_seconds1800): self.max_history max_history self.expire_seconds expire_seconds self._sessions defaultdict(deque) self._timestamps {} def _touch(self, key): self._timestamps[key] time.time() def _is_expired(self, key): if key not in self._timestamps: return True return time.time() - self._timestamps[key] self.expire_seconds def get_messages(self, key, system_promptNone): 获取某个会话的完整 messages可选拼接系统提示词。 if self._is_expired(key): self._sessions[key] deque(maxlenself.max_history) self._timestamps[key] time.time() messages [] if system_prompt: messages.append({role: system, content: system_prompt}) for role, content in self._sessions[key]: messages.append({role: role, content: content}) return messages def add_message(self, key, role, content): 记录一条对话消息。 if self._is_expired(key): self._sessions[key] deque(maxlenself.max_history) self._timestamps[key] time.time() else: self._touch(key) self._sessions[key].append({role: role, content: content})设计要点max_history限制最多保留多少条历史消息避免上下文无限膨胀。expire_seconds控制会话有效期比如 30 分钟没聊天就重置上下文。每条消息记录role和content与大模型 API 要求的格式一致。实际项目中如果用户量大可以把历史存到 Redis并设置EXPIRE。当前示例用内存deque适合个人项目和小规模部署。4.3 业务处理服务文件service.py这是机器人核心逻辑负责判断是否回复、过滤敏感词、拼装上下文、调用模型、保存记录。# service.py from llm_client import LLMClient from session_manager import SessionManager SYSTEM_PROMPT 你是一个在微信上陪伴用户的 AI 聊天机器人。 你的风格是友好、简洁、真诚。 如果用户问你不确定的事情请如实说明不知道。 回答不要过长控制在 200 字以内。 class ChatBotService: def __init__(self): self.llm LLMClient() self.sessions SessionManager(max_history12, expire_seconds1800) def should_reply(self, msg_type, message_text, is_groupFalse): 判断一条消息是否需要机器人回复。 if msg_type ! text: return False if not message_text or not message_text.strip(): return False if is_group: # 群聊里只处理 机器人 的消息 return message_text.startswith(机器人) or 机器人 in message_text[:20] return True def check_sensitive(self, text): 敏感词/违法违规内容过滤。 sensitive_words [测试违禁词] for word in sensitive_words: if word in text: return True return False def handle_message(self, session_key, msg_type, message_text, is_groupFalse): # 是否该回复 if not self.should_reply(msg_type, message_text, is_group): return None # 敏感内容直接返回安全话术 if self.check_sensitive(message_text): return 这个话题我暂时不方便聊我们换个话题吧。 # 清理消息中的 前缀避免把 机器人 喂给模型 clean_text message_text.strip() if is_group: clean_text clean_text.replace(机器人, , 1).strip() # 拼接历史上下文 messages self.sessions.get_messages(session_key, SYSTEM_PROMPT) messages.append({role: user, content: clean_text}) # 调用大模型 reply self.llm.chat(messages) # 保存本轮记录 self.sessions.add_message(session_key, user, clean_text) self.sessions.add_message(session_key, assistant, reply) return reply这里说明几个易错点session_key不是简单的用户名。在私聊里可以用用户的 openid在群聊里建议用群ID 用户ID组合否则同一个人的上下文会在不同群里串掉。群聊消息给大模型前要清理机器人前缀不让机器人把自己的名字当成问题的一部分。handle_message返回None表示“不需要回复”上层通道收到None时直接返回微信要求的成功响应。5. 接入微信通道核心逻辑完成后接下来就是对接真实的微信入口。这里我把三种情况都讲一下。5.1 微信公众号接入推荐微信公众号是目前最稳定的个人开发者接入方式。你需要有一个公众号然后在后台开启服务器配置把接收消息的地址指向你自己的服务。文件wechat_server.py# wechat_server.py import hashlib import time import xml.etree.ElementTree as ET from fastapi import FastAPI, Request, Response from service import ChatBotService TOKEN 你的服务器配置Token bot ChatBotService() app FastAPI() def check_signature(signature: str, timestamp: str, nonce: str) - bool: 微信服务器签名校验。 if not signature or not timestamp or not nonce: return False tmp_list sorted([TOKEN, timestamp, nonce]) tmp_str .join(tmp_list) return hashlib.sha1(tmp_str.encode(utf-8)).hexdigest() signature def build_text_reply(to_user: str, from_user: str, content: str) - str: 构造公众号被动回复的 XML 消息。 timestamp int(time.time()) return fxml ToUserName![CDATA[{to_user}]]/ToUserName FromUserName![CDATA[{from_user}]]/FromUserName CreateTime{timestamp}/CreateTime MsgType![CDATA[text]]/MsgType Content![CDATA[{content}]]/Content /xml app.get(/wechat) async def wechat_get(request: Request): 服务器配置时的 URL 校验。 params request.query_params signature params.get(signature, ) timestamp params.get(timestamp, ) nonce params.get(nonce, ) echostr params.get(echostr, ) if check_signature(signature, timestamp, nonce): return Response(contentechostr, media_typetext/plain) return Response(contentbad signature, status_code403) app.post(/wechat) async def wechat_post(request: Request): 接收微信消息并返回 AI 回复。 body await request.body() try: root ET.fromstring(body) except ET.ParseError: return Response(contentsuccess, media_typetext/plain) msg_type root.findtext(MsgType) from_user root.findtext(FromUserName) to_user root.findtext(ToUserName) content root.findtext(Content) # 只处理文本消息 if msg_type ! text: return Response(contentsuccess, media_typetext/plain) # session_key 使用用户 openid保证不同用户上下文隔离 reply bot.handle_message(from_user, msg_type, content) if reply: xml_reply build_text_reply(from_user, to_user, reply) return Response(contentxml_reply, media_typeapplication/xml) return Response(contentsuccess, media_typetext/plain)关键点说明GET /wechat是公众号后台配置服务器地址时微信发起的验证请求。POST /wechat是用户每发一条消息微信推送过来的消息内容格式是 XML。build_text_reply里的ToUserName要填接收消息时的FromUserName也就是用户 openidFromUserName要填原始ToUserName也就是公众号原始 ID。顺序反了会导致消息回复失败。被动回复接口必须在 5 秒内响应。如果你的模型调用较慢建议升级为“先回复成功再通过客服消息异步发送”。公众号后台需要配置的 URL 是https://你的域名/wechatToken 就是wechat_server.py里的TOKEN。5.2 企业微信群机器人接入如果你只是想在某些群里推送消息不想做完整问答交互企业微信群机器人是最快的方式。它不需要写服务器回调只需要一个 Webhook 地址。文件wecom_notify.py# wecom_notify.py import requests def send_wecom_webhook(webhook_url: str, content: str, mentioned_listNone): 向企业微信群机器人发送文本消息。 data { msgtype: text, text: { content: content, mentioned_list: mentioned_list or [] } } resp requests.post(webhook_url, jsondata, timeout5) resp.raise_for_status() return resp.json()这个接口只能主动发送不能接收群消息。如果你需要“群成员发消息后自动回复”就需要企业微信回调服务来接收消息再走类似公众号回调解密流程复杂度会高一些。我在个人项目里先用群机器人做通知推送完整问答走公众号。5.3 个人微信自动化的风险说明很多同学看到“微信聊天机器人”第一反应是让自己的个人微信号自动回复。这个问题我必须重点提醒个人微信没有官方开放的机器人接口。市面上一些自动化方案基于破解协议、Hook 或模拟点击等方式实现这些都属于非官方行为违反了微信用户协议。使用后你可能会遇到账号被临时限制登录。好友列表被清空或账号被永久封禁。无法使用微信支付等功能。第三方服务停止维护或窃取聊天数据。所以我强烈不建议在常用微信号上使用非官方自动化方案。如果只是本地研究技术也应该用小号并且充分了解风险。这也是我最终转向公众号和企业微信的根本原因稳定、合规、可持续。6. 本地模拟与线上验证在接入真实微信之前我建议先写一个本地模拟脚本快速验证整个对话链路是否正常。6.1 本地命令行模拟文件simulate_test.py# simulate_test.py from service import ChatBotService def main(): bot ChatBotService() print(微信 AI 机器人本地模拟器输出 exit 退出) while True: text input(你) if text.lower() in (exit, quit): break reply bot.handle_message(local_user, text, text) print(机器人, reply) if __name__ __main__: main()运行python simulate_test.py这个脚本不依赖微信只测试“消息处理 上下文管理 大模型调用”是否正常。建议在接入微信前先跑通。注意这里handle_message默认is_groupFalse所以每条文本消息都会回复。如果大模型 API 密钥或 base_url 配置错误运行时会直接抛异常可以提前暴露问题。6.2 启动 Web 服务本地验证通过后启动微信回调服务uvicorn wechat_server:app --host 0.0.0.0 --port 8000默认监听 8000 端口。微信公众号后台要求 URL 必须是公网可访问的地址而且 80 或 443 端口是常用入口。本地开发时可以用内网穿透工具把本机端口暴露到公网方便调试。正式生产建议直接部署在云服务器上并用 Nginx 做反向代理和 HTTPS。6.3 线上部署要点域名需要 ICP 备案公众号后台服务器配置才会稳定生效。必须使用 HTTPS 回调否则微信后台可能拒绝或提示配置失败。如果部署在云服务器注意安全组放行对应端口。建议使用systemd或容器方式托管服务保证进程崩溃后自动重启。回调接口要求高可用服务不可用时微信会重试一段时间要保证接口能快速返回。7. 常见问题与排查我在折腾过程中整理了一批高频问题列成表格方便排查。问题现象常见原因解决思路公众号服务器配置保存失败Token 不一致或 URL 不可访问检查 Token 是否与代码一致确认公网能访问确认签名校验逻辑正确能收到消息但不回复消息类型不是 text或handle_message返回 None在wechat_post中打印日志查看 XML 内容大模型接口调用报错base_url、api_key、model 配置错误查看平台文档确认模型名和接口地址回复内容超过微信限制AI 回答太长在 system prompt 中限制长度或代码中截断多轮对话上下文串了session_key 设计不合理私聊用 openid群聊用 群ID用户ID群聊里不 机器人也回复should_reply 逻辑没判断群聊确认传入is_groupTrue回调请求超时大模型响应太慢异步化处理或使用更快模型部署后无法访问安全组/防火墙没放行检查云服务器安全组规则机器人总说车轱辘话上下文太长导致模型迷失只保留最近几轮增加 system prompt 明确指令微信后台提示消息签名失败时间戳/token 排序错误确认sorted([TOKEN, timestamp, nonce])后再 sha1这里单独说下超时优化。微信公众号被动回复要求 5 秒内响应如果大模型接口偶尔不稳定回复可能超时。常见方案是收到消息后立即返回success给微信。使用客服消息接口主动向用户推送 AI 回复。客服消息也有调用频率限制需要控制节奏。这个方案能解决超时但代码复杂度会明显增加。个人项目如果用的是响应快的模型同步方案也可以接受。8. 最佳实践与工程建议代码跑通只是第一步。如果你希望这个机器人更接近生产可用下面这些点值得认真对待。8.1 上下文与 Token 控制多轮对话的上下文不能无限累积。大模型输入长度有限而且历史越长接口响应越慢、费用越高。建议只保留最近 10 到 20 条消息。对长消息做截断。超过 30 分钟没有活跃对话主动重置上下文。如果系统提示词非常长优先对历史做摘要压缩。8.2 敏感词与内容安全AI 生成内容有不可控性。接入公开场景前一定要做内容安全过滤。具体做法用户输入侧做敏感词检测命中后不调用大模型。模型输出侧增加二次过滤防止生成违规内容。对高风险问题可以提示用户“换个话题”。有条件时接入专业内容安全服务不能只依赖关键词。8.3 群聊回复策略群聊和私聊逻辑完全不同必须显式区分。只有被 时才回复避免机器人在群里刷屏。回复前清理机器人前缀。不同群的会话要隔离避免上下文串群。设置单人在群内的调用频率限制避免恶意刷消息。8.4 日志与监控任何线上服务都需要日志。建议至少记录每次收到的原始消息。是否命中回复逻辑。调用大模型耗时。模型返回结果。异常堆栈。日志可以帮助定位问题也可以用来分析用户请求质量。注意不要记录敏感个人信息微信 openid 属于标识信息需要脱敏处理。8.5 并发与限流公众号回调可能有同时进入的请求。FastAPI 本身是异步框架并发能力足够但大模型接口有速率限制。建议在ChatBotService入口增加线程锁或分布式限流。对同一个用户设置冷却时间比如 5 秒只能请求一次。调用大模型时设置超时时间避免接口卡死拖垮整个服务。8.6 合规与安全再次强调合规优先使用公众号、企业微信等官方接口。不要尝试绕过微信平台限制。涉及用户数据时遵守隐私规范不使用用户聊天记录训练模型。保存的聊天记录加密存储不存明文敏感信息。对外提供服务前确认内容安全机制已上线。9. 总结与后续学习方向这个项目让我把“大模型应用开发”完整走了一遍从选型、接消息、做会话管理到上线部署、排查问题整个过程比单独调 API 有意思得多。现在你手上已经有了一个可扩展的基础版本大模型客户端封装、会话管理、业务处理、微信公众号接入、企业微信通知、本地模拟测试。在此基础上你可以继续往下面几个方向深入接入 RAG把个人知识库或文档导入让机器人回答得更准确。多模态扩展支持图片、语音消息识别。定时任务每天早上推送日报、天气、新闻。企业微信应用回调在内部 IM 场景做完整问答机器人。异步回复解决大模型响应慢导致超时的问题。多模型路由根据问题类型选择不同模型。如果你准备继续折腾建议先从小规模私聊场景开始不要一上来就做群聊机器人。先把请求链路、日志、限流打磨好再逐步放开更多消息类型和功能。做一个稳定、可维护、合规的微信 AI 聊天机器人不是只写一个if message 你好的玩具。把消息管道、上下文管理、内容安全和部署运维这几个基本功练扎实你就能基于这套架构做出很多实用的 AI 应用。