---
read_when:
    - تعديل مسار الوسائط أو المرفقات
summary: قواعد التعامل مع الصور والوسائط للإرسال، والبوابة، وردود الوكيل
title: دعم الصور والوسائط
x-i18n:
    generated_at: "2026-04-05T12:48:59Z"
    model: gpt-5.4
    provider: openai
    source_hash: c3bb372b45a3bae51eae03b41cb22c4cde144675a54ddfd12e01a96132e48a8a
    source_path: nodes/images.md
    workflow: 15
---

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

تعمل قناة WhatsApp عبر **Baileys Web**. توثق هذه الصفحة قواعد التعامل الحالية مع الوسائط في الإرسال، والبوابة، وردود الوكيل.

## الأهداف

- إرسال الوسائط مع تسميات توضيحية اختيارية عبر `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` لمعالجة عدة مرفقات.

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

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

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

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