image_generate tworzy i edytuje obrazy za pośrednictwem skonfigurowanych
dostawców. W sesjach czatu działa asynchronicznie: OpenClaw rejestruje
zadanie w tle, natychmiast zwraca identyfikator zadania i wybudza agenta, gdy
dostawca zakończy pracę. Agent kończący stosuje zwykły tryb widocznej
odpowiedzi sesji: automatyczne dostarczenie odpowiedzi końcowej, jeśli zostało
skonfigurowane, albo message(action="send"), gdy sesja wymaga narzędzia
wiadomości. Jeśli sesja zlecającego jest nieaktywna lub jej aktywne wybudzenie
się nie powiedzie, OpenClaw wysyła idempotentną bezpośrednią wiadomość
awaryjną z wygenerowanymi obrazami, aby wynik nie został utracony.
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 lub zaloguj się przez OpenAI ChatGPT/Codex OAuth.Szybki start
1
Skonfiguruj uwierzytelnianie
Ustaw klucz API co najmniej jednego dostawcy (na przykład
OPENAI_API_KEY,
GEMINI_API_KEY, OPENROUTER_API_KEY) lub zaloguj się przez OpenAI Codex OAuth.2
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ć użyć OPENAI_API_KEY. Jawna konfiguracja
models.providers.openai (klucz API, niestandardowy lub Azure bazowy adres
URL) ponownie włącza bezpośrednią ścieżkę przez OpenAI Images API.3
Poproś agenta
„Wygeneruj obraz przyjaznej maskotki-robota”.Agent automatycznie wywołuje
image_generate. Nie trzeba dodawać narzędzia
do listy dozwolonych — jest domyślnie włączone, gdy dostępny jest dostawca.
Narzędzie zwraca identyfikator zadania w tle, a następnie agent kończący
wysyła wygenerowany załącznik przez narzędzie message, gdy jest gotowy.Typowe ścieżki
To samo narzędzie obsługuje generowanie obrazu z tekstu oraz edycję z użyciem
obrazu referencyjnego. Użyj
image dla jednego obrazu referencyjnego lub
images dla wielu. W przypadku modeli Krea 2 w fal te obrazy referencyjne są
przesyłane jako odniesienia stylistyczne zamiast danych wejściowych do edycji.
Obsługiwane przez dostawcę wskazówki dotyczące wyniku, takie jak quality,
outputFormat i background, są przekazywane, gdy jest to możliwe, a gdy
dostawca nie deklaruje ich obsługi, są zgłaszane jako zignorowane. Wbudowana
obsługa przezroczystego tła jest właściwa dla OpenAI; inni dostawcy również
mogą zachować kanał alfa PNG, jeśli generuje go ich zaplecze.
Obsługiwani dostawcy
Użyj
action: "list", aby sprawdzić dostawców i modele dostępne w czasie działania:
action: "status", aby sprawdzić aktywne zadanie generowania obrazów dla
bieżącej sesji:
Możliwości dostawców
Parametry narzędzia
string
wymagane
Polecenie generowania obrazu. Wymagane dla
action: "generate"."generate" | "status" | "list"
domyślnie:"generate"
Użyj
"status", aby sprawdzić aktywne zadanie sesji, lub "list", aby
sprawdzić dostawców i modele dostępne w czasie działania.string
Zastąpienie dostawcy/modelu (np.
openai/gpt-image-2). Użyj
openai/gpt-image-1.5 dla przezroczystych teł OpenAI.string
Ścieżka lub adres URL pojedynczego obrazu referencyjnego dla trybu edycji.
string[]
Wiele obrazów referencyjnych dla trybu edycji lub modeli korzystających z
odniesień stylistycznych (do 14 za pośrednictwem wspólnego narzędzia; nadal
obowiązują limity właściwe dla dostawcy).
string
Wskazówka rozmiaru:
1024x1024, 1536x1024, 1024x1536, 2048x2048, 3840x2160.string
Proporcje obrazu:
1:1, 2:1, 20:9, 19.5:9, 2:3, 3:2, 2.35:1, 3:4,
4:3, 4:5, 5:4, 9:16, 9:19.5, 9:20, 16:9, 21:9, 1:2, 4:1,
1:4, 8:1, 1:8. Dostawcy weryfikują podzbiór właściwy dla danego modelu."1K" | "2K" | "4K"
Wskazówka rozdzielczości.
"low" | "medium" | "high" | "auto"
Wskazówka jakości, gdy dostawca ją obsługuje.
"png" | "jpeg" | "webp"
Wskazówka formatu wyjściowego, gdy dostawca go obsługuje.
"transparent" | "opaque" | "auto"
Wskazówka dotycząca tła, gdy dostawca ją obsługuje. Użyj
transparent wraz
z outputFormat: "png" lub "webp" w przypadku dostawców obsługujących
przezroczystość.number
Liczba obrazów do wygenerowania (1–4).
number
Opcjonalny limit czasu żądania do dostawcy w milisekundach. Gdy Codex
wywołuje
image_generate za pośrednictwem narzędzi dynamicznych, ta wartość
dla pojedynczego wywołania nadal zastępuje skonfigurowaną wartość domyślną
i jest ograniczona do 600000 ms.string
Wskazówka nazwy pliku wyjściowego.
object
Wskazówki wyłącznie dla OpenAI:
background, moderation, outputCompression i user."raw" | "low" | "medium" | "high"
Sterowanie kreatywnością fal Krea 2. Wartość domyślna to
medium.Nie wszyscy dostawcy obsługują wszystkie parametry. Gdy dostawca awaryjny
obsługuje zbliżoną opcję geometrii zamiast dokładnie żądanej, OpenClaw przed
przesłaniem mapuje ją na najbliższy obsługiwany rozmiar, proporcje obrazu lub
rozdzielczość. Nieobsługiwane wskazówki dotyczące wyniku są pomijane w
przypadku dostawców, którzy nie deklarują ich obsługi, i zgłaszane w wyniku
narzędzia. Wyniki narzędzia zawierają zastosowane ustawienia;
details.normalization rejestruje każde przekształcenie wartości żądanej na
zastosowaną.Konfiguracja
Wybór modelu
Kolejność wyboru dostawców
OpenClaw próbuje użyć dostawców w następującej kolejności:- Parametr
modelz wywołania narzędzia (jeśli agent go określi). imageGenerationModel.primaryz konfiguracji.imageGenerationModel.fallbacksw podanej kolejności.- Automatyczne wykrywanie — tylko domyślni dostawcy z dostępnym uwierzytelnianiem:
- najpierw bieżący domyślny dostawca;
- następnie pozostali zarejestrowani dostawcy generowania obrazów, według identyfikatora dostawcy.
Per-call model overrides are exact
Per-call model overrides are exact
Nadpisanie
model dla pojedynczego wywołania powoduje wypróbowanie tylko
tego dostawcy i modelu, bez przechodzenia do skonfigurowanego modelu
podstawowego, modeli rezerwowych ani automatycznie wykrytych dostawców.Auto-detection is auth-aware
Auto-detection is auth-aware
Domyślny model dostawcy trafia na listę kandydatów tylko wtedy, gdy OpenClaw
może faktycznie uwierzytelnić się u tego dostawcy. Ustaw
agents.defaults.mediaGenerationAutoProviderFallback: false, aby używać
wyłącznie jawnych wpisów model, primary i fallbacks.Timeouts
Timeouts
Ustaw
agents.defaults.imageGenerationModel.timeoutMs dla wolnych
mechanizmów generowania 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 dostawców
określone przez plugin. Hostowani dostawcy obrazów Google i OpenRouter
domyślnie używają 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 limitu 120 sekund dla mostka image_generate
i po skonfigurowaniu respektują ten sam budżet czasu, ograniczony
maksymalnym limitem 600000 ms mostka narzędzi dynamicznych OpenClaw.Inspect at runtime
Inspect at runtime
Użyj
action: "list", aby sprawdzić aktualnie zarejestrowanych dostawców,
ich domyślne modele 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 referencji stylu, a nie jako
danych wejściowych do edycji. Przekaż ścieżkę lub adres URL obrazu
referencyjnego:
images; xAI obsługuje do 3. fal obsługuje 1 obraz referencyjny
dla konwersji obrazu na obraz w Flux, do 10 dla edycji GPT Image 2, do 10
referencji stylu dla Krea 2 oraz 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 (and gpt-image-1.5)
OpenAI gpt-image-2 (and gpt-image-1.5)
Generowanie obrazów OpenAI domyślnie używa
openai/gpt-image-2. Jeśli
skonfigurowano profil OAuth openai, OpenClaw ponownie wykorzystuje ten
sam profil OAuth, którego używają modele czatu subskrypcji Codex,
i wysyła żądanie obrazu przez mechanizm Codex Responses. Starsze bazowe
adresy URL Codex, takie jak https://chatgpt.com/backend-api, są
normalizowane do https://chatgpt.com/backend-api/codex na potrzeby
żądań obrazów. OpenClaw nie przełącza się niejawnie na
OPENAI_API_KEY dla takiego żądania — aby wymusić bezpośrednie kierowanie
do OpenAI Images API, skonfiguruj jawnie models.providers.openai
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 wybierać jawnie. Użyj
gpt-image-1.5, aby uzyskać pliki PNG/WebP z przezroczystym tłem;
bieżące API gpt-image-2 odrzuca background: "transparent".gpt-image-2 obsługuje zarówno generowanie obrazu z tekstu, jak i edycję
obrazu referencyjnego za pomocą tego samego narzędzia image_generate.
OpenClaw przekazuje do OpenAI prompt, count, size, quality,
outputFormat oraz obrazy referencyjne. OpenAI nie otrzymuje
bezpośrednio aspectRatio ani resolution; gdy jest to możliwe, OpenClaw
mapuje je na obsługiwaną wartość size, a w przeciwnym razie narzędzie
zgłasza je jako zignorowane nadpisania.Opcje specyficzne dla OpenAI znajdują się w obiekcie openai:openai.background przyjmuje transparent, opaque lub auto;
przezroczyste obrazy wyjściowe wymagają wartości png albo webp dla
outputFormat oraz modelu obrazów OpenAI obsługującego przezroczystość.
OpenClaw kieruje domyślne żądania gpt-image-2 z przezroczystym tłem
do gpt-image-1.5. openai.outputCompression ma zastosowanie do obrazów
wyjściowych JPEG/WebP i jest ignorowane dla obrazów PNG.Wskazówka background najwyższego poziomu jest niezależna od dostawcy
i obecnie jest mapowana na to samo pole żądania OpenAI background,
gdy wybrano dostawcę OpenAI. Dostawcy, którzy nie deklarują obsługi tła,
zwracają ją w ignoredOverrides, zamiast otrzymywać nieobsługiwany
parametr.Aby kierować generowanie obrazów OpenAI przez wdrożenie Azure OpenAI
zamiast api.openai.com, zobacz
punkty końcowe Azure OpenAI.Microsoft Foundry MAI image models
Microsoft Foundry MAI image models
Generowanie obrazów Microsoft Foundry używa nazw wdrożeń obrazów MAI
z prefiksem dostawcy Dostawca używa API MAI Microsoft Foundry, a nie OpenAI Images API:
microsoft-foundry/. Nie istnieje domyślny model
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 - Dane wyjściowe: jeden obraz PNG
- Rozmiar: domyślnie
1024x1024; szerokość i wysokość muszą wynosić co najmniej 768 px, a łączna liczba pikseli nie może przekraczać 1 048 576 - Edycja: 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 albo MAI-Image-2.5.Bieżące modele obrazów MAI to MAI-Image-2.5-Flash, MAI-Image-2.5,
MAI-Image-2e i MAI-Image-2. Informacje o konfiguracji i działaniu
modeli czatu zawiera
plugin Microsoft Foundry.OpenRouter image models
OpenRouter image models
Generowanie obrazów OpenRouter używa tego samego OpenClaw przekazuje do OpenRouter
OPENROUTER_API_KEY
i jest kierowane przez API obrazów uzupełnień czatu OpenRouter. Wybieraj
modele obrazów OpenRouter z prefiksem openrouter/:prompt, count, obrazy referencyjne
oraz zgodne z Gemini wskazówki aspectRatio / resolution. Bieżące
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 dostarczanego przez
fal zamiast ogólnego schematu Krea 2 zwraca obecnie jeden obraz na żądanie. W przypadku Krea preferuj
image_size używanego przez Flux. OpenClaw
wysyła:aspect_ratiodla wskazówek dotyczących proporcji obrazucreativity, domyślniemediumimage_style_references, gdy podanoimagelubimages
aspectRatio; OpenClaw mapuje size na najbliższe obsługiwane proporcje
Krea, natomiast odrzuca resolution dla Krea zamiast je pomijać. Użyj
fal.creativity, jeśli chcesz ustawić natywny poziom kreatywności Krea:MiniMax dual-auth
MiniMax dual-auth
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ń opartych
wyłącznie na monicie oraz /v1/images/edits, gdy występuje image
lub images.- Modele:
xai/grok-imagine-image,xai/grok-imagine-image-quality - Liczba: do 4
- Referencje: jedno
imagelub maksymalnie trzyimages - Proporcje obrazu:
1:1,16:9,9:16,4:3,3:4,3:2,2:3,2:1,1:2,19.5:9,9:19.5,20:9,9:20 - Rozdzielczości:
1K,2K - Dane wyjściowe: zwracane jako załączniki obrazów zarządzane przez OpenClaw
quality, mask,
user ani proporcji obrazu auto, dopóki te mechanizmy sterowania nie
znajdą się we wspólnej, międzydostawczej umowie image_generate.Przykłady
- Generate (4K landscape)
- Generate (transparent PNG)
- Generate (OpenAI low quality)
- Generowanie (dwa kwadratowe obrazy)
- Edycja (jeden obraz referencyjny)
- Edycja (wiele obrazów referencyjnych)
- Referencje stylu Krea
--output-format, --background, --quality i
--openai-moderation są dostępne w poleceniu openclaw infer image edit;
--openai-background pozostaje aliasem właściwym dla OpenAI. Obecnie wbudowani dostawcy
inni niż OpenAI nie deklarują jawnego sterowania tłem, dlatego
background: "transparent" jest w ich przypadku zgłaszane jako zignorowane.
Powiązane materiały
- Przegląd narzędzi — wszystkie dostępne narzędzia agenta
- ComfyUI — konfiguracja lokalnego przepływu pracy ComfyUI i 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
- Dokumentacja konfiguracji — konfiguracja
imageGenerationModel - Modele — konfiguracja modeli i przełączanie awaryjne