> ## Documentation Index
> Fetch the complete documentation index at: https://openclaw.veiseule.ai/llms.txt
> Use this file to discover all available pages before exploring further.

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

# دعم الصور والوسائط — 2025-12-05

تعمل قناة 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 (أقصى ضلع 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` لمعالجة عدة مرفقات.

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

**حدود الإرسال الصادر (إرسال WhatsApp Web)**

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

**حدود فهم الوسائط (التفريغ/الوصف)**

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

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

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