Przejdź do głównej treści
Narzędzie image_generate pozwala agentowi tworzyć i edytować obrazy przy użyciu skonfigurowanych dostawców. W sesjach czatu generowanie obrazów działa asynchronicznie: OpenClaw zapisuje zadanie w tle, natychmiast zwraca identyfikator zadania i wybudza agenta, gdy dostawca zakończy pracę. Agent ukończenia używa normalnego dla sesji trybu widocznej odpowiedzi: automatycznego dostarczenia końcowej odpowiedzi, gdy jest skonfigurowane, albo message(action="send"), gdy sesja wymaga narzędzia wiadomości. Jeśli sesja żądająca jest nieaktywna albo jej aktywne wybudzenie się nie powiedzie, a w odpowiedzi ukończenia nadal brakuje części wygenerowanych obrazów, OpenClaw wysyła idempotentną bezpośrednią odpowiedź awaryjną zawierającą tylko brakujące obrazy.
Narzędzie pojawia się tylko wtedy, gdy dostępny jest co najmniej jeden dostawca generowania obrazów. Jeśli nie widzisz image_generate w narzędziach agenta, skonfiguruj agents.defaults.imageGenerationModel, ustaw klucz API dostawcy albo zaloguj się przez OpenAI ChatGPT/Codex OAuth.

Szybki start

1

Skonfiguruj uwierzytelnianie

Ustaw klucz API dla co najmniej jednego dostawcy (na przykład OPENAI_API_KEY, GEMINI_API_KEY, OPENROUTER_API_KEY) albo zaloguj się przez OpenAI Codex OAuth.
2

Wybierz model domyślny (opcjonalnie)

{
  agents: {
    defaults: {
      imageGenerationModel: {
        primary: "openai/gpt-image-2",
        timeoutMs: 180_000,
      },
    },
  },
}
ChatGPT/Codex OAuth używa tego samego odwołania do modelu openai/gpt-image-2. Gdy skonfigurowany jest profil OAuth openai, OpenClaw kieruje żądania obrazów przez ten profil OAuth zamiast najpierw próbować OPENAI_API_KEY. Jawna konfiguracja models.providers.openai (klucz API, niestandardowy/Azure bazowy URL) ponownie wybiera bezpośrednią trasę API OpenAI Images.
3

Poproś agenta

“Wygeneruj obraz przyjaznej maskotki robota.”Agent automatycznie wywołuje image_generate. Nie trzeba dodawać narzędzia do listy dozwolonych - jest włączone domyślnie, gdy dostępny jest dostawca. Narzędzie zwraca identyfikator zadania w tle, a następnie agent ukończenia wysyła wygenerowany załącznik przez narzędzie message, gdy będzie gotowy.
W przypadku punktów końcowych LAN zgodnych z OpenAI, takich jak LocalAI, zachowaj niestandardowy models.providers.openai.baseUrl i jawnie włącz zgodę przez browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true. Prywatne i wewnętrzne punkty końcowe obrazów pozostają domyślnie zablokowane.

Typowe trasy

CelOdwołanie do modeluUwierzytelnianie
Generowanie obrazów OpenAI z rozliczeniem APIopenai/gpt-image-2OPENAI_API_KEY
Generowanie obrazów OpenAI z uwierzytelnianiem subskrypcji Codexopenai/gpt-image-2OpenAI ChatGPT/Codex OAuth
OpenAI PNG/WebP z przezroczystym tłemopenai/gpt-image-1.5OPENAI_API_KEY albo OpenAI Codex OAuth
Generowanie obrazów DeepInfradeepinfra/black-forest-labs/FLUX-1-schnellDEEPINFRA_API_KEY
fal Krea 2: ekspresyjne generowanie sterowane stylemfal/krea/v2/medium/text-to-imageFAL_KEY
Generowanie obrazów OpenRouteropenrouter/google/gemini-3.1-flash-image-previewOPENROUTER_API_KEY
Generowanie obrazów LiteLLMlitellm/gpt-image-2LITELLM_API_KEY
Generowanie obrazów Microsoft Foundry MAImicrosoft-foundry/<deployment-name>AZURE_OPENAI_API_KEY albo Entra ID
Generowanie obrazów Google Geminigoogle/gemini-3.1-flash-image-previewGEMINI_API_KEY albo GOOGLE_API_KEY
To samo narzędzie image_generate obsługuje generowanie tekst-na-obraz i edycję z obrazami referencyjnymi. Użyj image dla jednej referencji albo images dla wielu referencji. W przypadku modeli Krea 2 na fal te referencje są wysyłane jako referencje stylu zamiast wejść edycyjnych. Obsługiwane przez dostawcę podpowiedzi wyjściowe, takie jak quality, outputFormat i background, są przekazywane, gdy są dostępne, i raportowane jako zignorowane, gdy dostawca ich nie obsługuje. Wbudowana obsługa przezroczystego tła jest specyficzna dla OpenAI; inni dostawcy nadal mogą zachować alfę PNG, jeśli ich backend ją emituje.

Obsługiwani dostawcy

DostawcaModel domyślnyObsługa edycjiUwierzytelnianie
ComfyUIworkflowTak (1 obraz, skonfigurowane przez workflow)COMFY_API_KEY albo COMFY_CLOUD_API_KEY dla chmury
DeepInfrablack-forest-labs/FLUX-1-schnellTak (1 obraz)DEEPINFRA_API_KEY
falfal-ai/flux/devTak (limity zależne od modelu)FAL_KEY
Googlegemini-3.1-flash-image-previewTakGEMINI_API_KEY albo GOOGLE_API_KEY
LiteLLMgpt-image-2Tak (do 5 obrazów wejściowych)LITELLM_API_KEY
Microsoft Foundry<deployment-name>Tak (tylko modele MAI-Image-2.5)AZURE_OPENAI_API_KEY albo Entra ID (az login)
MiniMaximage-01Tak (referencja obiektu)MINIMAX_API_KEY albo MiniMax OAuth (minimax-portal)
OpenAIgpt-image-2Tak (do 4 obrazów)OPENAI_API_KEY albo OpenAI ChatGPT/Codex OAuth
OpenRoutergoogle/gemini-3.1-flash-image-previewTak (do 5 obrazów wejściowych)OPENROUTER_API_KEY
Vydragrok-imagineNieVYDRA_API_KEY
xAIgrok-imagine-imageTak (do 5 obrazów)XAI_API_KEY
Użyj action: "list", aby sprawdzić dostępnych dostawców i modele w czasie działania:
/tool image_generate action=list
Użyj action: "status", aby sprawdzić aktywne zadanie generowania obrazów dla bieżącej sesji:
/tool image_generate action=status

Możliwości dostawców

MożliwośćComfyUIDeepInfrafalGoogleMicrosoft FoundryMiniMaxOpenAIVydraxAI
Generowanie (maks. liczba)Zdefiniowane przez workflow44419414
Edycja / referencja1 obraz (workflow)1 obrazFlux: 1; GPT: 10; referencje stylu Krea: 10; NB2: 14Do 5 obrazów1 obraz1 obraz (referencja obiektu)Do 5 obrazów-Do 5 obrazów
Kontrola rozmiaru--Do 4K--
Proporcje obrazu-----
Rozdzielczość (1K/2K/4K)------1K, 2K

Parametry narzędzia

prompt
string
wymagane
Prompt generowania obrazu. Wymagany dla action: "generate".
action
"generate" | "status" | "list"
domyślnie:"generate"
Użyj "status", aby sprawdzić aktywne zadanie sesji, albo "list", aby sprawdzić dostępnych dostawców i modele w czasie działania.
model
string
Nadpisanie dostawcy/modelu (np. openai/gpt-image-2). Użyj openai/gpt-image-1.5 dla przezroczystych teł OpenAI.
image
string
Ścieżka albo URL pojedynczego obrazu referencyjnego dla trybu edycji.
images
string[]
Wiele obrazów referencyjnych dla trybu edycji albo modeli z referencjami stylu (do 10 przez wspólne narzędzie; nadal obowiązują limity specyficzne dla dostawcy).
size
string
Podpowiedź rozmiaru: 1024x1024, 1536x1024, 1024x1536, 2048x2048, 3840x2160.
aspectRatio
string
Proporcje obrazu: 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. Dostawcy walidują swój podzbiór specyficzny dla modelu.
resolution
"1K" | "2K" | "4K"
Podpowiedź rozdzielczości.
quality
"low" | "medium" | "high" | "auto"
Podpowiedź jakości, gdy dostawca ją obsługuje.
outputFormat
"png" | "jpeg" | "webp"
Podpowiedź formatu wyjściowego, gdy dostawca ją obsługuje.
background
"transparent" | "opaque" | "auto"
Podpowiedź tła, gdy dostawca ją obsługuje. Użyj transparent z outputFormat: "png" albo "webp" dla dostawców obsługujących przezroczystość.
count
number
Liczba obrazów do wygenerowania (1-4).
timeoutMs
number
Opcjonalny limit czasu żądania do dostawcy w milisekundach. Gdy Codex wywołuje image_generate przez narzędzia dynamiczne, ta wartość dla pojedynczego wywołania nadal nadpisuje skonfigurowaną wartość domyślną i jest ograniczona do 600000 ms.
filename
string
Podpowiedź nazwy pliku wyjściowego.
openai
object
Podpowiedzi tylko dla OpenAI: background, moderation, outputCompression i user.
fal.creativity
"raw" | "low" | "medium" | "high"
Kontrola kreatywności fal Krea 2. Domyślnie medium.
Nie wszyscy dostawcy obsługują wszystkie parametry. Gdy dostawca awaryjny obsługuje zbliżoną opcję geometrii zamiast dokładnie żądanej, OpenClaw przed wysłaniem mapuje ją na najbliższy obsługiwany rozmiar, proporcje obrazu albo rozdzielczość. Nieobsługiwane podpowiedzi wyjściowe są odrzucane dla dostawców, którzy nie deklarują obsługi, i raportowane w wyniku narzędzia. Wyniki narzędzia raportują zastosowane ustawienia; details.normalization zapisuje każdą translację z żądanej wartości na zastosowaną.

Konfiguracja

Wybór modelu

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

Kolejność wyboru dostawców

OpenClaw próbuje dostawców w tej kolejności:
  1. Parametr model z wywołania narzędzia (jeśli agent go określi).
  2. imageGenerationModel.primary z konfiguracji.
  3. imageGenerationModel.fallbacks w kolejności.
  4. Automatyczne wykrywanie - tylko domyślne ustawienia dostawców oparte na uwierzytelnianiu:
    • najpierw bieżący domyślny dostawca;
    • pozostali zarejestrowani dostawcy generowania obrazów w kolejności identyfikatorów dostawców.
Jeśli dostawca zawiedzie (błąd uwierzytelniania, limit szybkości itd.), następny skonfigurowany kandydat jest automatycznie próbowany. Jeśli wszystkie próby zawiodą, błąd zawiera szczegóły z każdej próby.
Nadpisanie model dla pojedynczego wywołania próbuje tylko tego dostawcy/modelu i nie przechodzi do skonfigurowanego podstawowego/zapasowego ani automatycznie wykrytych dostawców.
Domyślny dostawca trafia na listę kandydatów tylko wtedy, gdy OpenClaw może faktycznie uwierzytelnić tego dostawcę. Ustaw agents.defaults.mediaGenerationAutoProviderFallback: false, aby używać tylko jawnych wpisów model, primary i fallbacks.
Ustaw agents.defaults.imageGenerationModel.timeoutMs dla wolnych backendów obrazów. Parametr narzędzia timeoutMs dla pojedynczego wywołania nadpisuje skonfigurowaną wartość domyślną, a skonfigurowane wartości domyślne nadpisują wartości domyślne dostawcy zdefiniowane przez Plugin. Dostawcy obrazów hostowani przez Google i OpenRouter używają domyślnie 180 sekund; generowanie obrazów Microsoft Foundry MAI, xAI i Azure OpenAI używa 600 sekund. Wywołania narzędzi dynamicznych Codex używają domyślnego mostka image_generate wynoszącego 120 sekund i respektują ten sam budżet limitu czasu, gdy jest skonfigurowany, ograniczony przez maksymalny limit mostka narzędzi dynamicznych OpenClaw wynoszący 600000 ms.
Użyj action: "list", aby sprawdzić obecnie zarejestrowanych dostawców, ich modele domyślne oraz wskazówki dotyczące zmiennych środowiskowych uwierzytelniania.

Edycja obrazów

OpenAI, OpenRouter, Google, DeepInfra, fal, Microsoft Foundry, MiniMax, ComfyUI i xAI obsługują edycję obrazów referencyjnych. Modele Krea 2 w fal używają tych samych pól image / images jako odniesień stylu zamiast danych wejściowych edycji. Przekaż ścieżkę lub URL obrazu referencyjnego:
"Generate a watercolor version of this photo" + image: "/path/to/photo.jpg"
OpenAI, OpenRouter, Google i xAI obsługują do 5 obrazów referencyjnych przez parametr images. fal obsługuje 1 obraz referencyjny dla Flux image-to-image, do 10 dla edycji GPT Image 2, do 10 odniesień stylu dla Krea 2 i do 14 dla edycji Nano Banana 2. Microsoft Foundry, MiniMax i ComfyUI obsługują 1.

Szczegółowe omówienie dostawców

Generowanie obrazów OpenAI domyślnie używa openai/gpt-image-2. Jeśli skonfigurowano profil OAuth openai, OpenClaw ponownie używa tego samego profilu OAuth, którego używają modele czatu subskrypcji Codex, i wysyła żądanie obrazu przez backend Codex Responses. Starsze bazowe adresy URL Codex, takie jak https://chatgpt.com/backend-api, są kanonizowane do https://chatgpt.com/backend-api/codex dla żądań obrazów. OpenClaw nie przełącza się po cichu na OPENAI_API_KEY dla tego żądania - aby wymusić bezpośrednie trasowanie przez OpenAI Images API, skonfiguruj models.providers.openai jawnie z kluczem API, niestandardowym bazowym adresem URL lub punktem końcowym Azure.Modele openai/gpt-image-1.5, openai/gpt-image-1 i openai/gpt-image-1-mini nadal można wybrać jawnie. Użyj gpt-image-1.5 dla wyników PNG/WebP z przezroczystym tłem; obecne API gpt-image-2 odrzuca background: "transparent".gpt-image-2 obsługuje zarówno generowanie tekst-na-obraz, jak i edycję obrazu referencyjnego przez to samo narzędzie image_generate. OpenClaw przekazuje do OpenAI prompt, count, size, quality, outputFormat oraz obrazy referencyjne. OpenAI nie otrzymuje bezpośrednio aspectRatio ani resolution; gdy to możliwe, OpenClaw mapuje je na obsługiwane size, w przeciwnym razie narzędzie zgłasza je jako zignorowane nadpisania.Opcje specyficzne dla OpenAI znajdują się pod obiektem openai:
{
  "quality": "low",
  "outputFormat": "jpeg",
  "openai": {
    "background": "opaque",
    "moderation": "low",
    "outputCompression": 60,
    "user": "end-user-42"
  }
}
openai.background przyjmuje transparent, opaque lub auto; przezroczyste wyniki wymagają outputFormat png lub webp oraz modelu obrazów OpenAI obsługującego przezroczystość. OpenClaw trasuje domyślne żądania przezroczystego tła gpt-image-2 do gpt-image-1.5. openai.outputCompression dotyczy wyników JPEG/WebP i jest ignorowane dla wyników PNG.Wskazówka najwyższego poziomu background jest neutralna względem dostawcy i obecnie mapuje się na to samo pole żądania OpenAI background, gdy wybrany jest dostawca OpenAI. Dostawcy, którzy nie deklarują obsługi tła, zwracają ją w ignoredOverrides zamiast otrzymywać nieobsługiwany parametr.Aby trasować generowanie obrazów OpenAI przez wdrożenie Azure OpenAI zamiast api.openai.com, zobacz punkty końcowe Azure OpenAI.
Generowanie obrazów Microsoft Foundry używa nazw wdrożeń obrazów MAI pod prefiksem dostawcy microsoft-foundry/. Nie ma domyślnego modelu na poziomie dostawcy, ponieważ API MAI oczekuje nazwy wdrożenia w polu model:
{
  agents: {
    defaults: {
      imageGenerationModel: {
        primary: "microsoft-foundry/<deployment-name>",
        timeoutMs: 600_000,
      },
    },
  },
}
Dostawca używa MAI API Microsoft Foundry, a nie OpenAI Images API:
  • Punkt końcowy generowania: /mai/v1/images/generations
  • Punkt końcowy edycji: /mai/v1/images/edits
  • Uwierzytelnianie: AZURE_OPENAI_API_KEY / klucz API dostawcy albo Entra ID przez az login
  • Wynik: jeden obraz PNG
  • Rozmiar: domyślnie 1024x1024; szerokość i wysokość muszą mieć co najmniej 768 px, a łączna liczba pikseli musi wynosić co najwyżej 1 048 576
  • Edycje: jeden obraz referencyjny PNG lub JPEG, obsługiwany tylko przez wdrożenia MAI-Image-2.5-Flash i MAI-Image-2.5
Generowanie wyłącznie z promptu może używać niestandardowej nazwy wdrożenia tylko ze skonfigurowanym punktem końcowym Foundry. Edycje z niestandardowymi nazwami wdrożeń wymagają onboardingu/metadanych modelu, aby OpenClaw mógł zweryfikować, że wdrożenie jest oparte na MAI-Image-2.5-Flash lub MAI-Image-2.5.Obecne modele obrazów MAI to MAI-Image-2.5-Flash, MAI-Image-2.5, MAI-Image-2e i MAI-Image-2. Zobacz Plugin Microsoft Foundry, aby poznać konfigurację i zachowanie modeli czatu.
Generowanie obrazów OpenRouter używa tego samego OPENROUTER_API_KEY i trasuje przez obrazowe API uzupełnień czatu OpenRouter. Wybieraj modele obrazów OpenRouter z prefiksem openrouter/:
{
  agents: {
    defaults: {
      imageGenerationModel: {
        primary: "openrouter/google/gemini-3.1-flash-image-preview",
      },
    },
  },
}
OpenClaw przekazuje do OpenRouter prompt, count, obrazy referencyjne oraz zgodne z Gemini wskazówki aspectRatio / resolution. Obecne wbudowane skróty modeli obrazów OpenRouter obejmują google/gemini-3.1-flash-image-preview, google/gemini-3-pro-image-preview i openai/gpt-5.4-image-2. Użyj action: "list", aby zobaczyć, co udostępnia skonfigurowany Plugin.
Modele Krea 2 w fal używają natywnego schematu Krea fal zamiast ogólnego schematu image_size używanego przez Flux. OpenClaw wysyła:
  • aspect_ratio dla wskazówek proporcji obrazu
  • creativity, domyślnie medium
  • image_style_references, gdy podano image lub images
Wybierz Krea 2 Medium dla szybszej, ekspresyjnej ilustracji oraz Krea 2 Large dla wolniejszych, bardziej szczegółowych fotorealistycznych i teksturowanych efektów:
{
  agents: {
    defaults: {
      imageGenerationModel: {
        primary: "fal/krea/v2/medium/text-to-image",
      },
    },
  },
}
Krea 2 obecnie zwraca jeden obraz na żądanie. Preferuj aspectRatio dla Krea; OpenClaw mapuje size na najbliższą obsługiwaną proporcję Krea i odrzuca resolution dla Krea zamiast je pomijać. Użyj fal.creativity, gdy chcesz natywnego poziomu kreatywności Krea:
{
  "model": "fal/krea/v2/medium/text-to-image",
  "prompt": "A cyber zine portrait with risograph texture",
  "aspectRatio": "9:16",
  "fal": {
    "creativity": "high"
  }
}
Generowanie obrazów MiniMax jest dostępne przez obie dołączone ścieżki uwierzytelniania MiniMax:
  • minimax/image-01 dla konfiguracji z kluczem API
  • minimax-portal/image-01 dla konfiguracji OAuth
Dołączony dostawca xAI używa /v1/images/generations dla żądań wyłącznie z promptu oraz /v1/images/edits, gdy obecne jest image lub images.
  • Modele: xai/grok-imagine-image, xai/grok-imagine-image-quality
  • Liczba: do 4
  • Referencje: jedno image lub do pięciu images
  • Proporcje obrazu: 1:1, 16:9, 9:16, 4:3, 3:4, 2:3, 3:2
  • Rozdzielczości: 1K, 2K
  • Wyniki: zwracane jako załączniki obrazów zarządzane przez OpenClaw
OpenClaw celowo nie udostępnia natywnych dla xAI pól quality, mask, user ani dodatkowych natywnych proporcji obrazu, dopóki te kontrolki nie istnieją we wspólnym kontrakcie międzydostawcowym image_generate.

Przykłady

/tool image_generate action=generate model=openai/gpt-image-2 prompt="A clean editorial poster for OpenClaw image generation" size=3840x2160 count=1
Te same flagi --output-format, --background, --quality i --openai-moderation są dostępne w openclaw infer image edit; --openai-background pozostaje aliasem specyficznym dla OpenAI. Dołączeni dostawcy inni niż OpenAI nie deklarują obecnie jawnego sterowania tłem, więc background: "transparent" jest dla nich zgłaszane jako ignorowane.

Powiązane

  • Przegląd narzędzi - wszystkie dostępne narzędzia agenta
  • ComfyUI - konfiguracja lokalnego ComfyUI i przepływu pracy Comfy Cloud
  • fal - konfiguracja dostawcy obrazów i wideo fal
  • Google (Gemini) - konfiguracja dostawcy obrazów Gemini
  • Plugin Microsoft Foundry - konfiguracja czatu Microsoft Foundry i obrazów MAI
  • MiniMax - konfiguracja dostawcy obrazów MiniMax
  • OpenAI - konfiguracja dostawcy OpenAI Images
  • Vydra - konfiguracja obrazów, wideo i mowy Vydra
  • xAI - konfiguracja obrazów, wideo, wyszukiwania, wykonywania kodu i TTS Grok
  • Odniesienie do konfiguracji - konfiguracja imageGenerationModel
  • Modele - konfiguracja modelu i przełączanie awaryjne