本项目非微信官方项目，代码由 @tencent-weixin/openclaw-weixin 改造而来，仅供学习交流使用。
微信 AI Agent 桥接框架 —— 通过简单的 Agent 接口，将任意 AI 后端接入微信。
packages/ sdk/ weixin-agent-sdk —— 微信桥接 SDK weixin-acp/ ACP (Agent Client Protocol) 适配器 example-openai/ 基于 OpenAI 的示例 ACP (Agent Client Protocol) 是一个开放的 Agent 通信协议。如果你已有兼容 ACP 的 agent，可以直接通过 weixin-acp 接入微信，无需编写任何代码。
npx weixin-acp claude-codenpx weixin-acp codex比如 kimi-cli：
npx weixin-acp start -- kimi acp-- 后面的部分就是你的 ACP agent 启动命令，weixin-acp 会自动以子进程方式启动它，通过 JSON-RPC over stdio 进行通信。
更多 ACP 兼容 agent 请参考 ACP agent 列表。
SDK 只导出三样东西：
Agent接口 —— 实现它就能接入微信login()—— 扫码登录start(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(); await start(echo);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(); await start(myAgent);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支持的环境变量：
| 变量 | 必填 | 说明 |
|---|---|---|
OPENAI_API_KEY | 是 | OpenAI API Key |
OPENAI_BASE_URL | 否 | 自定义 API 地址（兼容 OpenAI 接口的第三方服务） |
OPENAI_MODEL | 否 | 模型名称，默认 gpt-5.4 |
SYSTEM_PROMPT | 否 | 系统提示词 |
| 类型 | media.type | 说明 |
|---|---|---|
| 文本 | — | request.text 直接拿到文字 |
| 图片 | image | 自动从 CDN 下载解密，filePath 指向本地文件 |
| 语音 | audio | SILK 格式自动转 WAV（需安装 silk-wasm） |
| 视频 | video | 自动下载解密 |
| 文件 | file | 自动下载解密，保留原始文件名 |
| 引用消息 | — | 被引用的文本拼入 request.text，被引用的媒体作为 media 传入 |
| 语音转文字 | — | 微信侧转写的文字直接作为 request.text |
| 类型 | 用法 |
|---|---|
| 文本 | 返回 { text: "..." } |
| 图片 | 返回 { media: { type: "image", url: "/path/to/img.png" } } |
| 视频 | 返回 { media: { type: "video", url: "/path/to/video.mp4" } } |
| 文件 | 返回 { media: { type: "file", url: "/path/to/doc.pdf" } } |
| 文本 + 媒体 | text 和 media 同时返回，文本作为附带说明发送 |
| 远程图片 | url 填 HTTPS 链接，SDK 自动下载后上传到微信 CDN |
在微信中发送以下命令：
/echo <消息>—— 直接回复（不经过 Agent），附带通道耗时统计/toggle-debug—— 开关 debug 模式，启用后每条回复追加全链路耗时
- 使用 长轮询 (
getUpdates) 接收消息，无需公网服务器 - 媒体文件通过微信 CDN 中转，AES-128-ECB 加密传输
- 单账号模式：每次
login覆盖之前的账号 - 断点续传：
get_updates_buf持久化到~/.openclaw/，重启后从上次位置继续 - 会话过期自动重连（errcode -14 触发 1 小时冷却后恢复）
- Node.js >= 22