فهم الوسائط

يمكن لـ 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"],}

بيانات اعتماد المزوّد (apiKey)

يستخدم فهم الوسائط عبر المزوّدين آلية حل مصادقة المزوّد نفسها المستخدمة في استدعاءات النماذج العادية: ملفات تعريف المصادقة، ثم متغيرات البيئة، ثم models.providers.<providerId>.apiKey.

لا تقبل إدخالات tools.media.*.models[] حقل apiKey مضمنًا. يجب أن تكون قيمة provider في إدخال نموذج الوسائط، مثل openai أو moonshot، لديها بيانات اعتماد متاحة عبر أحد مصادر مصادقة المزوّد القياسية.

مثال أدنى:

{  models: {    providers: {      openai: { apiKey: "<OPENAI_API_KEY>" },      moonshot: { apiKey: "<MOONSHOT_API_KEY>" },    },  },}

للمرجع الكامل لمصادقة المزوّد، بما في ذلك ملفات التعريف ومتغيرات البيئة وعناوين URL الأساسية المخصصة، راجع الأدوات والمزوّدون المخصصون.

الافتراضات والحدود

الافتراضات الموصى بها:

• 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 لتحديد مواضع تشغيل الفهم (مثل الرسائل المباشرة فقط).

ذات صلة

• التكوين
• دعم الصور والوسائط