Wechaty 微信机器人框架 - 完整配置与使用教程-共创计划-国电神策网游活动网

前言

环境准备

安装 Wechaty

创建第一个机器人

配置 Token

运行和测试

进阶使用

常见问题解决

参考资料

前言

什么是 Wechaty？

Wechaty 是一个开源的聊天机器人框架 SDK，具有以下特性：

跨平台支持：微信、微信公众号、钉钉、飞书、WhatsApp 等

多语言支持：TypeScript/Node.js、Python、Go、Java

高度封装：用简单的代码实现强大的聊天机器人

生产级别：服务了数万名开发者，GitHub 1w+ Stars

你能学到什么？

通过本教程，您将学会：

✅ 配置 Wechaty 开发环境

✅ 创建微信机器人

✅ 实现消息监听和自动回复

✅ 对接 AI API 实现智能对话

✅ 部署和运行机器人

项目结构

wechaty-bot/├── venv/ # Python 虚拟环境├── kokonoe_bot.py # 机器人主程序├── requirements.txt # 依赖列表└── README.md # 项目说明

环境准备

1. 检查系统要求

操作系统：

Windows 10/11（本教程使用）

macOS

Linux

必需软件：

Python 3.7 或更高版本

pip 包管理器

微信账号（用于扫码登录）

2. 检查 Python 环境

打开 PowerShell 或命令提示符，运行：

python --version

预期输出：

Python 3.10.5

如果没有安装 Python，请访问：https://www.python.org/downloads/

3. 检查 pip

pip --version

预期输出：

pip 22.0.4 from ... (python 3.10)

安装 Wechaty

步骤 1：创建项目目录

# 创建项目文件夹mkdir c:\Users\11715\wechaty-bot# 进入项目目录cd c:\Users\11715\wechaty-bot

步骤 2：创建虚拟环境（推荐）

# 创建 Python 虚拟环境python -m venv venv# 激活虚拟环境（Windows）.\venv\Scripts\Activate.ps1

注意：如果激活失败，需要先设置执行策略：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

步骤 3：安装 Wechaty

pip install wechaty

安装过程：

Collecting wechaty Downloading wechaty-0.10.7-py3-none-any.whl (1.6 MB)Collecting wechaty-puppet-service>=0.8.9 Downloading wechaty_puppet_service-0.8.10-py3-none-any.whl (17 kB)Collecting wechaty-puppet>=0.4.19 Downloading wechaty_puppet-0.4.23-py3-none-any.whl (34 kB)...Successfully installed wechaty-0.10.7 wechaty-puppet-0.4.23 ...

步骤 4：验证安装

python -c "import wechaty; print('Wechaty 安装成功！版本:', wechaty.__version__)"

预期输出：

Wechaty 安装成功！版本: 0.10.7

创建第一个机器人

示例 1：最简机器人

创建文件 simple_bot.py：

"""Wechaty 最简机器人示例"""import asynciofrom wechaty import Wechaty, Contactfrom wechaty.user import Messageclass MyBot(Wechaty): """最简单的机器人""" async def on_message(self, msg: Message): """监听消息""" if msg.is_self(): # 忽略自己的消息 return from_contact = msg.talker() # 获取发送者 text = msg.text() # 获取消息内容 print(f'收到消息: {from_contact.name} 说: {text}') # 自动回复 if text == '你好': await msg.say('你好！我是你的微信机器人助手！') async def on_login(self, contact: Contact): """登录成功""" print(f'✅ 登录成功！用户: {contact.name}')async def main(): bot = MyBot() await bot.start()if __name__ == '__main__': asyncio.run(main())

示例 2：Kokonoe 风格机器人

创建文件 kokonoe_bot.py：

"""Wechaty 微信机器人 - Kokonoe Mercury 版本天才科学家的暴躁助手"""import asynciofrom wechaty import Wechaty, Contactfrom wechaty.user import Messageclass KokonoeBot(Wechaty): """Kokonoe Mercury 风格的微信机器人""" async def on_message(self, msg: Message): """ 监听并处理消息事件 """ # 获取消息信息 from_contact = msg.talker() text = msg.text() room = msg.room() # 群聊信息 # 忽略自己发送的消息 if msg.is_self(): return # 判断是群聊还是私聊 if room: # 群聊消息 print(f'[群聊] {room.name} - {from_contact.name}: {text}') else: # 私聊消息 print(f'[私聊] {from_contact.name}: {text}') # 关键词回复 if text == '你好' or text == '在吗': await msg.say('哈？又在叫我？行吧，什么事快说！') elif text == ' Kokonoe' or text == 'kokonoe': await msg.say('干嘛？想我了？别做梦了，我正在忙实验呢！') elif text == '帮助': help_text = """🔬 Kokonoe 机器人命令：- 你好/在吗 - 打招呼- Kokonoe - 召唤本天才科学家- 帮助 - 显示帮助信息- 测试 - 测试机器人是否正常Powered by Wechaty & AI""" await msg.say(help_text) elif text == '测试': await msg.say('测试成功！本天才科学家的机器人运行正常！') # 智能回复（需要配置 AI API） else: # 这里可以调用 AI API 生成回复 # ai_reply = await call_ai_api(text) # await msg.say(ai_reply) pass async def on_login(self, contact: Contact): """登录成功回调""" print('=' * 50) print('✅ 登录成功！') print(f'👤 昵称: {contact.name}') print(f'🆔 ID: {contact.contact_id}') print(f'🤖 Kokonoe 机器人已启动，等待消息中...') print('=' * 50) async def on_logout(self, contact: Contact): """登出回调""" print(f'❌ 已登出: {contact.name}') async def on_error(self, error: str): """错误回调""" print(f'⚠️ 发生错误: {error}')async def main(): """主函数""" print('=' * 50) print('🔬 Kokonoe Mercury 微信机器人') print('Powered by Python-Wechaty') print('=' * 50) print() # 创建机器人实例 bot = KokonoeBot() # 启动机器人（会显示二维码供扫码登录） await bot.start()if __name__ == '__main__': # 运行机器人 asyncio.run(main())

配置 Token

什么是 Token？

Token 是 Wechaty 连接微信服务的密钥。没有 Token，机器人无法登录微信。

方式 1：使用官方 Puppet Service（推荐）

步骤 1：注册账号

10. 访问 https://wechaty.js.org/

11. 点击 "GET TOKEN" 或 "Sign In"

12. 使用 GitHub 账号登录

13. 进入控制台

步骤 2：获取 Token

14. 在控制台找到 "Puppet Service Token"

15. 复制你的 Token（格式类似：puppet_**）

步骤 3：设置环境变量

方法 A - 在代码中设置：

import osos.environ['WECHATY_PUPPET_SERVICE_TOKEN'] = 'your-token-here'

方法 B - 在 PowerShell 中设置：

# 临时设置（当前会话有效）$env:WECHATY_PUPPET_SERVICE_TOKEN = "your-token-here"# 永久设置（用户级别）[System.Environment]::SetEnvironmentVariable( "WECHATY_PUPPET_SERVICE_TOKEN", "your-token-here", "User")

方式 2：使用免费 Puppet

wechaty-puppet-wechat4u（基于网页版）

# 安装pip install wechaty-puppet-wechat4u# 设置环境变量$env:WECHATY_PUPPET = "wechaty-puppet-wechat4u"

注意：部分新注册微信账号可能无法使用网页版协议。

方式 3：使用本地 Puppet

wechaty-puppet-wechat（基于浏览器）

# 安装pip install wechaty-puppet-wechat# 设置$env:WECHATY_PUPPET = "wechaty-puppet-wechat"

运行和测试

步骤 1：准备运行环境

# 进入项目目录cd c:\Users\11715\wechaty-bot# 激活虚拟环境（如果使用）.\venv\Scripts\Activate.ps1

步骤 2：运行机器人

python kokonoe_bot.py

步骤 3：扫码登录

运行后会显示二维码：

==================================================🔬 Kokonoe Mercury 微信机器人Powered by Python-Wechaty==================================================▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ ▓▓▓▓ [二维码区域] ▓▓▓▓ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓请使用微信扫码登录...

16. 打开微信

17. 点击右上角 "+" → "扫一扫"

18. 扫描终端中的二维码

19. 在手机端确认登录

步骤 4：测试机器人

登录成功后，发送消息测试：

测试用例：

发送内容

预期回复

你好

哈？又在叫我？行吧，什么事快说！

帮助

显示帮助信息

测试

测试成功！本天才科学家的机器人运行正常！

步骤 5：查看日志

运行时会看到实时日志：

✅ 登录成功！👤 昵称: 张三🆔 ID: wxid_xxxxx🤖 Kokonoe 机器人已启动，等待消息中...[私聊] 李四: 你好[私聊] 王五: 帮助[群聊] 测试群 - 赵六: 在吗

进阶使用

1. 对接 OpenAI API

实现智能回复功能：

import openai# 配置 OpenAIopenai.api_key = "your-openai-api-key"async def get_ai_reply(user_message: str) -> str: """调用 OpenAI 生成回复""" response = openai.ChatCompletion.create( model="gpt-3.5-turbo", messages=[ { "role": "system", "content": "你是 Kokonoe Mercury，一个暴躁但靠谱的天才科学家。" }, { "role": "user", "content": user_message } ] ) return response.choices[0].message.content# 在 on_message 中使用async def on_message(self, msg: Message): text = msg.text() # 调用 AI 生成回复 reply = await get_ai_reply(text) await msg.say(reply)

2. 群聊管理

async def on_message(self, msg: Message): room = msg.room() if room: # 群聊消息 room_name = await room.topic() print(f'群聊: {room_name}') # @机器人时回复 if msg.mention_self(): await msg.say('干嘛@我？有话快说！')

3. 好友管理

# 获取好友列表contacts = await bot.Contact.findAll()for contact in contacts: print(f'好友: {contact.name}')# 查找好友friend = await bot.Contact.find('好友昵称')# 发送消息给指定好友await friend.say('你好！')

4. 消息类型处理

from wechaty.user import Messageasync def on_message(self, msg: Message): # 文本消息 if msg.type() == Message.Type.MESSAGE_TYPE_TEXT: print(f'文本: {msg.text()}') # 图片消息 elif msg.type() == Message.Type.MESSAGE_TYPE_IMAGE: print('收到图片') # 下载图片 # img_file = await msg.to_file_box() # await img_file.to_file('./image.jpg') # 语音消息 elif msg.type() == Message.Type.MESSAGE_TYPE_AUDIO: print('收到语音') # 视频消息 elif msg.type() == Message.Type.MESSAGE_TYPE_VIDEO: print('收到视频')

5. 定时任务

from apscheduler.schedulers.asyncio import AsyncIOSchedulerscheduler = AsyncIOScheduler()# 定时任务async def daily_report(): """每日报告""" print('发送每日报告...') # 发送消息给管理员# 添加定时任务scheduler.add_job(daily_report, 'cron', hour=9, minute=0)scheduler.start()

常见问题解决

Q1: 安装时出现 "No module named 'wechaty'"

解决方法：

# 确认已安装pip list | findstr wechaty# 重新安装pip install --upgrade wechaty

Q2: 虚拟环境激活失败

解决方法：

# 设置执行策略Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser# 重新激活.\venv\Scripts\Activate.ps1

Q3: 扫码后无法登录

可能原因：

Token 配置错误

账号不支持网页版协议

网络问题

解决方法：

20. 检查 Token 是否正确

21. 尝试使用其他 Puppet Service

22. 检查网络连接

Q4: 机器人启动后立即退出

检查事项：

# 确保使用 asyncio.run()if __name__ == '__main__': asyncio.run(main())# 检查是否有未捕获的异常async def on_error(self, error: str): print(f'错误: {error}')

Q5: 消息监听不工作

排查步骤：

23. 确认已登录

24. 检查 on_message 方法是否正确

25. 确认没有过滤掉所有消息（msg.is_self()）

Q6: Token 在哪里获取？

获取途径：

26. 官网注册：https://wechaty.js.org/

27. GitHub Issues 寻找免费 Token

28. 加入 Wechaty 社区

Q7: 如何保持机器人持续运行？

Windows 方案：

# 使用 nohup（需要安装）nohup python kokonoe_bot.py &# 或使用任务计划程序# 创建定时任务，开机自动运行

Linux 方案：

# 使用 systemdsudo systemctl enable wechaty-botsudo systemctl start wechaty-bot# 或使用 screen/tmuxscreen -S botpython kokonoe_bot.py

完整示例代码

requirements.txt

wechaty==0.10.7wechaty-puppet-service==0.8.10wechaty-puppet==0.4.23

start.bat（Windows 快捷启动）

@echo offecho ========================================echo 启动 Kokonoe 微信机器人echo ========================================echo.cd c:\Users\11715\wechaty-botcall .\venv\Scripts\activate.batpython kokonoe_bot.pyecho.echo 机器人已退出pause

完整项目结构

c:\Users\11715\wechaty-bot\├── venv/ # Python 虚拟环境├── kokonoe_bot.py # 主机器人程序├── simple_bot.py # 简单示例├── requirements.txt # 依赖列表├── start.bat # 快捷启动脚本└── README.md # 项目说明

参考资料

官方文档

Wechaty 官网：https://wechaty.js.org/

Python-Wechaty 文档：https://wechaty.readthedocs.io/

GitHub 仓库：https://github.com/wechaty/python-wechaty

Puppet Services：https://wechaty.js.org/docs/puppet-services/

基础教程：https://wechaty.github.io/chatbot-1-to-2/docs/basic/basic-wechaty/

CSDN 教程：https://blog.csdn.net/gitblog_01146/article/details/141118320

掘金教程：https://juejin.cn/post/7347973138787549194

腾讯云教程：https://developer.cloud.tencent.com/article/2255926

GitHub Issues：https://github.com/wechaty/python-wechaty/issues

Stack Overflow：https://stackoverflow.com/questions/tagged/wechaty

Gitter 聊天：https://gitter.im/wechaty/wechaty

Gewechat：https://github.com/Devo919/Gewechat

itchat：https://itchat.readthedocs.io/

Dify on Wechat：https://github.com/hanfangyuan4396/dify-on-wechat

教程资源

社区支持