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

WhatsApp Channel 通过 Baileys Web 运行。本文档记录了当前发送、Gateway 和 Agent 回复的媒体处理规则。

目标

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

CLI 命令

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

WhatsApp Web Channel 行为

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

自动回复管道

  • getReplyFromConfig 返回 { text?, mediaUrl?, mediaUrls? }。
  • 当存在媒体时，网页发送器使用与 openclaw message send 相同的管道解析本地路径或 URL。
  • 如果提供了多个媒体条目，会按顺序依次发送。

入站媒体到命令（Pi）

  • 当入站网页消息包含媒体时，OpenClaw 会下载到临时文件并暴露模板变量：
    • {{MediaUrl}} 入站媒体的伪 URL。
    • {{MediaPath}} 运行命令前写入的本地临时路径。
  • 当启用了 per-session Docker Sandbox 时，入站媒体会被复制到 Sandbox Workspace，MediaPath/MediaUrl 会被重写为相对路径，如 media/inbound/<filename>。
  • 媒体理解功能（如果通过 tools.media.* 或共享的 tools.media.models 配置）会在模板化之前运行，可以在 Body 中插入 [Image]、[Audio] 和 [Video] 块。
    • 音频会设置 {{Transcript}} 并使用转录文本进行命令解析，这样斜杠命令仍然有效。
    • 视频和图片描述会保留任何说明文字用于命令解析。
  • 默认只处理第一个匹配的图片/音频/视频附件；设置 tools.media.<cap>.attachments 可处理多个附件。

限制与错误

出站发送上限（WhatsApp web send）

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

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

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

测试注意事项

  • 覆盖图片/音频/文档的发送 + 回复流程。
  • 验证图片的重新压缩（大小限制）和音频的语音消息标志。
  • 确保多媒体回复按顺序依次发送。