การรองรับรูปภาพและสื่อ

ช่องทาง WhatsApp ทำงานผ่าน Baileys Web เอกสารนี้บันทึกกฎการจัดการสื่อปัจจุบันสำหรับการส่ง, Gateway, และการตอบกลับของเอเจนต์

# เป้าหมาย

• ส่งสื่อพร้อมคำบรรยายที่เป็นทางเลือกผ่าน 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

• อินพุต: พาธไฟล์ในเครื่อง หรือ URL HTTP(S)
• โฟลว์: โหลดเข้า Buffer, ตรวจหาชนิดสื่อ, แล้วสร้างเพย์โหลดที่ถูกต้อง:
  • รูปภาพ: ปรับขนาดและบีบอัดใหม่เป็น JPEG (ด้านยาวสุด 2048px) โดยตั้งเป้าตาม channels.whatsapp.mediaMaxMb (ค่าเริ่มต้น: 50 MB)
  • เสียง/เสียงพูด/วิดีโอ: ส่งผ่านได้สูงสุด 16 MB; เสียงจะถูกส่งเป็นบันทึกเสียง (ptt: true)
  • เอกสาร: อย่างอื่นทั้งหมด สูงสุด 100 MB โดยคงชื่อไฟล์ไว้เมื่อมี
• การเล่นแบบ GIF ของ WhatsApp: ส่ง MP4 พร้อม gifPlayback: true (CLI: --gif-playback) เพื่อให้ไคลเอนต์มือถือเล่นวนแบบฝังในบรรทัด
• การตรวจจับ MIME จะให้ความสำคัญกับ magic bytes ก่อน ตามด้วย headers แล้วจึงเป็นนามสกุลไฟล์
• คำบรรยายมาจาก --message หรือ reply.text; อนุญาตให้คำบรรยายว่างได้
• การบันทึกล็อก: โหมดไม่ละเอียดแสดง ↩️/✅; โหมดละเอียดรวมขนาดและพาธ/URL ต้นทาง

# ไปป์ไลน์การตอบกลับอัตโนมัติ

• getReplyFromConfig คืนค่า { text?, mediaUrl?, mediaUrls? }
• เมื่อมีสื่อ ตัวส่งผ่านเว็บจะแก้ไขพาธในเครื่องหรือ URL โดยใช้ไปป์ไลน์เดียวกับ openclaw message send
• หากมีสื่อหลายรายการ จะส่งเรียงตามลำดับ

# สื่อขาเข้าไปยังคำสั่ง (Pi)

• เมื่อข้อความเว็บขาเข้ามีสื่อ OpenClaw จะดาวน์โหลดไปยังไฟล์ชั่วคราวและเปิดเผยตัวแปรเทมเพลต:
  • {{MediaUrl}} pseudo-URL สำหรับสื่อขาเข้า
  • {{MediaPath}} พาธชั่วคราวในเครื่องที่เขียนก่อนเรียกใช้คำสั่ง
• เมื่อเปิดใช้งานแซนด์บ็อกซ์ Docker ต่อเซสชัน สื่อขาเข้าจะถูกคัดลอกไปยังเวิร์กสเปซของแซนด์บ็อกซ์ และ MediaPath/MediaUrl จะถูกเขียนใหม่เป็นพาธสัมพัทธ์ เช่น media/inbound/<filename>
• ความเข้าใจสื่อ (หากกำหนดค่าผ่าน tools.media.* หรือ tools.media.models ที่ใช้ร่วมกัน) จะทำงานก่อนการทำเทมเพลต และสามารถแทรกบล็อก [Image], [Audio], และ [Video] ลงใน Body
  • เสียงตั้งค่า {{Transcript}} และใช้ transcript สำหรับการแยกวิเคราะห์คำสั่ง เพื่อให้คำสั่ง slash ยังทำงานได้
  • คำอธิบายวิดีโอและรูปภาพจะคงข้อความคำบรรยายไว้สำหรับการแยกวิเคราะห์คำสั่ง
  • หากโมเดลรูปภาพหลักที่ใช้งานอยู่รองรับวิชันโดยตรงอยู่แล้ว OpenClaw จะข้ามบล็อกสรุป [Image] และส่งรูปภาพต้นฉบับไปยังโมเดลแทน
• โดยค่าเริ่มต้น จะประมวลผลเฉพาะไฟล์แนบรูปภาพ/เสียง/วิดีโอรายการแรกที่ตรงกัน; ตั้งค่า tools.media.<cap>.attachments เพื่อประมวลผลไฟล์แนบหลายรายการ

# ขีดจำกัดและข้อผิดพลาด

ขีดจำกัดการส่งออก (การส่งผ่าน WhatsApp web)

• รูปภาพ: สูงสุด channels.whatsapp.mediaMaxMb (ค่าเริ่มต้น: 50 MB) หลังการบีบอัดใหม่
• เสียง/เสียงพูด/วิดีโอ: ขีดจำกัด 16 MB; เอกสาร: ขีดจำกัด 100 MB
• สื่อที่ใหญ่เกินหรืออ่านไม่ได้ → ข้อผิดพลาดที่ชัดเจนในล็อก และจะข้ามการตอบกลับ

ขีดจำกัดความเข้าใจสื่อ (การถอดเสียง/คำอธิบาย)

• ค่าเริ่มต้นของรูปภาพ: 10 MB (tools.media.image.maxBytes)
• ค่าเริ่มต้นของเสียง: 20 MB (tools.media.audio.maxBytes)
• ค่าเริ่มต้นของวิดีโอ: 50 MB (tools.media.video.maxBytes)
• สื่อที่ใหญ่เกินจะข้ามความเข้าใจสื่อ แต่การตอบกลับยังคงดำเนินต่อด้วยเนื้อหาต้นฉบับ

# หมายเหตุสำหรับการทดสอบ

• ครอบคลุมโฟลว์การส่งและการตอบกลับสำหรับกรณีรูปภาพ/เสียง/เอกสาร
• ตรวจสอบการบีบอัดใหม่สำหรับรูปภาพ (ขอบเขตขนาด) และแฟล็กบันทึกเสียงสำหรับเสียง
• ตรวจสอบให้แน่ใจว่าการตอบกลับที่มีหลายสื่อกระจายออกเป็นการส่งตามลำดับ

# ที่เกี่ยวข้อง

• การจับภาพจากกล้อง
• ความเข้าใจสื่อ
• เสียงและบันทึกเสียง