图片与媒体支持 — 2025-12-05

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

目标

通过 openclaw message send --media 发送带可选说明文字的媒体。
支持网页收件箱的自动回复中包含媒体和文本。
各类型的大小限制保持合理、可预测。

CLI 接口

openclaw message send --media <path-or-url> [--message <caption>]
- --media 可选；说明文字可以为空，实现纯媒体发送。
- --dry-run 打印解析后的 payload；--json 输出 { channel, to, messageId, mediaUrl, caption }。

WhatsApp Web 频道行为

输入：本地文件路径或 HTTP(S) URL。
处理流程：加载到 Buffer，检测媒体类型，构建对应的 payload：
- 图片： 缩放并重压缩为 JPEG（最大边 2048px），目标大小为 agents.defaults.mediaMaxMb（默认 5 MB），上限 6 MB。
- 音频/语音/视频： 直接透传，上限 16 MB；音频以语音消息形式发送（ptt: true）。
- 文档： 其他类型，上限 100 MB，尽可能保留原始文件名。
WhatsApp GIF 效果：发送 MP4 时带上 gifPlayback: true（CLI: --gif-playback），手机客户端会循环播放。
MIME 类型检测优先级：魔术字节 > 响应头 > 文件扩展名。
说明文字来自 --message 或 reply.text；允许空说明文字。
日志：非 verbose 模式显示 ↩️/✅；verbose 模式包含大小和来源路径/URL。

自动回复流程

getReplyFromConfig 返回 { text?, mediaUrl?, mediaUrls? }。
当回复包含媒体时，网页发送器使用与 openclaw message send 相同的流程解析本地路径或 URL。
多个媒体条目按顺序依次发送。

入站媒体与命令（Pi）

收到的 Web 消息包含媒体时，OpenClaw 下载到临时文件并暴露模板变量：
- {{MediaUrl}}：入站媒体的伪 URL。
- {{MediaPath}}：运行命令前写入的本地临时路径。
启用按会话的 Docker 沙箱时，入站媒体会被复制到沙箱工作区，MediaPath/MediaUrl 被重写为类似 media/inbound/<filename> 的相对路径。
媒体理解（如果通过 tools.media.* 或共享 tools.media.models 配置）在模板替换前运行，可以在 Body 中插入 [Image]、[Audio] 和 [Video] 块。
- 音频会设置 {{Transcript}}，并使用转写文本进行命令解析，斜杠命令照常工作。
- 视频和图片描述会保留说明文字用于命令解析。
默认只处理第一个匹配的图片/音频/视频附件；设置 tools.media.<cap>.attachments 可处理多个附件。

限制与错误

出站发送上限（WhatsApp 网页发送）

图片：重压缩后约 6 MB 上限。
音频/语音/视频：16 MB 上限；文档：100 MB 上限。
超大或无法读取的媒体 → 日志中记录错误，跳过该回复。

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

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

测试须知

覆盖图片/音频/文档的发送和回复流程。
验证图片的重压缩（大小上限）和音频的语音消息标记。
确保多媒体回复按顺序逐条发送。

Media Understanding