​

فهم الوسائط - الوارد (2026-01-17)

​

الأهداف

• اختياري: هضم أولي للوسائط الواردة إلى نص قصير لتوجيه أسرع + تحليل أفضل للأوامر.
• الحفاظ دائمًا على تسليم الوسائط الأصلية إلى النموذج.
• دعم واجهات API الخاصة بالموفّرين والمسارات الاحتياطية عبر CLI.
• السماح بعدة نماذج مع تراجع احتياطي مرتب (خطأ/حجم/مهلة).

​

السلوك عالي المستوى

1. جمع المرفقات الواردة (MediaPaths وMediaUrls وMediaTypes).
2. لكل قدرة مفعلة (صورة/صوت/فيديو)، تحديد المرفقات وفق السياسة (الافتراضي: الأول).
3. اختيار أول إدخال نموذج مؤهل (الحجم + القدرة + المصادقة).
4. إذا فشل نموذج أو كانت الوسائط كبيرة جدًا، يتم الرجوع إلى الإدخال التالي.
5. عند النجاح:
   • تصبح Body كتلة [Image] أو [Audio] أو [Video].
   • يضبط الصوت {{Transcript}}؛ ويستخدم تحليل الأوامر نص التسمية التوضيحية عند وجوده، وإلا يستخدم النص المفرغ.
   • تُحفَظ التسميات التوضيحية بوصفها User text: داخل الكتلة.

​

نظرة عامة على الإعداد

• tools.media.models: قائمة النماذج المشتركة (استخدم capabilities للبوابة).
• tools.media.image / tools.media.audio / tools.media.video:
  • القيم الافتراضية (prompt وmaxChars وmaxBytes وtimeoutSeconds وlanguage)
  • تجاوزات الموفّر (baseUrl وheaders وproviderOptions)
  • خيارات Deepgram للصوت عبر tools.media.audio.providerOptions.deepgram
  • عناصر تحكم صدى النص المفرغ للصوت (echoTranscript، الافتراضي false؛ وechoFormat)
  • قائمة models اختيارية لكل قدرة (وتُفضَّل قبل النماذج المشتركة)
  • سياسة attachments ‏(mode وmaxAttachments وprefer)
  • scope ‏(بوابة اختيارية حسب القناة/نوع الدردشة/مفتاح الجلسة)
• tools.media.concurrency: الحد الأقصى لتشغيلات القدرات المتزامنة (الافتراضي 2).

{
  tools: {
    media: {
      models: [
        /* قائمة مشتركة */
      ],
      image: {
        /* تجاوزات اختيارية */
      },
      audio: {
        /* تجاوزات اختيارية */
        echoTranscript: true,
        echoFormat: '📝 "{transcript}"',
      },
      video: {
        /* تجاوزات اختيارية */
      },
    },
  },
}

​

إدخالات النماذج

{
  type: "provider", // الافتراضي إذا تم حذفه
  provider: "openai",
  model: "gpt-5.4-mini",
  prompt: "Describe the image in <= 500 chars.",
  maxChars: 500,
  maxBytes: 10485760,
  timeoutSeconds: 60,
  capabilities: ["image"], // اختياري، ويُستخدم للإدخالات متعددة الوسائط
  profile: "vision-profile",
  preferredProfile: "vision-fallback",
}

{
  type: "cli",
  command: "gemini",
  args: [
    "-m",
    "gemini-3-flash",
    "--allowed-tools",
    "read_file",
    "Read the media at {{MediaPath}} and describe it in <= {{MaxChars}} characters.",
  ],
  maxChars: 500,
  maxBytes: 52428800,
  timeoutSeconds: 120,
  capabilities: ["video", "image"],
}

• {{MediaDir}} ‏(الدليل الذي يحتوي على ملف الوسائط)
• {{OutputDir}} ‏(دليل مؤقت أُنشئ لهذا التشغيل)
• {{OutputBase}} ‏(المسار الأساسي للملف المؤقت، من دون امتداد)

​

القيم الافتراضية والحدود

• maxChars: ‏500 للصورة/الفيديو (قصير وملائم للأوامر)
• maxChars: ‏غير مضبوطة للصوت (النص المفرغ الكامل ما لم تضبط حدًا)
• maxBytes:
  • الصورة: 10MB
  • الصوت: 20MB
  • الفيديو: 50MB

• إذا تجاوزت الوسائط maxBytes، يتم تخطي ذلك النموذج وتجربة النموذج التالي.
• تُعامَل الملفات الصوتية الأصغر من 1024 بايت على أنها فارغة/تالفة ويتم تخطيها قبل النسخ عبر الموفّر/CLI.
• إذا أعاد النموذج أكثر من maxChars، يتم اقتطاع الإخراج.
• تفترض prompt افتراضيًا عبارة بسيطة من نوع “Describe the .” بالإضافة إلى توجيه maxChars ‏(للصورة/الفيديو فقط).
• إذا كان نموذج الصورة الأساسي النشط يدعم الرؤية أصلًا، فإن OpenClaw يتخطى كتلة الملخص [Image] ويمرر الصورة الأصلية مباشرة إلى النموذج.
• إذا كانت <capability>.enabled: true لكن لا توجد نماذج مهيأة، يحاول OpenClaw نموذج الرد النشط عندما يدعم موفّره تلك القدرة.

​

الاكتشاف التلقائي لفهم الوسائط (الافتراضي)

1. نموذج الرد النشط عندما يدعم موفّره تلك القدرة.
2. مراجع agents.defaults.imageModel ‏primary/fallback ‏(للصورة فقط).
3. CLI محلية ‏(للصوت فقط؛ إذا كانت مثبتة)
   • sherpa-onnx-offline ‏(يتطلب SHERPA_ONNX_MODEL_DIR مع encoder/decoder/joiner/tokens)
   • whisper-cli ‏(whisper-cpp; يستخدم WHISPER_CPP_MODEL أو النموذج tiny المضمّن)
   • whisper ‏(Python CLI؛ ينزّل النماذج تلقائيًا)
4. Gemini CLI ‏(gemini) باستخدام read_many_files
5. مصادقة الموفّر
   • تتم تجربة إدخالات models.providers.* المهيأة التي تدعم القدرة قبل ترتيب التراجع الاحتياطي المضمّن.
   • يتم تسجيل موفّري الإعداد ذوي الصور فقط مع نموذج قادر على الصور تلقائيًا لفهم الوسائط حتى عندما لا يكونون إضافة vendor مدمجة.
   • ترتيب التراجع الاحتياطي المضمّن:
     • الصوت: OpenAI → Groq → Deepgram → Google → Mistral
     • الصورة: OpenAI → Anthropic → Google → MiniMax → MiniMax Portal → Z.AI
     • الفيديو: Google → Qwen → Moonshot

{
  tools: {
    media: {
      audio: {
        enabled: false,
      },
    },
  },
}

​

دعم بيئة Proxy ‏(نماذج الموفّر)

• HTTPS_PROXY
• HTTP_PROXY
• https_proxy
• http_proxy

​

القدرات (اختياري)

• openai وanthropic وminimax: صورة
• minimax-portal: صورة
• moonshot: صورة + فيديو
• openrouter: صورة
• google ‏(Gemini API): صورة + صوت + فيديو
• qwen: صورة + فيديو
• mistral: صوت
• zai: صورة
• groq: صوت
• deepgram: صوت
• أي فهرس models.providers.<id>.models[] يحتوي على نموذج قادر على الصور: صورة

​

مصفوفة دعم الموفّر (تكاملات OpenClaw)

• يأتي فهم الصور في minimax وminimax-portal من موفّر الوسائط MiniMax-VL-01 المملوك للإضافة.
• لا يزال فهرس النصوص المضمّن لـ MiniMax يبدأ كنصي فقط؛ وتُنشئ إدخالات models.providers.minimax الصريحة مراجع دردشة M2.7 القادرة على الصور.

​

إرشادات اختيار النموذج

• فضّل أقوى نموذج من أحدث الأجيال متاح لكل قدرة وسائط عندما تكون الجودة والسلامة مهمتين.
• بالنسبة إلى الوكلاء المفعلة لديهم الأدوات ويتعاملون مع مدخلات غير موثوقة، تجنب نماذج الوسائط الأقدم/الأضعف.
• احتفظ بمسار احتياطي واحد على الأقل لكل قدرة من أجل التوافر (نموذج عالي الجودة + نموذج أسرع/أرخص).
• تُعد المسارات الاحتياطية عبر CLI ‏(whisper-cli وwhisper وgemini) مفيدة عندما لا تتوفر واجهات API الخاصة بالموفّرين.
• ملاحظة parakeet-mlx: مع --output-dir، يقرأ OpenClaw الملف <output-dir>/<media-basename>.txt عندما يكون تنسيق الإخراج هو txt ‏(أو غير محدد)؛ أما التنسيقات غير txt فتعود احتياطيًا إلى stdout.

​

سياسة المرفقات

• mode: ‏first ‏(الافتراضي) أو all
• maxAttachments: حد أقصى للعدد المعالَج (الافتراضي 1)
• prefer: ‏first أو last أو path أو url

• يُغلَّف النص المستخرج من الملفات بوصفه محتوى خارجيًا غير موثوق قبل إلحاقه بموجّه الوسائط.
• تستخدم الكتلة المحقونة علامات حدود صريحة مثل <<<EXTERNAL_UNTRUSTED_CONTENT id="...">>> / <<<END_EXTERNAL_UNTRUSTED_CONTENT id="...">>> وتتضمن سطر بيانات وصفية Source: External.
• يتعمد مسار استخراج المرفقات هذا حذف لافتة SECURITY NOTICE: الطويلة لتجنب تضخيم موجّه الوسائط؛ لكن تظل علامات الحدود والبيانات الوصفية موجودة.
• إذا لم يكن للملف نص قابل للاستخراج، يحقن OpenClaw القيمة [No extractable text].
• إذا عاد PDF في هذا المسار احتياطيًا إلى صور صفحات معروضة، فإن موجّه الوسائط يحتفظ بالنص النائب [PDF content rendered to images; images not forwarded to model] لأن خطوة استخراج المرفقات هذه تمرر كتل نصية، وليس صور PDF المعروضة.

​

أمثلة على الإعداد

​

1) قائمة نماذج مشتركة + تجاوزات

{
  tools: {
    media: {
      models: [
        { provider: "openai", model: "gpt-5.4-mini", capabilities: ["image"] },
        {
          provider: "google",
          model: "gemini-3-flash-preview",
          capabilities: ["image", "audio", "video"],
        },
        {
          type: "cli",
          command: "gemini",
          args: [
            "-m",
            "gemini-3-flash",
            "--allowed-tools",
            "read_file",
            "Read the media at {{MediaPath}} and describe it in <= {{MaxChars}} characters.",
          ],
          capabilities: ["image", "video"],
        },
      ],
      audio: {
        attachments: { mode: "all", maxAttachments: 2 },
      },
      video: {
        maxChars: 500,
      },
    },
  },
}

​

2) الصوت + الفيديو فقط (الصورة معطلة)

{
  tools: {
    media: {
      audio: {
        enabled: true,
        models: [
          { provider: "openai", model: "gpt-4o-mini-transcribe" },
          {
            type: "cli",
            command: "whisper",
            args: ["--model", "base", "{{MediaPath}}"],
          },
        ],
      },
      video: {
        enabled: true,
        maxChars: 500,
        models: [
          { provider: "google", model: "gemini-3-flash-preview" },
          {
            type: "cli",
            command: "gemini",
            args: [
              "-m",
              "gemini-3-flash",
              "--allowed-tools",
              "read_file",
              "Read the media at {{MediaPath}} and describe it in <= {{MaxChars}} characters.",
            ],
          },
        ],
      },
    },
  },
}

​

3) فهم الصور الاختياري

{
  tools: {
    media: {
      image: {
        enabled: true,
        maxBytes: 10485760,
        maxChars: 500,
        models: [
          { provider: "openai", model: "gpt-5.4-mini" },
          { provider: "anthropic", model: "claude-opus-4-6" },
          {
            type: "cli",
            command: "gemini",
            args: [
              "-m",
              "gemini-3-flash",
              "--allowed-tools",
              "read_file",
              "Read the media at {{MediaPath}} and describe it in <= {{MaxChars}} characters.",
            ],
          },
        ],
      },
    },
  },
}

​

4) إدخال واحد متعدد الوسائط (قدرات صريحة)

{
  tools: {
    media: {
      image: {
        models: [
          {
            provider: "google",
            model: "gemini-3.1-pro-preview",
            capabilities: ["image", "video", "audio"],
          },
        ],
      },
      audio: {
        models: [
          {
            provider: "google",
            model: "gemini-3.1-pro-preview",
            capabilities: ["image", "video", "audio"],
          },
        ],
      },
      video: {
        models: [
          {
            provider: "google",
            model: "gemini-3.1-pro-preview",
            capabilities: ["image", "video", "audio"],
          },
        ],
      },
    },
  },
}

​

إخراج الحالة

📎 Media: image ok (openai/gpt-5.4-mini) · audio skipped (maxBytes)

​

ملاحظات

• يكون الفهم بأفضل جهد. ولا تمنع الأخطاء الردود.
• تظل المرفقات تُمرَّر إلى النماذج حتى عندما يكون الفهم معطلًا.
• استخدم scope لتقييد الأماكن التي يعمل فيها الفهم (مثل الرسائل المباشرة فقط).

​

مستندات ذات صلة

• التهيئة
• دعم الصور والوسائط