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
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.Wybierz model domyślny (opcjonalnie)
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.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.Typowe trasy
| Cel | Odwołanie do modelu | Uwierzytelnianie |
|---|---|---|
| Generowanie obrazów OpenAI z rozliczeniem API | openai/gpt-image-2 | OPENAI_API_KEY |
| Generowanie obrazów OpenAI z uwierzytelnianiem subskrypcji Codex | openai/gpt-image-2 | OpenAI ChatGPT/Codex OAuth |
| OpenAI PNG/WebP z przezroczystym tłem | openai/gpt-image-1.5 | OPENAI_API_KEY albo OpenAI Codex OAuth |
| Generowanie obrazów DeepInfra | deepinfra/black-forest-labs/FLUX-1-schnell | DEEPINFRA_API_KEY |
| fal Krea 2: ekspresyjne generowanie sterowane stylem | fal/krea/v2/medium/text-to-image | FAL_KEY |
| Generowanie obrazów OpenRouter | openrouter/google/gemini-3.1-flash-image-preview | OPENROUTER_API_KEY |
| Generowanie obrazów LiteLLM | litellm/gpt-image-2 | LITELLM_API_KEY |
| Generowanie obrazów Microsoft Foundry MAI | microsoft-foundry/<deployment-name> | AZURE_OPENAI_API_KEY albo Entra ID |
| Generowanie obrazów Google Gemini | google/gemini-3.1-flash-image-preview | GEMINI_API_KEY albo GOOGLE_API_KEY |
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
| Dostawca | Model domyślny | Obsługa edycji | Uwierzytelnianie |
|---|---|---|---|
| ComfyUI | workflow | Tak (1 obraz, skonfigurowane przez workflow) | COMFY_API_KEY albo COMFY_CLOUD_API_KEY dla chmury |
| DeepInfra | black-forest-labs/FLUX-1-schnell | Tak (1 obraz) | DEEPINFRA_API_KEY |
| fal | fal-ai/flux/dev | Tak (limity zależne od modelu) | FAL_KEY |
gemini-3.1-flash-image-preview | Tak | GEMINI_API_KEY albo GOOGLE_API_KEY | |
| LiteLLM | gpt-image-2 | Tak (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) |
| MiniMax | image-01 | Tak (referencja obiektu) | MINIMAX_API_KEY albo MiniMax OAuth (minimax-portal) |
| OpenAI | gpt-image-2 | Tak (do 4 obrazów) | OPENAI_API_KEY albo OpenAI ChatGPT/Codex OAuth |
| OpenRouter | google/gemini-3.1-flash-image-preview | Tak (do 5 obrazów wejściowych) | OPENROUTER_API_KEY |
| Vydra | grok-imagine | Nie | VYDRA_API_KEY |
| xAI | grok-imagine-image | Tak (do 5 obrazów) | XAI_API_KEY |
action: "list", aby sprawdzić dostępnych dostawców i modele w czasie działania:
action: "status", aby sprawdzić aktywne zadanie generowania obrazów dla
bieżącej sesji:
Możliwości dostawców
| Możliwość | ComfyUI | DeepInfra | fal | Microsoft Foundry | MiniMax | OpenAI | Vydra | xAI | |
|---|---|---|---|---|---|---|---|---|---|
| Generowanie (maks. liczba) | Zdefiniowane przez workflow | 4 | 4 | 4 | 1 | 9 | 4 | 1 | 4 |
| Edycja / referencja | 1 obraz (workflow) | 1 obraz | Flux: 1; GPT: 10; referencje stylu Krea: 10; NB2: 14 | Do 5 obrazów | 1 obraz | 1 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 generowania obrazu. Wymagany dla
action: "generate".Użyj
"status", aby sprawdzić aktywne zadanie sesji, albo "list", aby sprawdzić
dostępnych dostawców i modele w czasie działania.Nadpisanie dostawcy/modelu (np.
openai/gpt-image-2). Użyj
openai/gpt-image-1.5 dla przezroczystych teł OpenAI.Ścieżka albo URL pojedynczego obrazu referencyjnego dla trybu edycji.
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).
Podpowiedź rozmiaru:
1024x1024, 1536x1024, 1024x1536, 2048x2048, 3840x2160.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.Podpowiedź rozdzielczości.
Podpowiedź jakości, gdy dostawca ją obsługuje.
Podpowiedź formatu wyjściowego, gdy dostawca ją obsługuje.
Podpowiedź tła, gdy dostawca ją obsługuje. Użyj
transparent z
outputFormat: "png" albo "webp" dla dostawców obsługujących przezroczystość.Liczba obrazów do wygenerowania (1-4).
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.Podpowiedź nazwy pliku wyjściowego.
Podpowiedzi tylko dla OpenAI:
background, moderation, outputCompression i user.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
Kolejność wyboru dostawców
OpenClaw próbuje dostawców w tej kolejności:- Parametr
modelz wywołania narzędzia (jeśli agent go określi). imageGenerationModel.primaryz konfiguracji.imageGenerationModel.fallbacksw kolejności.- 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.
Nadpisania modelu dla pojedynczego wywołania są dokładne
Nadpisania modelu dla pojedynczego wywołania są dokładne
Nadpisanie
model dla pojedynczego wywołania próbuje tylko tego dostawcy/modelu i
nie przechodzi do skonfigurowanego podstawowego/zapasowego ani automatycznie wykrytych dostawców.Automatyczne wykrywanie uwzględnia uwierzytelnianie
Automatyczne wykrywanie uwzględnia uwierzytelnianie
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.Limity czasu
Limity czasu
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.Inspekcja w czasie działania
Inspekcja w czasie działania
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ólimage / images jako odniesień stylu zamiast danych wejściowych edycji. Przekaż
ścieżkę lub URL obrazu referencyjnego:
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
OpenAI gpt-image-2 (i gpt-image-1.5)
OpenAI gpt-image-2 (i gpt-image-1.5)
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: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.Modele obrazów Microsoft Foundry MAI
Modele obrazów Microsoft Foundry MAI
Generowanie obrazów Microsoft Foundry używa nazw wdrożeń obrazów MAI
pod prefiksem dostawcy Dostawca używa MAI API Microsoft Foundry, a nie OpenAI Images API:
microsoft-foundry/. Nie ma domyślnego modelu
na poziomie dostawcy, ponieważ API MAI oczekuje nazwy wdrożenia w polu
model:- 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 przezaz 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-FlashiMAI-Image-2.5
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.Modele obrazów OpenRouter
Modele obrazów OpenRouter
Generowanie obrazów OpenRouter używa tego samego OpenClaw przekazuje do OpenRouter
OPENROUTER_API_KEY i
trasuje przez obrazowe API uzupełnień czatu OpenRouter. Wybieraj
modele obrazów OpenRouter z prefiksem 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.fal Krea 2
fal Krea 2
Modele Krea 2 w fal używają natywnego schematu Krea fal zamiast ogólnego
schematu Krea 2 obecnie zwraca jeden obraz na żądanie. Preferuj
image_size używanego przez Flux. OpenClaw wysyła:aspect_ratiodla wskazówek proporcji obrazucreativity, domyślniemediumimage_style_references, gdy podanoimagelubimages
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:Podwójne uwierzytelnianie MiniMax
Podwójne uwierzytelnianie MiniMax
Generowanie obrazów MiniMax jest dostępne przez obie dołączone ścieżki
uwierzytelniania MiniMax:
minimax/image-01dla konfiguracji z kluczem APIminimax-portal/image-01dla konfiguracji OAuth
xAI grok-imagine-image
xAI grok-imagine-image
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
imagelub do pięciuimages - 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
quality, mask,
user ani dodatkowych natywnych proporcji obrazu, dopóki te kontrolki nie istnieją
we wspólnym kontrakcie międzydostawcowym image_generate.Przykłady
- Generowanie (krajobraz 4K)
- Generowanie (przezroczysty PNG)
- Generowanie (niska jakość OpenAI)
- Generate (two square)
- Edit (one reference)
- Edit (multiple references)
- Krea style references
--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