图片与媒体文件支持（2025-12-05）

WhatsApp 频道通过 Baileys Web 运行。本文记录发送、网关及 agent 回复中的媒体处理规则。

目标

通过 openclaw message send --media 发送带可选标题的媒体文件。
允许 Web 收件箱的自动回复同时包含媒体和文字。
保持各类型文件大小限制合理可预测。

CLI 接口

openclaw message send --media <本地路径或URL> [--message <标题>]
- --media 可选；标题可为空（仅发媒体不带说明）。
- --dry-run 打印解析后的请求体；--json 输出 { channel, to, messageId, mediaUrl, caption }。

WhatsApp Web 频道行为

输入：本地文件路径或 HTTP(S) URL。
流程：加载为 Buffer → 检测媒体类型 → 构建对应的发送载荷：
- 图片： 压缩并转换为 JPEG（最长边 2048px），目标大小不超过 channels.whatsapp.mediaMaxMb（默认 50 MB）。
- 音频/语音/视频： 直传，上限 16 MB；音频以语音消息形式发送（ptt: true）。
- 文档： 其他类型，最大 100 MB，文件名保留。
WhatsApp GIF 循环播放：发送 MP4 时加 gifPlayback: true（CLI：--gif-playback），移动端自动内联循环。
MIME 检测优先顺序：魔数 → 响应头 → 文件扩展名。
标题来源：--message 或 reply.text；空标题合法。
日志：非详细模式显示 ↩️/✅；详细模式包含文件大小和来源路径/URL。

自动回复流程

getReplyFromConfig 返回 { text?, mediaUrl?, mediaUrls? }。
有媒体时，Web 发送器使用与 openclaw message send 相同的流程解析本地路径或 URL。
多条媒体按顺序逐条发送。

入站媒体传给命令（Pi）

当入站 Web 消息包含媒体时，OpenClaw 将其下载到临时文件，并暴露模板变量：
- ：入站媒体的伪 URL。
- ：运行命令前写入的本地临时路径。
启用了每会话 Docker 沙箱时，入站媒体会被复制到沙箱工作空间，MediaPath/MediaUrl 被重写为相对路径，如 media/inbound/<filename>。
若通过 tools.media.* 或共享的 tools.media.models 配置了媒体理解，会在模板化之前运行，可将 [Image]、[Audio]、[Video] 块插入 Body。
- 音频会设置，转录内容用于命令解析，斜杠命令仍可正常工作。
- 视频和图片描述会保留标题文字以供命令解析。
默认只处理第一个匹配的图片/音频/视频附件；设置 tools.media.<cap>.attachments 可处理多个。

大小限制与错误

发送上限（WhatsApp Web 发送）

图片：压缩后不超过 channels.whatsapp.mediaMaxMb（默认 50 MB）。
音频/语音/视频：16 MB；文档：100 MB。
文件过大或不可读 → 日志中给出明确错误，跳过该回复。

媒体理解上限（转录/描述）

图片默认：10 MB（tools.media.image.maxBytes）。
音频默认：20 MB（tools.media.audio.maxBytes）。
视频默认：50 MB（tools.media.video.maxBytes）。
超大媒体跳过理解，但回复仍使用原始 body 正常发送。

测试要点

覆盖图片/音频/文档的发送和回复流程。
验证图片重压缩（大小限制）和音频语音消息标志。
确认多媒体回复以顺序方式逐条发出。