فهم الوسائط

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

تسجّل Plugins الخاصة بالمورّدين بيانات تعريف القدرات (أي مزوّد يدعم أي نوع وسائط، والنموذج الافتراضي، والأولوية). تتولى نواة OpenClaw ملكية تكوين tools.media المشترك، وترتيب البدائل، والتكامل مع مسار معالجة الرد.

آلية العمل

التكوين

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

{  tools: {    media: {      concurrency: 2, // max concurrent capability runs (default)      models: [/* shared list, gate with capabilities */],      image: {/* optional overrides */},      audio: {        /* optional overrides */        echoTranscript: true,        echoFormat: '📝 "{transcript}"',      },      video: {/* optional overrides */},    },  },}

مفاتيح كل قدرة (image/audio/video):

توضع الخيارات الخاصة بـ Deepgram ضمن providerOptions.deepgram (الحقل ذو المستوى الأعلى deepgram: { detectLanguage, punctuate, smartFormat } مهمل، لكنه لا يزال مقروءًا).

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

كل إدخال في models[] هو إدخال مزوّد (افتراضيًا) أو إدخال CLI:

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

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

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

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

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

القواعد والسلوك

• تتجاوز الوسائط التي تتخطى maxBytes ذلك النموذج وتجرّب النموذج التالي.
• تُعامل الملفات الصوتية التي يقل حجمها عن 1024 بايت على أنها فارغة/تالفة، ويجري تخطيها قبل النسخ؛ ويحصل الوكيل بدلًا منها على نص نائب حتمي.
• إذا كان نموذج الصور الأساسي النشط يدعم الرؤية أصلًا، يتخطى OpenClaw كتلة ملخص [Image] ويمرر الصورة الأصلية مباشرةً إلى النموذج. يُعد MiniMax استثناءً: توجّه minimax وminimax-cn وminimax-portal وminimax-portal-cn دائمًا فهم الصور عبر مزوّد الوسائط MiniMax-VL-01 المملوك للـPlugin، حتى إذا ادّعت بيانات تعريف محادثة MiniMax M2.x القديمة دعم إدخال الصور (لا تُعامل إلا MiniMax-M3 والإصدارات اللاحقة على أنها تدعم الرؤية أصلًا).
• إذا كان نموذج Gateway/WebChat الأساسي نصيًا فقط، تُحفظ مرفقات الصور كمراجع media://inbound/* مُرحّلة، بحيث تظل أدوات الصور/PDF أو نموذج صور مكوّن قادرة على فحصها بدلًا من فقدان المرفق.
• يشغّل الأمر الصريح openclaw infer image describe --file <path> --model <provider/model> (الاسم البديل: openclaw capability image describe) ذلك المزوّد/النموذج الداعم للصور مباشرةً، بما في ذلك مراجع Ollama مثل ollama/qwen2.5vl:7b عند تكوين نموذج مطابق يدعم الصور ضمن models.providers.ollama.models[].
• إذا لم تكن <capability>.enabled مساوية لـfalse ولم تُكوّن أي نماذج، يجرّب OpenClaw نموذج الرد النشط عندما يدعم مزوّده القدرة.

الاكتشاف التلقائي (افتراضي)

عندما لا تكون tools.media.<capability>.enabled مساوية لـfalse ولم تُكوّن أي نماذج، يجرّب OpenClaw الخيارات التالية بالترتيب ويتوقف عند أول خيار يعمل:

لتعطيل الاكتشاف التلقائي لقدرة ما:

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

دعم الوكيل (استدعاءات مزوّدي الصوت/الفيديو)

يحترم فهم الصوت والفيديو المستند إلى المزوّد متغيرات بيئة الوكيل القياسية للاتصالات الصادرة، بما في ذلك قواعد التجاوز NO_PROXY/no_proxy:‏ HTTPS_PROXY وHTTP_PROXY وALL_PROXY وhttps_proxy وhttp_proxy وall_proxy. تكون للمتغيرات ذات الأحرف الصغيرة أولوية على نظيراتها ذات الأحرف الكبيرة. إذا لم يُعيّن أي منها، يستخدم فهم الوسائط اتصالًا صادرًا مباشرًا؛ وإذا كانت قيمة الوكيل غير صالحة، يسجّل OpenClaw تحذيرًا ويعود إلى الجلب المباشر. لا يمر فهم الصور عبر مسار الوكيل هذا.

القدرات

عيّن capabilities في إدخال models[] لتقييده بأنواع وسائط محددة. بالنسبة إلى القوائم المشتركة، يستنتج OpenClaw القيم الافتراضية لكل مزوّد مضمّن:

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

مصفوفة دعم المزوّدين

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

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

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

يتحكم attachments الخاص بكل إمكانية في المرفقات التي تتم معالجتها:

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

استخراج مرفقات الملفات

• يُغلَّف نص الملف المستخرج بوصفه محتوى خارجيًا غير موثوق قبل إلحاقه بموجّه الوسائط، باستخدام علامات حدود مثل <<&lt;EXTERNAL_UNTRUSTED_CONTENT id=&quot;...&quot;&gt;>> / <<&lt;END_EXTERNAL_UNTRUSTED_CONTENT id=&quot;...&quot;&gt;>> إضافةً إلى سطر البيانات الوصفية Source: External.
• يحذف هذا المسار عمدًا لافتة SECURITY NOTICE: الطويلة للحفاظ على قِصر موجّه الوسائط؛ وتظل علامات الحدود والبيانات الوصفية مطبقة.
• يحصل الملف الذي لا يحتوي على نص قابل للاستخراج على [لا يوجد نص قابل للاستخراج].
• إذا لجأ ملف PDF إلى صور الصفحات المعروضة، يمرر OpenClaw تلك الصور إلى نماذج الرد التي تدعم الرؤية، ويُبقي العنصر النائب [تم عرض محتوى PDF على هيئة صور] في كتلة الملف.

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

{  tools: {    media: {      models: [        { provider: "openai", model: "gpt-5.6-sol", 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.6-sol" },          { provider: "anthropic", model: "claude-opus-4-8" },          {            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.6-sol) · audio ok (whisper-cli observed=metal)

لجرد الفحص التمهيدي، شغّل openclaw capability audio providers. تعرض الصفوف المحلية الفائز الاحتياطي المحلي بصورة منفصلة عن اختيار المزوّد العام، والجاهزية، وحقول الخلفية المنفصلة التي توضح القادر والمطلوب والمُلاحظ. يتوفر الاختيار المحلي نفسه أيضًا بوصفه نتيجة معلوماتية من doctor:

openclaw doctor --lint --only core/doctor/local-audio-acceleration --severity-min info

ملاحظات

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

ذو صلة

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