Skip to content
BSWEN
Blog

How to Connect WeChat to AI Agent in 4 Simple Steps with MMClaw

Cowrie
Cowrie
Dev @ Bswen

Problem

I wanted to connect my AI agent to WeChat. After hours of frustration, I kept hitting the same walls:

Error Messages
Error: webhook url required
Error: public IP address not detected
Error: Node.js runtime required for WeChat SDK
Error: registration failed - enterprise verification needed

The official WeChat SDK only supports Node.js. I’m a Python developer. I don’t want to maintain two codebases.

I tried the bridge approach with wechaty:

Terminal
npm install wechaty wechaty-puppet-wechat
pip install wechaty

But then I got this:

wechaty-error.sh
(node:12345) Warning: Accessing non-existent property 'puppet' of module 'wechaty'
Error: PUPPET_NOT_FOUND

I spent an entire afternoon debugging Node.js dependency issues. This is ridiculous. I just want my AI agent to respond on WeChat.

Environment

Let me show you my setup:

env-check.sh
$ python --version
Python 3.11.4


$ node --version
v18.17.0  # I have Node.js but I don't want to use it


$ sw_vers
ProductName:            macOS
ProductVersion:         14.3
BuildVersion:           23D56

The Traditional Way (Painful)

Here’s what I tried first. The official documentation says to use the WeChat Node.js SDK:

bot.js
const { WechatyBuilder } = require('wechaty')


const bot = WechatyBuilder.build({
  name: 'my-bot',
  puppet: 'wechaty-puppet-wechat',
})


bot.on('message', async (msg) => {
  const contact = msg.talker()
  const text = msg.text()


  if (msg.self()) return


  // Call Python AI agent via HTTP
  const response = await fetch('http://localhost:8000/chat', {
    method: 'POST',
    body: JSON.stringify({ message: text })
  })


  const data = await response.json()
  await msg.say(data.reply)
})


bot.start()

Then I need to run a Python server for my AI agent:

agent_server.py
from fastapi import FastAPI
from pydantic import BaseModel


app = FastAPI()


class Message(BaseModel):
    message: str


@app.post("/chat")
async def chat(msg: Message):
    # Your AI agent logic here
    reply = f"You said: {msg.message}"
    return {"reply": reply}

This architecture looks like this:

┌─────────────┐     HTTP      ┌─────────────┐
│   WeChat    │──────────────▶│  Node.js    │
│   Server    │               │   Bot       │
└─────────────┘               └──────┬──────┘
                                     │ HTTP
                                     ▼
                              ┌─────────────┐
                              │   Python    │
                              │  AI Agent   │
                              └─────────────┘

Problems with this approach:

  1. Two runtimes to manage (Node.js + Python)
  2. Two processes to debug
  3. Complex error handling across languages
  4. Extra latency from HTTP calls
  5. Harder to deploy

The Solution: MMClaw

Then I discovered MMClaw. It’s a lightweight (1700 lines) pure Python AI Agent kernel that supports WeChat natively.

The key difference: MMClaw reimplemented the WeChat protocol in pure Python. No Node.js required.

New Architecture
┌─────────────┐              ┌─────────────┐
│   WeChat    │──────────────│   Python    │
│   Server    │              │  MMClaw     │
└─────────────┘              │  + Agent    │
                             └─────────────┘

One runtime. One process. Much simpler.

Step 1: Install Python

I recommend using Miniconda for isolation:

Terminal
# Download and install Miniconda
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-arm64.sh
bash Miniconda3-latest-MacOSX-arm64.sh


# Create a new environment
conda create -n mmclaw python=3.11
conda activate mmclaw

On Linux:

Terminal
# Ubuntu/Debian
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
bash Miniconda3-latest-Linux-x86_64.sh


conda create -n mmclaw python=3.11
conda activate mmclaw

Step 2: Install MMClaw

Terminal
pip install mmclaw

That’s it. No npm install. No dependency hell.

Let me verify the installation:

Terminal
$ pip show mmclaw
Name: mmclaw
Version: 0.3.2
Summary: Lightweight Pure Python AI Agent Kernel
Author: MMClaw Team
Location: /opt/miniconda3/envs/mmclaw/lib/python3.11/site-packages
Requires: httpx, pydantic, websockets

Notice the dependencies: only httpx, pydantic, and websockets. No Node.js bindings.

Step 3: Configure WeChat

Run the configuration wizard:

Terminal
$ mmclaw config


? Select messaging platform: (Use arrow keys)
  ❯ WeChat
    Telegram
    WhatsApp
    Feishu
    QQ Bot


? Select WeChat mode:
  ❯ Personal (scan QR code)
    Enterprise (corporate account)


? Enable message logging? (y/N) y


? Set log level: (Use arrow keys)
  DEBUG
  ❯ INFO
  WARNING
  ERROR


Configuration saved to ~/.mmclaw/config.yaml


Now scan the QR code with WeChat:

A QR code will appear in your terminal:

█████████████████████████████████████████
█████████████████████████████████████████
████   ▄▄▄▄▄ ██▄ ▄█▀▄▄ ▄▄▄▄▄ ████
████   █   █ █▀▀▀█ ▄█ █   █ ████
████   █▄▄▄█ ▀▀▀█ ▄ █ █▄▄▄█ ████
████   ▄▄▄▄▄ █ █▄▀▄▀▀█ ▄▄▄▄▄ ████
████   █   █ █▄▀▀█ ▄██ █   █ ████
████   █▄▄▄█ ██ █▀█ ▀▀█ █▄▄▄█ ████
████   ▄▄▄▄▄ █ █▀▀▀ █▀▀█ ▄▄▄▄▄ ████
████   █   █ █▀█ █▀▀▀▀██ █   █ ████
████   █▄▄▄█ █▄█ ▄▀▀▀▀▀█ █▄▄▄█ ████
█████████████████████████████████████████
█████████████████████████████████████████

Open WeChat on your phone, scan the QR code, and confirm the login.

Terminal Output
Scan successful!
Logged in as: Your Name
WeChat ID: your_wechat_id

Step 4: Run Your Agent

Create a simple AI agent:

my_agent.py
from mmclaw import Agent, Tool


@Tool
def get_weather(city: str) -> str:
    """Get current weather for a city"""
    # Your weather API logic here
    return f"Weather in {city}: Sunny, 22C"


# Create agent with your LLM
agent = Agent(
    name="wechat-assistant",
    model="gpt-4",
    tools=[get_weather],
    system_prompt="""You are a helpful assistant on WeChat.
    Respond concisely since WeChat messages should be brief."""
)


# Run with WeChat
agent.run(platform="wechat")

Now run it:

Terminal
$ mmclaw run my_agent.py


[2026-03-24 15:10:01] INFO  Starting MMClaw agent...
[2026-03-24 15:10:01] INFO  Connected to WeChat as: Your Name
[2026-03-24 15:10:01] INFO  Agent ready. Listening for messages...


[2026-03-24 15:10:15] MESSAGE from John: Hello!
[2026-03-24 15:10:15] REPLY: Hi! How can I help you today?


[2026-03-24 15:10:23] MESSAGE from John: What's the weather in Beijing?
[2026-03-24 15:10:23] TOOL CALL: get_weather(city="Beijing")
[2026-03-24 15:10:23] REPLY: The weather in Beijing is sunny with 22C. Great day for a walk!

Your AI agent is now live on WeChat.

How It Works

Let me explain what MMClaw does under the hood.

1. WebSocket Connection

MMClaw establishes a WebSocket connection to WeChat servers:

mmclaw/wechat/connection.py (simplified)
import websockets


class WeChatConnection:
    async def connect(self, qr_callback):
        """Connect to WeChat via QR code login"""
        ws_url = self._get_websocket_url()


        async with websockets.connect(ws_url) as ws:
            # Send login request
            await ws.send(json.dumps({
                "type": "login_request",
                "device_id": self.device_id
            }))


            # Receive QR code
            response = await ws.recv()
            data = json.loads(response)


            if data["type"] == "qr_code":
                qr_callback(data["qr_url"])  # Display QR code


            # Wait for scan confirmation
            while True:
                response = await ws.recv()
                data = json.loads(response)


                if data["type"] == "login_success":
                    self.session_key = data["session_key"]
                    return True

2. Message Handling

Messages are handled through a simple event loop:

mmclaw/wechat/handler.py (simplified)
class MessageHandler:
    async def listen(self, on_message):
        """Listen for incoming messages"""
        async for message in self.connection.stream():
            if message["type"] == "message":
                await on_message(
                    sender=message["sender"],
                    content=message["content"],
                    room=message.get("room")
                )

3. Pure Python Implementation

The key innovation is that MMClaw reimplemented the WeChat protocol without Node.js:

protocol-comparison.txt
Official WeChat SDK:
  WeChat Server <--WebSocket--> Node.js SDK <--HTTP--> Your Python Code


MMClaw:
  WeChat Server <--WebSocket--> Pure Python SDK + Your Code

This is possible because:

  1. WeChat’s protocol is based on standard WebSocket
  2. The authentication flow uses standard QR code login
  3. MMClaw reverse-engineered the message format

Common Issues and Solutions

Issue 1: QR Code Timeout

If the QR code expires before you scan:

Terminal
[2026-03-24 15:05:01] ERROR QR code expired, please re-run mmclaw config

Solution: The QR code expires in 5 minutes. Run mmclaw config again for a new QR code.

Issue 2: Login Frequency Limit

WeChat limits how often you can log in:

Terminal
[2026-03-24 15:15:01] ERROR Login frequency exceeded. Try again in 24 hours.

Solution: MMClaw caches your session. Don’t restart the agent frequently. Use mmclaw run --daemon for long-running processes.

Issue 3: Message Rate Limiting

If you send too many messages:

Terminal
[2026-03-24 15:20:01] WARN Rate limited: waiting 60 seconds

Solution: Add delays between messages:

rate_limit_fix.py
from mmclaw import Agent


agent = Agent(
    name="wechat-assistant",
    model="gpt-4",
    message_delay=2.0  # Wait 2 seconds between replies
)

Why MMClaw Exists

I asked the MMClaw maintainers why they built this. Here’s what they said:

“We built AI agents in Python. We wanted to deploy them to WeChat. The official SDK required Node.js. We didn’t want to maintain two codebases. So we reimplemented the WeChat protocol in pure Python. MMClaw was born.”

The entire kernel is only 1700 lines of Python. It supports:

  • WeChat (personal and enterprise)
  • Telegram
  • WhatsApp
  • Feishu
  • QQ Bot

Summary

In this post, I showed you how to connect an AI agent to WeChat in 4 steps:

  1. Install Python with Miniconda
  2. pip install mmclaw
  3. mmclaw config and scan the QR code
  4. mmclaw run your_agent.py

The key advantage of MMClaw is that it’s pure Python. No Node.js, no webhook configuration, no public IP address required. Just write your agent in Python and run it.

If you’re building AI agents and need WeChat integration, give MMClaw a try. It saved me hours of frustration.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!

Comments

Tags: