WeChatBot

WeChat iLink Bot SDK for OpenClaw / AI Agent
_{Modular, production-grade, multi-language WeChat iLink Bot SDK}

---

中文文档

Connect any agent to WeChat in 5 minutes. Inspired by openclaw-weixin-cli.

📦 SDKs

SDK	Install	Status
Node.js	npm install @wechatbot/wechatbot	✅ Production Ready
Python	pip install wechatbot-sdk	✅ Production Ready
Go	go get github.com/corespeed-io/wechatbot/golang	✅ Production Ready
Rust	cargo add wechatbot	✅ Production Ready

🔧 Quick Install (Prebuilt Binaries)

No build tools needed — download and run. Supports Windows / macOS / Linux.

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/corespeed-io/wechatbot/main/install.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/corespeed-io/wechatbot/main/install.ps1 | iex

Pin a version:

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/corespeed-io/wechatbot/main/install.sh | bash -s -- --version v0.1.0

# Windows
install.ps1 -Version v0.1.0

Or download directly from GitHub Releases.

Platform	Go Binary	Rust Binary
Windows x64	✅ windows-amd64.exe	✅ rust-windows-amd64.exe
Windows ARM64	✅ windows-arm64.exe	🔜
macOS x64	✅ darwin-amd64	✅ rust-darwin-amd64
macOS ARM64	✅ darwin-arm64	✅ rust-darwin-arm64
Linux x64	✅ linux-amd64	✅ rust-linux-amd64
Linux ARM64	✅ linux-arm64	✅ rust-linux-arm64

⚡ Quick Start

Node.js

import { WeChatBot } from '@wechatbot/wechatbot'

const bot = new WeChatBot()
await bot.login()                             // QR code login
bot.onMessage(async (msg) => {
  await bot.reply(msg, `Echo: ${msg.text}`)   // Auto reply
})
await bot.start()

Python

from wechatbot import WeChatBot

bot = WeChatBot()

@bot.on_message
async def handle(msg):
    await bot.reply(msg, f"Echo: {msg.text}")

bot.run()  # login + start in one call

Go

bot := wechatbot.New()
bot.Login(ctx, false)
bot.OnMessage(func(msg *wechatbot.IncomingMessage) {
    bot.Reply(ctx, msg, fmt.Sprintf("Echo: %s", msg.Text))
})
bot.Run(ctx)

Rust

let bot = WeChatBot::new(BotOptions::default());
bot.login(false).await?;
bot.on_message(Box::new(|msg| {
    println!("{}: {}", msg.user_id, msg.text);
})).await;
bot.run().await?;

🤖 Pi Agent Extension

Chat with Pi coding agent directly from WeChat — scan QR code to connect.

# Install the extension (recommended)
pi install npm:@wechatbot/pi-agent

# Then in Pi:
/wechat          # Show QR code → Scan with WeChat → Connected!

See pi-agent/README.md for details.

✨ Features

All SDKs share the following capabilities:

Feature	Description
🔐 QR Code Login	Credential persistence, stored in ~/.wechatbot/
📨 Long Polling	Reliable message receiving with automatic cursor management
💬 Rich Media	Images, files, voice, video (upload + download)
🔗 context_token	Automatic lifecycle management, persists across restarts
⌨️ Typing Status	"Typing..." indicator with ticket caching
🔒 CDN Encryption	AES-128-ECB with dual-key format support
♻️ Session Recovery	Auto re-login on session expiry (-14)
📝 Smart Chunking	Split text by natural boundaries (paragraphs → lines → spaces)

Node.js Exclusive Features

Feature	Description
🧩 Middleware Pipeline	Express/Koa-style composable middleware
📦 Pluggable Storage	File, memory, or custom (Redis, SQLite…)
🎯 Typed Events	Full IntelliSense lifecycle monitoring
📝 Structured Logging	Leveled, context-aware, pluggable transports
🏗️ Message Builder	.text().image().file().build() chaining API

🏗 Architecture

graph TD
    A["🤖 Your Bot"] --> B["Bot Client (Orchestrator)"]
    B --> C["Poller"]
    B --> D["Sender"]
    B --> E["Typing"]
    B --> F["Media"]
    C --> G["Context Store (Token Cache)"]
    D --> G
    E --> G
    F --> G
    G --> H["Protocol / API (HTTP Calls)"]
    H --> I["Storage (Credentials & State Persistence)"]

📖 Documentation

Document	Description
docs/protocol.md	iLink Bot API Protocol Reference
docs/architecture.md	Architecture Design & SDK Comparison
nodejs/README.md	Node.js SDK Documentation
python/README.md	Python SDK Documentation
golang/README.md	Go SDK Documentation
rust/README.md	Rust SDK Documentation
pi-agent/README.md	Pi Extension (WeChat ↔ Pi Bridge)

🌐 Website

The bilingual documentation website has been moved to a separate repository: jiweiyuan/wechatbot-landing

📁 Project Structure

wechatbot/
├── nodejs/                # Node.js SDK (TypeScript)
│   ├── src/               #   11 modules
│   ├── tests/             #   8 test files
│   └── examples/          #   4 example bots
├── python/                # Python SDK (async/aiohttp)
│   ├── wechatbot/         #   6 modules
│   └── tests/             #   2 test files
├── golang/                # Go SDK (pure stdlib)
│   ├── bot.go             #   Bot client
│   ├── types.go           #   Type definitions
│   └── internal/          #   protocol, auth, crypto
├── rust/                  # Rust SDK
│   └── src/               #   6 modules
├── pi-agent/              # Pi Extension (WeChat ↔ Pi Bridge)
│   └── src/               #   Extension entry & WeChat client
└── docs/                  # Shared documentation
    ├── protocol.md        #   iLink API Protocol Spec
    └── architecture.md    #   Architecture & SDK Comparison

📄 License

MIT