图像和媒体支持

WhatsApp 渠道运行在 Baileys Web 上。本页介绍发送、Gateway 网关和智能体回复中的媒体处理规则。

目标

openclaw message send --target <dest> --media <path-or-url> [--message <caption>]

--media <path-or-url> — 附加媒体（图片/音频/视频/文档）；接受本地路径或 URL。可选；纯媒体发送时说明文字可以为空。
--gif-playback — 将视频媒体作为 GIF 播放处理（仅 WhatsApp）。
--force-document — 将媒体作为文档发送，以避免渠道压缩（Telegram、WhatsApp）；适用于图片、GIF 和视频。
--reply-to <id>、--thread-id <id>、--pin、--silent — 与纯文本发送共享的投递/线程选项。
--dry-run — 打印解析后的载荷并跳过发送。
--json — 将结果打印为 JSON：{ action, channel, dryRun, handledBy, messageId?, payload }（payload 携带特定渠道的发送结果，包括任何媒体引用）。

输入：本地文件路径或 HTTP(S) URL。
流程：加载到缓冲区，检测媒体类型，然后按类型构建出站载荷：
- 图片： 优化到低于 channels.whatsapp.mediaMaxMb（默认 50MB）。不透明图片会重新压缩为 JPEG（默认边长阶梯从 2048px 开始，反复超出大小时逐级下降）；带透明度的图片保留为 PNG。如果源文件已经是可接受的 JPEG/PNG/WebP，并且处于大小和边长预算内，则会原样保留原始字节，而不是重新压缩。动态 GIF 永不重新编码，只检查大小。
- 音频/语音： 除非已经是原生语音音频（.ogg/.opus，或 audio/ogg/audio/opus），否则出站音频会通过 ffmpeg 转码为 Opus/OGG（48kHz 单声道，64kbps，最长 20 分钟），然后作为语音消息（ptt: true）发送。
- 视频： 最高 16MB 直传。
- 文档： 其他任何内容，最高 100MB；可用时保留文件名。
WhatsApp GIF 风格播放：发送带 gifPlayback: true 的 MP4（CLI：--gif-playback），让移动客户端以内联方式循环播放。
MIME 检测优先使用嗅探到的魔数字节，其次是文件扩展名，再其次是响应头；通用嗅探容器（application/octet-stream、zip）绝不会覆盖更具体的扩展名映射（例如 XLSX 与 ZIP）。
说明文字来自 --message 或 reply.text；允许空说明文字。
日志：非详细模式显示 ↩️/✅；详细模式包含大小和源路径/URL。

上面的 16MB 音频/视频和 100MB 文档数值，是未传入显式字节上限时使用的共享按类型媒体默认值。WhatsApp 发送会从 channels.whatsapp.mediaMaxMb（默认 50MB）设置显式上限，该上限会统一应用于该账号的所有类型。

getReplyFromConfig 返回一个回复载荷（或载荷数组），其中包含 text?、mediaUrl? 和 mediaUrls? 等字段。
存在媒体时，Web 发送器会使用与 openclaw message send 相同的流水线解析本地路径或 URL。
如果提供了多个媒体条目，会按顺序依次发送。

当入站 Web 消息包含媒体时，OpenClaw 会将其下载到临时文件，并暴露模板变量：
- {{MediaUrl}} — 入站媒体的伪 URL。
- {{MediaPath}} — 运行命令前写入的本地临时路径。
启用按会话 Docker 沙箱时，入站媒体会复制到沙箱工作区，并且 MediaPath/MediaUrl 会重写为类似 media/inbound/<filename> 的沙箱相对路径。
媒体理解（通过 tools.media.* 或共享的 tools.media.models 配置）会在模板渲染前运行，并且可以向 Body 插入 [Image]、[Audio] 和 [Video] 块。
- 音频会设置 {{Transcript}}，并使用转录文本进行命令解析，因此斜杠命令仍可正常工作。
- 视频和图片描述会保留任何说明文字，用于命令解析。
- 如果当前活动的主模型已经原生支持视觉，OpenClaw 会跳过 [Image] 摘要块，改为将原始图片传递给模型。
默认只处理第一个匹配的图片/音频/视频附件；设置 tools.media.<capability>.attachments 可处理多个附件。

出站发送上限（WhatsApp Web 发送）

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