การรองรับรูปภาพและสื่อ — 2025-12-05¶

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

เป้าหมาย¶

• ส่งสื่อพร้อมคำบรรยาย(ไม่บังคับ)ผ่าน openclaw message send --media
• อนุญาตให้การตอบกลับอัตโนมัติจากเว็บอินบ็อกซ์รวมสื่อควบคู่กับข้อความ
• รักษาขีดจำกัดตามประเภทให้เหมาะสมและคาดเดาได้

พื้นผิว CLI¶

• openclaw message send --media <path-or-url> [--message <caption>]
• --media ไม่บังคับ; คำบรรยายสามารถเว้นว่างได้สำหรับการส่งเฉพาะสื่อ
• --dry-run แสดง payload ที่แก้ไขแล้ว; --json ส่งออก { channel, to, messageId, mediaUrl, caption }

พฤติกรรมช่องทาง WhatsApp Web¶

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

พายป์ไลน์การตอบกลับอัตโนมัติ¶

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

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

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

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

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