دعم الصور والوسائط

تعمل قناة 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 (الحد الأقصى للضلع 2048 بكسل) مع استهداف channels.whatsapp.mediaMaxMb (الافتراضي: 50 MB).
  • الصوت/الصوتيات/الفيديو: تمرير كما هو حتى 16 MB؛ يُرسل الصوت كملاحظة صوتية (ptt: true).
  • المستندات: أي شيء آخر، حتى 100 MB، مع الحفاظ على اسم الملف عند توفره.
• تشغيل WhatsApp بنمط GIF: أرسل MP4 مع gifPlayback: true (CLI: --gif-playback) حتى تعيد تطبيقات الهاتف تشغيله داخل السطر.
• يفضل اكتشاف MIME البايتات السحرية، ثم الترويسات، ثم امتداد الملف.
• تأتي التسمية التوضيحية من --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.<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).
• تتخطى الوسائط كبيرة الحجم الفهم، لكن الردود تظل تمر مع النص الأصلي.

ملاحظات للاختبارات

• غط تدفقات الإرسال والرد لحالات الصور/الصوت/المستندات.
• تحقق من إعادة ضغط الصور (حد الحجم) ومن علامة الملاحظة الصوتية للصوت.
• تأكد من أن الردود متعددة الوسائط تتفرع كعمليات إرسال متتابعة.

ذو صلة

• التقاط الكاميرا
• فهم الوسائط
• الصوت والملاحظات الصوتية