weixin-agent-sdk

随着微信正式支持 OpenClaw 插件生态，开发者社区迅速迎来了新的创新浪潮。近期，一个名为 weixin-agent-sdk 的开源项目引发关注。该项目并非微信官方出品，而是由社区开发者基于微信官方 OpenClaw 插件 @tencent-weixin/openclaw-weixin 深度改造而来，旨在打造一个通用的 微信 AI Agent 桥接框架。

它的核心价值在于：通过统一的 Agent 接口，将任意 AI 后端（如 Claude Code, Codex, Kimi-cli, OpenAI 等）无缝接入微信，让微信瞬间变身为强大的 AI 智能体交互终端。

项目定位：通用桥接层

weixin-agent-sdk 本质上是一个位于 微信 与 AI Agent 之间的桥接层（Bridge）。

• 向下兼容微信：复用 OpenClaw 插件的通信能力，处理消息收发、媒体解密与会话管理。
• 向上统一接口：定义标准的 Agent 接口，或通过 ACP (Agent Client Protocol) 协议与各类智能体通信。

无论你的 AI 后端是本地运行的 CLI 工具，还是云端的 API 服务，只要适配该框架，即可在微信中实现多轮对话、文件传输、图片识别等复杂交互。

⚠️ 免责声明：本项目为第三方开源作品，仅供学习与交流使用，非微信官方产品。

核心玩法：两种接入模式

模式一：零代码接入 ACP 兼容 Agent

如果你使用的 AI 工具已经兼容 ACP (Agent Client Protocol) 标准，那么接入微信无需编写任何代码。weixin-acp 命令行工具会自动作为子进程启动 Agent，并通过 JSON-RPC over stdio 进行通信。

支持的主流 Agent：

• Claude Code (Zed Industries)
• Codex
• kimi-cli
• 以及其他任何兼容 ACP 协议的智能体。

快速启动示例：

1. 扫码登录微信

   npx weixin-acp login
   

2. 启动 Claude Code 机器人

   # 安装适配器
   npm install -g @zed-industries/claude-agent-acp
   
   # 启动桥接
   npx weixin-acp start -- claude-agent-acp
   

3. 启动 Kimi 机器人

   npx weixin-acp start -- kimi acp
   

-- 后面的部分即为任意 ACP Agent 的启动命令，框架会自动接管其输入输出并转发至微信。

模式二：自定义开发 Agent

对于需要深度定制逻辑的场景，SDK 提供了极简的 TypeScript 接口。开发者只需实现 chat 方法，即可构建专属的微信机器人。

核心接口定义：

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

interface ChatRequest {
  conversationId: string;         // 会话 ID，用于维护多轮对话上下文
  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;
  };
}

最简实现示例（Echo Bot）：

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

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

await login();
await start(echoAgent);

完整示例（带上下文记忆）：
开发者可自行管理 conversationId 对应的历史记录，实现真正的多轮对话智能体。

强大的多媒体处理能力

weixin-agent-sdk 不仅支持文本，还全面覆盖了微信的多媒体消息类型，并自动处理复杂的加解密与格式转换：

技术架构亮点

该项目在技术实现上充分考虑了部署的便捷性与稳定性：

1. 无需公网服务器：采用 长轮询 (Long Polling / getUpdates) 机制接收消息，本地运行即可，无需暴露公网 IP 或配置反向代理。
2. 安全传输：媒体文件通过微信 CDN 中转，采用 AES-128-ECB 加密传输，确保数据链路安全。
3. 断点续传：get_updates_buf 持久化存储于 ~/.openclaw/ 目录，重启后可从上次位置继续拉取消息，避免消息丢失。
4. 自动重连机制：检测到会话过期（errcode -14）时，自动触发 1 小时冷却后恢复连接，提升鲁棒性。
5. 单账号模式：每次 login 操作会覆盖之前的账号会话，适合单设备单账号场景。

内置调试工具

为了方便开发与测试，SDK 内置了实用的斜杠命令：

• /echo <消息>：直接回复消息，不经过 Agent 逻辑，附带通道耗时统计，用于测试网络延迟。
• /toggle-debug：开关 Debug 模式。启用后，每条机器人回复末尾将追加全链路耗时信息，便于性能调优。

快速开始指南

环境要求：Node.js >= 22

步骤 1：克隆与安装

git clone <项目地址>
cd weixin-agent-sdk
pnpm install

步骤 2：运行 OpenAI 示例

项目内置了完整的 OpenAI Agent 示例 (packages/example-openai)，支持多轮对话与图片输入。

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

# 启动机器人 (需配置环境变量)
OPENAI_API_KEY=sk-xxx pnpm run start -w packages/example-openai

支持的环境变量配置：

• OPENAI_API_KEY (必填): 你的 API Key。
• OPENAI_BASE_URL: 自定义 API 地址，兼容各类第三方中转服务。
• OPENAI_MODEL: 指定模型，默认 gpt-5.4。
• SYSTEM_PROMPT: 设定系统提示词，定制机器人人格。