Tools

توليد الصور

تتيح أداة image_generate للوكيل إنشاء الصور وتحريرها باستخدام المزوّدين الذين قمت بتكوينهم. تُسلَّم الصور المُنشأة تلقائيًا كمرفقات وسائط في رد الوكيل.

البدء السريع

تكوين المصادقة

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

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

{
  agents: {
    defaults: {
      imageGenerationModel: {
        primary: "openai/gpt-image-2",
        timeoutMs: 180_000,
      },
    },
  },
}

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

اسأل الوكيل

"أنشئ صورة لروبوت ودود يمثل العلامة."

يستدعي الوكيل image_generate تلقائيًا. لا حاجة إلى قائمة سماح للأدوات

فهي مفعّلة افتراضيًا عند توفر مزوّد.

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

الهدف	مرجع النموذج	المصادقة
إنشاء الصور عبر OpenAI مع فوترة API	`openai/gpt-image-2`	`OPENAI_API_KEY`
إنشاء الصور عبر OpenAI بمصادقة اشتراك Codex	`openai/gpt-image-2`	OpenAI Codex OAuth
PNG/WebP بخلفية شفافة عبر OpenAI	`openai/gpt-image-1.5`	`OPENAI_API_KEY` أو OpenAI Codex OAuth
إنشاء الصور عبر DeepInfra	`deepinfra/black-forest-labs/FLUX-1-schnell`	`DEEPINFRA_API_KEY`
إنشاء الصور عبر OpenRouter	`openrouter/google/gemini-3.1-flash-image-preview`	`OPENROUTER_API_KEY`
إنشاء الصور عبر LiteLLM	`litellm/gpt-image-2`	`LITELLM_API_KEY`
إنشاء الصور عبر Google Gemini	`google/gemini-3.1-flash-image-preview`	`GEMINI_API_KEY` أو `GOOGLE_API_KEY`

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

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

المزوّد	النموذج الافتراضي	دعم التحرير	المصادقة
ComfyUI	`workflow`	نعم (صورة واحدة، مكوّنة عبر سير العمل)	`COMFY_API_KEY` أو `COMFY_CLOUD_API_KEY` للسحابة
DeepInfra	`black-forest-labs/FLUX-1-schnell`	نعم (صورة واحدة)	`DEEPINFRA_API_KEY`
fal	`fal-ai/flux/dev`	نعم	`FAL_KEY`
Google	`gemini-3.1-flash-image-preview`	نعم	`GEMINI_API_KEY` أو `GOOGLE_API_KEY`
LiteLLM	`gpt-image-2`	نعم (حتى 5 صور إدخال)	`LITELLM_API_KEY`
MiniMax	`image-01`	نعم (مرجع الموضوع)	`MINIMAX_API_KEY` أو MiniMax OAuth (`minimax-portal`)
OpenAI	`gpt-image-2`	نعم (حتى 4 صور)	`OPENAI_API_KEY` أو OpenAI Codex OAuth
OpenRouter	`google/gemini-3.1-flash-image-preview`	نعم (حتى 5 صور إدخال)	`OPENROUTER_API_KEY`
Vydra	`grok-imagine`	لا	`VYDRA_API_KEY`
xAI	`grok-imagine-image`	نعم (حتى 5 صور)	`XAI_API_KEY`

استخدم action: "list" لفحص المزوّدين والنماذج المتاحة أثناء التشغيل:

/tool image_generate action=list

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

القدرة	ComfyUI	DeepInfra	fal	Google	MiniMax	OpenAI	Vydra	xAI
الإنشاء (الحد الأقصى للعدد)	محدد بسير العمل	4	4	4	9	4	1	4
التحرير / المرجع	صورة واحدة (سير العمل)	صورة واحدة	صورة واحدة	حتى 5 صور	صورة واحدة (مرجع الموضوع)	حتى 5 صور	-	حتى 5 صور
التحكم في الحجم	-	✓	✓	✓	-	حتى 4K	-	-
نسبة العرض إلى الارتفاع	-	-	✓ (الإنشاء فقط)	✓	✓	-	-	✓
الدقة (1K/2K/4K)	-	-	✓	✓	-	-	-	1K, 2K

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

promptstringrequired

مطالبة إنشاء الصورة. مطلوبة لـ action: "generate".

action"generate" | "list"

استخدم "list" لفحص المزوّدين والنماذج المتاحة أثناء التشغيل.

modelstring

تجاوز المزوّد/النموذج (مثل openai/gpt-image-2). استخدم openai/gpt-image-1.5 للخلفيات الشفافة في OpenAI.

imagestring

مسار صورة مرجعية واحد أو URL لوضع التحرير.

imagesstring[]

عدة صور مرجعية لوضع التحرير (حتى 5 لدى المزوّدين الداعمين).

sizestring

تلميح الحجم: 1024x1024، 1536x1024، 1024x1536، 2048x2048، 3840x2160.

aspectRatiostring

نسبة العرض إلى الارتفاع: 1:1، 2:3، 3:2، 3:4، 4:3، 4:5، 5:4، 9:16، 16:9، 21:9.

resolution"1K" | "2K" | "4K"

quality"low" | "medium" | "high" | "auto"

تلميح الجودة عندما يدعمه المزوّد.

outputFormat"png" | "jpeg" | "webp"

تلميح تنسيق الإخراج عندما يدعمه المزوّد.

background"transparent" | "opaque" | "auto"

تلميح الخلفية عندما يدعمه المزوّد. استخدم transparent مع outputFormat: "png" أو "webp" للمزوّدين القادرين على الشفافية.

countnumber

timeoutMsnumber

filenamestring

openaiobject

تلميحات خاصة بـ OpenAI فقط: background وmoderation وoutputCompression وuser.

التكوين

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

{
  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 استخدام المزوّدين بهذا الترتيب:

معلمة model من استدعاء الأداة (إذا حدد الوكيل واحدة).
imageGenerationModel.primary من التكوين.
imageGenerationModel.fallbacks بالترتيب.
الاكتشاف التلقائي - افتراضيات المزوّدين المدعومة بالمصادقة فقط:
- المزوّد الافتراضي الحالي أولًا؛
- بقية مزوّدي إنشاء الصور المسجلين بترتيب معرّف المزوّد.

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

تجاوزات النموذج لكل استدعاء دقيقة

يحاول تجاوز model لكل استدعاء ذلك المزوّد/النموذج فقط ولا يتابع إلى المزوّدين الأساسي/الاحتياطي المكوّنين أو المكتشفين تلقائيًا.

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

لا يدخل افتراضي المزوّد إلى قائمة المرشحين إلا عندما يستطيع OpenClaw مصادقة ذلك المزوّد فعليًا. عيّن agents.defaults.mediaGenerationAutoProviderFallback: false لاستخدام إدخالات model وprimary وfallbacks الصريحة فقط.

المهل الزمنية

عيّن agents.defaults.imageGenerationModel.timeoutMs لواجهات إنشاء الصور الخلفية البطيئة. تتجاوز معلمة الأداة timeoutMs لكل استدعاء القيمة الافتراضية المكوّنة.

الفحص أثناء التشغيل

استخدم action: "list" لفحص المزوّدين المسجلين حاليًا، ونماذجهم الافتراضية، وتلميحات متغيرات بيئة المصادقة.

تحرير الصور

يدعم OpenAI وOpenRouter وGoogle وDeepInfra وfal وMiniMax وComfyUI وxAI تحرير الصور المرجعية. مرّر مسار صورة مرجعية أو URL:

"Generate a watercolor version of this photo" + image: "/path/to/photo.jpg"

يدعم OpenAI وOpenRouter وGoogle وxAI ما يصل إلى 5 صور مرجعية عبر معلمة images. يدعم fal وMiniMax وComfyUI صورة واحدة.

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

OpenAI gpt-image-2 (and gpt-image-1.5)

يعتمد توليد الصور في OpenAI افتراضيًا على openai/gpt-image-2. إذا كان ملف تعريف OAuth باسم openai-codex مهيأً، يعيد 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:

{
  "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.

تلميح background على المستوى الأعلى محايد للمزوّد، ويُعيَّن حاليًا إلى حقل طلب OpenAI background نفسه عند اختيار مزود OpenAI. أما المزودون الذين لا يعلنون دعم الخلفية فيعيدونه في ignoredOverrides بدلاً من تلقي المعامل غير المدعوم.

لتوجيه توليد صور OpenAI عبر نشر Azure OpenAI بدلاً من api.openai.com، راجع نقاط نهاية Azure OpenAI.

OpenRouter image models

يستخدم توليد الصور في 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 المهيأ لديك.

MiniMax dual-auth

يتوفر توليد الصور في MiniMax عبر مساري مصادقة MiniMax المدمجين:

minimax/image-01 لإعدادات مفتاح API
minimax-portal/image-01 لإعدادات OAuth

xAI grok-imagine-image

يستخدم مزود xAI المدمج /v1/images/generations للطلبات التي تحتوي على مطالبة فقط و/v1/images/edits عند وجود image أو images.

النماذج: xai/grok-imagine-image، xai/grok-imagine-image-pro
العدد: حتى 4
المراجع: image واحدة أو ما يصل إلى خمس images
نسب العرض إلى الارتفاع: 1:1، 16:9، 9:16، 4:3، 3:4، 2:3، 3:2
الدقات: 1K، 2K
المخرجات: تُعاد كمرفقات صور يديرها OpenClaw

لا يعرّض OpenClaw عمدًا عناصر التحكم الأصلية الخاصة بـ xAI مثل quality أو mask أو user أو نسب العرض إلى الارتفاع الإضافية الأصلية فقط إلى أن توجد هذه العناصر في عقد image_generate المشترك بين المزودين.

أمثلة

Generate (4K landscape)

/tool image_generate action=generate model=openai/gpt-image-2 prompt="A clean editorial poster for OpenClaw image generation" size=3840x2160 count=1

Generate (transparent PNG)

/tool image_generate action=generate model=openai/gpt-image-1.5 prompt="A simple red circle sticker on a transparent background" outputFormat=png background=transparent

CLI المكافئ:

openclaw infer image generate \
--model openai/gpt-image-1.5 \
--output-format png \
--background transparent \
--prompt "A simple red circle sticker on a transparent background" \
--json

Generate (two square)

/tool image_generate action=generate model=openai/gpt-image-2 prompt="Two visual directions for a calm productivity app icon" size=1024x1024 count=2

Edit (one reference)

/tool image_generate action=generate model=openai/gpt-image-2 prompt="Keep the subject, replace the background with a bright studio setup" image=/path/to/reference.png size=1024x1536

Edit (multiple references)

/tool image_generate action=generate model=openai/gpt-image-2 prompt="Combine the character identity from the first image with the color palette from the second" images='["/path/to/character.png","/path/to/palette.jpg"]' size=1536x1024

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

توليد الصور

البدء السريع

تكوين المصادقة

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

اسأل الوكيل

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

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

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

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

التكوين

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

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

تحرير الصور

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

أمثلة

Generate (4K landscape)

Generate (transparent PNG)

Generate (two square)

Edit (one reference)

Edit (multiple references)

ذات صلة

Ask OpenClaw

# البدء السريع

تكوين المصادقة

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

اسأل الوكيل

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

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

# قدرات المزوّدين

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

# التكوين

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

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

# تحرير الصور

# تعمقات المزوّدين

# أمثلة

Generate (4K landscape)

Generate (transparent PNG)

Generate (two square)

Edit (one reference)

Edit (multiple references)

# ذات صلة

البدء السريع

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

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

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

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

التكوين

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

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

تحرير الصور

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

أمثلة

ذات صلة