图像和媒体支持

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

关于 Control UI 和原生应用中的内联音频与视频，包括便携格式、字节限制和惰性转码，请参阅媒体播放。

目标¶

• 通过 openclaw message send --media 发送媒体，并附带可选说明文字。
• 允许 Web 收件箱的自动回复在文本之外包含媒体。
• 保持各类型的限制合理且可预测。

CLI 命令集¶

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

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

消息工具附件元数据¶

对于 buffer 附件，contentType 优先于 mimeType；只有在两者都未提供时，才会使用 data URL 的 MIME 类型。对于 reply、sendAttachment、upload-file 和 setGroupIcon，顶层 MIME 元数据也优先于选定的 attachments[] 条目。水合过程会将该选择作为 contentType 传递，并据此推断缺失的文件名。显式提供的文件名会被保留。当媒体字节被加载或暂存时，此元数据优先级不会改变 MIME 检测。

WhatsApp Web 通道行为¶

• 输入：本地文件路径或 HTTP(S) URL。
• 流程：加载到缓冲区，检测媒体类型，然后按类型构建出站 payload：
• 图片： 优化至 channels.whatsapp.mediaMaxMb（默认 50MB）限额以内。不透明图片会重新压缩为 JPEG（默认边长阶梯从 2048px 开始，若尺寸仍超限则逐级下降）；带透明度的图片保留为 PNG。如果源文件已经是符合大小和边长预算的可接受 JPEG/PNG/WebP，则保留原始字节不变，而不重新压缩；即使转换后仍残留过时的 .heic 或 .heif 文件名也是如此。GIF 和动画 WebP 图片保留原始字节；超过字节上限或显式模型尺寸限制的图片会被拒绝，而不会被压平为单帧。
• 音频/语音： 除非已经是原生语音音频（.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。

自动回复流水线¶

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

生成的附件与后续的工具错误警告保持分离。错误或推理中的图片引用不会选择或丢弃已生成的附件。

当通道将 Markdown 图片链接转换为附件时，位于代码块或行内代码中的图片语法，以及转义后的图片语法，仍会保留在文本中。行内图片目标保留其 URL 中的标点。

入站媒体到命令¶

• 当入站 Web 消息包含媒体时，OpenClaw 会将其下载到临时文件，并暴露以下模板变量：
• {{AttachmentUrl}} — 当前附件的原始 URL 或提供方引用。
• {{AttachmentPath}} — 运行命令前写入的本地临时路径。
• {{AttachmentContentType}} — MIME 内容类型。
• {{AttachmentDir}} — 包含该本地路径的目录。
• {{AttachmentIndex}} — 从零开始的源事实索引。
• 当启用每会话 Docker 沙箱时，入站媒体会被复制到沙箱工作区，附件路径/引用会被重写为沙箱相对路径，例如 media/inbound/<filename>。
• {{MediaPath}}、{{MediaUrl}}、{{MediaType}} 和 {{MediaDir}} 仍是已弃用的兼容性别名，对应 2026.8.1 中取代它们的 {{Attachment*}} 名称。它们获批的 removeAfter 日期为 2026-10-01，前提是通过一次干净的已发布插件制品扫描；请在此之前迁移。参见媒体旧版投影。
• 媒体理解（通过 tools.media.* 或共享的 tools.media.models 配置）在模板解析之前运行，并可将 [Image]、[Audio] 和 [Video] 块插入 Body 中。
• 音频会设置 {{Transcript}}，并使用转写文本来解析命令，因此斜杠命令仍然有效。
• 视频和图片描述会保留任何说明文字，以供命令解析使用。
• 原生视觉模型可以跳过 [Image] 摘要块。相关规则及其 MiniMax 例外请参阅规则与行为。
• 默认情况下，仅处理第一个匹配的图片/音频/视频附件；可使用 tools.media.<capability>.attachments 选择多个附件。

限制与错误¶

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

• 图片：优化后最大为 channels.whatsapp.mediaMaxMb（默认 50MB）。
• 音频/视频：16MB 上限（共享默认值；通过 WhatsApp 发送时由 mediaMaxMb 覆盖）。
• 文档：100MB 上限（共享默认值；通过 WhatsApp 发送时由 mediaMaxMb 覆盖）。
• 超大或不可读的媒体会在日志中产生明确错误，并跳过该回复。大小错误使用可读的字节单位，而不是将小数上限四舍五入到整数 MB。

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

• 图片默认：10MB（使用 tools.media.image.maxBytes 覆盖，或按 tools.media.models[] 条目使用 maxBytes 覆盖）。
• 音频默认：20MB（使用 tools.media.audio.maxBytes 覆盖，或按条目覆盖）。
• 视频默认：50MB（使用 tools.media.video.maxBytes 覆盖，或按条目覆盖）。
• 超大媒体会跳过理解，但回复仍会携带原始正文发送。

图片描述会在调整大小前检查源字节上限。识别出的图片随后会针对所选模型声明的图片限制进行准备；每个回退都从同一规范化原始图片开始。未声明图片限制的模型保留这些规范化字节。agents.defaults.imageQuality 仍是图像工具设置，不会改变媒体理解准备。

测试注意事项¶

• 覆盖图片/音频/文档场景的发送和回复流程。
• 验证图片优化后的大小边界以及音频的语音留言标志。
• 确保多媒体回复以顺序发送的方式展开。

相关¶

• 相机拍摄
• 媒体理解
• 媒体播放
• 音频和语音留言