Bilder mit OpenClaw generieren und bearbeiten: Modelle, Anbieter und Auslieferung einrichten

OpenClaw kann mit dem Werkzeug image_generate Bilder erzeugen und vorhandene Bilder bearbeiten. Dafür braucht die Agentenplattform einen berechtigten Bildanbieter; ein Modellname allein genügt nicht. Dieser Durchlauf richtet einen Standard ein, prüft Generierung und Bearbeitung getrennt und zeigt den Rückweg zur vorherigen Einstellung.

Voraussetzungen: Zugang vor Modellwahl

Du brauchst eine laufende OpenClaw-Installation, Zugriff auf deren Konfiguration und einen beim Anbieter freigeschalteten Bildzugang. Die Bild-Dokumentation nennt unter anderem API-Schlüssel sowie OpenAI-ChatGPT/Codex-OAuth. Prüfe die Berechtigung für das gewählte Modell und die Abrechnung deines Zugangs vor dem ersten Test. Bildanfragen können kostenpflichtig sein; prüfe Modellfreigabe und Kontingent unabhängig von deiner Chat-Anmeldung.

Die Anbieter-Authentifizierung ist Pflicht. Ein ausdrücklich gesetztes Standardmodell ist dagegen optional: OpenClaw kann verfügbare Bildanbieter auch automatisch erkennen. In diesem Tutorial legen wir den Standard bewusst fest, damit das Testergebnis nachvollziehbar bleibt.

Wenn noch kein OpenAI-OAuth-Profil eingerichtet ist und du einen API-Schlüssel verwenden willst, öffnest du die globale Runtime-Datei ~/.openclaw/.env in einem lokalen Editor und ergänzt die Variable deines Anbieters, bei OpenAI beispielsweise OPENAI_API_KEY. Bestehende Einträge bleiben erhalten. Setze den Dateimodus auf 0600 (POSIX-Referenz zu chmod):

chmod 600 ~/.openclaw/.env

Das ist der in der Umgebungsvariablen-Dokumentation empfohlene Ablageort für Provider-Schlüssel. Eine Workspace-.env ist dafür kein Ersatz. Schreibe echte Schlüssel weder in Bildprompts noch in den folgenden Modellblock, ein Repository oder öffentlich geteilte Diagnoseausgaben. Nutzt du bereits einen passenden OpenAI-ChatGPT/Codex-OAuth-Zugang, bleibst du für diesen Durchlauf dabei und legst keinen zusätzlichen API-Schlüssel an. Die Bild-Dokumentation gibt einem vorhandenen OpenAI-OAuth-Profil Vorrang gegenüber OPENAI_API_KEY. Ein Schlüssel allein schaltet diese Installation also nicht auf API-Abrechnung um. Ein bewusster Wechsel zur direkten Images API benötigt eine ausdrückliche models.providers.openai-Konfiguration; diesen zusätzlichen Provider-Umbau nehmen wir hier nicht vor. Möchtest du gerade diesen Wechsel, kläre ihn anhand der Anbieter-Dokumentation, bevor du kostenpflichtige Tests startest. Starte nach einer Änderung der Runtime-Umgebung den Gateway-Dienst neu und prüfe anschließend die Anbieterübersicht.

1. Ausgangszustand sichern und nur den Bildblock ändern

Plane die kurze Gateway-Unterbrechung, bevor du die Konfiguration änderst. Laufende Agentenaufträge sollten vorher abgeschlossen sein. Die folgenden Befehle sind für eine lokale Installation mit installiertem Gateway-Dienst gedacht; bei Containern oder einem externen Service-Manager steuerst du den Dienst über dessen Betreiberwerkzeug.

Prüfe zunächst die vorhandene Bildeinstellung und speichere ihren JSON-Wert lokal:

openclaw config get agents.defaults.mediaModels.image --json
openclaw config get agents.defaults.mediaModels.image --json > image-model-before.json

Wenn der Pfad noch nicht existiert, notiere stattdessen ausdrücklich „vorher nicht gesetzt“. Die fehlerhafte oder leere Ausgabedatei ist dann keine Rücksicherung. Veröffentliche auch lokale Sicherungen nicht.

Lege anschließend eine Datei image-model.patch.json5 mit diesem Inhalt an:

{
  agents: {
    defaults: {
      mediaModels: {
        image: {
          primary: "openai/gpt-image-2",
          timeoutMs: 180000,
        },
      },
    },
  },
}

Die Config-CLI führt Objekt-Patches rekursiv zusammen. Damit ersetzt dieses Beispiel nicht deine gesamte Gateway-Konfiguration. Bereits vorhandene Bild-Fallbacks bleiben erhalten; prüfe sie vorher mit, denn sie können das tatsächlich verwendete Modell beeinflussen. Arrays werden beim Patchen dagegen ersetzt, nicht elementweise ergänzt.

Führe den Stop im Terminal des Gateway-Rechners aus, nicht als Auftrag an den Agenten, dessen Dienst du gerade anhältst:

openclaw gateway stop
openclaw config patch --file image-model.patch.json5 --dry-run
openclaw config patch --file image-model.patch.json5
openclaw config validate
openclaw gateway start

Setze die Folge nur fort, wenn der jeweilige Schritt erfolgreich ist. Der Dry-Run schreibt nicht; validate muss die Konfiguration akzeptieren. Scheitert eine Prüfung, starte den Dienst nicht mit einer ungeklärten Änderung. Prüfe nach dem Dienststart, ob der gewünschte Anbieter verfügbar ist. Ein gültiger Modellblock bestätigt allerdings nur die Konfiguration, nicht deine Anbieterberechtigung.

2. Generierung wirklich anfragen

Öffne nach dem erfolgreichen Gateway-Start deinen OpenClaw-Chat. Die aktuelle Bild-Dokumentation beschreibt diesen Diagnoseaufruf:

/tool image_generate action=list

Er listet zur Laufzeit verfügbare Anbieter und Modelle. Prüfe, ob dein beabsichtigter Anbieter verfügbar ist. Fehlt das Werkzeug ganz, kontrolliere Authentifizierung und Modellkonfiguration; eine zusätzliche gewöhnliche Tool-Allowlist ist laut Bild-Dokumentation nicht erforderlich, sobald ein Anbieter verfügbar ist.

Sende danach einen konkreten Testauftrag:

Erzeuge genau ein quadratisches Bild: ein roter Papierwürfel auf weißem Hintergrund, ohne Schrift. Nutze das konfigurierte Standard-Bildmodell.

Bei einem gestarteten Chat-Auftrag liefert das Tool zunächst eine Hintergrund-Task-ID. Erst die spätere Abschlussantwort mit Bildanhang ist das Ergebnis. Prüfe den Anhang selbst: Ist ein Bild vorhanden, zeigt es einen roten Würfel und fehlt die Schrift? Eine Task-ID allein ist kein bestandener Bildtest. Wie Hintergrundabschlüsse zurückkehren, erklärt der Beitrag zu asynchronen Ergebnissen im Unterhaltungskontext.

3. Bearbeitung mit einem echten Anhang prüfen

Speichere das erzeugte Bild und hänge es an eine neue Nachricht an. Wähle den Anhang ausdrücklich als Referenz für diesen Bearbeitungsauftrag aus.

Bearbeite ausschließlich das angehängte Bild: Ändere den roten Papierwürfel in einen blauen Papierwürfel. Perspektive und weißer Hintergrund sollen erhalten bleiben. Erzeuge genau ein Ergebnis.

Prüfe erneut die spätere Abschlussantwort und ihren Bildanhang. Der Würfel soll blau sein, die übrige Gestaltung möglichst erhalten bleiben. Generierung und Bearbeitung sind verschiedene Tests: Ein Anbieter kann beim ersten erfolgreich sein, aber das gewählte Modell oder die Referenzeingabe beim zweiten ablehnen. Diese Anleitung beschreibt die erwarteten Kontrollen; sie ersetzt keinen Test mit deinem eigenen Anbieterzugang.

4. Fallbacks nach Fähigkeiten auswählen

Unter agents.defaults.mediaModels.image.fallbacks kannst du geordnete Ersatzmodelle eintragen. Trage nur Modelle ein, für die du ebenfalls einen eingerichteten Zugang hast. Wie du Ausweichpfade grundsätzlich bewertest, erläutert das Tutorial zum Model-Failover.

Die Bild-Dokumentation beschreibt die Reihenfolge primary, danach fallbacks. Ein ausdrücklich gesetzter Tool-Parameter model begrenzt die Auswahl dagegen auf dieses Modell. Für den ersten Standardtest lässt du ihn deshalb weg. Bei Referenzbildern überspringt OpenClaw Kandidaten ohne passende Bearbeitungsfähigkeit beziehungsweise ohne ausreichende Referenzkapazität.

Ausgabeoptionen sind eine weitere Grenze. Ein Modellwechsel kann Transparenz oder Ausgabeformat verändern. Prüfe deshalb den fertigen Anhang statt nur den Erfolg der Anfrage. Bei nicht unterstützten Hinweisen meldet OpenClaw ignorierte Optionen; Größenanpassungen können in details.normalization stehen. Die konkrete Anbieterfähigkeit entnimmst du der aktuellen Bild-Dokumentation, nicht einer alten Modellliste.

Fehler eingrenzen und zurückbauen

• Werkzeug fehlt: Prüfe Modellblock und Provider-Anmeldung. Der erwartete Zwischenstand ist ein verfügbares image_generate, noch kein erzeugtes Bild.
• Anmeldung abgelehnt: Kontrolliere den verwendeten Zugang beim Anbieter. Nach einer korrigierten Runtime-Umgebungsvariable starte den Gateway-Dienst neu. Bleibt der Fehler unverändert, prüfe anhand der Umgebungsvariablen-Dokumentation den tatsächlichen State-Ordner und mögliche vorrangige Prozess- oder Service-Werte. Bei einem eigenen OPENCLAW_STATE_DIR liegt die globale Runtime-.env dort. Ändere nur die beabsichtigte Credential-Quelle; gib dabei keine Schlüsselwerte aus und poste sie nicht in den Chat.
• Auftrag hängt oder läuft in einen Timeout: Frage im selben Chat /tool image_generate action=status ab. Warte auf einen belegten Abschluss oder Fehler, bevor du einen neuen kostenpflichtigen Versuch startest.
• Alle Modellversuche scheitern: Die Bild-Dokumentation sieht Fehlerdetails je Versuch vor. Prüfe diese und die Zugänge zu den konfigurierten Kandidaten. Noch mehr Fallbacks helfen nicht gegen eine überall fehlende Berechtigung.
• Bild kommt, aber Eigenschaften fehlen: Kontrolliere Modell, ignorierte Hinweise und fertige Datei. Teste anschließend gezielt ein Modell mit der benötigten Fähigkeit statt denselben Auftrag unverändert zu wiederholen.

Für den Rückweg stoppst du den Gateway-Dienst erneut. Entferne einen neu angelegten Schlüssel in der Runtime-.env nur dann wieder, wenn keine andere Funktion ihn braucht; bestehende Zugänge bleiben unangetastet. Nimm diese berechtigte Entfernung nach dem Stop und vor dem abschließenden Start vor. War vorher ein Bildwert gesetzt, stellst du ausschließlich diesen gesicherten Wert wieder her:

openclaw gateway stop
openclaw config set agents.defaults.mediaModels.image "$(cat image-model-before.json)" --strict-json
openclaw config validate
openclaw gateway start

War der Pfad vorher nicht gesetzt, verwendest du anstelle von config set den Befehl openclaw config unset agents.defaults.mediaModels.image. Wiederhole anschließend die Anbieterübersicht. Vergleiche auch den Konfigurationswert mit der Sicherung beziehungsweise prüfe, dass der zuvor fehlende Pfad wieder fehlt. Automatische Anbietererkennung kann das Werkzeug weiterhin verfügbar halten.

Fazit: Zwei Bildtests statt eines grünen Modellblocks

Ich würde zuerst genau einen berechtigten Anbieter einrichten und Generierung sowie Bearbeitung getrennt prüfen. Erst danach kommen Fallbacks hinzu. Entscheidend sind ein sichtbarer Bildanhang mit dem gewünschten Motiv, ein nachvollziehbares Bearbeitungsergebnis und ein funktionierender Rückweg – nicht nur eine schema-gültige Konfiguration.