Skip to main content
تنشئ أداة image_generate الصور وتحررها عبر المزوّدين الذين أعددتهم. وتعمل بصورة غير متزامنة في جلسات الدردشة: يسجل OpenClaw مهمة في الخلفية، ويعيد معرّف المهمة فورًا، وينبّه الوكيل عند انتهاء المزوّد. يتبع وكيل الإكمال وضع الرد المرئي المعتاد للجلسة: تسليم الرد النهائي تلقائيًا عند إعداده، أو استخدام message(action="send") عندما تتطلب الجلسة أداة الرسائل. إذا كانت جلسة مقدم الطلب غير نشطة أو فشل تنبيهها النشط، يرسل OpenClaw رسالة احتياطية مباشرة قابلة للتنفيذ المتكرر بأمان تتضمن الصور المُنشأة، كي لا تضيع النتيجة.
لا تظهر الأداة إلا عند توفر مزوّد واحد على الأقل لتوليد الصور. إذا لم تظهر image_generate ضمن أدوات وكيلك، فاضبط agents.defaults.imageGenerationModel، أو أعدّ مفتاح API لأحد المزوّدين، أو سجّل الدخول باستخدام OpenAI ChatGPT/Codex OAuth.

البدء السريع

1

إعداد المصادقة

عيّن مفتاح API لمزوّد واحد على الأقل (مثل OPENAI_API_KEY، أو GEMINI_API_KEY، أو OPENROUTER_API_KEY) أو سجّل الدخول باستخدام OpenAI Codex OAuth.
2

اختيار نموذج افتراضي (اختياري)

يستخدم ChatGPT/Codex OAuth مرجع النموذج نفسه openai/gpt-image-2. عند إعداد ملف تعريف OAuth من نوع openai، يوجّه OpenClaw طلبات الصور عبر ملف تعريف OAuth هذا بدلًا من تجربة OPENAI_API_KEY أولًا. ويؤدي إعداد models.providers.openai صراحةً (مفتاح API، أو عنوان URL أساسي مخصص/Azure) إلى إعادة استخدام مسار OpenAI Images API المباشر.
3

اطلب من الوكيل

“أنشئ صورة لتميمة روبوت ودودة.”يستدعي الوكيل image_generate تلقائيًا. لا حاجة إلى إدراج الأداة في قائمة السماح، فهي مفعّلة افتراضيًا عند توفر مزوّد. تعيد الأداة معرّف مهمة في الخلفية، ثم يرسل وكيل الإكمال المرفق المُنشأ عبر أداة message عندما يصبح جاهزًا.
بالنسبة إلى نقاط نهاية LAN المتوافقة مع OpenAI مثل LocalAI، احتفظ بعنوان models.providers.openai.baseUrl المخصص وفعّل صراحةً browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true. تظل نقاط نهاية الصور الخاصة والداخلية محظورة افتراضيًا.

المسارات الشائعة

تتعامل الأداة نفسها مع تحويل النص إلى صورة وتحرير الصور المرجعية. استخدم image لمرجع واحد أو images لعدة مراجع. بالنسبة إلى نماذج Krea 2 على fal، تُرسل هذه المراجع كمراجع أسلوب بدلًا من مدخلات التحرير. تُمرر تلميحات الإخراج التي يدعمها المزوّد، مثل quality وoutputFormat وbackground، عند توفرها، ويُبلّغ عن تجاهلها عندما لا يعلن المزوّد دعمه لها. يختص دعم الخلفية الشفافة المضمّن بـ OpenAI؛ وقد يحافظ مزوّدون آخرون مع ذلك على قناة ألفا في PNG إذا كانت خلفيتهم البرمجية تُخرجها.

المزوّدون المدعومون

استخدم action: "list" لفحص المزوّدين والنماذج المتاحة في وقت التشغيل:
استخدم action: "status" لفحص مهمة توليد الصور النشطة للجلسة الحالية:

إمكانات المزوّدين

معلمات الأداة

string
مطلوب
مطالبة توليد الصورة. مطلوبة مع action: "generate".
"generate" | "status" | "list"
افتراضي:"generate"
استخدم "status" لفحص مهمة الجلسة النشطة أو "list" لفحص المزوّدين والنماذج المتاحة في وقت التشغيل.
string
تجاوز المزوّد/النموذج (مثل openai/gpt-image-2). استخدم openai/gpt-image-1.5 للحصول على خلفيات OpenAI شفافة.
string
مسار صورة مرجعية واحدة أو عنوان URL لوضع التحرير.
string[]
عدة صور مرجعية لوضع التحرير أو نماذج مراجع الأسلوب (حتى 14 عبر الأداة المشتركة؛ وتظل الحدود الخاصة بكل مزوّد سارية).
string
تلميح الحجم: 1024x1024، 1536x1024، 1024x1536، 2048x2048، 3840x2160.
string
نسبة العرض إلى الارتفاع: 1:1، 2:1، 20:9، 19.5:9، 2:3، 3:2، 2.35:1، 3:4، 4:3، 4:5، 5:4، 9:16، 9:19.5، 9:20، 16:9، 21:9، 1:2، 4:1، 1:4، 8:1، 1:8. يتحقق المزوّدون من المجموعة الفرعية الخاصة بكل نموذج.
"1K" | "2K" | "4K"
تلميح الدقة.
"low" | "medium" | "high" | "auto"
تلميح الجودة عندما يدعمه المزوّد.
"png" | "jpeg" | "webp"
تلميح تنسيق الإخراج عندما يدعمه المزوّد.
"transparent" | "opaque" | "auto"
تلميح الخلفية عندما يدعمه المزوّد. استخدم transparent مع outputFormat: "png" أو "webp" للمزوّدين القادرين على دعم الشفافية.
number
عدد الصور المطلوب توليدها (1-4).
number
مهلة اختيارية لطلب المزوّد بالمللي ثانية. عندما يستدعي Codex أداة image_generate عبر الأدوات الديناميكية، تظل هذه القيمة الخاصة بكل استدعاء متجاوزةً للقيمة الافتراضية المضبوطة، ويكون حدها الأقصى 600000 مللي ثانية.
string
تلميح اسم ملف الإخراج.
object
تلميحات خاصة بـ OpenAI: ‏background وmoderation وoutputCompression وuser.
"raw" | "low" | "medium" | "high"
التحكم في إبداع fal Krea 2. القيمة الافتراضية هي medium.
لا يدعم جميع المزوّدين جميع المعلمات. عندما يدعم مزوّد احتياطي خيارًا هندسيًا قريبًا بدلًا من الخيار المطلوب بالضبط، يعيد OpenClaw تعيينه إلى أقرب حجم أو نسبة عرض إلى ارتفاع أو دقة مدعومة قبل الإرسال. تُحذف تلميحات الإخراج غير المدعومة لدى المزوّدين الذين لا يعلنون دعمها، ويُبلّغ عنها في نتيجة الأداة. تعرض نتائج الأداة الإعدادات المطبقة؛ ويسجل details.normalization أي تحويل من القيمة المطلوبة إلى القيمة المطبقة.

الإعداد

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

ترتيب اختيار المزوّدين

يجرّب OpenClaw المزوّدين بالترتيب التالي:
  1. معامل model من استدعاء الأداة (إذا حدّد الوكيل واحدًا).
  2. imageGenerationModel.primary من الإعدادات.
  3. imageGenerationModel.fallbacks بالترتيب.
  4. الاكتشاف التلقائي - الإعدادات الافتراضية لموفّري الخدمة المدعومين بالمصادقة فقط:
    • موفّر الخدمة الافتراضي الحالي أولًا؛
    • ثم بقية موفّري توليد الصور المسجّلين مرتّبين حسب معرّف موفّر الخدمة.
إذا فشل موفّر خدمة (بسبب خطأ في المصادقة أو حدّ المعدل أو غير ذلك)، تُجرَّب تلقائيًا الجهة المرشحة التالية التي جرى إعدادها. وإذا فشلت جميع الجهات، يتضمن الخطأ تفاصيل كل محاولة.
لا يجرّب تجاوز model لكل استدعاء سوى موفّر الخدمة/النموذج المحدّد، ولا ينتقل إلى النموذج الأساسي أو الاحتياطيات التي جرى إعدادها ولا إلى موفّري الخدمة المكتشفين تلقائيًا.
لا يدخل الإعداد الافتراضي لموفّر الخدمة في قائمة الجهات المرشحة إلا عندما يستطيع OpenClaw مصادقة موفّر الخدمة هذا فعليًا. اضبط agents.defaults.mediaGenerationAutoProviderFallback: false لاستخدام إدخالات model وprimary وfallbacks الصريحة فقط.
اضبط agents.defaults.imageGenerationModel.timeoutMs للواجهات الخلفية البطيئة للصور. يتجاوز معامل الأداة timeoutMs لكل استدعاء القيمة الافتراضية المضبوطة، وتتجاوز القيم الافتراضية المضبوطة القيم الافتراضية لموفّر الخدمة التي يحددها Plugin. تستخدم جهات استضافة الصور لدى Google وOpenRouter قيمًا افتراضية قدرها 180 ثانية؛ بينما يستخدم توليد الصور في Microsoft Foundry MAI وxAI وAzure OpenAI مدة 600 ثانية. تستخدم استدعاءات الأدوات الديناميكية في Codex قيمة افتراضية قدرها 120 ثانية لجسر image_generate، وتلتزم بميزانية المهلة الزمنية نفسها عند ضبطها، ضمن الحد الأقصى البالغ 600000 مللي ثانية لجسر الأدوات الديناميكية في OpenClaw.
استخدم action: "list" لفحص موفّري الخدمة المسجّلين حاليًا، ونماذجهم الافتراضية، وتلميحات متغيرات البيئة الخاصة بالمصادقة.

تحرير الصور

تدعم OpenAI وOpenRouter وGoogle وDeepInfra وfal وMicrosoft Foundry وMiniMax وComfyUI وxAI تحرير الصور المرجعية. تستخدم نماذج Krea 2 على fal حقلي image / images نفسيهما كمراجع للأسلوب بدلًا من مدخلات التحرير. مرّر مسار صورة مرجعية أو عنوان URL:
تدعم OpenAI وOpenRouter وGoogle ما يصل إلى 5 صور مرجعية عبر معامل images، بينما تدعم xAI ما يصل إلى 3 صور. تدعم fal صورة مرجعية واحدة لتحويل صورة إلى صورة باستخدام Flux، وما يصل إلى 10 صور لتعديلات GPT Image 2، وما يصل إلى 10 مراجع أسلوب لـ Krea 2، وما يصل إلى 14 صورة لتعديلات Nano Banana 2. وتدعم Microsoft Foundry وMiniMax وComfyUI صورة واحدة.

تفاصيل متعمقة عن موفّري الخدمة

يستخدم توليد الصور في OpenAI افتراضيًا openai/gpt-image-2. إذا جرى إعداد ملف تعريف OAuth لـ openai، يعيد OpenClaw استخدام ملف تعريف OAuth نفسه الذي تستخدمه نماذج محادثة اشتراك Codex، ويرسل طلب الصورة عبر الواجهة الخلفية Codex Responses. تُوحَّد عناوين URL الأساسية القديمة لـ Codex مثل https://chatgpt.com/backend-api إلى https://chatgpt.com/backend-api/codex لطلبات الصور. لا يعود OpenClaw تلقائيًا إلى OPENAI_API_KEY لذلك الطلب؛ ولإجبار التوجيه المباشر إلى OpenAI Images API، اضبط models.providers.openai صراحةً باستخدام مفتاح API أو عنوان URL أساسي مخصص أو نقطة نهاية Azure.لا يزال من الممكن تحديد النماذج openai/gpt-image-1.5 وopenai/gpt-image-1 وopenai/gpt-image-1-mini صراحةً. استخدم gpt-image-1.5 لإخراج PNG/WebP بخلفية شفافة؛ إذ ترفض واجهة API الحالية لـ gpt-image-2 القيمة background: "transparent".يدعم gpt-image-2 كلًا من توليد الصور من النص وتحرير الصور المرجعية عبر أداة image_generate نفسها. يمرّر OpenClaw القيم prompt وcount وsize وquality وoutputFormat والصور المرجعية إلى OpenAI. لا تتلقى OpenAI aspectRatio أو resolution مباشرةً؛ وعندما يكون ذلك ممكنًا، يحوّل OpenClaw هاتين القيمتين إلى size مدعوم، وإلا تُبلّغ الأداة عنهما كتجاوزين متجاهلين.توجد الخيارات الخاصة بـ OpenAI ضمن الكائن openai:
يقبل openai.background القيم transparent أو opaque أو auto؛ وتتطلب المخرجات الشفافة أن تكون قيمة outputFormat هي png أو webp وأن يكون نموذج الصور في OpenAI قادرًا على دعم الشفافية. يوجّه OpenClaw طلبات الخلفية الشفافة لنموذج gpt-image-2 الافتراضي إلى gpt-image-1.5. ينطبق openai.outputCompression على مخرجات JPEG/WebP، ويُتجاهل مع مخرجات PNG.تلميح background في المستوى الأعلى محايد لموفّر الخدمة، ويُطابق حاليًا حقل طلب background نفسه في OpenAI عند تحديد موفّر OpenAI. تعيد الجهات التي لا تصرّح بدعم الخلفية هذا التلميح ضمن ignoredOverrides بدلًا من تلقي المعامل غير المدعوم.لتوجيه توليد الصور في OpenAI عبر عملية نشر Azure OpenAI بدلًا من api.openai.com، راجع نقاط نهاية Azure OpenAI.
يستخدم توليد الصور في Microsoft Foundry أسماء عمليات نشر صور MAI المنشورة ضمن بادئة موفّر الخدمة microsoft-foundry/. لا يوجد نموذج افتراضي على مستوى موفّر الخدمة لأن واجهة MAI API تتوقع اسم عملية النشر في حقل model:
يستخدم موفّر الخدمة واجهة MAI API الخاصة بـ Microsoft Foundry، وليس OpenAI Images API:
  • نقطة نهاية التوليد: /mai/v1/images/generations
  • نقطة نهاية التحرير: /mai/v1/images/edits
  • المصادقة: AZURE_OPENAI_API_KEY / مفتاح API لموفّر الخدمة، أو Entra ID عبر az login
  • المخرجات: صورة PNG واحدة
  • الحجم: القيمة الافتراضية 1024x1024؛ يجب ألا يقل كل من العرض والارتفاع عن 768 بكسل، وألا يتجاوز إجمالي عدد البكسلات 1,048,576
  • التعديلات: صورة مرجعية واحدة بصيغة PNG أو JPEG، ولا تدعمها سوى عمليات نشر MAI-Image-2.5-Flash وMAI-Image-2.5
يمكن للتوليد المعتمد على المطالبة فقط استخدام اسم عملية نشر مخصص مع ضبط نقطة نهاية Foundry وحدها. تحتاج التعديلات ذات أسماء عمليات النشر المخصصة إلى بيانات تعريف الإعداد الأولي/النموذج حتى يتمكن OpenClaw من التحقق من أن عملية النشر مدعومة بـ MAI-Image-2.5-Flash أو MAI-Image-2.5.نماذج صور MAI الحالية هي MAI-Image-2.5-Flash وMAI-Image-2.5 وMAI-Image-2e وMAI-Image-2. راجع Plugin Microsoft Foundry لمعرفة خطوات الإعداد وسلوك نموذج المحادثة.
يستخدم توليد الصور في OpenRouter قيمة OPENROUTER_API_KEY نفسها، ويوجّه الطلبات عبر واجهة صور إكمال المحادثة في OpenRouter. حدّد نماذج صور OpenRouter باستخدام البادئة openrouter/:
يمرّر OpenClaw القيم prompt وcount والصور المرجعية وتلميحات aspectRatio / resolution المتوافقة مع Gemini إلى OpenRouter. تتضمن الاختصارات المضمنة الحالية لنماذج صور OpenRouter google/gemini-3.1-flash-image-preview وgoogle/gemini-3-pro-image-preview وopenai/gpt-5.4-image-2. استخدم action: "list" لمعرفة ما يتيحه Plugin الذي أعددته.
تستخدم نماذج Krea 2 على fal مخطط Krea الأصلي في fal بدلًا من مخطط image_size العام الذي يستخدمه Flux. يرسل OpenClaw:
  • aspect_ratio لتلميحات نسبة العرض إلى الارتفاع
  • creativity، وقيمته الافتراضية medium
  • image_style_references عند توفير image أو images
حدّد Krea 2 Medium للحصول على رسوم توضيحية تعبيرية أسرع، وKrea 2 Large للحصول على مظاهر واقعية فوتوغرافيًا وذات خامات أكثر تفصيلًا ولكن أبطأ:
يعيد Krea 2 حاليًا صورة واحدة لكل طلب. يُفضَّل استخدام aspectRatio مع Krea؛ إذ يحوّل OpenClaw قيمة size إلى أقرب نسبة عرض إلى ارتفاع مدعومة في Krea، ويرفض resolution مع Krea بدلًا من إسقاطه. استخدم fal.creativity عندما تريد مستوى إبداع أصليًا من Krea:
يتوفر توليد الصور في MiniMax عبر مساري المصادقة المضمّنين في MiniMax:
  • minimax/image-01 لعمليات الإعداد باستخدام مفتاح API
  • minimax-portal/image-01 لعمليات الإعداد باستخدام OAuth
يستخدم موفّر xAI المضمّن /v1/images/generations للطلبات المعتمدة على المطالبة فقط، ويستخدم /v1/images/edits عند وجود image أو images.
  • النماذج: xai/grok-imagine-image، وxai/grok-imagine-image-quality
  • العدد: ما يصل إلى 4
  • المراجع: قيمة image واحدة أو ما يصل إلى ثلاث قيم images
  • نسب العرض إلى الارتفاع: 1:1، و16:9، و9:16، و4:3، و3:4، و3:2، و2:3، و2:1، و1:2، و19.5:9، و9:19.5، و20:9، و9:20
  • درجات الدقة: 1K، و2K
  • المخرجات: تُعاد كمرفقات صور يديرها OpenClaw
لا يتيح OpenClaw عمدًا قيم xAI الأصلية quality أوmask أوuser أو نسبة العرض إلى الارتفاع auto إلى أن تتوفر عناصر التحكم هذه في عقد image_generate المشترك بين موفّري الخدمة.

أمثلة

تتوفر علامات --output-format و--background و--quality و --openai-moderation نفسها في openclaw infer image edit؛ وتظل --openai-background اسمًا بديلًا خاصًا بـ OpenAI. لا تُعلن المزوّدات المضمّنة الأخرى غير OpenAI حاليًا عن تحكم صريح في الخلفية، لذا يتم الإبلاغ عن تجاهل background: "transparent" لديها.

مواضيع ذات صلة

  • نظرة عامة على الأدوات - جميع أدوات الوكيل المتاحة
  • ComfyUI - إعداد سير عمل ComfyUI المحلي وComfy Cloud
  • fal - إعداد مزوّد الصور والفيديو fal
  • Google (Gemini) - إعداد مزوّد الصور Gemini
  • Plugin ‏Microsoft Foundry - إعداد محادثة Microsoft Foundry وصور MAI
  • MiniMax - إعداد مزوّد الصور MiniMax
  • OpenAI - إعداد مزوّد OpenAI Images
  • Vydra - إعداد الصور والفيديو والكلام في Vydra
  • xAI - إعداد الصور والفيديو والبحث وتنفيذ التعليمات البرمجية وتحويل النص إلى كلام في Grok
  • مرجع الإعدادات - إعداد imageGenerationModel
  • النماذج - إعداد النماذج والتحويل التلقائي عند التعطل