Image & Media Support — 2025-12-05

WhatsApp channel 通过 Baileys Web 运行。本文档记录了当前在 send、gateway 和 agent replies 中的媒体处理规则。

目标

openclaw message send --media <path-or-url> [--message <caption>]
- --media 是可选的；对于仅发送媒体的场景，caption 可以为空。
- --dry-run 会打印解析后的 payload；--json 会输出 { channel, to, messageId, mediaUrl, caption }。

输入：本地文件路径或 HTTP(S) URL。
流程：先加载为 Buffer，识别媒体类型，然后构造正确的 payload：
- Images：调整尺寸并重新压缩为 JPEG（最长边 2048px），目标大小为 agents.defaults.mediaMaxMb（默认 5 MB），上限为 6 MB。
- Audio/Voice/Video：直接透传，大小上限 16 MB；audio 会以 voice note 形式发送（ptt: true）。
- Documents：其他所有类型，大小上限 100 MB，并在可用时保留原始文件名。
WhatsApp 的 GIF 风格播放：发送带 gifPlayback: true 的 MP4（CLI 参数：--gif-playback），这样移动端客户端会以内联循环方式播放。
MIME 检测优先顺序：magic bytes，其次 headers，最后 file extension。
Caption 来自 --message 或 reply.text；允许为空 caption。
日志：非 verbose 模式显示 ↩️ / ✅；verbose 模式会额外包含大小及来源路径/URL。

当入站 web 消息包含媒体时，OpenClaw 会下载到临时文件，并暴露以下模板变量：
- {{MediaUrl}}：指向该入站媒体的 pseudo-URL。
- {{MediaPath}}：在运行命令前写入的本地临时路径。
当启用了按 session 隔离的 Docker sandbox 时，入站媒体会被复制到 sandbox workspace 中，且 MediaPath / MediaUrl 会被重写为类似 media/inbound/<filename> 的相对路径。
Media understanding（如果通过 tools.media.* 或共享的 tools.media.models 进行了配置）会在模板渲染前运行，并可向 Body 中插入 [Image]、[Audio] 和 [Video] block。
- Audio 会设置 {{Transcript}}，并在命令解析中使用 transcript，这样 slash commands 仍然可用。
- Video 和 image 的描述会保留任何 caption text，以便命令解析使用。
默认情况下，只处理第一个匹配的 image/audio/video 附件；如需处理多个附件，可设置 tools.media.<cap>.attachments。

出站发送上限（WhatsApp web send）

Media understanding 上限（转录/描述）