Ana içeriğe atla
image_generate aracı, ajanın yapılandırdığınız sağlayıcıları kullanarak görüntü oluşturmasını ve düzenlemesini sağlar. Sohbet oturumlarında görüntü oluşturma eşzamansız çalışır: OpenClaw bir arka plan görevi kaydeder, görev kimliğini hemen döndürür ve sağlayıcı tamamladığında ajanı uyandırır. Tamamlama ajanı, oturumun normal görünür yanıt modunu izler: yapılandırılmışsa otomatik son yanıt teslimi ya da oturum ileti aracını gerektiriyorsa message(action="send"). İstek sahibi oturum etkin değilse veya etkin uyandırma başarısız olursa ve bazı oluşturulan görüntüler tamamlama yanıtında hâlâ eksikse, OpenClaw yalnızca eksik görüntülerle idempotent bir doğrudan yedek gönderir.
Araç yalnızca en az bir görüntü oluşturma sağlayıcısı kullanılabilir olduğunda görünür. Ajanınızın araçlarında image_generate görmüyorsanız agents.defaults.imageGenerationModel yapılandırın, bir sağlayıcı API anahtarı ayarlayın veya OpenAI ChatGPT/Codex OAuth ile oturum açın.

Hızlı başlangıç

1

Kimlik doğrulamayı yapılandırın

En az bir sağlayıcı için bir API anahtarı ayarlayın (örneğin OPENAI_API_KEY, GEMINI_API_KEY, OPENROUTER_API_KEY) veya OpenAI Codex OAuth ile oturum açın.
2

Varsayılan bir model seçin (isteğe bağlı)

{
  agents: {
    defaults: {
      imageGenerationModel: {
        primary: "openai/gpt-image-2",
        timeoutMs: 180_000,
      },
    },
  },
}
ChatGPT/Codex OAuth aynı openai/gpt-image-2 model başvurusunu kullanır. Bir openai OAuth profili yapılandırıldığında, OpenClaw görüntü isteklerini önce OPENAI_API_KEY denemek yerine bu OAuth profili üzerinden yönlendirir. Açık models.providers.openai yapılandırması (API anahtarı, özel/Azure temel URL) doğrudan OpenAI Images API yoluna geri geçiş yapar.
3

Ajana istekte bulunun

“Dost canlısı bir robot maskotunun görüntüsünü oluştur.”Ajan image_generate aracını otomatik olarak çağırır. Araç izin listesine alma gerekmez - bir sağlayıcı kullanılabilir olduğunda varsayılan olarak etkindir. Araç bir arka plan görev kimliği döndürür, ardından tamamlama ajanı hazır olduğunda oluşturulan eki message aracı üzerinden gönderir.
LocalAI gibi OpenAI uyumlu LAN uç noktaları için özel models.providers.openai.baseUrl değerini koruyun ve browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true ile açıkça dahil olun. Özel ve dahili görüntü uç noktaları varsayılan olarak engelli kalır.

Yaygın yollar

AmaçModel refKimlik doğrulama
API faturalandırmasıyla OpenAI görüntü oluşturmaopenai/gpt-image-2OPENAI_API_KEY
Codex abonelik kimlik doğrulamasıyla OpenAI görüntü oluşturmaopenai/gpt-image-2OpenAI ChatGPT/Codex OAuth
OpenAI şeffaf arka planlı PNG/WebPopenai/gpt-image-1.5OPENAI_API_KEY veya OpenAI Codex OAuth
DeepInfra görüntü oluşturmadeepinfra/black-forest-labs/FLUX-1-schnellDEEPINFRA_API_KEY
fal Krea 2 ifade/stil yönlendirmeli oluşturmafal/krea/v2/medium/text-to-imageFAL_KEY
OpenRouter görüntü oluşturmaopenrouter/google/gemini-3.1-flash-image-previewOPENROUTER_API_KEY
LiteLLM görüntü oluşturmalitellm/gpt-image-2LITELLM_API_KEY
Microsoft Foundry MAI görüntü oluşturmamicrosoft-foundry/<deployment-name>AZURE_OPENAI_API_KEY veya Entra ID
Google Gemini görüntü oluşturmagoogle/gemini-3.1-flash-image-previewGEMINI_API_KEY veya GOOGLE_API_KEY
Aynı image_generate aracı metinden görüntüye ve referans görüntü düzenlemeyi işler. Tek referans için image, birden fazla referans için images kullanın. fal üzerindeki Krea 2 modellerinde bu referanslar düzenleme girdileri yerine stil referansları olarak gönderilir. quality, outputFormat ve background gibi sağlayıcının desteklediği çıktı ipuçları kullanılabilir olduğunda iletilir ve sağlayıcı desteklemiyorsa yok sayıldı olarak raporlanır. Yerleşik şeffaf arka plan desteği OpenAI’ye özeldir; diğer sağlayıcılar arka uçları bunu yayıyorsa PNG alfa bilgisini yine de koruyabilir.

Desteklenen sağlayıcılar

SağlayıcıVarsayılan modelDüzenleme desteğiKimlik doğrulama
ComfyUIworkflowEvet (1 görüntü, iş akışı yapılandırmalı)bulut için COMFY_API_KEY veya COMFY_CLOUD_API_KEY
DeepInfrablack-forest-labs/FLUX-1-schnellEvet (1 görüntü)DEEPINFRA_API_KEY
falfal-ai/flux/devEvet (modele özgü sınırlar)FAL_KEY
Googlegemini-3.1-flash-image-previewEvetGEMINI_API_KEY veya GOOGLE_API_KEY
LiteLLMgpt-image-2Evet (en fazla 5 giriş görüntüsü)LITELLM_API_KEY
Microsoft Foundry<deployment-name>Evet (yalnızca MAI-Image-2.5 modelleri)AZURE_OPENAI_API_KEY veya Entra ID (az login)
MiniMaximage-01Evet (konu referansı)MINIMAX_API_KEY veya MiniMax OAuth (minimax-portal)
OpenAIgpt-image-2Evet (en fazla 4 görüntü)OPENAI_API_KEY veya OpenAI ChatGPT/Codex OAuth
OpenRoutergoogle/gemini-3.1-flash-image-previewEvet (en fazla 5 giriş görüntüsü)OPENROUTER_API_KEY
Vydragrok-imagineHayırVYDRA_API_KEY
xAIgrok-imagine-imageEvet (en fazla 5 görüntü)XAI_API_KEY
Çalışma zamanında kullanılabilir sağlayıcıları ve modelleri incelemek için action: "list" kullanın:
/tool image_generate action=list
Geçerli oturum için etkin görüntü oluşturma görevini incelemek üzere action: "status" kullanın:
/tool image_generate action=status

Sağlayıcı yetenekleri

YetenekComfyUIDeepInfrafalGoogleMicrosoft FoundryMiniMaxOpenAIVydraxAI
Oluştur (azami sayı)İş akışı tanımlı44419414
Düzenle / referans1 görüntü (iş akışı)1 görüntüFlux: 1; GPT: 10; Krea stil referansları: 10; NB2: 14En fazla 5 görüntü1 görüntü1 görüntü (konu ref)En fazla 5 görüntü-En fazla 5 görüntü
Boyut kontrolü--En fazla 4K--
En-boy oranı-----
Çözünürlük (1K/2K/4K)------1K, 2K

Araç parametreleri

prompt
string
gerekli
Görüntü oluşturma istemi. action: "generate" için gereklidir.
action
"generate" | "status" | "list"
varsayılan:"generate"
Etkin oturum görevini incelemek için "status" veya çalışma zamanında kullanılabilir sağlayıcıları ve modelleri incelemek için "list" kullanın.
model
string
Sağlayıcı/model geçersiz kılması (örn. openai/gpt-image-2). Şeffaf OpenAI arka planları için openai/gpt-image-1.5 kullanın.
image
string
Düzenleme modu için tek referans görüntü yolu veya URL’si.
images
string[]
Düzenleme modu veya stil referansı modelleri için birden fazla referans görüntü (paylaşılan araç üzerinden en fazla 10; sağlayıcıya özgü sınırlar yine de geçerlidir).
size
string
Boyut ipucu: 1024x1024, 1536x1024, 1024x1536, 2048x2048, 3840x2160.
aspectRatio
string
En-boy oranı: 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. Sağlayıcılar modele özgü alt kümelerini doğrular.
resolution
"1K" | "2K" | "4K"
Çözünürlük ipucu.
quality
"low" | "medium" | "high" | "auto"
Sağlayıcı desteklediğinde kalite ipucu.
outputFormat
"png" | "jpeg" | "webp"
Sağlayıcı desteklediğinde çıktı biçimi ipucu.
background
"transparent" | "opaque" | "auto"
Sağlayıcı desteklediğinde arka plan ipucu. Şeffaflık destekleyen sağlayıcılar için transparent değerini outputFormat: "png" veya "webp" ile kullanın.
count
number
Oluşturulacak görüntü sayısı (1-4).
timeoutMs
number
İsteğe bağlı sağlayıcı istek zaman aşımı, milisaniye cinsinden. Codex image_generate aracını dinamik araçlar üzerinden çağırdığında, bu çağrı başına değer yine de yapılandırılmış varsayılanı geçersiz kılar ve 600000 ms ile sınırlanır.
filename
string
Çıktı dosya adı ipucu.
openai
object
Yalnızca OpenAI ipuçları: background, moderation, outputCompression ve user.
fal.creativity
"raw" | "low" | "medium" | "high"
fal Krea 2 yaratıcılık kontrolü. Varsayılan değer medium.
Tüm sağlayıcılar tüm parametreleri desteklemez. Bir yedek sağlayıcı, tam olarak istenen seçenek yerine yakın bir geometri seçeneğini desteklediğinde, OpenClaw göndermeden önce en yakın desteklenen boyuta, en-boy oranına veya çözünürlüğe yeniden eşler. Desteklenmeyen çıktı ipuçları, destek beyan etmeyen sağlayıcılar için kaldırılır ve araç sonucunda raporlanır. Araç sonuçları uygulanan ayarları raporlar; details.normalization istenenden uygulanana yapılan her türlü çeviriyi yakalar.

Yapılandırma

Model seçimi

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

Sağlayıcı seçim sırası

OpenClaw sağlayıcıları şu sırayla dener:
  1. Araç çağrısından model parametresi (agent bir tane belirtirse).
  2. Yapılandırmadan imageGenerationModel.primary.
  3. Sırasıyla imageGenerationModel.fallbacks.
  4. Otomatik algılama - yalnızca kimlik doğrulama destekli sağlayıcı varsayılanları:
    • önce geçerli varsayılan sağlayıcı;
    • kalan kayıtlı görüntü oluşturma sağlayıcıları, sağlayıcı kimliği sırasıyla.
Bir sağlayıcı başarısız olursa (kimlik doğrulama hatası, hız sınırı vb.), sonraki yapılandırılmış aday otomatik olarak denenir. Tümü başarısız olursa, hata her denemenin ayrıntılarını içerir.
Çağrı başına model geçersiz kılması yalnızca o sağlayıcı/modeli dener ve yapılandırılmış primary/fallback ya da otomatik algılanan sağlayıcılarla devam etmez.
Bir sağlayıcı varsayılanı, aday listesine yalnızca OpenClaw o sağlayıcıda gerçekten kimlik doğrulaması yapabildiğinde girer. Yalnızca açık model, primary ve fallbacks girdilerini kullanmak için agents.defaults.mediaGenerationAutoProviderFallback: false ayarlayın.
Yavaş görüntü backend’leri için agents.defaults.imageGenerationModel.timeoutMs ayarlayın. Çağrı başına timeoutMs araç parametresi yapılandırılmış varsayılanı geçersiz kılar; yapılandırılmış varsayılanlar da Plugin tarafından yazılmış sağlayıcı varsayılanlarını geçersiz kılar. Google ve OpenRouter tarafından barındırılan görüntü sağlayıcıları 180 saniyelik varsayılanlar kullanır; Microsoft Foundry MAI, xAI ve Azure OpenAI görüntü oluşturma 600 saniye kullanır. Codex dinamik araç çağrıları 120 saniyelik image_generate köprü varsayılanını kullanır ve yapılandırıldığında aynı zaman aşımı bütçesine uyar; OpenClaw’ın 600000 ms dinamik araç köprüsü üst sınırıyla sınırlıdır.
Şu anda kayıtlı sağlayıcıları, varsayılan modellerini ve kimlik doğrulama ortam değişkeni ipuçlarını incelemek için action: "list" kullanın.

Görüntü düzenleme

OpenAI, OpenRouter, Google, DeepInfra, fal, Microsoft Foundry, MiniMax, ComfyUI ve xAI referans görüntülerini düzenlemeyi destekler. fal üzerindeki Krea 2 modelleri, düzenleme girdileri yerine stil referansları olarak aynı image / images alanlarını kullanır. Bir referans görüntü yolu veya URL’si geçirin:
"Generate a watercolor version of this photo" + image: "/path/to/photo.jpg"
OpenAI, OpenRouter, Google ve xAI, images parametresiyle 5 adede kadar referans görüntüsünü destekler. fal, Flux image-to-image için 1 referans görüntüsünü, GPT Image 2 düzenlemeleri için 10 adede kadarını, Krea 2 için 10 adede kadar stil referansını ve Nano Banana 2 düzenlemeleri için 14 adede kadarını destekler. Microsoft Foundry, MiniMax ve ComfyUI 1 destekler.

Sağlayıcı ayrıntılı incelemeleri

OpenAI görüntü oluşturma varsayılanı openai/gpt-image-2 şeklindedir. Bir openai OAuth profili yapılandırılmışsa, OpenClaw Codex abonelik sohbet modelleri tarafından kullanılan aynı OAuth profilini yeniden kullanır ve görüntü isteğini Codex Responses backend’i üzerinden gönderir. https://chatgpt.com/backend-api gibi eski Codex temel URL’leri, görüntü istekleri için https://chatgpt.com/backend-api/codex biçimine kanonikleştirilir. OpenClaw bu istek için sessizce OPENAI_API_KEY seçeneğine geri dönmez - doğrudan OpenAI Images API yönlendirmesini zorlamak için models.providers.openai değerini bir API anahtarı, özel temel URL veya Azure uç noktasıyla açıkça yapılandırın.openai/gpt-image-1.5, openai/gpt-image-1 ve openai/gpt-image-1-mini modelleri hâlâ açıkça seçilebilir. Saydam arka planlı PNG/WebP çıktısı için gpt-image-1.5 kullanın; mevcut gpt-image-2 API’si background: "transparent" değerini reddeder.gpt-image-2, aynı image_generate aracı üzerinden hem metinden görüntü oluşturmayı hem de referans görüntü düzenlemeyi destekler. OpenClaw prompt, count, size, quality, outputFormat ve referans görüntülerini OpenAI’ye iletir. OpenAI aspectRatio veya resolution değerlerini doğrudan almaz; mümkün olduğunda OpenClaw bunları desteklenen bir size değerine eşler, aksi halde araç bunları yok sayılan geçersiz kılmalar olarak bildirir.OpenAI’ye özgü seçenekler openai nesnesinin altında bulunur:
{
  "quality": "low",
  "outputFormat": "jpeg",
  "openai": {
    "background": "opaque",
    "moderation": "low",
    "outputCompression": 60,
    "user": "end-user-42"
  }
}
openai.background transparent, opaque veya auto kabul eder; saydam çıktılar için outputFormat değerinin png veya webp olması ve saydamlık özellikli bir OpenAI görüntü modeli gerekir. OpenClaw, varsayılan gpt-image-2 saydam arka plan isteklerini gpt-image-1.5 modeline yönlendirir. openai.outputCompression JPEG/WebP çıktılarına uygulanır ve PNG çıktıları için yok sayılır.Üst düzey background ipucu sağlayıcıdan bağımsızdır ve OpenAI sağlayıcısı seçildiğinde şu anda aynı OpenAI background istek alanına eşlenir. Arka plan desteği bildirmeyen sağlayıcılar, desteklenmeyen parametreyi almak yerine bunu ignoredOverrides içinde döndürür.OpenAI görüntü oluşturmayı api.openai.com yerine bir Azure OpenAI dağıtımı üzerinden yönlendirmek için Azure OpenAI uç noktaları bölümüne bakın.
Microsoft Foundry görüntü oluşturma, microsoft-foundry/ sağlayıcı öneki altında dağıtılmış MAI görüntü dağıtım adlarını kullanır. Sağlayıcı düzeyinde varsayılan model yoktur, çünkü MAI API’si dağıtım adınızı model alanında bekler:
{
  agents: {
    defaults: {
      imageGenerationModel: {
        primary: "microsoft-foundry/<deployment-name>",
        timeoutMs: 600_000,
      },
    },
  },
}
Sağlayıcı OpenAI Images API’yi değil, Microsoft Foundry’nin MAI API’sini kullanır:
  • Oluşturma uç noktası: /mai/v1/images/generations
  • Düzenleme uç noktası: /mai/v1/images/edits
  • Kimlik doğrulama: AZURE_OPENAI_API_KEY / sağlayıcı API anahtarı veya az login üzerinden Entra ID
  • Çıktı: bir PNG görüntüsü
  • Boyut: varsayılan 1024x1024; genişlik ve yükseklik ayrı ayrı en az 768 px olmalı, toplam piksel sayısı en fazla 1.048.576 olmalıdır
  • Düzenlemeler: yalnızca MAI-Image-2.5-Flash ve MAI-Image-2.5 dağıtımları tarafından desteklenen bir PNG veya JPEG referans görüntüsü
Yalnızca istemli oluşturma, sadece Foundry uç noktası yapılandırılmış olarak özel bir dağıtım adı kullanabilir. Özel dağıtım adlarıyla yapılan düzenlemeler, OpenClaw’ın dağıtımın MAI-Image-2.5-Flash veya MAI-Image-2.5 tarafından desteklendiğini doğrulayabilmesi için onboarding/model meta verisine ihtiyaç duyar.Geçerli MAI görüntü modelleri MAI-Image-2.5-Flash, MAI-Image-2.5, MAI-Image-2e ve MAI-Image-2 şeklindedir. Kurulum ve sohbet modeli davranışı için Microsoft Foundry Plugin bölümüne bakın.
OpenRouter görüntü oluşturma aynı OPENROUTER_API_KEY değerini kullanır ve OpenRouter’ın sohbet tamamlama görüntü API’si üzerinden yönlendirilir. OpenRouter görüntü modellerini openrouter/ önekiyle seçin:
{
  agents: {
    defaults: {
      imageGenerationModel: {
        primary: "openrouter/google/gemini-3.1-flash-image-preview",
      },
    },
  },
}
OpenClaw prompt, count, referans görüntülerini ve Gemini uyumlu aspectRatio / resolution ipuçlarını OpenRouter’a iletir. Mevcut yerleşik OpenRouter görüntü modeli kısayolları arasında google/gemini-3.1-flash-image-preview, google/gemini-3-pro-image-preview ve openai/gpt-5.4-image-2 bulunur. Yapılandırılmış Plugin’inizin ne sunduğunu görmek için action: "list" kullanın.
fal üzerindeki Krea 2 modelleri, Flux tarafından kullanılan genel image_size şeması yerine fal’ın yerel Krea şemasını kullanır. OpenClaw şunları gönderir:
  • en-boy oranı ipuçları için aspect_ratio
  • varsayılanı medium olan creativity
  • image veya images sağlandığında image_style_references
Daha hızlı, ifadeli illüstrasyon için Krea 2 Medium’u; daha yavaş, daha ayrıntılı fotogerçekçi ve dokulu görünümler için Krea 2 Large’ı seçin:
{
  agents: {
    defaults: {
      imageGenerationModel: {
        primary: "fal/krea/v2/medium/text-to-image",
      },
    },
  },
}
Krea 2 şu anda istek başına bir görüntü döndürür. Krea için aspectRatio tercih edin; OpenClaw size değerini en yakın desteklenen Krea en-boy oranına eşler ve Krea için resolution değerini sessizce atmak yerine reddeder. Yerel Krea yaratıcılık düzeyi istediğinizde fal.creativity kullanın:
{
  "model": "fal/krea/v2/medium/text-to-image",
  "prompt": "A cyber zine portrait with risograph texture",
  "aspectRatio": "9:16",
  "fal": {
    "creativity": "high"
  }
}
MiniMax görüntü oluşturma, iki yerleşik MiniMax kimlik doğrulama yolu üzerinden kullanılabilir:
  • API anahtarı kurulumları için minimax/image-01
  • OAuth kurulumları için minimax-portal/image-01
Yerleşik xAI sağlayıcısı, yalnızca istemli istekler için /v1/images/generations, image veya images bulunduğunda /v1/images/edits kullanır.
  • Modeller: xai/grok-imagine-image, xai/grok-imagine-image-quality
  • Sayı: en fazla 4
  • Referanslar: bir image veya en fazla beş images
  • En-boy oranları: 1:1, 16:9, 9:16, 4:3, 3:4, 2:3, 3:2
  • Çözünürlükler: 1K, 2K
  • Çıktılar: OpenClaw tarafından yönetilen görüntü ekleri olarak döndürülür
OpenClaw, bu denetimler paylaşılan sağlayıcılar arası image_generate sözleşmesinde var olana kadar xAI’ye özgü quality, mask, user veya ek yerel-only en-boy oranlarını özellikle açığa çıkarmaz.

Örnekler

/tool image_generate action=generate model=openai/gpt-image-2 prompt="A clean editorial poster for OpenClaw image generation" size=3840x2160 count=1
Aynı --output-format, --background, --quality ve --openai-moderation bayrakları openclaw infer image edit üzerinde kullanılabilir; --openai-background, OpenAI’a özgü bir takma ad olarak kalır. OpenAI dışındaki paketle gelen sağlayıcılar bugün açık arka plan denetimi bildirmez, bu nedenle background: "transparent" onlar için yok sayılmış olarak raporlanır.

İlgili

  • Araçlara genel bakış - kullanılabilen tüm ajan araçları
  • ComfyUI - yerel ComfyUI ve Comfy Cloud iş akışı kurulumu
  • fal - fal görüntü ve video sağlayıcısı kurulumu
  • Google (Gemini) - Gemini görüntü sağlayıcısı kurulumu
  • Microsoft Foundry Plugin - Microsoft Foundry sohbet ve MAI görüntü kurulumu
  • MiniMax - MiniMax görüntü sağlayıcısı kurulumu
  • OpenAI - OpenAI Images sağlayıcısı kurulumu
  • Vydra - Vydra görüntü, video ve konuşma kurulumu
  • xAI - Grok görüntü, video, arama, kod yürütme ve TTS kurulumu
  • Yapılandırma referansı - imageGenerationModel yapılandırması
  • Modeller - model yapılandırması ve hata durumunda devretme