wecom-app 运维/使用规范（本地技能）

本技能针对你这套 OpenClaw + 企业微信自建应用（wecom-app）环境，提供可复用的“怎么做”步骤。

0) 快速判断：你要做哪一类事？

• A. 回发媒体（图片/录音/文件）：需要拿到本地路径 + 正确的 target（通常 user:<name>）
• B. 从消息里拿 saved: 路径做 OCR/二次处理：使用 saved:/.../inbound/YYYY-MM-DD/... 的稳定路径
• C. 修复“找不到图片/自动删除”：检查 wecom-app 的 inboundMedia.keepDays/dir/maxBytes
• D. 语音发不出去：优先 .amr/.speex，或开启 voiceTranscode.enabled

---

1) target 与 replyTo（最容易踩坑）

1.1 target 是什么

使用 message.send 向 wecom-app 主动发消息时，必须提供可解析 target（否则会报 Action send requires a target.）。

常见可用形式（以本环境为准）：

• target: "wecom-app:user:<userId>"
• target: "user:<userId>"
• target: "<userId>"（裸 ID，插件会按用户 ID 处理）
• target: "user:<userId>@<accountId>"（多账号场景）

注意：当前 wecom-app 出站实现以用户私聊为主，运维侧不要依赖 chatid:<id> 作为通用 target 格式。

1.2 replyTo 怎么用

• 如果你要“回复当前对话”，优先使用消息的 message_id 作为 replyTo。
• replyTo 不是 target；target 仍然要填。

1.3 Unknown target 怎么办（排查步骤）

• 显示名（比如 CaiHongYu）不一定能被解析。
• 优先尝试：target: "user:CaiHongYu"

若仍报 Unknown target：

1. 先确认是 私聊 还是 群聊：

• 私聊：使用 user:<userId>（推荐）
• 群聊：本技能默认不走该路径（请先确认插件是否已实现对应目标解析）

2. 让对方（或你自己）在企业微信里再发一条消息（任意内容），以便系统记录真实标识。
3. 从以下任意来源抓取真实的 userId/chatId：
   • OpenClaw / wecom-app 插件日志（~/.openclaw/logs/）
   • 或把“收到消息时的原始字段/报错日志”贴出来，我来反推。
4. 拿到真实值后再发：

• target: "user:<userId>"（或 wecom-app:user:<userId>）

---

2) 媒体文件在哪里？（图片/录音/文件）

2.1 入站媒体（推荐稳定路径）

wecom-app 现在会把入站媒体归档到：

• inboundMedia.dir/YYYY-MM-DD/
• 默认（跨平台）：~/.openclaw/media/wecom-app/inbound/YYYY-MM-DD/

消息正文会出现：

• [image] saved:/.../inbound/YYYY-MM-DD/img_...jpg
• [voice] saved:/.../inbound/YYYY-MM-DD/voice_...amr

这条 saved 路径用于：OCR、回发、复用。

2.2 临时目录（不建议依赖）

• /tmp/wecom-app-media/ 只作为下载中转，不保证长期存在。
• Windows 也同理：临时目录仅中转，不作为业务引用路径。

---

3) 回发图片/文件/录音（标准做法）

3.1 回发图片（注意：必须是真图片格式）

使用 message 工具：

• channel: "wecom-app"
• target: "user:<name>"
• path: "<本地文件路径>"
• replyTo: "<message_id>"（可选但推荐）