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

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

เป้าหมาย

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

รูปแบบ CLI

openclaw message send --target <dest> --media <path-or-url> [--message <caption>]

• --media <path-or-url> — แนบสื่อ (รูปภาพ/เสียง/วิดีโอ/เอกสาร) รองรับพาธในเครื่องหรือ URL ไม่บังคับ และคำบรรยายสามารถเว้นว่างสำหรับการส่งเฉพาะสื่อได้
• --gif-playback — จัดการสื่อวิดีโอให้เล่นแบบ GIF (เฉพาะ WhatsApp)
• --force-document — ส่งสื่อเป็นเอกสารเพื่อหลีกเลี่ยงการบีบอัดของช่องทาง (Telegram, WhatsApp) ใช้ได้กับรูปภาพ, GIF และวิดีโอ
• --reply-to <id>, --thread-id <id>, --pin, --silent — ตัวเลือกการนำส่ง/เธรดที่ใช้ร่วมกับการส่งเฉพาะข้อความ
• --dry-run — แสดงเพย์โหลดที่แก้ไขค่าเรียบร้อยแล้วและข้ามการส่ง
• --json — แสดงผลลัพธ์เป็น JSON: { action, channel, dryRun, handledBy, messageId?, payload } (payload มีผลลัพธ์การส่งเฉพาะช่องทาง รวมถึงการอ้างอิงสื่อ หากมี)

ลักษณะการทำงานของช่องทาง WhatsApp Web

• อินพุต: พาธไฟล์ในเครื่อง หรือ URL แบบ HTTP(S)
• ขั้นตอน: โหลดลงในบัฟเฟอร์ ตรวจหาชนิดสื่อ แล้วสร้างเพย์โหลดขาออกตามแต่ละชนิด:
  • รูปภาพ: ปรับให้เหมาะสมเพื่อให้มีขนาดไม่เกิน channels.whatsapp.mediaMaxMb (ค่าเริ่มต้น 50MB) รูปภาพทึบจะถูกบีบอัดใหม่เป็น JPEG (ลำดับขนาดด้านเริ่มต้นที่ 2048px และลดลงเมื่อยังเกินขนาดซ้ำ) ส่วนรูปภาพที่มีความโปร่งใสจะคงไว้เป็น PNG หากต้นฉบับเป็น JPEG/PNG/WebP ที่ยอมรับได้และอยู่ภายในงบขนาดไฟล์และความยาวด้านอยู่แล้ว ระบบจะคงไบต์ต้นฉบับไว้โดยไม่เปลี่ยนแปลงแทนการบีบอัดใหม่ GIF แบบเคลื่อนไหวจะไม่ถูกเข้ารหัสใหม่ แต่จะตรวจสอบเฉพาะขนาด
  • เสียง/ข้อความเสียง: เว้นแต่ว่าจะเป็นเสียงข้อความเสียงแบบเนทีฟอยู่แล้ว (.ogg/.opus หรือ audio/ogg/audio/opus) เสียงขาออกจะถูกแปลงรหัสผ่าน ffmpeg เป็น Opus/OGG (48kHz โมโน, 64kbps, จำกัดสูงสุด 20 นาที) ก่อนส่งเป็นข้อความเสียง (ptt: true)
  • วิดีโอ: ส่งผ่านโดยไม่แปลง ขนาดสูงสุด 16MB
  • เอกสาร: ไฟล์อื่นทั้งหมด ขนาดสูงสุด 100MB โดยคงชื่อไฟล์ไว้เมื่อมี
• การเล่นแบบ GIF ของ WhatsApp: ส่ง MP4 พร้อม gifPlayback: true (CLI: --gif-playback) เพื่อให้ไคลเอนต์บนมือถือเล่นวนซ้ำภายในข้อความ
• การตรวจหา MIME จะให้ความสำคัญกับไบต์ลายเซ็นที่ตรวจพบ ตามด้วยนามสกุลไฟล์ แล้วจึงส่วนหัวการตอบกลับ คอนเทนเนอร์ทั่วไปที่ตรวจพบ (application/octet-stream, zip) จะไม่แทนที่การแมปนามสกุลที่เฉพาะเจาะจงกว่า (เช่น XLSX เทียบกับ ZIP)
• คำบรรยายมาจาก --message หรือ reply.text และสามารถเว้นว่างได้
• การบันทึกล็อก: โหมดไม่ละเอียดแสดง ↩️/✅ ส่วนโหมดละเอียดจะแสดงขนาดและพาธต้นทาง/URL

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

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

สื่อขาเข้าสู่คำสั่ง

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

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

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

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

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

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

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

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

เนื้อหาที่เกี่ยวข้อง

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