​

دعم الصور والوسائط (2025-12-05)

​

الأهداف

• إرسال الوسائط مع تسميات توضيحية اختيارية عبر 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، مع الحفاظ على اسم الملف عند توفره.
• تشغيل WhatsApp بأسلوب GIF: أرسل ملف MP4 مع gifPlayback: true ‏(في CLI: ‏--gif-playback) حتى تقوم تطبيقات الهاتف بالتكرار داخل السطر.
• يفضّل اكتشاف MIME بايتات magic أولًا، ثم الترويسات، ثم امتداد الملف.
• تأتي التسمية التوضيحية من --message أو reply.text؛ ويُسمح بأن تكون فارغة.
• التسجيل: في الوضع غير المفصل يظهر ↩️/✅؛ وفي الوضع المفصل يتضمن الحجم ومسار/عنوان URL المصدر.

​

مسار الرد التلقائي

• تعيد getReplyFromConfig القيمة { text?, mediaUrl?, mediaUrls? }.
• عند وجود وسائط، يقوم مرسل الويب بحل المسارات المحلية أو عناوين URL باستخدام المسار نفسه الذي يستخدمه openclaw message send.
• إذا تم توفير عدة عناصر وسائط، فسيتم إرسالها بالتتابع.

​

الوسائط الواردة إلى الأوامر (Pi)

• عندما تتضمن رسائل الويب الواردة وسائط، يقوم OpenClaw بتنزيلها إلى ملف مؤقت ويكشف متغيرات القوالب:
  • {{MediaUrl}} عنوان URL زائف للوسائط الواردة.
  • {{MediaPath}} مسار محلي مؤقت يُكتب قبل تشغيل الأمر.
• عند تمكين Docker sandbox لكل جلسة، يتم نسخ الوسائط الواردة إلى مساحة عمل sandbox وتُعاد كتابة MediaPath/MediaUrl إلى مسار نسبي مثل media/inbound/<filename>.
• يعمل فهم الوسائط (إذا تم إعداده عبر tools.media.* أو tools.media.models المشتركة) قبل إدراج القوالب ويمكنه إدخال كتل [Image] و[Audio] و[Video] داخل Body.
  • يعيّن الصوت {{Transcript}} ويستخدم النص المفرغ لتحليل الأوامر بحيث تظل أوامر الشرطة المائلة تعمل.
  • تحافظ أوصاف الفيديو والصور على أي نص تسمية توضيحية لتحليل الأوامر.
  • إذا كان نموذج الصور الأساسي النشط يدعم الرؤية أصلًا، فإن OpenClaw يتخطى كتلة الملخص [Image] ويمرر الصورة الأصلية إلى النموذج بدلًا من ذلك.
• افتراضيًا، تتم معالجة أول مرفق صورة/صوت/فيديو مطابق فقط؛ اضبط tools.media.<cap>.attachments لمعالجة عدة مرفقات.

​

الحدود والأخطاء

• الصور: حتى 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).
• الوسائط كبيرة الحجم تتخطى الفهم، لكن الردود تظل تمر مع النص الأصلي.

​

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

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