weixin-agent-sdk 是一个 TypeScript 框架，用于将任意 AI 后端桥接到微信，通过 Clawbot 通道工作。它使用长轮询接收消息，因此无需公网服务器，并暴露一个极简的 Agent 接口，便于快速接入 OpenAI、Claude 或任何自定义逻辑。
用途 该框架的用途是作为微信与 AI 智能体之间的桥梁：在微信侧接收用户消息，交给开发者实现的 Agent 处理，再把结果发回微信。
主要能力
- 长轮询接收消息，无需公网服务器。
- 极简 Agent 接口，可插入 OpenAI、Claude 或自定义逻辑。
- 支持入站消息类型：文本、图片、语音、视频、文件；语音 SILK 自动转 WAV（需 silk-wasm）；引用消息的文本会附加到 request.text，引用媒体作为 media；微信语音转文字作为 request.text 传递。
- 支持出站消息类型：文本、图片、视频、文件，以及文本加媒体组合；远程图片可设为 HTTPS 链接，SDK 自动下载并上传到微信 CDN。
- 自动在会话过期时重连。
- 内置聊天命令：/echo 直接回显并显示通道延迟；/toggle-debug 切换调试模式，在每条回复后附加完整延迟统计。
使用方式 安装：npm install weixin-agent-sdk 或 pnpm add weixin-agent-sdk。要求 Node.js >= 22。
登录：调用 login()，触发二维码扫描并把会话持久化到 ~/.openclaw/，只需运行一次。
实现 Agent 接口： interface Agent { chat(request: ChatRequest): Promise<ChatResponse>; } ChatRequest 包含 conversationId（用户/会话唯一标识）、text（消息文本）、media（可选，含 type、filePath、mimeType、fileName）。ChatResponse 可返回 text（支持 Markdown，会自动转纯文本）和 media（含 type、url、fileName）。
启动：调用 start(agent)，启动消息循环，阻塞直到进程退出，并在会话过期时自动重连。
多轮对话可通过 Map 按 conversationId 保存历史。OpenAI 示例中读取 req.media 图片并转为 base64 传入模型。
如果已有 ACP（Agent Client Protocol）兼容的智能体（如 Claude Code、Codex、kimi-cli 等），可使用 weixin-acp 包，无需写代码： npx weixin-acp claude-code npx weixin-acp codex npx weixin-acp start -- kimi acp weixin-acp 会把智能体作为子进程启动，并通过 stdio 上的 JSON-RPC 通信。
OpenAI 示例使用的环境变量：OPENAI_API_KEY（必填）、OPENAI_BASE_URL（可选，自定义 API 地址）、OPENAI_MODEL（可选，默认 gpt-5.4）、SYSTEM_PROMPT（可选）。
Monorepo / pnpm 设置：克隆仓库后 pnpm install，运行 pnpm run login -w packages/example-openai 扫码登录，再用 OPENAI_API_KEY 运行 pnpm run start -w packages/example-openai。
适用场景 适合需要将 AI 智能体接入微信、且不便部署公网服务器的开发者；适合已有 ACP 兼容智能体并希望快速接入微信的场景；也适合需要处理微信侧文本、图片、语音、视频、文件等多模态消息的应用。
限制与注意事项
- 需要 Node.js >= 22。
- 语音 SILK 转 WAV 需安装可选依赖 silk-wasm，否则无法转换。
- 远程媒体 URL 需要使用 HTTPS 且可公开访问。
- 会话过期（errcode -14）时 SDK 自动进入 1 小时冷却后重连，无需手动干预。
- 重启后通过 ~/.openclaw/get_updates_buf 中的状态自动从上次位置恢复。
- login() 二维码不显示时，需确认终端支持渲染二维码，或检查 ~/.openclaw/ 中的原始二维码数据。
- 关于收费、价格、平台覆盖等更多信息，资料中暂未提供。
分类说明 该产品用于把 AI 智能体接入微信，属于智能体与模型相关工具，故分类为 agents。