​

دعم الصور والوسائط — 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) مع استهداف agents.defaults.mediaMaxMb (الافتراضي 5 MB)، وبحد أقصى 6 MB.
  • الصوت/المقاطع الصوتية/الفيديو: تمرير مباشر حتى 16 MB؛ يُرسل الصوت كملاحظة صوتية (ptt: true).
  • المستندات: أي شيء آخر، حتى 100 MB، مع الحفاظ على اسم الملف عند توفره.
• تشغيل GIF بأسلوب WhatsApp: إرسال MP4 مع gifPlayback: true (CLI: --gif-playback) لكي تقوم تطبيقات الهاتف بالتشغيل المتكرر داخل الرسالة.
• يفضّل اكتشاف MIME «البتّات السحرية»، ثم الرؤوس، ثم امتداد الملف.
• تأتي التسمية التوضيحية من --message أو reply.text؛ ويُسمح بتسمية توضيحية فارغة.
• التسجيل: في الوضع غير المفصّل يظهر ↩️/✅؛ وفي الوضع المفصّل تتضمن السجلات الحجم ومسار المصدر/عنوان URL.

​

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

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

​

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

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

​

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

• الصور: حد ~6 MB بعد إعادة الضغط.
• الصوت/المقاطع الصوتية/الفيديو: حد 16 MB؛ المستندات: حد 100 MB.
• الوسائط كبيرة الحجم أو غير القابلة للقراءة → خطأ واضح في السجلات ويتم تخطي الرد.

• الصور: الافتراضي 10 MB (tools.media.image.maxBytes).
• الصوت: الافتراضي 20 MB (tools.media.audio.maxBytes).
• الفيديو: الافتراضي 50 MB (tools.media.video.maxBytes).
• الوسائط كبيرة الحجم تتجاوز الفهم، لكن الردود تستمر مع النص الأصلي.

​

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

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