الانتقال إلى المحتوى الرئيسي
تتيح أداة 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

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

{
  agents: {
    defaults: {
      imageGenerationModel: {
        primary: "openai/gpt-image-2",
        timeoutMs: 180_000,
      },
    },
  },
}
يستخدم 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. تظل نقاط نهاية الصور الخاصة والداخلية محظورة افتراضيًا.

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

الهدفمرجع النموذجالمصادقة
إنشاء صور OpenAI مع فوترة APIopenai/gpt-image-2OPENAI_API_KEY
إنشاء صور OpenAI باستخدام مصادقة اشتراك Codexopenai/gpt-image-2OpenAI ChatGPT/Codex OAuth
PNG/WebP بخلفية شفافة من OpenAIopenai/gpt-image-1.5OPENAI_API_KEY أو OpenAI Codex OAuth
إنشاء صور DeepInfradeepinfra/black-forest-labs/FLUX-1-schnellDEEPINFRA_API_KEY
إنشاء fal Krea 2 تعبيري/موجّه بالأسلوبfal/krea/v2/medium/text-to-imageFAL_KEY
إنشاء صور OpenRouteropenrouter/google/gemini-3.1-flash-image-previewOPENROUTER_API_KEY
إنشاء صور LiteLLMlitellm/gpt-image-2LITELLM_API_KEY
إنشاء صور Microsoft Foundry MAImicrosoft-foundry/<deployment-name>AZURE_OPENAI_API_KEY أو Entra ID
إنشاء صور Google Geminigoogle/gemini-3.1-flash-image-previewGEMINI_API_KEY أو GOOGLE_API_KEY
تتعامل أداة image_generate نفسها مع التحويل من نص إلى صورة وتحرير الصور المرجعية. استخدم image لمرجع واحد أو images لعدة مراجع. بالنسبة إلى نماذج Krea 2 على fal، تُرسل تلك المراجع كمراجع أسلوب بدلًا من مدخلات تحرير. تُمرر تلميحات الإخراج المدعومة من الموفّر مثل quality وoutputFormat و background عند توفرها، ويُبلّغ عنها كمتجاهلة عندما لا يدعمها الموفّر. دعم الخلفية الشفافة المضمّن خاص بـ OpenAI؛ وقد يحافظ موفّرون آخرون على شفافية PNG إذا كان نظامهم الخلفي يصدرها.

الموفّرون المدعومون

الموفّرالنموذج الافتراضيدعم التحريرالمصادقة
ComfyUIworkflowنعم (صورة واحدة، مضبوطة في سير العمل)COMFY_API_KEY أو COMFY_CLOUD_API_KEY للسحابة
DeepInfrablack-forest-labs/FLUX-1-schnellنعم (صورة واحدة)DEEPINFRA_API_KEY
falfal-ai/flux/devنعم (حدود خاصة بالنموذج)FAL_KEY
Googlegemini-3.1-flash-image-previewنعمGEMINI_API_KEY أو GOOGLE_API_KEY
LiteLLMgpt-image-2نعم (حتى 5 صور إدخال)LITELLM_API_KEY
Microsoft Foundry<deployment-name>نعم (نماذج MAI-Image-2.5 فقط)AZURE_OPENAI_API_KEY أو Entra ID (az login)
MiniMaximage-01نعم (مرجع موضوع)MINIMAX_API_KEY أو MiniMax OAuth (minimax-portal)
OpenAIgpt-image-2نعم (حتى 4 صور)OPENAI_API_KEY أو OpenAI ChatGPT/Codex OAuth
OpenRoutergoogle/gemini-3.1-flash-image-previewنعم (حتى 5 صور إدخال)OPENROUTER_API_KEY
Vydragrok-imagineلاVYDRA_API_KEY
xAIgrok-imagine-imageنعم (حتى 5 صور)XAI_API_KEY
استخدم action: "list" لفحص الموفّرين والنماذج المتاحة وقت التشغيل:
/tool image_generate action=list
استخدم action: "status" لفحص مهمة إنشاء الصور النشطة للجلسة الحالية:
/tool image_generate action=status

قدرات الموفّرين

القدرةComfyUIDeepInfrafalGoogleMicrosoft FoundryMiniMaxOpenAIVydraxAI
الإنشاء (العدد الأقصى)محدد في سير العمل44419414
التحرير / المرجعصورة واحدة (سير العمل)صورة واحدةFlux: 1؛ GPT: 10؛ مراجع أسلوب Krea: 10؛ NB2: 14حتى 5 صورصورة واحدةصورة واحدة (مرجع موضوع)حتى 5 صور-حتى 5 صور
التحكم في الحجم--حتى 4K--
نسبة العرض إلى الارتفاع-----
الدقة (1K/2K/4K)------1K, 2K

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

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

الضبط

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

{
  agents: {
    defaults: {
      imageGenerationModel: {
        primary: "openai/gpt-image-2",
        timeoutMs: 180_000,
        fallbacks: [
          "openrouter/google/gemini-3.1-flash-image-preview",
          "google/gemini-3.1-flash-image-preview",
          "fal/fal-ai/flux/dev",
        ],
      },
    },
  },
}

ترتيب اختيار الموفّر

يجرب OpenClaw الموفّرين بهذا الترتيب:
  1. معامل model من استدعاء الأداة (إذا حدده الوكيل).
  2. imageGenerationModel.primary من الإعدادات.
  3. imageGenerationModel.fallbacks بالترتيب.
  4. الاكتشاف التلقائي - افتراضيات المزوّد المدعومة بالمصادقة فقط:
    • المزوّد الافتراضي الحالي أولاً؛
    • بقية مزوّدي توليد الصور المسجلين بترتيب معرف المزوّد.
إذا فشل مزوّد (خطأ مصادقة، حد معدل، وما إلى ذلك)، تتم تجربة المرشح المكوّن التالي تلقائياً. إذا فشلت كلها، يتضمن الخطأ تفاصيل كل محاولة.
يحاول تجاوز model لكل استدعاء ذلك المزوّد/النموذج فقط ولا يتابع إلى primary/fallback المكوّنة أو المزوّدين المكتشفين تلقائياً.
لا يدخل افتراضي المزوّد في قائمة المرشحين إلا عندما يستطيع 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 الديناميكية افتراضياً جسراً image_generate مدته 120 ثانية وتحترم ميزانية المهلة نفسها عند تكوينها، ضمن الحد الأقصى لجسر الأدوات الديناميكية في OpenClaw وهو 600000 مللي ثانية.
استخدم action: "list" لفحص المزوّدين المسجلين حالياً، ونماذجهم الافتراضية، وتلميحات متغيرات بيئة المصادقة.

تحرير الصور

يدعم OpenAI وOpenRouter وGoogle وDeepInfra وfal وMicrosoft Foundry وMiniMax وComfyUI وxAI تحرير الصور المرجعية. تستخدم نماذج Krea 2 على fal حقول image / images نفسها كمراجع أسلوب بدلاً من مدخلات التحرير. مرّر مسار صورة مرجعية أو URL:
"Generate a watercolor version of this photo" + image: "/path/to/photo.jpg"
يدعم OpenAI وOpenRouter وGoogle وxAI ما يصل إلى 5 صور مرجعية عبر معامل images. يدعم 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. تتم صياغة URLs الأساسية القديمة لـ 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:
{
  "quality": "low",
  "outputFormat": "jpeg",
  "openai": {
    "background": "opaque",
    "moderation": "low",
    "outputCompression": 60,
    "user": "end-user-42"
  }
}
يقبل 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:
{
  agents: {
    defaults: {
      imageGenerationModel: {
        primary: "microsoft-foundry/<deployment-name>",
        timeoutMs: 600_000,
      },
    },
  },
}
يستخدم المزوّد 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 px على الأقل، ويجب ألا يتجاوز إجمالي البكسلات 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. راجع Microsoft Foundry Plugin للإعداد وسلوك نماذج الدردشة.
يستخدم توليد الصور في OpenRouter مفتاح OPENROUTER_API_KEY نفسه ويوجه عبر API صور إكمالات الدردشة في OpenRouter. اختر نماذج صور OpenRouter باستخدام بادئة openrouter/:
{
  agents: {
    defaults: {
      imageGenerationModel: {
        primary: "openrouter/google/gemini-3.1-flash-image-preview",
      },
    },
  },
}
يمرر 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 للمظاهر الفوتوغرافية الواقعية والملمسية الأبطأ والأكثر تفصيلاً:
{
  agents: {
    defaults: {
      imageGenerationModel: {
        primary: "fal/krea/v2/medium/text-to-image",
      },
    },
  },
}
يعيد Krea 2 حالياً صورة واحدة لكل طلب. فضّل aspectRatio مع Krea؛ يخرط OpenClaw size إلى أقرب نسبة عرض إلى ارتفاع مدعومة في Krea ويرفض resolution مع Krea بدلاً من إسقاطه. استخدم fal.creativity عندما تريد مستوى إبداع Krea أصلياً:
{
  "model": "fal/krea/v2/medium/text-to-image",
  "prompt": "A cyber zine portrait with risograph texture",
  "aspectRatio": "9:16",
  "fal": {
    "creativity": "high"
  }
}
يتوفر توليد الصور في 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، 2:3، 3:2
  • الدقات: 1K، 2K
  • المخرجات: تُعاد كمرفقات صور يديرها OpenClaw
لا يكشف OpenClaw عمداً quality أو mask أو user الأصلية في xAI أو نسب العرض إلى الارتفاع الإضافية الأصلية فقط إلى أن توجد هذه عناصر التحكم في عقد image_generate المشترك عبر المزوّدين.

أمثلة

/tool image_generate action=generate model=openai/gpt-image-2 prompt="A clean editorial poster for OpenClaw image generation" size=3840x2160 count=1
تتوفر أعلام --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 - إعداد الصور والفيديو والبحث وتنفيذ التعليمات البرمجية وTTS في Grok
  • مرجع التهيئة - إعداد imageGenerationModel
  • النماذج - تهيئة النماذج وتجاوز الفشل