WoneBot 部署说明
一、产品概述
WoneBot 是一款基于本地 AI 的 Windows 自动回复机器人。它以本地 Ollama 大语言模型为智能核心，模拟真实用户操作WX PC 客户端，实现智能对话回复、角色扮演、多功能助手等能力。所有 AI 推理均运行在本地，数据不出本地机器，隐私安全可控。
核心定位
- 本地化部署：AI 模型运行在用户自有设备上，无需云端 API
- 零接入成本：使用开源 Ollama + 开源模型，无需付费调用第三方接口
- 开箱即用：配置简单，小白也能快速上手
- 高度可定制：支持自定义角色 Prompt、对话风格、回复参数
适用场景
| 场景 | 说明 |
|---|---|
| 个人助理 | 自动回复常问问题，节省重复性沟通时间 |
| AI 群运营 | WX群自动欢迎、自动答疑、活跃气氛 |
| 角色扮演 | 自定义角色人设，进行游戏/娱乐对话 |
| 自动客服 | 小型工作室/个人业务快速搭建WX客服 |
| 开发测试 | 本地测试 AI 对话能力，快速验证 Prompt 效果 |
核心亮点
- 🚀 全本地运行 — 模型在本地推理，不上传任何聊天数据
- 🎭 多角色支持 — 预设多个性格迥异的 AI 角色自由切换
- 🔧 可视化配置 — 内置 Web 页面，浏览器即可调整所有参数
- ⏸️ 一键控制 — 支持随时暂停、恢复、重启，无需重启程序
- 💬 拟人化回复 — 模拟真实用户打字节奏和表达方式
- 📝 详细日志 — 完整操作日志，方便排查问题和审计对话
二、详细功能介绍
2.1 核心功能模块
AI 自动回复引擎
内置 AI 对话引擎，深度集成 Ollama API，支持任意 Ollama 支持的开源模型（如 Qwen、Llama、Mistral、DeepSeek 等）。
主要参数：
| 参数 | 说明 | 默认值 |
|---|---|---|
| Temperature | 回复随机性（0.0-2.0） | 0.7 |
| Top_P | 采样概率阈值 | 0.9 |
| Repeat_Penalty | 重复惩罚系数 | 1.0 |
| Max_Tokens | 单次最大输出 Token 数 | 512 |
| Num_Context | 对话上下文窗口大小 | 4096 |
多角色系统
支持同时配置多个 AI 角色，每个角色拥有独立的 Prompt 人设、性格设定和对话风格。
内置角色类型：
- 🤖 通用助手 — 中立友善的日常助手
- 🎀 温柔女友 — 甜蜜温柔的聊天伴侣
- 🔥 霸道总裁 — 强势直接的决策型角色
- 📚 知识导师 — 专业严谨的知识解答者
自定义角色方法： 直接在 config.py 或 Web 配置页面中修改 ROLE_PROMPTS 字典即可添加新角色。
拟人化模拟
为防止被WX识别为机器人，程序内置拟人化机制：
- 随机延迟：回复前随机等待 2~10 秒，模拟真实打字时间
- 打字节奏：分批次输出文字，模拟人工输入过程
- 自然停顿：在适当位置插入语气词和停顿符号
- 随机变化：同一问题不同时段回复略有差异
Web 配置面板
无需修改代码，通过浏览器即可配置所有参数：
- AI 模型选择与参数调整
- 角色 Prompt 在线编辑
- 回复开关控制
- 对话日志查看
- 实时状态监控
访问地址：http://localhost:9527（默认端口 9527，可在 config.py 中修改）
WX操作接口
通过 Windows 消息Hook和剪贴板模拟，实现以下WX操作：
- 获取当前聊天窗口信息
- 读取聊天消息内容
- 模拟键盘输入文字
- 自动发送消息
2.2 内置指令系统
在WX聊天窗口发送以下指令即可控制机器人：
| 指令 | 功能 | 权限 |
|---|---|---|
| /help | 显示所有可用指令帮助信息 | 所有用户 |
| /暂停 | 暂停 AI 自动回复功能 | 管理员 |
| /恢复 | 恢复 AI 自动回复功能 | 管理员 |
| /重启 | 重启机器人（重新加载配置） | 管理员 |
| /状态 | 查看当前运行状态 | 所有用户 |
| /切换 [角色名] | 切换当前 AI 角色 | 所有用户 |
| /模型 [模型名] | 切换使用的 AI 模型 | 管理员 |
| /清空 | 清空当前对话上下文 | 所有用户 |
注：/暂停、/恢复、/重启、/模型等管理指令仅管理员可执行。管理员WX号在config.py中的ADMIN_WXID配置。
2.3 消息队列与并发处理
- 所有收到的消息先进入消息队列，逐一处理
- 避免多条消息同时处理导致回复错乱
- 队列状态实时显示在 Web 配置面板中
- 支持查看队列中待处理的消息数量
三、运行环境与硬件配置
3.1 系统要求
| 项目 | 最低要求 | 推荐配置 |
|---|---|---|
| 操作系统 | Windows 10 (64位) | Windows 11 (64位) |
| 系统架构 | x86_64 | x86_64 |
| .NET Framework | 4.7.2+ | 4.8+ |
| 内存（RAM） | 8 GB | 16 GB 及以上 |
| 可用磁盘空间 | 2 GB | 10 GB+（含模型文件） |
| 网络 | 必要（下载依赖和模型） | 稳定宽带 |
⚠️ 如果使用较大的模型（如 7B 以上），强烈建议配备独立显卡（NVIDIA GPU）以获得流畅体验。无显卡环境下建议使用 3B~4B 的量化模型。
3.2 软件依赖
| 组件 | 版本要求 | 安装方式 |
|---|---|---|
| Python | 3.9 ~ 3.13 | 官网下载或 conda |
| Ollama | 最新稳定版 | ollama.com/download |
| 3.9.x ~ 4.1.x（PC版） | WX官网 | |
| pip | 最新版 | Python 自带 |
Python 依赖包：pywin32>=306 requests>=2.31.0
3.3 Ollama 模型要求
WoneBot 支持所有 Ollama 支持的开源模型，以下为推荐模型：
| 模型 | 参数量 | 内存需求（CPU） | 推荐场景 |
|---|---|---|---|
| qwen2.5:0.5b | 500M | ~2GB | 低配机器、快速测试 |
| qwen2.5:1.5b | 1.5B | ~4GB | 日常对话、轻量使用 |
| qwen2.5:3b | 3B | ~6GB | 均衡对话、推荐配置 |
| llama3.2:1b | 1B | ~3GB | 英文为主场景 |
| mistral:7b | 7B | ~8-12GB | 高质量对话（有GPU） |
| deepseek-r1:7b | 7B | ~8-12GB | 推理能力强（有GPU） |
四、下载安装教程
第一步：安装 Ollama
- 访问 ollama.com/download
- 下载 Windows 版本安装包（约 200MB）
- 运行安装程序，一路点击"下一步"完成安装
- 安装完成后，按
Win + R，输入cmd，打开命令提示符 - 验证安装：在命令行中执行
ollama -v，显示版本号即成功
ollama -v
输出示例：ollama version 0.5.x- 下载 AI 模型（以 qwen2.5:3b 为例）：
ollama pull qwen2.5:3b💡 模型文件较大（通常 1-10GB），请确保网络稳定且磁盘空间充足。首次下载可能需要 10-30 分钟。
第二步：获取 WoneBot 程序
方式一：Git 克隆（以下为示例，开发者未部署）
git clone https://github.com/YOUR_USERNAME/wechat-ollama-bot.git
cd wechat-ollama-bot方式二：直接下载（以下为示例，开发者未部署）
访问 GitHub 仓库 Releases 页面，下载最新版本的 Source code (zip)，解压即可。
第三步：安装 Python 依赖
确保已安装 Python 3.9+，然后在程序目录下执行：
pip install -r requirements.txt或者手动安装：
pip install pywin32 requests第四步：配置参数
用文本编辑器（推荐 VS Code 或 Notepad++）打开 config.py，按需修改以下配置：
# ========== Ollama 配置 ==========
OLLAMA_BASE_URL = "http://localhost:11434" # Ollama 服务地址
DEFAULT_MODEL = "qwen2.5:3b" # 默认使用的模型名称
# ========== 管理员配置 ==========
ADMIN_WXID = "your_admin_wxid" # 管理员WX号
# ========== Web 配置页面 ==========
WEB_PORT = 9527 # Web 配置页面端口号
# ========== 角色配置 ==========
ROLE_PROMPTS = {
"default": "你是一个友善的AI助手...",
"girlfriend": "你是一个温柔体贴的女友..."
}第五步：启动 Ollama 服务
在命令行中执行：
ollama serve💡 Ollama 服务启动后请保持窗口开启，不要关闭此窗口。
第六步：启动 WoneBot
打开一个新的命令行窗口（或在程序目录下直接运行）：
python bot.py
或使用 Python 模块方式：
python -m bot第七步：打开 Web 配置页面
启动成功后，浏览器访问：
http://localhost:9527
在 Web 页面中可以：
- 查看运行状态
- 调整 AI 参数
- 编辑角色 Prompt
- 查看对话日志
安装注意事项
| 注意事项 | 说明 |
|---|---|
| ⚠️ 路径不含中文 | 安装路径中不要包含中文字符或特殊符号 |
| ⚠️ 以管理员权限运行 | 右键 cmd.exe 选择"以管理员身份运行" |
| ⚠️ 关闭杀毒软件 | 部分杀毒软件可能误报拦截，按提示添加白名单即可 |
| ⚠️ WX版本 | 仅支持WX PC 3.9.x ~ 4.1.x，其他版本可能不兼容 |
| ⚠️ Ollama 先启动 | 务必先启动 ollama serve，再运行 bot.py |
| ⚠️ 端口占用 | 若 9527 端口被占用，修改 config.py 中的 WEB_PORT |
五、新手快速上手
快速启动流程（5分钟上手）
Step 1：安装 Ollama（2分钟）
下载并安装 Ollama Windows 版，无需复杂配置。
Step 2：拉取模型（3分钟，取决于网络）
ollama pull qwen2.5:3bStep 3：启动 Ollama
ollama serveStep 4：启动 WoneBot
cd wechat-ollama-bot
python bot.pyStep 5：打开WX
正常登录WX PC 客户端，找到需要自动回复的聊天窗口。
Step 6：发送测试消息
向聊天窗口发送任意消息，WoneBot 将在几秒后自动回复。
基础操作讲解
切换 AI 角色
在WX聊天窗口发送：
/切换 girlfriend即可将 AI 角色切换为"温柔女友"。所有后续回复将由该角色的人设风格生成。
暂停自动回复
发送管理员指令：
/暂停机器人将停止自动回复。发送 /恢复 即可重新启用。
查看当前状态
发送：
/状态将收到当前运行状态报告，包括：模型名称、角色名称、消息队列状态、Ollama 连接状态等。
六、常见问题（FAQ）
6.1 安装与启动问题
Q：运行 python bot.py 报错 ModuleNotFoundError: No module named 'pywin32'
A：未安装依赖包。执行 pip install pywin32 requests 后重试。
Q：Ollama 命令找不到（'ollama' is not recognized...）
A：Ollama 未正确安装或环境变量未配置。重新安装 Ollama，或将 C:\Users\<用户名>\AppData\Local\Programs\Ollama 加入系统 PATH 环境变量后重启命令行。
Q：提示 Failed to connect to Ollama at http://localhost:11434
A：Ollama 服务未启动。请先在命令行执行 ollama serve 启动服务，确保服务窗口保持开启状态。
Q：提示 Model not found 或模型无法加载
A：模型未下载或名称错误。执行 ollama pull 模型名称 重新下载，或在 config.py 中确认 DEFAULT_MODEL 名称与下载的模型完全一致。
Q：端口 9527 被占用，Web 页面打不开
A：端口被其他程序占用。修改 config.py 中的 WEB_PORT 为其他未占用端口（如 8080、5000 等），然后重新运行。
6.2 使用与运行问题
Q：WX收到消息后机器人没有自动回复
A：按以下顺序排查：
- 确认机器人已启动（命令行无报错）
- 确认WX版本是否在支持范围内（3.9.x ~ 4.1.x）
- 确认消息发送者是私聊或群聊，且没有被过滤
- 检查日志文件，看是否有消息接收记录
- 尝试发送
/状态指令检查运行状态
Q：机器人回复速度很慢
A：可能原因：
- 模型较大，CPU 推理速度有限 → 建议使用量化版本或更小的模型
- Ollama 服务资源不足 → 关闭其他占用内存的程序
- 网络延迟（使用远程 Ollama 时）→ 检查网络连接
Q：程序运行一段时间后崩溃/闪退
A：常见原因：
- 内存不足（OOM）→ 减少模型大小或关闭其他程序
- WX版本更新导致接口不兼容 → 更新 WoneBot 到最新版本
- 长时间运行导致资源泄漏 → 定期使用
/重启指令重置状态
6.3 兼容性问题
Q：支持WX Mac 版吗？
A：不支持。WoneBot 当前仅支持 Windows WX PC 客户端，因为其使用了 Windows 特有的消息 Hook 和窗口操作机制。
Q：程序会被WX封号吗？
A：WoneBot 模拟的是人工操作行为，不会使用任何违规协议。但请勿频繁大量发送消息，遵守WX使用规范。建议控制消息频率，设置合理的回复间隔。
七、隐私政策与免责声明
7.1 隐私政策
- 所有聊天数据均在本地设备上处理
- 程序不会主动收集、存储、上传任何聊天记录
- AI 模型推理完全在本地 Ollama 环境中完成
- Web 配置页面仅在本机 localhost 访问，不对外网开放
7.2 合规声明
- 仅处理用户自有数据：程序仅读取和回复用户主动发起或接收的WX消息
- 不破坏WX服务条款边界：程序仅模拟人工操作行为
- 尊重他人隐私：请勿在未经对方同意的情况下将其对话内容用于 AI 训练
7.3 免责声明
请您在使用 WoneBot 前仔细阅读以下声明：
- 用户自担风险：WoneBot 按"原样"（AS IS）提供
- 非WX官方产品：与腾讯公司（WX）无任何关联
- 账号风险提示：WX有权根据其服务条款对异常操作行为进行检测和处理
- AI 内容责任：AI 模型生成的回复内容不代表本程序开发者立场
八、问题反馈
提交问题前请先确认以下信息：
- 操作系统版本（Windows 10/11，具体版本号）
- WX版本（WX PC 客户端版本号）
- Python 版本（
python --version输出） - Ollama 版本（
ollama -v输出） - 使用的模型名称
- 问题描述（越详细越好）
- 复现步骤（如何一步步复现该问题）
- 错误日志（程序运行窗口中的报错信息，完整复制）