weixin-agent-sdk

Skill by ara.so — Daily 2026 Skills collection.

weixin-agent-sdk

Agent

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/

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

# 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

Environment Variables (OpenAI Example)

OPENAI_API_KEY

OPENAI_BASE_URL

OPENAI_MODEL

gpt-5.4

SYSTEM_PROMPT

Built-in Slash Commands

Send these in WeChat chat to control the bot:

/echo <message>

/toggle-debug

Supported Message Types

Incoming (WeChat → Agent)

media.type

request.text

image

filePath

audio

silk-wasm

video

file

request.text

media

request.text

Outgoing (Agent → WeChat)

{ text: "..." }

{ media: { type: "image", url: "..." } }

{ media: { type: "video", url: "..." } }

{ media: { type: "file", url: "...", fileName: "..." } }

text

media

url

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

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

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

login()

~/.openclaw/