wong2/weixin-agent-sdk

weixin-agent-sdk

本项目非微信官方项目，代码由 @tencent-weixin/openclaw-weixin 改造而来，仅供学习交流使用。

微信 AI Agent 桥接框架 —— 通过简单的 Agent 接口，将任意 AI 后端接入微信。

项目结构

packages/
  sdk/                  weixin-agent-sdk —— 微信桥接 SDK
  weixin-acp/           ACP (Agent Client Protocol) 适配器
  example-openai/       基于 OpenAI 的示例

通过 ACP 接入 Claude Code, Codex, kimi-cli 等 Agent

ACP (Agent Client Protocol) 是一个开放的 Agent 通信协议。如果你已有兼容 ACP 的 agent，可以直接通过 weixin-acp 接入微信，无需编写任何代码。

Claude Code

npx weixin-acp claude-code

Codex

npx weixin-acp codex

其它 ACP Agent

比如 kimi-cli：

npx weixin-acp start -- kimi acp

-- 后面的部分就是你的 ACP agent 启动命令，weixin-acp 会自动以子进程方式启动它，通过 JSON-RPC over stdio 进行通信。

更多 ACP 兼容 agent 请参考 ACP agent 列表。

自定义 Agent

SDK 主要导出三样东西：

• Agent 接口 —— 实现它就能接入微信
• login() —— 扫码登录
• start(agent) —— 启动消息循环，立即返回可主动发消息的 Bot

Agent 接口

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

interface ChatRequest {
  conversationId: string;         // 用户标识，可用于维护多轮对话
  text: string;                   // 文本内容
  media?: {                       // 附件（图片/语音/视频/文件）
    type: "image" | "audio" | "video" | "file";
    filePath: string;             // 本地文件路径（已下载解密）
    mimeType: string;
    fileName?: string;
  };
}

interface ChatResponse {
  text?: string;                  // 回复文本（支持 markdown，发送前自动转纯文本）
  media?: {                       // 回复媒体
    type: "image" | "video" | "file";
    url: string;                  // 本地路径或 HTTPS URL
    fileName?: string;
  };
}

最简示例

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

const echo: Agent = {
  async chat(req) {
    return { text: `你说了: ${req.text}` };
  },
};

await login();
const bot = start(echo);
await bot.wait();

完整示例（自己管理对话历史）

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(req.text);

    // 调用你的 AI 服务...
    const reply = await callMyAI(history);

    history.push(reply);
    conversations.set(req.conversationId, history);
    return { text: reply };
  },
};

await login();
const bot = start(myAgent);
await bot.wait();

主动发送消息

start() 会立即返回 Bot 实例。Bot 提供了 sendMessage()，可以在收到微信消息之外，主动给当前登录用户发送内容；如果是 CLI/脚本程序，可以用 bot.wait() 等待消息循环结束。

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

const agent: Agent = {
  async chat(req) {
    if (req.text === "ping") {
      return { text: "pong" };
    }
    return { text: `收到：${req.text}` };
  },
};

await login();
const bot = start(agent);

setInterval(() => {
  void bot.sendMessage("定时提醒：记得查看最新状态");
}, 60_000);

await bot.wait();

也可以主动发送完整的 ChatResponse，包括图片、视频或文件：

await bot.sendMessage({
  text: "这是最新报表",
  media: {
    type: "file",
    url: "./reports/daily.pdf",
    fileName: "daily.pdf",
  },
});

注意事项：

• 主动发送依赖微信下发的 context_token
• 需要在 start() 运行期间，至少先收到过当前账号的一条入站消息
• context_token 有时效，可能是 24 小时；过期后需要再次收到新消息才能继续主动发送

OpenAI 示例

packages/example-openai/ 是一个完整的 OpenAI Agent 实现，支持多轮对话和图片输入：

pnpm install

# 扫码登录微信
pnpm run login -w packages/example-openai

# 启动 bot
OPENAI_API_KEY=sk-xxx pnpm run start -w packages/example-openai

支持的环境变量：

支持的消息类型

接收（微信 → Agent）

发送（Agent → 微信）

内置斜杠命令

在微信中发送以下命令：

• /echo <消息> —— 直接回复（不经过 Agent），附带通道耗时统计
• /toggle-debug —— 开关 debug 模式，启用后每条回复追加全链路耗时

技术细节

• 使用 长轮询 (getUpdates) 接收消息，无需公网服务器
• 媒体文件通过微信 CDN 中转，AES-128-ECB 加密传输
• 单账号模式：每次 login 覆盖之前的账号
• 断点续传：get_updates_buf 持久化到 ~/.openclaw/，重启后从上次位置继续
• 会话过期自动重连（errcode -14 触发 1 小时冷却后恢复）
• Node.js >= 22

Star History