weixin-agent-sdk: Best AI Agent SDKs for WeChat Bot Developers in 2026

What Is weixin-agent-sdk?

weixin-agent-sdk is an open-source AI Agent SDK built by wong2, forked and modified from Tencent's openclaw-weixin, designed to bridge any AI backend to WeChat via a simple Agent interface. Developers implement a single chat(request: ChatRequest): Promise<ChatResponse> method to handle incoming WeChat messages including text, images, SILK audio (auto-converted to WAV), videos, and files. weixin-agent-sdk is one of the best AI Agent SDKs for WeChat Bot Developers, with 889 GitHub stars as of October 2024, supporting seamless integration with Agent Client Protocol (ACP) agents like Claude Code and kimi-cli without custom code. The monorepo includes the core SDK, a WeChat ACP adapter, and an OpenAI example, enabling QR code login and stdio-based JSON-RPC communication in under 50 lines of code.

Quick Overview

Who Should Use weixin-agent-sdk?

• WeChat Bot Developers integrating AI like OpenAI or Claude into group chats who need media handling without manual file decryption.
• Indie hackers prototyping multilingual AI assistants for Chinese markets using existing ACP-compatible agents such as kimi-cli.
• Node.js teams maintaining conversation state across sessions with built-in conversationId tracking in a single-file deployment.
• AI Experimenters testing multimodal inputs like voice-to-text from WeChat without building full WeChat API wrappers.

Not ideal for:

• Python-only stacks preferring established libraries like itchat or wxpy.
• Enterprise-scale bots requiring official WeChat WorkCorp API compliance and audit logs.
• Non-media bots where raw WebSocket handling suffices without AI abstraction.

Key Features of weixin-agent-sdk

• Agent Interface — Single chat method processes ChatRequest with conversationId, text, and optional media (image/audio/video/file), returning ChatResponse with text or media URL; supports Markdown-to-plaintext conversion automatically.
• ACP Adapter (weixin-acp) — Launches any ACP-compatible agent as a subprocess via npx weixin-acp claude-code, communicating over JSON-RPC on stdio; zero-code setup for Claude Code, Codex, or kimi-cli.
• Media Handling — Auto-downloads and decrypts WeChat CDN files; converts SILK audio to WAV using silk-wasm (requires npm install); preserves original filenames for files.
• QR Login — login() function scans WeChat QR code for session auth, persisting across restarts if configured.
• Conversation Management — conversationId enables multi-turn history; developer-managed Map stores messages for context in AI calls.
• OpenAI Example — Full implementation in packages/example-openai with OPENAI_API_KEY, model selection (default gpt-5.4), and system prompts; handles image inputs via Vision API.
• Message Types — Supports quoted messages by appending text and media; WeChat-side voice-to-text feeds directly into request.text.

weixin-agent-sdk vs Alternatives

Wechaty suits broad bot automation with plugins for 20+ puppets but lacks built-in AI bridging and requires custom media pipelines. itchat excels in Python for desktop WeChat control via UOS protocol but ignores modern MP/Channel APIs and multimodal AI. Claude Code Canvas pairs well for Claude users, as weixin-agent-sdk launches it directly via ACP, but lacks WeChat-specific login.

How weixin-agent-sdk Works

weixin-agent-sdk establishes a WebSocket connection to WeChat after QR login, decrypting incoming messages using WeChat's protocol keys. The core loop in start(agent) polls for events, normalizes them into ChatRequest (downloading media to local paths), calls the user's agent.chat(), and sends responses via ChatResponse. Architecture relies on TypeScript interfaces for type safety, with pnpm monorepo managing dependencies like @agentclientprotocol/sdk at v0.17.0.

For ACP integration, weixin-acp spawns the agent subprocess (e.g., npx weixin-acp start -- claude-code), piping JSON-RPC requests over stdin/stdout. This stdio bridge abstracts protocol details, allowing any ACP agent to respond without WeChat knowledge. Custom agents manage state externally, like a Map keyed by conversationId for history.

# Install and login
pnpm install weixin-agent-sdk
npx weixin-agent-sdk login

# Simple echo agent
node -e "
import { login, start, type Agent } from 'weixin-agent-sdk'; const agent: Agent = { async chat(req) { return { text: `Echo: ${req.text}` }; } }; login().then(() => start(agent));"

This script logs in via QR, starts the message loop, and echoes text inputs. Media requests appear in req.media with filePath ready for processing (e.g., OpenAI Vision). Expect sub-second latency for text, 2-5s for audio conversion.

Pros and Cons of weixin-agent-sdk

Pros:

• Minimal API surface: three exports (login, start, Agent) enable bots in 10 lines.
• Multimodal out-of-box: SILK-to-WAV, CDN decryption, file handling without extra libs.
• ACP zero-config: Run npx weixin-acp claude-code for instant Claude integration.
• TypeScript-native: Full interfaces for ChatRequest/ChatResponse, IDE autocomplete.
• Conversation-persistent: conversationId tracks users without session hacks.
• OpenAI-ready example: Supports images, custom models, base URLs for proxies.

Cons:

• Unofficial: Risks WeChat protocol changes breaking login/media (monitor commits).
• Node.js only: No Python/Rust ports; Python devs stick to itchat.
• Subprocess overhead for ACP: 100-300ms latency vs direct agent calls.
• No built-in persistence: Devs must implement DB for history beyond in-memory Map.
• silk-wasm dependency: Audio needs wasm install, fails on restricted envs.

Getting Started with weixin-agent-sdk

Clone the repo and install with pnpm for the monorepo.

git clone https://github.com/wong2/weixin-agent-sdk
cd weixin-agent-sdk
pnpm install

# Login to WeChat
pnpm run login

# Run OpenAI example
cd packages/example-openai
OPENAI_API_KEY=sk-proj-xxx pnpm run start

After login, scan the QR with your WeChat app; the session persists in memory. The OpenAI bot starts listening, processing texts/images via gpt-4-vision; set OPENAI_MODEL=gpt-4o-mini for speed. Initial config: Add SYSTEM_PROMPT env for custom behavior; test in a group chat for conversationId multi-turn.

For custom agents, implement Agent as shown earlier. Media outputs use local paths or HTTPS URLs; ensure files are served if remote. Scale by wrapping in PM2 for restarts.

Verdict

weixin-agent-sdk is the strongest option for WeChat Bot Developers bridging AI backends when multimodal support and ACP compatibility matter over official APIs. Its Agent interface cuts integration to one method with auto-media handling, beating Wechaty on AI focus. Caveat: Unofficial status demands commit monitoring; pair with OpenSwarm for agent orchestration.