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 asyncio
from wechaty import Wechaty, Contact
from wechaty.user import Message
class 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 asyncio
from wechaty import Wechaty, Contact
from wechaty.user import Message
class 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 os
os.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
# 配置 OpenAI
openai.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 Message
async 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 AsyncIOScheduler
scheduler = 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 方案：
# 使用 systemd
sudo systemctl enable wechaty-bot
sudo systemctl start wechaty-bot
# 或使用 screen/tmux
screen -S bot
python kokonoe_bot.py
完整示例代码
requirements.txt
wechaty==0.10.7
wechaty-puppet-service==0.8.10
wechaty-puppet==0.4.23
start.bat（Windows 快捷启动）
@echo off
echo ========================================
echo 启动 Kokonoe 微信机器人
echo ========================================
echo.
cd c:\Users\11715\wechaty-bot
call .\venv\Scripts\activate.bat
python kokonoe_bot.py
echo.
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
教程资源
社区支持
相关框架
附录
A. 环境变量设置速查表
# 设置 Token
$env:WECHATY_PUPPET_SERVICE_TOKEN = "your-token"
# 设置 Puppet
$env:WECHATY_PUPPET = "wechaty-puppet-wechat4u"
# 查看当前环境变量
echo $env:WECHATY_PUPPET_SERVICE_TOKEN
# 永久设置（用户级别）
[System.Environment]::SetEnvironmentVariable(
"WECHATY_PUPPET_SERVICE_TOKEN",
"your-token",
"User"
)
B. 常用命令速查
# 创建虚拟环境
python -m venv venv
# 激活虚拟环境
.\venv\Scripts\Activate.ps1
# 安装包
pip install wechaty
# 查看已安装包
pip list
# 导出依赖
pip freeze > requirements.txt
# 运行机器人
python kokonoe_bot.py
C. 消息类型对照表
|
类型 |
常量 |
说明 |
|
文本 |
MESSAGE_TYPE_TEXT |
文本消息 |
|
图片 |
MESSAGE_TYPE_IMAGE |
图片消息 |
|
语音 |
MESSAGE_TYPE_AUDIO |
语音消息 |
|
视频 |
MESSAGE_TYPE_VIDEO |
视频消息 |
|
文件 |
MESSAGE_TYPE_ATTACHMENT |
文件消息 |
|
链接 |
MESSAGE_TYPE_URL |
链接分享 |
|
小程序 |
MESSAGE_TYPE_MINI_PROGRAM |
小程序卡片 |
浙公网安备 33010602011771号