omni-bot-sdk

2025-07-18AI客服 / AI营销 / 桌面自动化2 次浏览

综合介绍

Omni Bot SDK 是一个专为微信4.0版本设计的机器人流程自动化（RPA）框架。它的核心技术基于视觉识别，通过自定义的YOLO模型、OCR（光学字符识别）和数据库监听来实现功能，避免了对微信客户端本身的任何修改或侵入，以此来降低被检测的风险。这个框架允许开发者构建个人微信聊天机器人，并且可以方便地接入大型语言模型（LLM）如OpenAI或Dify平台。它支持插件化架构，用户可以通过添加不同的插件来扩展机器人的功能。框架内置了发送文本、图片、文件的基础能力，并且理论上可以扩展至发送小程序和朋友圈等更复杂的操作。由于其工作原理，它在运行时需要独占鼠标和键盘，因此最适合在独立的设备上部署。

功能列表

零延迟消息接收: 基于数据库监听策略，能够近乎实时地接收新消息。
运行时零侵入: 通过YOLO模型和OCR进行界面识别和定位，不对微信程序本身进行任何注入或修改，降低了账号风险。
RPA功能可扩展: 允许用户自定义RPA动作，以支持如发送朋友圈、操作小程序等更多功能。
插件化架构: 开发者可以轻松创建和集成新插件来扩展机器人的能力，保持主代码的简洁。
异常自恢复: 在微信程序出现异常时，框架会尝试自动恢复RPA流程；如果失败，则会自动推送钉钉登录二维码以提醒用户。
快速启动: 提供简单的启动脚本，只需几行代码即可运行一个RPA机器人。
MCP工具支持: 支持通过mcp（可能是指某种控制协议）调用RPA，与微信进行交互，执行发送消息、群管理等操作。

使用帮助

Omni Bot SDK 是一个基于视觉识别技术的自动化框架，它模拟人的操作来与微信桌面版进行交互。以下是详细的安装和使用流程。

环境要求

操作系统: Windows
Python版本: 必须使用 Python 3.12
微信版本: 支持 4.0.6.17, 4.0.19, 4.0.21 等版本

1. 安装

首先，确保你的环境中已经安装了 Python 3.12。然后通过 pip 命令从PyPI软件源中安装SDK：

pip install omni-bot-sdk

2. 获取数据库密钥（DbKey）

SDK需要读取微信本地数据库来接收消息，而这个数据库是加密的。因此，必须获取解密所需的密钥（dbkey）。

获取工具: 项目本身不提供获取dbkey的工具。用户需要自行在GitHub上搜索并下载 DbkeyHookCMD.exe 或 DbkeyHookUI.exe 等工具。
操作步骤: 使用获取到的工具来提取密钥。
配置: 获取密钥后，需要将其填入后续步骤的配置文件 config.yaml 中的 dbkey 字段。

3. 启动MQTT服务

框架使用MQTT服务来进行消息转发和任务结果的回调。对于Windows用户，可以直接使用 nanomq 快速启动一个本地MQTT服务。

4. 配置文件

参考项目根目录中的 config.example.yaml 文件，创建一个名为 config.yaml 的配置文件，并填入你在上一步中获取到的 dbkey 和其他必要信息。

5. 启动机器人

重要提示：在启动RPA程序前，需要先启动微信并完成登录。然后，立即运行RPA程序。这是因为微信会在启动一段时间后污染用于图片解密的密钥，导致RPA无法正确解密和发送图片。

创建一个Python脚本（例如 run_bot.py），并写入以下代码：

from omni_bot_sdk.bot import Bot
def main():
# 确保配置文件config.yaml与脚本在同一目录下
bot = Bot(config_path="config.yaml")
bot.start()
if __name__ == "__main__":
main()

运行此脚本即可启动机器人。

6. 操作流程与核心机制

初始化:
- 启动后，RPA会首先对微信界面的各个控件进行视觉定位，例如聊天列表、输入框、联系人等。这个过程需要一些时间。
- 为了验证并获取图片解密密钥，程序会自动向“文件传输助手”发送一张图片。这是一个关键步骤，确保后续能正常处理图片消息。
消息监听:
- 程序会以只读模式轮询微信的本地数据库文件，以检测新消息。这种方式延迟极低。
插件处理:
- 当接收到新消息后，消息会经过一个“插件链”。你可以根据需求启用或编写不同的插件来处理消息。
- 例如，可以编写一个插件，当收到特定关键词时，自动调用LLM生成回复。
- SDK内置了两个基础插件：一个是阻断自己发送的消息，避免无限循环；另一个是阻断没有群名称的消息，因为目前还无法处理这类会话。
RPA执行:
- 插件处理完成后，会生成一系列需要执行的动作（Action），例如“找到联系人‘张三’”、“在输入框输入‘你好’”、“点击发送按钮”等。
- 这些动作会进入RPA动作队列，由RPA消费者逐一执行。
- 注意：在RPA运行时，它会完全控制鼠标和键盘。此时请不要手动操作电脑，否则会干扰RPA的执行，导致操作失败。建议将机器人部署在专用的电脑或虚拟机上。

项目局限性

准确性: 基于视觉识别，无法保证100%的定位准确率和操作成功率。
同名联系人问题: 如果出现同名的联系人或群聊，RPA可能无法准确找到目标，导致操作失败。
操作冲突: RPA运行时会与用户抢夺鼠标和键盘的控制权。
窗口识别: 尽管有优化，但仍可能将焦点给到错误的窗口，尤其是在有同名窗口标题的情况下。

应用场景

个人助理机器人可以编写插件，将微信接入待办事项（Todoist）、日历或笔记软件，通过与机器人聊天来管理个人事务，例如“提醒我明天下午3点开会”或“把这个链接保存到我的笔记”。
智能家居控制中枢如果你的智能家居设备支持API调用，可以创建一个插件，通过向微信机器人发送指令（如“打开客厅的灯”）来控制家中的设备，将微信变成一个方便的控制入口。
信息聚合与速览可以开发插件定期从特定信息源（如RSS订阅、特定网站）拉取信息，并将其格式化后推送到指定的微信聊天。这对于需要高效获取信息的用户非常有用。
与大模型（LLM）集成这是框架的核心应用场景之一。用户可以将机器人接入OpenAI、Dify或本地部署的任何语言模型，实现智能聊天、知识问答、文本翻译、内容创作等功能，打造一个专属于自己的高智能微信伙伴。

QA

使用这个项目会导致微信被封号吗？存在风险。该项目通过模拟人类操作来规避检测，属于RPA（机器人流程自动化）性质，而非使用逆向工程或Hook技术。但任何自动化操作都违反了微信的用户协议，因此账号仍有被封禁或功能限制的风险。建议使用非重要账号进行测试和学习。
为什么启动后，机器人无法发送图片或解密收到的图片？这通常是因为获取图片解密密钥失败。微信客户端启动一段时间后，内存中的密钥数据会被“污染”。因此，正确的操作流程是：先完全退出微信，然后重新登录，并立刻启动RPA程序。程序会自动给文件传输助手发图以获取密钥。
RPA运行时，我可以操作电脑吗？不可以。RPA需要完全控制鼠标和键盘来定位界面元素和执行点击、输入等操作。任何人为的干扰都会打断其操作流程，导致任务失败。最佳实践是将其部署在一台单独的、无人操作的电脑或虚拟机上。
如果我有两个同名的联系人或群聊，机器人会怎么处理？机器人会无法准确识别。它和人类一样，通过搜索框输入名称来查找联系人。如果搜索结果出现多个相同的名字，它目前无法区分，大概率会导致操作失败或将消息错发给第一个匹配到的联系人。