Vai al contenuto principale

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

Lo strumento image_generate consente all’agente di creare e modificare immagini usando i provider configurati. Le immagini generate vengono recapitate automaticamente come allegati multimediali nella risposta dell’agente.
Lo strumento compare solo quando è disponibile almeno un provider di generazione immagini. Se non vedi image_generate negli strumenti del tuo agente, configura agents.defaults.imageGenerationModel, imposta una chiave API del provider o accedi con OpenAI Codex OAuth.

​
Avvio rapido

1

Configura l'autenticazione

Imposta una chiave API per almeno un provider (per esempio OPENAI_API_KEY, GEMINI_API_KEY, OPENROUTER_API_KEY) oppure accedi con OpenAI Codex OAuth.
2

Scegli un modello predefinito (opzionale)

{
  agents: {
    defaults: {
      imageGenerationModel: {
        primary: "openai/gpt-image-2",
        timeoutMs: 180_000,
      },
    },
  },
}
Codex OAuth usa lo stesso riferimento modello openai/gpt-image-2. Quando è configurato un profilo OAuth openai-codex, OpenClaw instrada le richieste di immagini tramite quel profilo OAuth invece di provare prima OPENAI_API_KEY. La configurazione esplicita models.providers.openai (chiave API, URL di base personalizzato/Azure) riattiva il percorso diretto dell’API OpenAI Images.
3

Chiedi all'agente

“Genera un’immagine di una mascotte robot amichevole.”L’agente chiama automaticamente image_generate. Non è necessario inserirlo in una lista di strumenti consentiti: è abilitato per impostazione predefinita quando è disponibile un provider.
Per endpoint LAN compatibili con OpenAI, come LocalAI, mantieni il models.providers.openai.baseUrl personalizzato e abilitali esplicitamente con browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true. Gli endpoint di immagini privati e interni restano bloccati per impostazione predefinita.

​
Percorsi comuni

ObiettivoRif. modelloAutenticazione
Generazione immagini OpenAI con fatturazione APIopenai/gpt-image-2OPENAI_API_KEY
Generazione immagini OpenAI con autenticazione tramite abbonamento Codexopenai/gpt-image-2OpenAI Codex OAuth
PNG/WebP OpenAI con sfondo trasparenteopenai/gpt-image-1.5OPENAI_API_KEY o OpenAI Codex OAuth
Generazione immagini DeepInfradeepinfra/black-forest-labs/FLUX-1-schnellDEEPINFRA_API_KEY
Generazione immagini OpenRouteropenrouter/google/gemini-3.1-flash-image-previewOPENROUTER_API_KEY
Generazione immagini LiteLLMlitellm/gpt-image-2LITELLM_API_KEY
Generazione immagini Google Geminigoogle/gemini-3.1-flash-image-previewGEMINI_API_KEY o GOOGLE_API_KEY
Lo stesso strumento image_generate gestisce testo-in-immagine e la modifica con immagini di riferimento. Usa image per un riferimento o images per più riferimenti. I suggerimenti di output supportati dal provider, come quality, outputFormat e background, vengono inoltrati quando disponibili e segnalati come ignorati quando un provider non li supporta. Il supporto incluso per sfondi trasparenti è specifico di OpenAI; altri provider possono comunque preservare il canale alfa PNG se il loro backend lo emette.

​
Provider supportati

ProviderModello predefinitoSupporto modificaAutenticazione
ComfyUIworkflowSì (1 immagine, configurata dal workflow)COMFY_API_KEY o COMFY_CLOUD_API_KEY per il cloud
DeepInfrablack-forest-labs/FLUX-1-schnellSì (1 immagine)DEEPINFRA_API_KEY
falfal-ai/flux/devSì (limiti specifici del modello)FAL_KEY
Googlegemini-3.1-flash-image-previewSìGEMINI_API_KEY o GOOGLE_API_KEY
LiteLLMgpt-image-2Sì (fino a 5 immagini di input)LITELLM_API_KEY
MiniMaximage-01Sì (riferimento soggetto)MINIMAX_API_KEY o MiniMax OAuth (minimax-portal)
OpenAIgpt-image-2Sì (fino a 4 immagini)OPENAI_API_KEY o OpenAI Codex OAuth
OpenRoutergoogle/gemini-3.1-flash-image-previewSì (fino a 5 immagini di input)OPENROUTER_API_KEY
Vydragrok-imagineNoVYDRA_API_KEY
xAIgrok-imagine-imageSì (fino a 5 immagini)XAI_API_KEY
Usa action: "list" per ispezionare provider e modelli disponibili a runtime: 
/tool image_generate action=list

​
Capacità dei provider

CapacitàComfyUIDeepInfrafalGoogleMiniMaxOpenAIVydraxAI
Generazione (conteggio massimo)Definito dal workflow4449414
Modifica / riferimento1 immagine (workflow)1 immagineFlux: 1; GPT: 10; NB2: 14Fino a 5 immagini1 immagine (rif. soggetto)Fino a 5 immagini-Fino a 5 immagini
Controllo dimensioni-✓✓✓-Fino a 4K--
Proporzioni--✓✓✓--✓
Risoluzione (1K/2K/4K)--✓✓---1K, 2K

​
Parametri dello strumento

​
prompt
string
obbligatorio
Prompt di generazione immagini. Obbligatorio per action: "generate".
​
action
"generate" | "list"
predefinito:"generate"
Usa "list" per ispezionare provider e modelli disponibili a runtime.
​
model
string
Override provider/modello (ad es. openai/gpt-image-2). Usa openai/gpt-image-1.5 per sfondi OpenAI trasparenti.
​
image
string
Percorso o URL di una singola immagine di riferimento per la modalità di modifica.
​
images
string[]
Più immagini di riferimento per la modalità di modifica (fino a 5 sui provider supportati).
​
size
string
Suggerimento dimensione: 1024x1024, 1536x1024, 1024x1536, 2048x2048, 3840x2160.
​
aspectRatio
string
Proporzioni: 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9.
​
resolution
"1K" | "2K" | "4K"
Suggerimento risoluzione.
​
quality
"low" | "medium" | "high" | "auto"
Suggerimento qualità quando il provider lo supporta.
​
outputFormat
"png" | "jpeg" | "webp"
Suggerimento formato di output quando il provider lo supporta.
​
background
"transparent" | "opaque" | "auto"
Suggerimento sfondo quando il provider lo supporta. Usa transparent con outputFormat: "png" o "webp" per provider capaci di trasparenza.
​
count
number
Numero di immagini da generare (1-4).
​
timeoutMs
number
Timeout opzionale della richiesta al provider in millisecondi. Quando Codex chiama image_generate tramite strumenti dinamici, questo valore per chiamata sovrascrive comunque il valore predefinito configurato ed è limitato a 600000 ms.
​
filename
string
Suggerimento nome file di output.
​
openai
object
Suggerimenti solo OpenAI: background, moderation, outputCompression e user.
Non tutti i provider supportano tutti i parametri. Quando un provider di fallback supporta un’opzione geometrica simile invece di quella esatta richiesta, OpenClaw rimappa alla dimensione, alle proporzioni o alla risoluzione supportate più vicine prima dell’invio. I suggerimenti di output non supportati vengono scartati per i provider che non dichiarano supporto e segnalati nel risultato dello strumento. I risultati dello strumento riportano le impostazioni applicate; details.normalization registra ogni traduzione da richiesto ad applicato.

​
Configurazione

​
Selezione del modello

{
  agents: {
    defaults: {
      imageGenerationModel: {
        primary: "openai/gpt-image-2",
        timeoutMs: 180_000,
        fallbacks: [
          "openrouter/google/gemini-3.1-flash-image-preview",
          "google/gemini-3.1-flash-image-preview",
          "fal/fal-ai/flux/dev",
        ],
      },
    },
  },
}

​
Ordine di selezione dei provider

OpenClaw prova i provider in questo ordine:
  1. Parametro model dalla chiamata allo strumento (se l’agente ne specifica uno).
  2. imageGenerationModel.primary dalla configurazione.
  3. imageGenerationModel.fallbacks in ordine.
  4. Rilevamento automatico: solo valori predefiniti dei provider con autenticazione:
    • prima il provider predefinito corrente;
    • poi i restanti provider registrati per generazione immagini in ordine di ID provider.
Se un provider fallisce (errore di autenticazione, limite di frequenza, ecc.), il candidato configurato successivo viene provato automaticamente. Se tutti falliscono, l’errore include i dettagli di ogni tentativo.
Un override model per chiamata prova solo quel provider/modello e non continua con primary/fallback configurati o provider rilevati automaticamente.
Il valore predefinito di un provider entra nell’elenco dei candidati solo quando OpenClaw può effettivamente autenticare quel provider. Imposta agents.defaults.mediaGenerationAutoProviderFallback: false per usare solo voci esplicite model, primary e fallbacks.
Imposta agents.defaults.imageGenerationModel.timeoutMs per backend di immagini lenti. Un parametro dello strumento timeoutMs per chiamata sovrascrive il valore predefinito configurato. Le chiamate agli strumenti dinamici di Codex rispettano lo stesso budget di timeout, limitato dal massimo di 600000 ms del bridge per strumenti dinamici di OpenClaw.
Usa action: "list" per ispezionare i provider attualmente registrati, i loro modelli predefiniti e i suggerimenti per le variabili d’ambiente di autenticazione.

​
Modifica delle immagini

OpenAI, OpenRouter, Google, DeepInfra, fal, MiniMax, ComfyUI e xAI supportano la modifica delle immagini di riferimento. Passa un percorso o URL di un’immagine di riferimento: 
"Generate a watercolor version of this photo" + image: "/path/to/photo.jpg"
OpenAI, OpenRouter, Google e xAI supportano fino a 5 immagini di riferimento tramite il parametro images. fal supporta 1 immagine di riferimento per Flux image-to-image, fino a 10 per le modifiche GPT Image 2 e fino a 14 per le modifiche Nano Banana 2. MiniMax e ComfyUI ne supportano 1.

​
Approfondimenti sui provider

La generazione di immagini OpenAI usa per impostazione predefinita openai/gpt-image-2. Se è configurato un profilo OAuth openai-codex, OpenClaw riutilizza lo stesso profilo OAuth usato dai modelli chat in abbonamento Codex e invia la richiesta immagine tramite il backend Codex Responses. Gli URL di base Codex legacy come https://chatgpt.com/backend-api vengono canonicalizzati in https://chatgpt.com/backend-api/codex per le richieste immagine. OpenClaw non ripiega silenziosamente su OPENAI_API_KEY per quella richiesta - per forzare l’instradamento diretto tramite OpenAI Images API, configura esplicitamente models.providers.openai con una chiave API, un URL di base personalizzato o un endpoint Azure.I modelli openai/gpt-image-1.5, openai/gpt-image-1 e openai/gpt-image-1-mini possono ancora essere selezionati esplicitamente. Usa gpt-image-1.5 per output PNG/WebP con sfondo trasparente; l’API attuale gpt-image-2 rifiuta background: "transparent".gpt-image-2 supporta sia la generazione text-to-image sia la modifica con immagini di riferimento tramite lo stesso strumento image_generate. OpenClaw inoltra prompt, count, size, quality, outputFormat e le immagini di riferimento a OpenAI. OpenAI non riceve direttamente aspectRatio o resolution; quando possibile OpenClaw mappa questi valori in una size supportata, altrimenti lo strumento li segnala come override ignorati.Le opzioni specifiche di OpenAI si trovano nell’oggetto openai:
{
  "quality": "low",
  "outputFormat": "jpeg",
  "openai": {
    "background": "opaque",
    "moderation": "low",
    "outputCompression": 60,
    "user": "end-user-42"
  }
}
openai.background accetta transparent, opaque o auto; gli output trasparenti richiedono outputFormat png o webp e un modello immagine OpenAI compatibile con la trasparenza. OpenClaw instrada le richieste predefinite gpt-image-2 con sfondo trasparente verso gpt-image-1.5. openai.outputCompression si applica agli output JPEG/WebP.Il suggerimento di primo livello background è neutrale rispetto al provider e attualmente viene mappato allo stesso campo di richiesta OpenAI background quando è selezionato il provider OpenAI. I provider che non dichiarano il supporto per lo sfondo lo restituiscono in ignoredOverrides invece di ricevere il parametro non supportato.Per instradare la generazione di immagini OpenAI tramite una distribuzione Azure OpenAI invece di api.openai.com, consulta endpoint Azure OpenAI.
La generazione di immagini OpenRouter usa la stessa OPENROUTER_API_KEY e passa attraverso l’API immagini per chat completions di OpenRouter. Seleziona i modelli immagine OpenRouter con il prefisso openrouter/:
{
  agents: {
    defaults: {
      imageGenerationModel: {
        primary: "openrouter/google/gemini-3.1-flash-image-preview",
      },
    },
  },
}
OpenClaw inoltra prompt, count, le immagini di riferimento e i suggerimenti aspectRatio / resolution compatibili con Gemini a OpenRouter. Le scorciatoie integrate attuali per i modelli immagine OpenRouter includono google/gemini-3.1-flash-image-preview, google/gemini-3-pro-image-preview e openai/gpt-5.4-image-2. Usa action: "list" per vedere cosa espone il Plugin configurato.
La generazione di immagini MiniMax è disponibile tramite entrambi i percorsi di autenticazione MiniMax inclusi:
  • minimax/image-01 per configurazioni con chiave API
  • minimax-portal/image-01 per configurazioni OAuth
Il provider xAI incluso usa /v1/images/generations per le richieste con solo prompt e /v1/images/edits quando è presente image o images.
  • Modelli: xai/grok-imagine-image, xai/grok-imagine-image-pro
  • Conteggio: fino a 4
  • Riferimenti: una image o fino a cinque images
  • Rapporti d’aspetto: 1:1, 16:9, 9:16, 4:3, 3:4, 2:3, 3:2
  • Risoluzioni: 1K, 2K
  • Output: restituiti come allegati immagine gestiti da OpenClaw
OpenClaw intenzionalmente non espone quality, mask, user specifici di xAI, né rapporti d’aspetto aggiuntivi solo nativi, finché tali controlli non esistono nel contratto condiviso cross-provider image_generate.

​
Esempi

/tool image_generate action=generate model=openai/gpt-image-2 prompt="A clean editorial poster for OpenClaw image generation" size=3840x2160 count=1
Gli stessi flag --output-format e --background sono disponibili su openclaw infer image edit; --openai-background resta un alias specifico di OpenAI. I provider inclusi diversi da OpenAI oggi non dichiarano un controllo esplicito dello sfondo, quindi background: "transparent" viene segnalato come ignorato per loro.

​
Correlati

  • Panoramica degli strumenti - tutti gli strumenti agent disponibili
  • ComfyUI - configurazione del workflow ComfyUI locale e Comfy Cloud
  • fal - configurazione del provider immagini e video fal
  • Google (Gemini) - configurazione del provider immagini Gemini
  • MiniMax - configurazione del provider immagini MiniMax
  • OpenAI - configurazione del provider OpenAI Images
  • Vydra - configurazione di immagini, video e voce Vydra
  • xAI - configurazione di immagini Grok, video, ricerca, esecuzione di codice e TTS
  • Riferimento di configurazione - configurazione imageGenerationModel
  • Modelli - configurazione dei modelli e failover