背景

在大语言模型（LLM）发展的背景下，传统的聊天机器人已无法满足人们的日常需求，催生了大量基于 LLM 的智能 Bot。早期，许多基于多端微信登录的开源框架应运而生，如 itchat、wechaty 以及 gewechat 等。其中，最早的方案多采用 WeChat 的 Web 端协议，可能是因为实现相对简单。然而，出于安全性或产品发展策略的考虑，微信官方对这些第三方机器人进行了不同程度的限制。

尽管如此，第三方应用开发者始终秉持“野火烧不尽，春风吹又生”的精神，不断探索新的解决方案。为了实现一些个人需求，我对这些框架进行了测试和调用，发现 itchat 和 wechaty 的稳定性较差，wechaty 依赖 iPad 登录协议且需要订阅 Token，但仍可能无法成功登录。最终，在尝试 gewechat 之后，成功实现了微信机器人的接入，并且该框架完全免费。接下来，我将详细介绍基于 gewechat 的微信机器人实现原理、使用方法及注意事项。

我使用 dify-on-wechat

chatgpt-on-wechat

dify-on-wechat 是基于 chatgpt-on-wechat 进行 fork 的框架。原始 chatgpt-on-wechat 通过 itchat 协议调用微信，但由于 itchat 方式存在稳定性问题，当前框架增加了 gewechat 支持，即通过 iPad 协议登录微信。

gewechat 是一个基于 Java 的 API 项目，用于调用微信相关接口，官方文档见这里。它既支持自部署，也可以使用官方提供的 SaaS 服务。

框架概述

chatgpt-on-wechat 通过配置化方式实现与微信的通信，提供了 itchat 和 wechaty 两种接入方案。不同接入方式的主要逻辑如下：

1. wechaty（基于事件监听）

wechaty 通过事件监听拦截微信消息，并进入框架的处理流程。

# 启动一个 wechaty 机器人
loop = asyncio.get_event_loop()
# 绑定 asyncio 的事件循环
chat_channel.handler_pool._initializer = lambda: asyncio.set_event_loop(loop)
self.bot = Wechaty()
self.bot.on("login", self.on_login)
self.bot.on("message", self.on_message)
await self.bot.start()

2. itchat（基于 Web 协议）

itchat 通过 Web 协议与微信通信，但由于 WeChat 限制，该方式已无法稳定使用。

主要模块解析

1. channel（通信模块）

channel 负责处理不同社交平台的消息，包括钉钉、飞书、企业微信及个人微信等。用户可在 config.json 配置 channel_type，框架在启动时自动加载相应模块。

框架基于面向对象（OO）设计，channel 作为基类，提供 startup、handle_text、send 三个接口，分别用于初始化、接收消息和发送消息。ChatChannel 继承 channel，并实现了多线程消费消息的 produce 和 consume 方法。

不同 channel 实现类需要解析特定消息格式，例如微信的文字、语音、Emoji 等，并构造 context 以供 LLM 处理。

2. plugins（插件系统）

插件系统用于抽离自定义业务逻辑，可作用于不同消息处理阶段，如：

接收消息时
处理消息前
生成回复后
发送消息前

框架初始化时，会将 plugins 注册到不同阶段，使得 channel 处理消息时，可以动态调用插件。

3. bridge（消息桥接）

bridge 负责将不同 channel 获取的消息转换为 LLM 可处理的格式，并根据 config.json 配置的 model 选择合适的 Bot 进行处理。

4. bot（LLM 交互模块）

bot 模块封装了对 LLM（如 OpenAI API）的调用，主要包含：

bot：不同 LLM 的具体实现，提供 reply 方法
session：维护用户对话上下文
bot_factory：根据 config.json 配置创建 Bot

dify-on-wechat 基于 chatgpt-on-wechat 的改进

相比 chatgpt-on-wechat，dify-on-wechat 主要提供了 更稳定的 gewechat 接入，通过拦截 WeChat 用户操作，构建机器人上下文输入。

1. gewechat 接入实现

当 channel 选择 gewechat 时，框架会在初始化阶段启动 Web 服务器，暴露 gewechat_callback_url 接口：

POST /v2/api/callback/collect：处理微信消息
GET /v2/api/callback/collect：用于调试

gewechat 拦截到微信消息后，会调用该接口，框架内部使用 chat_channel._compose_context 解析消息，并调用 produce 方法推送至处理队列，使其进入标准处理流程。

1
2
3

# 启动 Web 服务器
app = web.application(urls, globals(), autoreload=False)
web.httpserver.runsimple(app.wsgifunc(), ("0.0.0.0", port))

2. dify 适配

dify 作为一个 Bot 接入当前框架，但并未直接复用 bot 结构，而是针对 Session 和 SessionManagement 进行重写，以支持 user_id、user_name、room_id、room_name 等额外信息。这些参数用于适配新增插件 custom_dify_app，以便根据不同条件切换 dify 机器人。

未来规划（idea）

接入 DeepSeek ✅
接入 Ollama 🔧
插件热部署 🔧
Session 持久化 🔧

dify on wechat based on gewechat框架理解

背景