فهم الوسائط

OpenClaw يمكنه تلخيص الوسائط الواردة (صور/صوت/فيديو) قبل تشغيل مسار الرد. يكتشف تلقائيا عندما تكون الأدوات المحلية أو مفاتيح المزوّدين متاحة، ويمكن تعطيله أو تخصيصه. إذا كان الفهم متوقفا، فستظل النماذج تتلقى الملفات/عناوين URL الأصلية كالمعتاد.

يتم تسجيل سلوك الوسائط الخاص بكل مورّد بواسطة Plugins الموردين، بينما يمتلك نواة OpenClaw إعدادات tools.media المشتركة، وترتيب الرجوع الاحتياطي، والتكامل مع مسار الرد.

# الأهداف

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

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

إذا فشل الفهم أو كان معطلا، يستمر تدفق الرد بالنص الأصلي + المرفقات الأصلية.

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

يدعم tools.media نماذج مشتركة بالإضافة إلى تجاوزات لكل قدرة:

{
  tools: {
    media: {
      models: [
        /* shared list */
      ],
      image: {
        /* optional overrides */
      },
      audio: {
        /* optional overrides */
        echoTranscript: true,
        echoFormat: '📝 "{transcript}"',
      },
      video: {
        /* optional overrides */
      },
    },
  },
}

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

يمكن أن يكون كل إدخال models[] مزوّدا أو CLI:

{
  type: "provider", // default if omitted
  provider: "openai",
  model: "gpt-5.5",
  prompt: "Describe the image in <= 500 chars.",
  maxChars: 500,
  maxBytes: 10485760,
  timeoutSeconds: 60,
  capabilities: ["image"], // optional, used for multi-modal entries
  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"],
}

# الإعدادات الافتراضية والحدود

الإعدادات الافتراضية الموصى بها:

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

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

إذا لم يتم ضبط tools.media.<capability>.enabled على false ولم تقم بضبط نماذج، يكتشف OpenClaw تلقائيا بهذا الترتيب ويتوقف عند أول خيار يعمل:

لتعطيل الاكتشاف التلقائي، اضبط:

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

# دعم بيئة الوكيل (نماذج المزوّدين)

عند تمكين فهم وسائط الصوت والفيديو المستند إلى المزوّد، يحترم OpenClaw متغيرات بيئة الوكيل الصادر القياسية لاستدعاءات HTTP الخاصة بالمزوّد:

• HTTPS_PROXY
• HTTP_PROXY
• ALL_PROXY
• https_proxy
• http_proxy
• all_proxy

إذا لم يتم ضبط أي متغيرات بيئة للوكيل، يستخدم فهم الوسائط خروجا مباشرا. إذا كانت قيمة الوكيل مشوّهة، يسجّل OpenClaw تحذيرا ويعود إلى الجلب المباشر.

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

إذا ضبطت capabilities، فلن يعمل الإدخال إلا لأنواع الوسائط تلك. بالنسبة إلى القوائم المشتركة، يمكن لـ OpenClaw استنتاج القيم الافتراضية:

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

بالنسبة إلى إدخالات CLI، اضبط capabilities صراحة لتجنب مطابقات مفاجئة. إذا حذفت capabilities، يكون الإدخال مؤهلا للقائمة التي يظهر فيها.

# مصفوفة دعم المزوّدين (تكاملات OpenClaw)

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

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

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

يتحكم attachments لكل قدرة في المرفقات التي تتم معالجتها:

عند استخدام mode: "all"، تُوسم المخرجات مثل [Image 1/2] و[Audio 2/2] وما إلى ذلك.

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

{
  tools: {
    media: {
      models: [
        { provider: "openai", model: "gpt-5.5", 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,
      },
    },
  },
}

{
  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.",
            ],
          },
        ],
      },
    },
  },
}

{
  tools: {
    media: {
      image: {
        enabled: true,
        maxBytes: 10485760,
        maxChars: 500,
        models: [
          { provider: "openai", model: "gpt-5.5" },
          { 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.",
            ],
          },
        ],
      },
    },
  },
}

{
  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"],
          },
        ],
      },
    },
  },
}

# مخرجات الحالة

عند تشغيل فهم الوسائط، يتضمن /status سطر ملخص قصيرًا:

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

يوضح هذا النتائج لكل قدرة وموفر/نموذج الاختيار عند انطباق ذلك.

# ملاحظات

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

# ذات صلة

• الإعداد
• دعم الصور والوسائط