--- slug: "wechatbot-pi-agent" source_type: "readme" source_url: "https://cdn.jsdelivr.net/gh/corespeed-io/wechatbot@main/README.md" repo: "https://github.com/corespeed-io/wechatbot" source_file: "README.md" branch: "main" --- # WeChatBot

微信 iLink Bot SDK for OpenClaw / AI Agent
模块化、生产级、多语言微信 iLink Bot SDK

npm License Stars

--- [English](https://github.com/corespeed-io/wechatbot/blob/HEAD/README.EN.MD) 5 分钟让任何 Agent 接入微信。灵感来自 [openclaw-weixin](https://github.com/Tencent/openclaw-weixin)。 ## 📦 SDK 一览 | SDK | 安装 | 状态 | |-----|------|------| | [Node.js](https://github.com/corespeed-io/wechatbot/tree/HEAD/nodejs/) | `npm install @wechatbot/wechatbot` | ✅ 生产就绪 | | [Python](https://github.com/corespeed-io/wechatbot/tree/HEAD/python/) | `pip install wechatbot-sdk` | ✅ 生产就绪 | | [Go](https://github.com/corespeed-io/wechatbot/tree/HEAD/golang/) | `go get github.com/corespeed-io/wechatbot/golang` | ✅ 生产就绪 | | [Rust](https://github.com/corespeed-io/wechatbot/tree/HEAD/rust/) | `cargo add wechatbot` | ✅ 生产就绪 | ## ⚡ 快速开始 ### Node.js ```typescript import { WeChatBot } from '@wechatbot/wechatbot' const bot = new WeChatBot() await bot.login() // 扫码登录 bot.onMessage(async (msg) => { await bot.reply(msg, `Echo: ${msg.text}`) // 自动回复 }) await bot.start() ``` ### Python ```python from wechatbot import WeChatBot bot = WeChatBot() @bot.on_message async def handle(msg): await bot.reply(msg, f"Echo: {msg.text}") bot.run() # 扫码登录 + 开始监听 ``` ### Go ```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 ```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?; ``` ## ✨ 核心功能 所有 SDK 共享以下能力： | 功能 | 说明 | |------|------| | 🔐 扫码登录 | 凭证持久化，存储于 `~/.wechatbot/` | | 📨 长轮询消息 | 可靠消息接收，自动游标管理 | | 💬 富媒体支持 | 图片、文件、语音、视频（上传 + 下载） | | 🔗 context_token | 自动生命周期管理，跨重启持久化 | | ⌨️ 输入状态 | "对方正在输入中"，含 ticket 缓存 | | 🔒 CDN 加密 | AES-128-ECB，支持双密钥格式 | | ♻️ 会话恢复 | 会话过期（`-14`）自动重新登录 | | 📝 智能分片 | 按自然边界拆分文本（段落 → 行 → 空格） | ### Node.js 独有功能 | 功能 | 说明 | |------|------| | 🧩 中间件管道 | Express/Koa 风格可组合中间件 | | 📦 可插拔存储 | 文件、内存，或自定义（Redis、SQLite…） | | 🎯 类型化事件 | 完整 IntelliSense 生命周期监控 | | 📝 结构化日志 | 分级、上下文感知、可插拔传输 | | 🏗️ 消息构建器 | `.text().image().file().build()` 链式 API | ## 👥 多租户 / 多账号 每个 Bot 实例完全隔离（独立 HTTP 客户端、事件、消息轮询器），无全局状态、不占本地端口——一个后端进程可以同时运行多个微信账号。二维码通过回调返回，可推给 Web 前端让每个用户在自己的页面上扫码： ```typescript // 每个租户一个实例，凭证按租户隔离 const bot = new WeChatBot({ storage: new PostgresStorage(pool, tenantId), // 或 { storageDir: `/data/${tenantId}` } }) await bot.login({ callbacks: { onQrUrl: (url) => pushQrToWebUI(tenantId, url), // 推给该用户的页面扫码 onScanned: () => notify(tenantId, '已扫码，等待确认'), onExpired: () => refreshQr(tenantId), }, }) await bot.start() ``` 三条注意事项： 1. **存储隔离** — 每个账号必须有独立的 `storageDir` 或存储命名空间，共用会互相覆盖凭证。 2. **单账号单实例** — 同一账号在全集群只能有一个实例轮询消息，否则游标互相覆盖；多机部署用 advisory lock 或租约表选主。 3. **重启免扫码** — 凭证已持久化，重启后 `login()` 自动恢复会话。 完整示例（含 PostgreSQL 自定义存储）见 [Node.js SDK 文档](https://github.com/jiweiyuan/wechatbot-landing)。 ## 🏗 架构 ```mermaid graph TD A["🤖 你的 Bot 代码"] --> B["Bot Client（核心调度器）"] B --> C["Poller"] B --> D["Sender"] B --> E["Typing"] B --> F["Media"] C --> G["Context Store（Token 缓存）"] D --> G E --> G F --> G G --> H["Protocol / API（HTTP 调用）"] H --> I["Storage（凭证 & 状态持久化）"] ``` ## 📖 文档 | 文档 | 说明 | |------|------| | [docs/protocol.md](https://github.com/corespeed-io/wechatbot/blob/HEAD/docs/protocol.md) | iLink Bot API 协议参考 | | [docs/architecture.md](https://github.com/corespeed-io/wechatbot/blob/HEAD/docs/architecture.md) | 架构设计 & SDK 对比 | | [nodejs/README.md](https://github.com/corespeed-io/wechatbot/blob/HEAD/nodejs/README.md) | Node.js SDK 文档 | | [python/README.md](https://github.com/corespeed-io/wechatbot/blob/HEAD/python/README.md) | Python SDK 文档 | | [golang/README.md](https://github.com/corespeed-io/wechatbot/blob/HEAD/golang/README.md) | Go SDK 文档 | | [rust/README.md](https://github.com/corespeed-io/wechatbot/blob/HEAD/rust/README.md) | Rust SDK 文档 | | [pi-agent/README.md](https://github.com/corespeed-io/wechatbot/blob/HEAD/pi-agent/README.md) | Pi 扩展文档（微信 ↔ Pi 桥接） | ## 🌐 网站 双语文档网站已移至独立仓库：[jiweiyuan/wechatbot-landing](https://github.com/jiweiyuan/wechatbot-landing) ## 🤖 Pi Agent 扩展 在微信中直接与 [Pi 编程助手](https://github.com/badlogic/pi-mono) 对话 — 扫码即连。详见 [pi-agent/README.md](https://github.com/corespeed-io/wechatbot/blob/HEAD/pi-agent/README.md)。 ```bash pi install npm:@wechatbot/pi-agent /wechat # 显示二维码 → 微信扫码 → 连接成功！ ``` ## 🔧 预编译 Echo Bot 不想写代码？可以直接下载预编译的 Echo Bot 体验。详见 [GitHub Releases](https://github.com/corespeed-io/wechatbot/releases)。 ```bash # 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 ``` ## 📁 项目结构 ``` wechatbot/ ├── nodejs/ # Node.js SDK（TypeScript） │ ├── src/ # 11 个模块 │ ├── tests/ # 8 个测试文件 │ └── examples/ # 4 个示例 Bot ├── python/ # Python SDK（async/aiohttp） │ ├── wechatbot/ # 6 个模块 │ └── tests/ # 2 个测试文件 ├── golang/ # Go SDK（纯标准库） │ ├── bot.go # Bot 客户端 │ ├── types.go # 类型定义 │ └── internal/ # protocol, auth, crypto ├── rust/ # Rust SDK │ └── src/ # 6 个模块 ├── pi-agent/ # Pi 扩展（微信 ↔ Pi 桥接） │ └── src/ # 扩展入口 & 微信客户端 └── docs/ # 共享文档 ├── protocol.md # iLink API 协议规范 └── architecture.md # 架构 & SDK 对比 ``` ## ⭐ Star History [![Star History Chart](https://api.star-history.com/svg?repos=corespeed-io/wechatbot&type=Date)](https://star-history.com/#corespeed-io/wechatbot&Date) ## 📄 License [MIT](https://github.com/corespeed-io/wechatbot/tree/HEAD/LICENSE)