omni-bot-sdk: A Step-by-Step Guide to Building a Zero-Invasion WeChat 4.0 RPA Bot

❝

An English-language walkthrough for installing, configuring, and extending the open-source omni-bot-sdk framework—no prior reverse-engineering background required.

❞

What You Will Achieve

By the end of this guide you will have:

1. A fully working WeChat bot that can 「send and receive messages in real time」 on Windows.
2. A 「clear understanding」 of how the framework avoids detection by using vision instead of code injection.
3. A 「plugin pipeline」 that can connect your bot to OpenAI, Dify, or any other service with only a few lines of Python.

1. Quick Overview

2. Safety, Privacy, and Compliance

❝

The project maintainers publish a clear set of rules. 「Read them once; follow them always.」

❞

• 「Account Risk」 – Any automation on WeChat can lead to temporary or permanent suspension.
• 「Privacy」 – The SDK never uploads data; everything stays on your own disk.
• 「Usage Limits」 – Marketing, spam, or commercial advertising are 「strictly forbidden」. Use only for personal learning or approved research.

3. Prerequisites Checklist

Before you type a single command, verify the items below.

4. Installation in Six Clear Steps

4.1 Install Python 3.12

Download the installer from python.org.
Tick 「Add python.exe to PATH」 before clicking Install.

4.2 Create a Clean Folder

mkdir C:\wechatbot
cd C:\wechatbot
python -m venv venv
.\venv\Scripts\activate

4.3 Install the SDK

pip install omni-bot-sdk

You should see Successfully installed omni-bot-sdk-x.x.x.

4.4 Fetch the Database Key

1. Visit DbkeyHook releases.
2. Download DbkeyHookCMD.exe.
3. Run DbkeyHookCMD.exe > dbkey.txt as 「Administrator」.
4. Copy the 64-character string into a new file called config.yaml.

Example config.yaml (minimal):

dbkey: "paste-your-64-char-key-here"
mqtt:
  host: 127.0.0.1
  port: 1883
plugins:
  echo:  # built-in demo
    module: omni_bot_sdk.plugins.echo

4.5 Start a Local MQTT Broker (Message Bus)

Windows users can use NanoMQ:

nanomq start

Leave this window open; the bot will connect automatically.

4.6 Launch WeChat and the Bot

1. 「Close WeChat」 if it is running.
2. 「Re-open WeChat」, log in, and leave it 「visible」 on the desktop (do not minimize).
3. In a new terminal:

python -c "from omni_bot_sdk.bot import Bot; Bot('config.yaml').start()"

The bot will send a test picture to “File Transfer” and print Decrypt Key OK.
Congratulations—your bot is alive!

5. Your First Conversation

Send any message to yourself (or a friend) from another device.
The built-in 「echo」 plugin will immediately reply with the same text.
You have just completed the classic “Hello, World” of WeChat bots.

6. Understanding the Plugin System

The architecture is purposely simple:

Database → Poller → Message Queue → Plugin Chain → RPA Queue → WeChat

6.1 Adding an OpenAI Chat Plugin

1. Install the plugin:

pip install omni-bot-plugin-openai

2. Edit config.yaml:

plugins:
  openai-chat:
    module: openai_bot_plugin.OpenAIChat
    api_key: sk-your-openai-key
    max_tokens: 150

3. Restart the bot.
   Every private message you receive will now be answered by ChatGPT.

6.2 Group Welcome Poster

1. Install the plugin:

pip install omni-bot-plugin-welcome

2. Provide a Dify workflow ID:

plugins:
  welcome:
    module: welcome_plugin.Welcome
    dify_api_key: your-dify-key
    workflow_id: 123456

Whenever a new member joins a group, the bot will generate and send a customized welcome image.

6.3 Writing Your Own Plugin (5 Minutes)

Create my_plugin.py:

from omni_bot_sdk.plugin import BasePlugin

class RepeaterPlugin(BasePlugin):
    async def handle(self, msg):
        if msg.is_group and "repeat" in msg.text.lower():
            return msg.reply(msg.text)

Add to config.yaml:

plugins:
  repeater:
    module: my_plugin.RepeaterPlugin

Restart and type “repeat hello” in any group—the bot will echo it.

7. Production-Ready Tips

7.1 Running 24/7

• Use an old laptop or cloud Windows VM.
• Disable sleep: powercfg /hibernate off.
• Create a scheduled task that starts the bot on reboot.

7.2 Avoiding Detection

• Keep message frequency 「below」 20 per minute.
• Do not send identical text to many users.
• Use Windows Task Scheduler to 「randomize」 start-up times.

7.3 Logging & Monitoring

The SDK writes daily logs to logs\bot-yyyy-mm-dd.log.
Set a simple PowerShell script to restart the bot if the log shows 「“RPA disconnected”」:

Select-String "disconnected" .\logs\bot-$(Get-Date -Format yyyy-MM-dd).log -quiet
if ($?) { Restart-Computer -Force }

7.4 Backup Your Key

Store dbkey and config.yaml in a password manager.
If WeChat updates, you may need to fetch a new key.

8. Troubleshooting Shortlist

9. Roadmap (What’s Coming Next)

• 「WXGF image decoding」 for better picture handling
• 「Multi-account support」 in a single process
• 「Web dashboard」 to control the bot from any browser
• 「Unit tests」 (yes, they are on the list)

You can follow or contribute to these features on the official GitHub repository.

10. Final Checklist

• [ ] Python 3.12 installed
• [ ] WeChat desktop updated
• [ ] Database key copied into config.yaml
• [ ] NanoMQ or another MQTT broker running
• [ ] Bot answers “Hello” when you send a message
• [ ] Optional: OpenAI key or other plugins configured

Once every box is ticked, you have a fully autonomous, zero-invasion WeChat bot ready for safe experimentation or personal productivity hacks.