Generación de imágenes

La herramienta image_generate permite al agente crear y editar imágenes utilizando sus proveedores configurados. En las sesiones de chat, la generación de imágenes se ejecuta de forma asíncrona: OpenClaw registra una tarea en segundo plano, devuelve el id. de tarea inmediatamente y despierta al agente cuando el proveedor termina. El agente de finalización debe enviar las imágenes generadas a través de la herramienta message; OpenClaw no publica automáticamente una respuesta final privada como alternativa.

Note

La herramienta solo aparece cuando hay al menos un proveedor de generación de imágenes disponible. Si no ve

image_generate

en las herramientas de su agente, configure

agents.defaults.imageGenerationModel

, configure una clave de API del proveedor, o inicie sesión con OpenAI Codex OAuth.

Inicio rápido

1. Configure la autenticación

   Establezca una clave de API para al menos un proveedor (por ejemplo OPENAI_API_KEY, GEMINI_API_KEY, OPENROUTER_API_KEY) o inicie sesión con OpenAI Codex OAuth.

2. Elija un modelo predeterminado (opcional)

   {
     agents: {
       defaults: {
         imageGenerationModel: {
           primary: "openai/gpt-image-2",
           timeoutMs: 180_000,
         },
       },
     },
   }

   Codex OAuth utiliza la misma referencia de modelo openai/gpt-image-2. Cuando se configura un perfil OAuth openai-codex, OpenClaw enruta las solicitudes de imagen a través de ese perfil OAuth en lugar de intentar primero OPENAI_API_KEY. La configuración explícita de models.providers.openai (clave de API, URL base personalizada/Azure) opta por volver a la ruta directa de la API de OpenAI Images.

3. Pídele al agente

   “Genera una imagen de una mascota robot amigable.”

   El agente llama a image_generate automáticamente. No es necesario incluir la herramienta en la lista de permitidos (allow-listing); está habilitada de forma predeterminada cuando hay un proveedor disponible. La herramienta devuelve un id de tarea en segundo plano y, cuando esté lista, el agente de finalización envía el adjunto generado a través de la herramienta message.

Warning

Para los endpoints de LAN compatibles con OpenAI, como LocalAI, mantén el

models.providers.openai.baseUrl

personalizado y opta explícitamente por participar con

browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true

. Los endpoints de imagen privados y internos permanecen bloqueados de forma predeterminada.

Rutas comunes

Objetivo	Referencia del modelo	Autenticación
Generación de imágenes de OpenAI con facturación de API	openai/gpt-image-2	OPENAI_API_KEY
Generación de imágenes de OpenAI con autenticación de suscripción a Codex	openai/gpt-image-2	OpenAI Codex OAuth
OpenAI PNG/WebP con fondo transparente	openai/gpt-image-1.5	OPENAI_API_KEY u OpenAI Codex OAuth
Generación de imágenes DeepInfra	deepinfra/black-forest-labs/FLUX-1-schnell	DEEPINFRA_API_KEY
Generación de imágenes OpenRouter	openrouter/google/gemini-3.1-flash-image-preview	OPENROUTER_API_KEY
Generación de imágenes LiteLLM	litellm/gpt-image-2	LITELLM_API_KEY
Generación de imágenes Google Gemini	google/gemini-3.1-flash-image-preview	GEMINI_API_KEY o GOOGLE_API_KEY

La misma herramienta image_generate se encarga de la conversión de texto a imagen y de la edición de imágenes de referencia. Usa image para una referencia o images para múltiples referencias. Las sugerencias de salida compatibles con el proveedor, como quality, outputFormat y background, se reenvían cuando están disponibles y se indican como ignoradas cuando un proveedor no las admite. La compatibilidad incluida con el fondo transparente es exclusiva de OpenAI; otros proveedores aún pueden conservar el canal alfa de PNG si su backend lo emite.

Proveedores compatibles

Proveedor	Modelo predeterminado	Soporte de edición	Autenticación
ComfyUI	workflow	Sí (1 imagen, configurado por flujo de trabajo)	COMFY_API_KEY o COMFY_CLOUD_API_KEY para la nube
DeepInfra	black-forest-labs/FLUX-1-schnell	Sí (1 imagen)	DEEPINFRA_API_KEY
fal	fal-ai/flux/dev	Sí (límites específicos del modelo)	FAL_KEY
Google	gemini-3.1-flash-image-preview	Sí	GEMINI_API_KEY o GOOGLE_API_KEY
LiteLLM	gpt-image-2	Sí (hasta 5 imágenes de entrada)	LITELLM_API_KEY
MiniMax	image-01	Sí (referencia del sujeto)	MINIMAX_API_KEY o MiniMax OAuth (minimax-portal)
OpenAI	gpt-image-2	Sí (hasta 4 imágenes)	OPENAI_API_KEY o OpenAI Codex OAuth
OpenRouter	google/gemini-3.1-flash-image-preview	Sí (hasta 5 imágenes de entrada)	OPENROUTER_API_KEY
Vydra	grok-imagine	No	VYDRA_API_KEY
xAI	grok-imagine-image	Sí (hasta 5 imágenes)	XAI_API_KEY

Use action: "list" to inspect available providers and models at runtime:

/tool image_generate action=list

Use action: "status" to inspect the active image-generation task for the current session:

/tool image_generate action=status

Provider capabilities

Capacidad	ComfyUI	DeepInfra	fal	Google	MiniMax	OpenAI	Vydra	xAI
Generar (máx. cantidad)	Definido por flujo de trabajo	4	4	4	9	4	1	4
Editar / referencia	1 imagen (flujo de trabajo)	1 imagen	Flux: 1; GPT: 10; NB2: 14	Hasta 5 imágenes	1 imagen (ref. de sujeto)	Hasta 5 imágenes	-	Hasta 5 imágenes
Control de tamaño	-	✓	✓	✓	-	Hasta 4K	-	-
Relación de aspecto	-	-	✓	✓	✓	-	-	✓
Resolución (1K/2K/4K)	-	-	✓	✓	-	-	-	1K, 2K

Tool parameters

Prompt de generación de imágenes. Obligatorio para `action: "generate"`. Use `"status"` para inspeccionar la tarea de la sesión activa o `"list"` para inspeccionar los proveedores y modelos disponibles en tiempo de ejecución. Sobrescritura de proveedor/modelo (ej. `openai/gpt-image-2`). Use `openai/gpt-image-1.5` para fondos transparentes de OpenAI. Ruta o URL de una sola imagen de referencia para el modo de edición. Múltiples imágenes de referencia para el modo de edición (hasta 5 en proveedores compatibles). Sugerencia de tamaño: `1024x1024`, `1536x1024`, `1024x1536`, `2048x2048`, `3840x2160`. Relación de aspecto: `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9`. Sugerencia de resolución. Sugerencia de calidad cuando el proveedor lo admite. Sugerencia de formato de salida cuando el proveedor lo admite. Sugerencia de fondo cuando el proveedor lo admite. Use `transparent` con `outputFormat: "png"` o `"webp"` para proveedores con capacidad de transparencia. Número de imágenes a generar (1-4). Tiempo de espera opcional de la solicitud del proveedor en milisegundos. Cuando Codex llama a `image_generate` a través de herramientas dinámicas, este valor por llamada todavía anula el valor predeterminado configurado y tiene un límite de 600000 ms. Sugerencia de nombre de archivo de salida. Sugerencias exclusivas de OpenAI: `background`, `moderation`, `outputCompression` y `user`.

Note

No todos los proveedores admiten todos los parámetros. Cuando un proveedor de respaldo admite una opción de geometría cercana en lugar de la solicitada exactamente, OpenClaw remapea a el tamaño, relación de aspecto o resolución compatible más cercano antes del envío. Las sugerencias de salida no admitidas se eliminan para los proveedores que no declaran soporte y se informan en el resultado de la herramienta. Los resultados de la herramienta informan de la configuración aplicada; details.normalization captura cualquier traducción de solicitado a aplicado.

Configuración

Selección del modelo

{
  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"],
      },
    },
  },
}

Orden de selección del proveedor

OpenClaw intenta los proveedores en este orden:

1. parámetro model de la llamada a la herramienta (si el agente especifica uno).
2. imageGenerationModel.primary de la configuración.
3. imageGenerationModel.fallbacks en orden.
4. Detección automática - solo para proveedores predeterminados con autenticación:
   • primero el proveedor predeterminado actual;
   • proveedores de generación de imágenes registrados restantes en orden de id de proveedor.

Si un proveedor falla (error de autenticación, límite de velocidad, etc.), el siguiente candidato configurado se intenta automáticamente. Si todos fallan, el error incluye detalles de cada intento.

Las anulaciones de modelo por llamada son exactas

Una anulación de model por llamada intenta solo ese proveedor/modelo y no continúa con los proveedores primarios/de respaldo configurados o detectados automáticamente.

La detección automática es consciente de la autenticación

Un proveedor predeterminado solo entra en la lista de candidatos cuando OpenClaw puede autenticar realmente ese proveedor. Establezca agents.defaults.mediaGenerationAutoProviderFallback: false para usar solo entradas explícitas de model, primary y fallbacks.

Tiempos de espera

Establezca agents.defaults.imageGenerationModel.timeoutMs para backends de imágenes lentos. Un parámetro de herramienta timeoutMs por llamada anula el predeterminado configurado. Los proveedores de imágenes alojados de Google, OpenRouter y xAI usan tiempos de espera predeterminados de 180 segundos; la generación de imágenes de Azure OpenAI usa 600 segundos. Las llamadas de herramientas dinámicas de Codex usan un puente image_generate predeterminado de 120 segundos y respetan el mismo presupuesto de tiempo de espera cuando se configura, limitado por el máximo de 600000 ms del puente de herramientas dinámicas de OpenClaw.

Inspeccionar en tiempo de ejecución

Use action: "list" para inspeccionar los proveedores registrados actualmente, sus modelos predeterminados y sugerencias de variables de entorno de autenticación.

Edición de imágenes

OpenAI, OpenRouter, Google, DeepInfra, fal, MiniMax, ComfyUI y xAI admiten la edición de imágenes de referencia. Pase una ruta o URL de imagen de referencia:

"Generate a watercolor version of this photo" + image: "/path/to/photo.jpg"

OpenAI, OpenRouter, Google y xAI admiten hasta 5 imágenes de referencia a través del parámetro images. fal admite 1 imagen de referencia para Flux de imagen a imagen, hasta 10 para ediciones de GPT Image 2 y hasta 14 para ediciones de Nano Banana 2. MiniMax y ComfyUI admiten 1.

Análisis detallados de proveedores

OpenAI gpt-image-2 (y gpt-image-1.5)

La generación de imágenes de OpenAI tiene como valor predeterminado openai/gpt-image-2. Si se ha configurado un perfil OAuth de openai-codex, OpenClaw reutiliza el mismo perfil OAuth utilizado por los modelos de chat de suscripción Codex y envía la solicitud de imagen a través del backend de Codex Responses. Las URL base heredadas de Codex, como https://chatgpt.com/backend-api, se canonizan a https://chatgpt.com/backend-api/codex para las solicitudes de imagen. OpenClaw no realiza una reserva silenciosa a OPENAI_API_KEY para esa solicitud - para forzar el enrutamiento directo a la API de OpenAI Images, configure models.providers.openai explícitamente con una clave de API, URL base personalizada o punto de conexión de Azure.

Los modelos openai/gpt-image-1.5, openai/gpt-image-1 y openai/gpt-image-1-mini todavía se pueden seleccionar explícitamente. Use gpt-image-1.5 para obtener una salida PNG/WebP con fondo transparente; la API actual de gpt-image-2 rechaza background: "transparent".

gpt-image-2 admite tanto la generación de texto a imagen como la edición de imágenes de referencia a través de la misma herramienta image_generate. OpenClaw reenvía prompt, count, size, quality, outputFormat e imágenes de referencia a OpenAI. OpenAI no recibe aspectRatio o resolution directamente; cuando es posible, OpenClaw las asigna a un size admitido; de lo contrario, la herramienta las informa como anulaciones ignoradas.

Las opciones específicas de OpenAI se encuentran bajo el objeto openai:

{
  "quality": "low",
  "outputFormat": "jpeg",
  "openai": {
    "background": "opaque",
    "moderation": "low",
    "outputCompression": 60,
    "user": "end-user-42"
  }
}

openai.background acepta transparent, opaque o auto; las salidas transparentes requieren outputFormat png o webp y un modelo de imagen OpenAI con capacidad de transparencia. OpenClaw enruta las solicitudes predeterminadas de fondo transparente de gpt-image-2 a gpt-image-1.5. openai.outputCompression se aplica a las salidas JPEG/WebP.

La sugerencia background de nivel superior es neutral para el proveedor y actualmente se asigna al mismo campo de solicitud background de OpenAI cuando se selecciona el proveedor OpenAI. Los proveedores que no declaran compatibilidad con el fondo lo devuelven en ignoredOverrides en lugar de recibir el parámetro no admitido.

Para enrutar la generación de imágenes de OpenAI a través de una implementación de Azure OpenAI en lugar de api.openai.com, consulte Puntos de conexión de Azure OpenAI.

Modelos de imagen de OpenRouter

La generación de imágenes de OpenRouter utiliza el mismo OPENROUTER_API_KEY y se enruta a través de la API de imágenes de completaciones de chat de OpenRouter. Seleccione los modelos de imagen de OpenRouter con el prefijo openrouter/:

{
  agents: {
    defaults: {
      imageGenerationModel: {
        primary: "openrouter/google/gemini-3.1-flash-image-preview",
      },
    },
  },
}

OpenClaw reenvía prompt, count, imágenes de referencia y sugerencias aspectRatio / resolution compatibles con Gemini a OpenRouter. Los atajos de modelos de imagen de OpenRouter integrados actuales incluyen google/gemini-3.1-flash-image-preview, google/gemini-3-pro-image-preview y openai/gpt-5.4-image-2. Use action: "list" para ver qué expone su complemento configurado.

Doble autenticación de MiniMax

La generación de imágenes de MiniMax está disponible a través de ambas rutas de autenticación de MiniMax incluidas:

• minimax/image-01 para configuraciones con clave de API
• minimax-portal/image-01 para configuraciones con OAuth

xAI grok-imagine-image

El proveedor xAI incluido utiliza /v1/images/generations para solicitudes solo con prompt y /v1/images/edits cuando image o images están presentes.

• Modelos: xai/grok-imagine-image, xai/grok-imagine-image-quality
• Recuento: hasta 4
• Referencias: una image o hasta cinco images
• Relaciones de aspecto: 1:1, 16:9, 9:16, 4:3, 3:4, 2:3, 3:2
• Resoluciones: 1K, 2K
• Salidas: devueltas como archivos adjuntos de imagen gestionados por OpenClaw

OpenClaw intencionalmente no expone quality, mask, user, o relaciones de aspecto adicionales exclusivas de xAI hasta que esos controles existan en el contrato image_generate compartido entre proveedores.

Ejemplos

Generar (paisaje 4K)Generar (PNG transparente)Generar (dos cuadradas)Editar (una referencia)Editar (múltiples referencias)

/tool image_generate action=generate model=openai/gpt-image-2 prompt="A clean editorial poster for OpenClaw image generation" size=3840x2160 count=1

/tool image_generate action=generate model=openai/gpt-image-1.5 prompt="A simple red circle sticker on a transparent background" outputFormat=png background=transparent

CLI equivalente:

openclaw infer image generate \
  --model openai/gpt-image-1.5 \
  --output-format png \
  --background transparent \
  --prompt "A simple red circle sticker on a transparent background" \
  --json

/tool image_generate action=generate model=openai/gpt-image-2 prompt="Two visual directions for a calm productivity app icon" size=1024x1024 count=2

/tool image_generate action=generate model=openai/gpt-image-2 prompt="Keep the subject, replace the background with a bright studio setup" image=/path/to/reference.png size=1024x1536

/tool image_generate action=generate model=openai/gpt-image-2 prompt="Combine the character identity from the first image with the color palette from the second" images='["/path/to/character.png","/path/to/palette.jpg"]' size=1536x1024

Las mismas opciones --output-format y --background están disponibles en openclaw infer image edit; --openai-background permanece como un alias específico de OpenAI. Los proveedores incluidos distintos de OpenAI no declaran control de fondo explícito hoy, por lo que se informa que background: "transparent" se ignora para ellos.

Relacionado

• Resumen de herramientas - todas las herramientas del agente disponibles
• ComfyUI - configuración de flujo de trabajo de ComfyUI local y Comfy Cloud
• fal - configuración del proveedor de imagen y video de fal
• Google (Gemini) - configuración del proveedor de imágenes Gemini
• MiniMax - configuración del proveedor de imágenes MiniMax
• OpenAI - configuración del proveedor OpenAI Images
• Vydra - configuración de imagen, video y voz de Vydra
• xAI - configuración de imagen, video, búsqueda, ejecución de código y TTS de Grok
• Referencia de configuración - imageGenerationModel config
• Modelos - configuración de modelos y conmutación por error