weixin-agent-sdk

weixin-agent-sdk

Skill by ara.so — Daily 2026 Skills collection.

weixin-agent-sdk is a TypeScript framework that bridges any AI backend to WeChat (微信) via the Clawbot channel. It uses long-polling to receive messages — no public server required — and exposes a minimal Agent interface so you can plug in OpenAI, Claude, or any custom logic in minutes.

---

Installation

# npm
npm install weixin-agent-sdk

# pnpm (monorepo)
pnpm add weixin-agent-sdk

Node.js >= 22 required.

---

Quick Start

1. Login (scan QR code once)

import { login } from "weixin-agent-sdk";

await login();
// Credentials are persisted to ~/.openclaw/ — run once, then use start()

2. Implement the Agent interface

import { login, start, type Agent } from "weixin-agent-sdk";

const echo: Agent = {
  async chat(req) {
    return { text: `You said: ${req.text}` };
  },
};

await login();
await start(echo);

---

Core API

Agent Interface

interface Agent {
  chat(request: ChatRequest): Promise<ChatResponse>;
}

interface ChatRequest {
  conversationId: string;   // Unique user/conversation identifier
  text: string;             // Message text content
  media?: {
    type: "image" | "audio" | "video" | "file";
    filePath: string;       // Local path (already downloaded & decrypted)
    mimeType: string;
    fileName?: string;
  };
}

interface ChatResponse {
  text?: string;            // Markdown supported; auto-converted to plain text
  media?: {
    type: "image" | "video" | "file";
    url: string;            // Local path OR HTTPS URL (auto-downloaded)
    fileName?: string;
  };
}

login()

Triggers QR code scan and persists session to ~/.openclaw/. Only needs to run once.

start(agent)

Starts the message loop. Blocks until process exits. Automatically reconnects on session expiry.

---

Common Patterns

Multi-turn Conversation with History

import { login, start, type Agent } from "weixin-agent-sdk";

const conversations = new Map<string, string[]>();

const myAgent: Agent = {
  async chat(req) {
    const history = conversations.get(req.conversationId) ?? [];
    history.push(`user: ${req.text}`);

    const reply = await callMyAIService(history);

    history.push(`assistant: ${reply}`);
    conversations.set(req.conversationId, history);

    return { text: reply };
  },
};

await login();
await start(myAgent);

OpenAI Agent (Full Example)

import OpenAI from "openai";
import { login, start, type Agent, type ChatRequest } from "weixin-agent-sdk";
import * as fs from "fs";

const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
  baseURL: process.env.OPENAI_BASE_URL, // optional override
});

const model = process.env.OPENAI_MODEL ?? "gpt-4o";
const systemPrompt = process.env.SYSTEM_PROMPT ?? "You are a helpful assistant.";

type Message = OpenAI.Chat.ChatCompletionMessageParam;
const histories = new Map<string, Message[]>();

const openaiAgent: Agent = {
  async chat(req: ChatRequest) {
    const history = histories.get(req.conversationId) ?? [];

    // Build user message — support image input
    const content: OpenAI.Chat.ChatCompletionContentPart[] = [];

    if (req.text) {
      content.push({ type: "text", text: req.text });
    }

    if (req.media?.type === "image") {
      const imageData = fs.readFileSync(req.media.filePath).toString("base64");
      content.push({
        type: "image_url",
        image_url: {
          url: `data:${req.media.mimeType};base64,${imageData}`,
        },
      });
    }

    history.push({ role: "user", content });

    const response = await client.chat.completions.create({
      model,
      messages: [
        { role: "system", content: systemPrompt },
        ...history,
      ],
    });

    const reply = response.choices[0].message.content ?? "";
    history.push({ role: "assistant", content: reply });
    histories.set(req.conversationId, history);

    return { text: reply };
  },
};

await login();
await start(openaiAgent);

Send Image Response

const imageAgent: Agent = {
  async chat(req) {
    return {
      text: "Here is your image:",
      media: {
        type: "image",
        url: "/tmp/output.png",       // local path
        // or: url: "https://example.com/image.png"  — auto-downloaded
      },
    };
  },
};

Send File Response

const fileAgent: Agent = {
  async chat(req) {
    return {
      media: {
        type: "file",
        url: "/tmp/report.pdf",
        fileName: "monthly-report.pdf",
      },
    };
  },
};

---

ACP (Agent Client Protocol) Integration

If you have an ACP-compatible agent (Claude Code, Codex, kimi-cli, etc.), use the weixin-acp package — no code needed.

# Claude Code
npx weixin-acp claude-code

# Codex
npx weixin-acp codex

# Any ACP-compatible agent (e.g. kimi-cli)
npx weixin-acp start -- kimi acp

weixin-acp launches your agent as a subprocess and communicates via JSON-RPC over stdio.

---

Environment Variables (OpenAI Example)

Variable	Required	Description
OPENAI_API_KEY	Yes	OpenAI API key
OPENAI_BASE_URL	No	Custom API base URL (OpenAI-compatible services)
OPENAI_MODEL	No	Model name, default gpt-5.4
SYSTEM_PROMPT	No	System prompt for the assistant

---

Built-in Slash Commands

Send these in WeChat chat to control the bot:

Command	Description
/echo <message>	Echoes back directly (bypasses Agent), shows channel latency
/toggle-debug	Toggles debug mode — appends full latency stats to each reply

---

Supported Message Types

Incoming (WeChat → Agent)

Type	media.type	Notes
Text	—	Plain text in request.text
Image	image	Downloaded & decrypted, filePath = local file
Voice	audio	SILK auto-converted to WAV (requires silk-wasm)
Video	video	Downloaded & decrypted
File	file	Downloaded & decrypted, original filename preserved
Quoted message	—	Quoted text appended to request.text, quoted media as media
Voice-to-text	—	WeChat transcription delivered as request.text

Outgoing (Agent → WeChat)

Type	Usage
Text	Return { text: "..." }
Image	Return { media: { type: "image", url: "..." } }
Video	Return { media: { type: "video", url: "..." } }
File	Return { media: { type: "file", url: "...", fileName: "..." } }
Text + Media	Return both text and media together
Remote image	Set url to an HTTPS link — SDK auto-downloads and uploads to WeChat CDN

---

Monorepo / pnpm Setup

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

# Login (scan QR code)
pnpm run login -w packages/example-openai

# Start the OpenAI bot
OPENAI_API_KEY=$OPENAI_API_KEY pnpm run start -w packages/example-openai

---

Troubleshooting

Session expired (errcode -14) The SDK automatically enters a 1-hour cooldown and then reconnects. No manual intervention needed.

Audio not converting from SILK to WAV Install the optional dependency: npm install silk-wasm

Bot not receiving messages after restart State is persisted in ~/.openclaw/get_updates_buf. The bot resumes from the last position automatically.

Remote image URL not sending Ensure the URL is HTTPS and publicly accessible. The SDK downloads it before uploading to WeChat CDN.

login() QR code not appearing Ensure your terminal supports rendering QR codes, or check ~/.openclaw/ for the raw QR data.