ClawCN - OpenClaw 中文版

主题

图片与媒体支持 — 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 的 MP4(CLI:--gif-playback),以便移动客户端内联循环播放。
  • 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)。
  • 超大媒体跳过理解,但回复仍使用原始正文进行。

测试注意事项 ​

  • 覆盖图片/音频/文档情况的发送 + 回复流程。
  • 验证图片的重新压缩(大小限制)和音频的语音笔记标志。
  • 确保多媒体回复按顺序发出。