Skip to main content
Narzędzie 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)

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ć 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.
W przypadku punktów końcowych w sieci LAN zgodnych z OpenAI, takich jak LocalAI, zachowaj niestandardowe ustawienie models.providers.openai.baseUrl i jawnie włącz browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true. Prywatne i wewnętrzne punkty końcowe obrazów pozostają domyślnie zablokowane.

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:
Użyj 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:
  1. Parametr model z wywołania narzędzia (jeśli agent go określi).
  2. imageGenerationModel.primary z konfiguracji.
  3. imageGenerationModel.fallbacks w podanej kolejności.
  4. 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.
Jeśli dostawca zawiedzie (błąd uwierzytelniania, limit żądań itp.), automatycznie wypróbowywany jest następny skonfigurowany kandydat. Jeśli zawiodą wszyscy, błąd zawiera szczegóły każdej próby.
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.
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.
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.
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ól image / images jako referencji stylu, a nie jako danych wejściowych do edycji. Przekaż ścieżkę lub adres URL obrazu referencyjnego:
OpenAI, OpenRouter i Google obsługują do 5 obrazów referencyjnych za pomocą parametru 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

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.
Generowanie obrazów Microsoft Foundry używa nazw wdrożeń obrazów MAI z prefiksem dostawcy microsoft-foundry/. Nie istnieje domyślny model na poziomie dostawcy, ponieważ API MAI oczekuje nazwy wdrożenia w polu model:
Dostawca używa API MAI 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
  • 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-Flash i MAI-Image-2.5
Generowanie wyłącznie na podstawie monitu może używać niestandardowej nazwy wdrożenia po skonfigurowaniu samego punktu końcowego Foundry. Edycja z niestandardowymi nazwami wdrożeń wymaga metadanych wdrażania lub modelu, aby OpenClaw mógł sprawdzić, czy wdrożenie jest oparte na 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.
Generowanie obrazów OpenRouter używa tego samego OPENROUTER_API_KEY i jest kierowane przez API obrazów uzupełnień czatu OpenRouter. Wybieraj modele obrazów OpenRouter z prefiksem openrouter/:
OpenClaw przekazuje do 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.
Modele Krea 2 w fal używają natywnego schematu Krea dostarczanego przez fal zamiast ogólnego schematu image_size używanego przez Flux. OpenClaw wysyła:
  • aspect_ratio dla wskazówek dotyczących proporcji obrazu
  • creativity, domyślnie medium
  • image_style_references, gdy podano image lub images
Wybierz Krea 2 Medium, aby szybciej tworzyć ekspresyjne ilustracje, lub Krea 2 Large, aby wolniej uzyskiwać bardziej szczegółowy, fotorealistyczny wygląd z wyraźnymi teksturami:
Krea 2 zwraca obecnie jeden obraz na żądanie. W przypadku Krea preferuj 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:
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ń 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 image lub maksymalnie trzy images
  • 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
OpenClaw celowo nie udostępnia natywnych dla xAI opcji 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

Te same flagi --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