图像和媒体支持 — 2025-12-05

WhatsApp 频道通过 Baileys Web 运行。本文档捕获了发送、网关和代理回复的当前媒体处理规则。

目标

  • 通过 openclaw message send --media 发送带有可选标题的媒体。
  • 允许来自 web 收件箱的自动回复包括媒体和文本。
  • 保持每种类型的限制合理和可预测。

CLI 界面

  • openclaw message send --media <path-or-url> [--message <caption>]
    • --media 可选；标题可以为空以发送仅媒体。
    • --dry-run 打印解析的负载；--json 发出 { channel, to, messageId, mediaUrl, caption }。

WhatsApp Web 频道行为

  • 输入：本地文件路径或 HTTP(S) URL。
  • 流程：加载到 Buffer，检测媒体类型，并构建正确的负载：
    • 图像： 调整大小并重新压缩为 JPEG（最大边 2048px）目标为 agents.defaults.mediaMaxMb（默认 5 MB），上限为 6 MB。
    • 音频/语音/视频： 直通最多 16 MB；音频作为语音笔记发送（ptt: true）。
    • 文档： 其他任何东西，最多 100 MB，在可用时保留文件名。
  • WhatsApp GIF 风格播放：使用 gifPlayback: true（CLI：--gif-playback）发送 MP4，以便移动客户端内联循环。
  • MIME 检测优先使用魔术字节，然后是头，然后是文件扩展名。
  • 标题来自 --message 或 reply.text；允许空标题。
  • 日志记录：非详细显示 ↩️/✅；详细包括大小和源路径/URL。

自动回复管道

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

入站媒体到命令（Pi）

  • 当入站 web 消息包括媒体时，OpenClaw 下载到临时文件并暴露模板变量：
    • {{MediaUrl}} 入站媒体的伪 URL。
    • {{MediaPath}} 在运行命令之前写入的本地临时路径。
  • 当启用每会话 Docker 沙箱时，入站媒体被复制到沙箱工作区，MediaPath/MediaUrl 被重写为相对路径，如 media/inbound/<filename>。
  • 媒体理解（如果通过 tools.media.* 或共享 tools.media.models 配置）在模板化之前运行，可以将 [Image]、[Audio] 和 [Video] 块插入到 Body 中。
    • 音频设置 {{Transcript}} 并使用转录用于命令解析，以便斜杠命令仍然工作。
    • 视频和图像描述保留任何标题文本用于命令解析。
  • 默认情况下，只处理第一个匹配的图像/音频/视频附件；设置 tools.media.<cap>.attachments 以处理多个附件。

限制和错误

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

  • 图像：重新压缩后约 6 MB 上限。
  • 音频/语音/视频：16 MB 上限；文档：100 MB 上限。
  • 超大或不可读的媒体 → 在日志中清楚的错误，并且跳过回复。

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

  • 图像默认：10 MB（tools.media.image.maxBytes）。
  • 音频默认：20 MB（tools.media.audio.maxBytes）。
  • 视频默认：50 MB（tools.media.video.maxBytes）。
  • 超大媒体跳过理解，但回复仍然使用原始正文进行。

测试注意事项

  • 覆盖图像/音频/文档情况的发送 + 回复流程。
  • 验证图像的重新压缩（大小限制）和音频的语音笔记标志。
  • 确保多媒体回复作为顺序发送扇出。
← 返回文档首页