image_generate erstellt und bearbeitet Bilder über Ihre konfigurierten
Provider. In Chatsitzungen wird es asynchron ausgeführt: OpenClaw zeichnet eine
Hintergrundaufgabe auf, gibt die Aufgaben-ID sofort zurück und reaktiviert den Agenten,
wenn der Provider fertig ist. Der Abschluss-Agent folgt dem normalen Modus der Sitzung
für sichtbare Antworten: automatische Zustellung der abschließenden Antwort, sofern
konfiguriert, oder message(action="send"), wenn die Sitzung das Nachrichtentool erfordert. Wenn die
anfragende Sitzung inaktiv ist oder ihre aktive Reaktivierung fehlschlägt, sendet OpenClaw
einen idempotenten direkten Fallback mit den generierten Bildern, damit das Ergebnis nicht
verloren geht.
Das Tool wird nur angezeigt, wenn mindestens ein Provider für die Bildgenerierung
verfügbar ist. Wenn
image_generate nicht unter den Tools Ihres Agenten angezeigt wird,
konfigurieren Sie agents.defaults.mediaModels.image, richten Sie einen Provider-API-Schlüssel ein
oder melden Sie sich mit OpenAI ChatGPT/Codex OAuth an.Schnellstart
1
Authentifizierung konfigurieren
Legen Sie einen API-Schlüssel für mindestens einen Provider fest (zum Beispiel
OPENAI_API_KEY,
GEMINI_API_KEY, OPENROUTER_API_KEY) oder melden Sie sich mit OpenAI Codex OAuth an.2
Ein Standardmodell auswählen (optional)
openai/gpt-image-2. Wenn ein
OAuth-Profil openai konfiguriert ist, leitet OpenClaw Bildanfragen
über dieses OAuth-Profil weiter, anstatt zuerst OPENAI_API_KEY zu versuchen.
Eine explizite Konfiguration von models.providers.openai (API-Schlüssel, benutzerdefinierte/Azure-Basis-URL)
aktiviert wieder die direkte Route über die OpenAI Images API.3
Den Agenten anweisen
„Generieren Sie ein Bild eines freundlichen Robotermaskottchens.“Der Agent ruft
image_generate automatisch auf. Eine Aufnahme in die Tool-Zulassungsliste
ist nicht erforderlich – das Tool ist standardmäßig aktiviert, wenn ein Provider verfügbar ist. Das Tool
gibt eine Hintergrundaufgaben-ID zurück. Anschließend sendet der Abschluss-Agent den
generierten Anhang über das Tool message, sobald er bereit ist.Häufige Routen
Dasselbe Tool verarbeitet Text-zu-Bild-Generierung und die Bearbeitung von Referenzbildern. Verwenden Sie
image
für eine Referenz oder images für mehrere. Bei Krea-2-Modellen auf fal werden diese
Referenzen als Stilreferenzen statt als Bearbeitungseingaben gesendet.
Vom Provider unterstützte Ausgabehinweise wie quality, outputFormat und
background werden weitergeleitet, wenn sie verfügbar sind, und als ignoriert gemeldet, wenn ein
Provider keine Unterstützung angibt. Die gebündelte Unterstützung für transparente Hintergründe ist
OpenAI-spezifisch; andere Provider können den PNG-Alphakanal dennoch beibehalten, wenn ihr
Backend ihn ausgibt.
Unterstützte Provider
Verwenden Sie
action: "list", um die zur Laufzeit verfügbaren Provider und Modelle zu prüfen:
action: "status", um die aktive Bildgenerierungsaufgabe für die
aktuelle Sitzung zu prüfen:
Provider-Funktionen
Tool-Parameter
string
erforderlich
Eingabeaufforderung für die Bildgenerierung. Für
action: "generate" erforderlich."generate" | "status" | "list"
Standard:"generate"
Verwenden Sie
"status", um die aktive Sitzungsaufgabe zu prüfen, oder "list", um
die zur Laufzeit verfügbaren Provider und Modelle zu prüfen.string
Überschreibung von Provider/Modell (z. B.
openai/gpt-image-2). Verwenden Sie
openai/gpt-image-1.5 für transparente OpenAI-Hintergründe.string
Pfad oder URL eines einzelnen Referenzbildes für den Bearbeitungsmodus.
string[]
Mehrere Referenzbilder für den Bearbeitungsmodus oder Modelle mit Stilreferenzen (bis zu 14
über das gemeinsame Tool; providerspezifische Beschränkungen gelten weiterhin).
string
Größenhinweis:
1024x1024, 1536x1024, 1024x1536, 2048x2048, 3840x2160.string
Seitenverhältnis:
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. Provider validieren ihre modellspezifische Teilmenge."1K" | "2K" | "4K"
Auflösungshinweis.
"low" | "medium" | "high" | "auto"
Qualitätshinweis, wenn der Provider ihn unterstützt.
"png" | "jpeg" | "webp"
Ausgabeformathinweis, wenn der Provider ihn unterstützt.
"transparent" | "opaque" | "auto"
Hintergrundhinweis, wenn der Provider ihn unterstützt. Verwenden Sie
transparent mit
outputFormat: "png" oder "webp" für Provider, die Transparenz unterstützen.number
Anzahl der zu generierenden Bilder (1-4).
number
Optionales Zeitlimit für Provider-Anfragen in Millisekunden. Wenn Codex
image_generate über dynamische Tools aufruft, überschreibt dieser Wert pro Aufruf weiterhin
den konfigurierten Standardwert und ist auf 600000 ms begrenzt.string
Hinweis zum Ausgabedateinamen.
object
Nur für OpenAI geltende Hinweise:
background, moderation, outputCompression und user."raw" | "low" | "medium" | "high"
Kreativitätssteuerung für fal Krea 2. Standardmäßig
medium.Nicht alle Provider unterstützen alle Parameter. Wenn ein Fallback-Provider statt der
exakt angeforderten Geometrieoption eine ähnliche unterstützt, ordnet OpenClaw die Anfrage vor
dem Senden der nächstgelegenen unterstützten Größe, dem nächstgelegenen Seitenverhältnis oder der
nächstgelegenen Auflösung zu. Nicht unterstützte Ausgabehinweise werden bei Providern verworfen,
die keine Unterstützung angeben, und im Tool-Ergebnis gemeldet. Tool-Ergebnisse melden die
angewendeten Einstellungen;
details.normalization erfasst jede Übersetzung
von angeforderten zu angewendeten Werten.Konfiguration
Modellauswahl
Reihenfolge der Provider-Auswahl
OpenClaw versucht Provider in dieser Reihenfolge:model-Parameter aus dem Tool-Aufruf (falls der Agent einen angibt).imageGenerationModel.primaryaus der Konfiguration.imageGenerationModel.fallbacksder Reihe nach.- Automatische Erkennung – nur durch Authentifizierung gestützte Provider-Standardwerte:
- zuerst der aktuelle Standard-Provider;
- anschließend die übrigen registrierten Provider für die Bildgenerierung, sortiert nach Provider-ID.
Modellüberschreibungen pro Aufruf gelten exakt
Modellüberschreibungen pro Aufruf gelten exakt
Eine
model-Überschreibung pro Aufruf versucht ausschließlich diesen Provider bzw. dieses Modell und
fährt nicht mit konfigurierten primären, Fallback- oder automatisch erkannten Providern fort.Die automatische Erkennung berücksichtigt die Authentifizierung
Die automatische Erkennung berücksichtigt die Authentifizierung
Ein Provider-Standardwert wird nur dann in die Kandidatenliste aufgenommen, wenn OpenClaw
diesen Provider tatsächlich authentifizieren kann. Automatisches Fallback zwischen authentifizierten
Providern ist immer aktiviert; ein
model pro Aufruf bleibt maßgeblich.Zeitüberschreitungen
Zeitüberschreitungen
Legen Sie
agents.defaults.mediaModels.image.timeoutMs für langsame Bild-
Backends fest. Ein timeoutMs-Tool-Parameter pro Aufruf überschreibt den konfigurierten
Standardwert, und konfigurierte Standardwerte überschreiben die vom Plugin definierten
Provider-Standardwerte. Bei Google und OpenRouter gehostete Bild-Provider verwenden
standardmäßig 180 Sekunden; die Bildgenerierung mit Microsoft Foundry MAI, xAI und Azure OpenAI verwendet
600 Sekunden. Aufrufe dynamischer Tools von Codex verwenden einen image_generate-
Bridge-Standardwert von 120 Sekunden und berücksichtigen bei entsprechender Konfiguration dasselbe Zeitlimit,
begrenzt durch das Maximum von 600000 ms für die Bridge dynamischer Tools von OpenClaw.Zur Laufzeit prüfen
Zur Laufzeit prüfen
Verwenden Sie
action: "list", um die derzeit registrierten Provider,
ihre Standardmodelle und Hinweise zu Umgebungsvariablen für die Authentifizierung zu prüfen.Bildbearbeitung
OpenAI, OpenRouter, Google, DeepInfra, fal, Microsoft Foundry, MiniMax, ComfyUI und xAI unterstützen die Bearbeitung von Referenzbildern. Krea-2-Modelle auf fal verwenden dieselben Felderimage / images als Stilreferenzen anstelle von
Bearbeitungseingaben. Übergeben Sie einen Pfad oder eine URL zu einem Referenzbild:
images bis zu 5 Referenzbilder; xAI unterstützt bis zu 3. fal unterstützt 1 Referenzbild für
Flux-Bild-zu-Bild, bis zu 10 für GPT-Image-2-Bearbeitungen, bis zu 10 Stilreferenzen
für Krea 2 und bis zu 14 für Nano-Banana-2-Bearbeitungen. Microsoft Foundry, MiniMax
und ComfyUI unterstützen 1.
Provider im Detail
OpenAI gpt-image-2 (und gpt-image-1.5)
OpenAI gpt-image-2 (und gpt-image-1.5)
Die OpenAI-Bildgenerierung verwendet standardmäßig
openai/gpt-image-2. Wenn ein
openai-OAuth-Profil konfiguriert ist, verwendet OpenClaw dasselbe
OAuth-Profil wie die Chatmodelle des Codex-Abonnements und sendet die
Bildanfrage über das Codex-Responses-Backend. Ältere Codex-Basis-
URLs wie https://chatgpt.com/backend-api werden für Bildanfragen zu
https://chatgpt.com/backend-api/codex kanonisiert. OpenClaw
weicht für diese Anfrage nicht stillschweigend auf OPENAI_API_KEY aus –
um das direkte Routing über die OpenAI Images API zu erzwingen, konfigurieren Sie
models.providers.openai ausdrücklich mit einem API-Schlüssel, einer benutzerdefinierten Basis-URL
oder einem Azure-Endpunkt.Die Modelle openai/gpt-image-1.5, openai/gpt-image-1 und
openai/gpt-image-1-mini können weiterhin ausdrücklich ausgewählt werden. Verwenden Sie
gpt-image-1.5 für PNG-/WebP-Ausgaben mit transparentem Hintergrund; die aktuelle
gpt-image-2-API lehnt background: "transparent" ab.gpt-image-2 unterstützt sowohl die Text-zu-Bild-Generierung als auch
die Bearbeitung von Referenzbildern über dasselbe image_generate-Tool.
OpenClaw leitet prompt, count, size, quality, outputFormat
und Referenzbilder an OpenAI weiter. OpenAI erhält
aspectRatio oder resolution nicht direkt; wenn möglich, ordnet OpenClaw
diese einem unterstützten size zu, andernfalls meldet das Tool sie als
ignorierte Überschreibungen.OpenAI-spezifische Optionen befinden sich unter dem Objekt openai:openai.background akzeptiert transparent, opaque oder auto;
transparente Ausgaben erfordern outputFormat png oder webp sowie ein
transparenzfähiges OpenAI-Bildmodell. OpenClaw leitet standardmäßige
gpt-image-2-Anfragen mit transparentem Hintergrund an gpt-image-1.5 weiter.
openai.outputCompression gilt für JPEG-/WebP-Ausgaben und wird
bei PNG-Ausgaben ignoriert.Der übergeordnete Hinweis background ist Provider-neutral und wird derzeit
demselben OpenAI-Anfragefeld background zugeordnet, wenn der OpenAI-Provider
ausgewählt ist. Provider, die keine Unterstützung für Hintergründe deklarieren, geben
ihn in ignoredOverrides zurück, anstatt den nicht unterstützten Parameter zu erhalten.Informationen zum Routing der OpenAI-Bildgenerierung über eine Azure-OpenAI-Bereitstellung
anstelle von api.openai.com finden Sie unter
Azure-OpenAI-Endpunkte.Microsoft-Foundry-MAI-Bildmodelle
Microsoft-Foundry-MAI-Bildmodelle
Die Microsoft-Foundry-Bildgenerierung verwendet die Namen bereitgestellter MAI-Bildbereitstellungen
unter dem Provider-Präfix Der Provider verwendet die MAI-API von Microsoft Foundry, nicht die OpenAI Images API:
microsoft-foundry/. Es gibt kein Standardmodell auf Provider-Ebene,
da die MAI-API den Namen Ihrer Bereitstellung im Feld
model erwartet:- Generierungsendpunkt:
/mai/v1/images/generations - Bearbeitungsendpunkt:
/mai/v1/images/edits - Authentifizierung:
AZURE_OPENAI_API_KEY/ Provider-API-Schlüssel oder Entra ID überaz login - Ausgabe: ein PNG-Bild
- Größe: standardmäßig
1024x1024; Breite und Höhe müssen jeweils mindestens 768 px betragen, und die Gesamtzahl der Pixel darf höchstens 1.048.576 betragen - Bearbeitungen: ein PNG- oder JPEG-Referenzbild, nur unterstützt von
den Bereitstellungen
MAI-Image-2.5-FlashundMAI-Image-2.5
MAI-Image-2.5-Flash oder MAI-Image-2.5 basiert.Aktuelle MAI-Bildmodelle sind MAI-Image-2.5-Flash, MAI-Image-2.5,
MAI-Image-2e und MAI-Image-2. Informationen zur Einrichtung
und zum Verhalten von Chatmodellen finden Sie unter
Microsoft-Foundry-Plugin.OpenRouter-Bildmodelle
OpenRouter-Bildmodelle
Die OpenRouter-Bildgenerierung verwendet dasselbe OpenClaw leitet
OPENROUTER_API_KEY und
wird über die Bild-API für Chat Completions von OpenRouter geleitet. Wählen Sie
OpenRouter-Bildmodelle mit dem Präfix openrouter/ aus:prompt, count, Referenzbilder und
Gemini-kompatible Hinweise aspectRatio / resolution an OpenRouter weiter.
Zu den aktuellen integrierten Kurzformen für OpenRouter-Bildmodelle gehören
google/gemini-3.1-flash-image,
google/gemini-3-pro-image und openai/gpt-5.4-image-2. Verwenden Sie
action: "list", um zu sehen, was Ihr konfiguriertes Plugin bereitstellt.fal Krea 2
fal Krea 2
Krea-2-Modelle auf fal verwenden das native Krea-Schema von fal anstelle des generischen
Krea 2 gibt derzeit ein Bild pro Anfrage zurück. Bevorzugen Sie
image_size-Schemas, das von Flux verwendet wird. OpenClaw sendet:aspect_ratiofür Hinweise zum Seitenverhältniscreativity, standardmäßigmediumimage_style_references, wennimageoderimagesangegeben werden
aspectRatio für
Krea; OpenClaw ordnet size dem nächstgelegenen unterstützten Krea-Seitenverhältnis zu und
lehnt resolution für Krea ab, anstatt es zu verwerfen. Verwenden Sie fal.creativity,
wenn Sie eine native Krea-Kreativitätsstufe wünschen:Doppelte MiniMax-Authentifizierung
Doppelte MiniMax-Authentifizierung
Die MiniMax-Bildgenerierung ist über beide gebündelten MiniMax-
Authentifizierungspfade verfügbar:
minimax/image-01für Einrichtungen mit API-Schlüsselminimax-portal/image-01für Einrichtungen mit OAuth
xAI grok-imagine-image
xAI grok-imagine-image
Der gebündelte xAI-Provider verwendet
/v1/images/generations für reine Prompt-
Anfragen und /v1/images/edits, wenn image oder images vorhanden ist.- Modelle:
xai/grok-imagine-image,xai/grok-imagine-image-quality - Anzahl: bis zu 4
- Referenzen: ein
imageoder bis zu dreiimages - Seitenverhältnisse:
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 - Auflösungen:
1K,2K - Ausgaben: werden als von OpenClaw verwaltete Bildanhänge zurückgegeben
quality, mask,
user oder das Seitenverhältnis auto bewusst nicht bereit, bis diese Steuerelemente im gemeinsamen
Provider-übergreifenden image_generate-Vertrag vorhanden sind.Beispiele
- Generieren (4K-Querformat)
- Generieren (transparentes PNG)
- Generieren (niedrige OpenAI-Qualität)
- Generieren (zwei quadratische Bilder)
- Bearbeiten (eine Referenz)
- Bearbeiten (mehrere Referenzen)
- Krea-Stilreferenzen
--output-format, --background, --quality und
--openai-moderation sind für openclaw infer image edit verfügbar;
--openai-background bleibt als OpenAI-spezifischer Alias erhalten. Gebündelte Provider
außer OpenAI deklarieren derzeit keine explizite Hintergrundsteuerung, daher wird
background: "transparent" für sie als ignoriert gemeldet.
Verwandte Themen
- Werkzeugübersicht - alle verfügbaren Agentenwerkzeuge
- ComfyUI - Einrichtung von Workflows für lokales ComfyUI und Comfy Cloud
- fal - Einrichtung des Providers fal für Bilder und Videos
- Google (Gemini) - Einrichtung des Gemini-Bild-Providers
- Microsoft Foundry-Plugin - Einrichtung von Microsoft Foundry Chat und MAI-Bildern
- MiniMax - Einrichtung des MiniMax-Bild-Providers
- OpenAI - Einrichtung des OpenAI Images-Providers
- Vydra - Einrichtung von Vydra für Bilder, Videos und Sprache
- xAI - Einrichtung von Grok für Bilder, Videos, Suche, Codeausführung und TTS
- Konfigurationsreferenz - Konfiguration von
imageGenerationModel - Modelle - Modellkonfiguration und Failover