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

​
الأهداف

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

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

1

جمع المرفقات

اجمع المرفقات الواردة (MediaPaths، MediaUrls، MediaTypes).
2

اختيار لكل قدرة

لكل قدرة مفعّلة (صورة/صوت/فيديو)، اختر المرفقات وفق السياسة (الافتراضي: الأول).
3

اختيار النموذج

اختر أول إدخال نموذج مؤهل (الحجم + القدرة + المصادقة).
4

الرجوع الاحتياطي عند الفشل

إذا فشل نموذج أو كانت الوسائط كبيرة جدًا، ارجع إلى الإدخال التالي.
5

تطبيق كتلة النجاح

عند النجاح:
  • يصبح Body كتلة [Image] أو [Audio] أو [Video].
  • يعيّن الصوت {{Transcript}}؛ ويستخدم تحليل الأوامر نص التسمية التوضيحية عند وجوده، وإلا فيستخدم النص المنسوخ.
  • تُحفَظ التسميات التوضيحية كـ User text: داخل الكتلة.
إذا فشل الفهم أو كان معطلًا، يستمر تدفق الرد مع المتن الأصلي + المرفقات.

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

يدعم tools.media نماذج مشتركة بالإضافة إلى تجاوزات لكل قدرة:
  • 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: [
        /* 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",
}

​
بيانات اعتماد المزوّد (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
  • إذا تجاوزت الوسائط maxBytes، يُتخطى ذلك النموذج وتُجرَّب النماذج التالية.
  • تُعامل ملفات الصوت الأصغر من 1024 بايت كفارغة/تالفة وتُتخطى قبل النسخ عبر المزوّد/CLI؛ ويتلقى سياق الرد الوارد نصًا منسوخًا بديلًا حتميًا حتى يعرف الوكيل أن الملاحظة كانت صغيرة جدًا.
  • إذا أعاد النموذج أكثر من maxChars، يُقص الناتج.
  • يكون prompt افتراضيًا على عبارة بسيطة “Describe the .” بالإضافة إلى إرشاد maxChars (للصور/الفيديو فقط).
  • إذا كان نموذج الصورة الأساسي النشط يدعم الرؤية أصلاً، يتخطى OpenClaw كتلة ملخص [Image] ويمرر الصورة الأصلية إلى النموذج بدلًا من ذلك.
  • إذا كان نموذج Gateway/WebChat الأساسي نصيًا فقط، تُحفظ مرفقات الصور كمراجع media://inbound/* مُرحّلة بحيث تظل أدوات الصورة/PDF أو نموذج الصورة المضبوط قادرة على فحصها بدل فقدان المرفق.
  • تختلف طلبات openclaw infer image describe --model <provider/model> الصريحة: فهي تشغّل ذلك المزوّد/النموذج القادر على الصور مباشرة، بما في ذلك مراجع Ollama مثل ollama/qwen2.5vl:7b.
  • إذا كان <capability>.enabled: true لكن لم تُضبط أي نماذج، يحاول OpenClaw استخدام نموذج الرد النشط عندما يدعم مزوّده القدرة.

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

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

نموذج الرد النشط

نموذج الرد النشط عندما يدعم مزوّده القدرة.
2

agents.defaults.imageModel

مراجع agents.defaults.imageModel الأساسية/الاحتياطية (للصور فقط). فضّل مراجع provider/model. تُؤهَّل المراجع المجردة من إدخالات نماذج المزوّدين القادرة على الصور المضبوطة فقط عندما تكون المطابقة فريدة.
3

واجهات CLI المحلية (للصوت فقط)

واجهات CLI المحلية (إذا كانت مثبتة):
  • sherpa-onnx-offline (يتطلب SHERPA_ONNX_MODEL_DIR مع encoder/decoder/joiner/tokens)
  • whisper-cli (whisper-cpp؛ يستخدم WHISPER_CPP_MODEL أو النموذج الصغير المضمّن)
  • whisper (Python CLI؛ يحمّل النماذج تلقائيًا)
4

Gemini CLI

gemini باستخدام read_many_files.
5

مصادقة المزوّد

  • تُجرَّب إدخالات models.providers.* المضبوطة التي تدعم القدرة قبل ترتيب الرجوع الاحتياطي المضمّن.
  • يسجل مزوّدو الإعدادات المخصصون للصور فقط الذين لديهم نموذج قادر على الصور أنفسهم تلقائيًا لفهم الوسائط حتى عندما لا يكونوا Plugin مورّدًا مضمّنًا.
  • يتوفر فهم الصور عبر Ollama عند اختياره صراحة، على سبيل المثال عبر agents.defaults.imageModel أو openclaw infer image describe --model ollama/<vision-model>.
ترتيب الرجوع الاحتياطي المضمّن:
  • الصوت: OpenAI → Groq → xAI → Deepgram → OpenRouter → Google → SenseAudio → ElevenLabs → Mistral
  • الصورة: OpenAI → Anthropic → Google → MiniMax → MiniMax Portal → Z.AI
  • الفيديو: Google → Qwen → Moonshot
لتعطيل الاكتشاف التلقائي، اضبط: 
{
  tools: {
    media: {
      audio: {
        enabled: false,
      },
    },
  },
}
اكتشاف الملفات التنفيذية يعمل بأفضل جهد عبر macOS/Linux/Windows؛ تأكد من أن CLI موجود على PATH (نوسّع ~)، أو اضبط نموذج CLI صريحًا بمسار أمر كامل.

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

عند تفعيل فهم الوسائط المعتمد على المزوّدين لكل من الصوت والفيديو، يحترم 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)

القدرةتكامل المزوّدملاحظات
الصورةOpenAI، OpenAI Codex OAuth، Codex app-server، OpenRouter، Anthropic، Google، MiniMax، Moonshot، Qwen، Z.AI، مزوّدو الإعداداتتسجل Plugins المورّدين دعم الصور؛ يمكن لـ openai/* استخدام مفتاح API أو توجيه Codex OAuth؛ يستخدم codex/* دورة Codex app-server محدودة؛ يستخدم MiniMax وMiniMax OAuth كلاهما MiniMax-VL-01؛ ويسجل مزوّدو الإعدادات القادرون على الصور أنفسهم تلقائيًا.
الصوتOpenAI، Groq، xAI، Deepgram، OpenRouter، Google، SenseAudio، ElevenLabs، Mistralنسخ عبر المزوّد (Whisper/Groq/xAI/Deepgram/OpenRouter STT/Gemini/SenseAudio/Scribe/Voxtral).
الفيديوGoogle، Qwen، Moonshotفهم الفيديو عبر المزوّد من خلال Plugins المورّدين؛ يستخدم فهم الفيديو في Qwen نقاط نهاية Standard DashScope.
ملاحظة MiniMax
  • يأتي فهم الصور في minimax وminimax-cn وminimax-portal وminimax-portal-cn من موفّر الوسائط MiniMax-VL-01 المملوك للـPlugin.
  • يواصل توجيه الصور التلقائي استخدام MiniMax-VL-01 حتى إذا كانت بيانات تعريف دردشة MiniMax M2.x القديمة تدّعي دعم إدخال الصور.

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

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

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

تتحكم attachments لكل قدرة في المرفقات التي تتم معالجتها:
​
mode
"first" | "all"
افتراضي:"first"
ما إذا كان ستتم معالجة أول مرفق محدد أم جميعها.
​
maxAttachments
number
افتراضي:"1"
حدّ عدد العناصر التي تتم معالجتها.
​
prefer
"first" | "last" | "path" | "url"
تفضيل الاختيار بين المرفقات المرشحة.
عند mode: "all"، تُوسم المخرجات مثل [Image 1/2] و[Audio 2/2] وما إلى ذلك.
  • يُغلّف نص الملف المستخرج باعتباره محتوى خارجيًا غير موثوق قبل إلحاقه بموجّه الوسائط.
  • تستخدم الكتلة المُحقنة علامات حدود صريحة مثل <<<EXTERNAL_UNTRUSTED_CONTENT id="...">>> / <<<END_EXTERNAL_UNTRUSTED_CONTENT id="...">>> وتتضمن سطر بيانات تعريف Source: External.
  • يتعمّد مسار استخراج المرفقات هذا حذف لافتة SECURITY NOTICE: الطويلة لتجنّب تضخيم موجّه الوسائط؛ وتبقى علامات الحدود والبيانات التعريفية موجودة.
  • إذا لم يكن في الملف نص قابل للاستخراج، يحقن OpenClaw العبارة [No extractable text].
  • إذا عاد ملف PDF إلى صور صفحات مُصيّرة في هذا المسار، يمرّر OpenClaw صور الصفحات تلك إلى نماذج الرد القادرة على الرؤية ويبقي العنصر النائب [PDF content rendered to images] في كتلة الملف.

​
أمثلة التكوين

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

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

عند تشغيل فهم الوسائط، يتضمن /status سطر ملخص قصيرًا: 
📎 Media: image ok (openai/gpt-5.4) · audio skipped (maxBytes)
يعرض هذا النتائج لكل قدرة والموفّر/النموذج المختار عند الاقتضاء.

​
ملاحظات

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

​
ذات صلة