Saltar al contenido principal
La herramienta image_generate crea y edita imágenes mediante tus proveedores configurados. En las sesiones de chat 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 sigue el modo normal de respuesta visible de la sesión: entrega automática de la respuesta final cuando está configurada, o message(action="send") cuando la sesión requiere la herramienta de mensajes. Si la sesión solicitante está inactiva o falla su activación activa, OpenClaw envía una alternativa directa idempotente con las imágenes generadas para que el resultado no se pierda.
La herramienta solo aparece cuando al menos un proveedor de generación de imágenes está disponible. Si no ves image_generate en las herramientas de tu agente, configura agents.defaults.imageGenerationModel, configura una clave de API de proveedor o inicia sesión con OpenAI ChatGPT/Codex OAuth.

​
Inicio rápido

1

Configure auth

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

Pick a default model (optional)

{
  agents: {
    defaults: {
      imageGenerationModel: {
        primary: "openai/gpt-image-2",
        timeoutMs: 180_000,
      },
    },
  },
}
ChatGPT/Codex OAuth usa la misma referencia de modelo openai/gpt-image-2. Cuando se configura un perfil OAuth de openai, OpenClaw enruta las solicitudes de imagen mediante 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) vuelve a optar por la ruta directa de la API de Imágenes de OpenAI.
3

Ask the agent

“Genera una imagen de una mascota robot amigable.”El agente llama a image_generate automáticamente. No hace falta incluir la herramienta en una lista de permitidas: está habilitada de forma predeterminada cuando hay un proveedor disponible. La herramienta devuelve un id de tarea en segundo plano y luego el agente de finalización envía el adjunto generado mediante la herramienta message cuando está listo.
Para endpoints LAN compatibles con OpenAI, como LocalAI, conserva el models.providers.openai.baseUrl personalizado y opta explícitamente con browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true. Los endpoints de imagen privados e internos permanecen bloqueados de forma predeterminada.

​
Rutas comunes

ObjetivoRef. de modeloAutenticación
Generación de imágenes de OpenAI con facturación de APIopenai/gpt-image-2OPENAI_API_KEY
Generación de imágenes de OpenAI con autenticación de suscripción de Codexopenai/gpt-image-2OpenAI ChatGPT/Codex OAuth
PNG/WebP con fondo transparente de OpenAIopenai/gpt-image-1.5OPENAI_API_KEY u OpenAI Codex OAuth
Generación de imágenes de DeepInfradeepinfra/black-forest-labs/FLUX-1-schnellDEEPINFRA_API_KEY
Generación expresiva/dirigida por estilo fal Krea 2fal/krea/v2/medium/text-to-imageFAL_KEY
Generación de imágenes de OpenRouteropenrouter/google/gemini-3.1-flash-image-previewOPENROUTER_API_KEY
Generación de imágenes de LiteLLMlitellm/gpt-image-2LITELLM_API_KEY
Generación de imágenes de Microsoft Foundry MAImicrosoft-foundry/<deployment-name>AZURE_OPENAI_API_KEY o Entra ID
Generación de imágenes de Google Geminigoogle/gemini-3.1-flash-image-previewGEMINI_API_KEY o GOOGLE_API_KEY
La misma herramienta gestiona texto a imagen y edición con imagen de referencia. Usa image para una referencia o images para varias. Para los modelos Krea 2 en fal, esas referencias se envían como referencias de estilo en lugar de entradas de edición. Las sugerencias de salida admitidas por el proveedor, como quality, outputFormat y background, se reenvían cuando están disponibles y se informan como ignoradas cuando un proveedor no declara compatibilidad. La compatibilidad incluida con fondos transparentes es específica de OpenAI; otros proveedores aún pueden conservar el alfa PNG si su backend lo emite.

​
Proveedores compatibles

ProveedorModelo predeterminadoCompatibilidad con ediciónAutenticación
ComfyUIworkflowSí (1 imagen, configurada por flujo de trabajo)COMFY_API_KEY o COMFY_CLOUD_API_KEY para la nube
DeepInfrablack-forest-labs/FLUX-1-schnellSí (1 imagen)DEEPINFRA_API_KEY
falfal-ai/flux/devSí (límites específicos del modelo)FAL_KEY
Googlegemini-3.1-flash-image-previewSí (hasta 5 imágenes)GEMINI_API_KEY o GOOGLE_API_KEY
LiteLLMgpt-image-2Sí (hasta 5 imágenes de entrada)LITELLM_API_KEY
Microsoft Foundry<deployment-name>Sí (solo modelos MAI-Image-2.5)AZURE_OPENAI_API_KEY o Entra ID (az login)
MiniMaximage-01Sí (referencia de sujeto)MINIMAX_API_KEY o MiniMax OAuth (minimax-portal)
OpenAIgpt-image-2Sí (hasta 5 imágenes)OPENAI_API_KEY u OpenAI ChatGPT/Codex OAuth
OpenRoutergoogle/gemini-3.1-flash-image-previewSí (hasta 5 imágenes de entrada)OPENROUTER_API_KEY
Vydragrok-imagineNoVYDRA_API_KEY
xAIgrok-imagine-imageSí (hasta 5 imágenes)XAI_API_KEY
Usa action: "list" para inspeccionar los proveedores y modelos disponibles en tiempo de ejecución: 
/tool image_generate action=list
Usa action: "status" para inspeccionar la tarea activa de generación de imágenes de la sesión actual: 
/tool image_generate action=status

​
Capacidades del proveedor

CapacidadComfyUIDeepInfrafalGoogleMicrosoft FoundryMiniMaxOpenAIVydraxAI
Generar (conteo máximo)144419414
Editar / referencia1 imagen (flujo de trabajo)1 imagenFlux: 1; GPT: 10; refs de estilo Krea: 10; NB2: 14Hasta 5 imágenes1 imagen1 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

​
Parámetros de la herramienta

​
prompt
string
requerido
Prompt de generación de imágenes. Requerido para action: "generate".
​
action
"generate" | "status" | "list"
predeterminado:"generate"
Usa "status" para inspeccionar la tarea activa de la sesión o "list" para inspeccionar los proveedores y modelos disponibles en tiempo de ejecución.
​
model
string
Anulación de proveedor/modelo (p. ej., openai/gpt-image-2). Usa openai/gpt-image-1.5 para fondos transparentes de OpenAI.
​
image
string
Ruta o URL de una sola imagen de referencia para el modo de edición.
​
images
string[]
Varias imágenes de referencia para el modo de edición o modelos de referencia de estilo (hasta 14 mediante la herramienta compartida; los límites específicos del proveedor siguen aplicándose).
​
size
string
Sugerencia de tamaño: 1024x1024, 1536x1024, 1024x1536, 2048x2048, 3840x2160.
​
aspectRatio
string
Relación de aspecto: 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. Los proveedores validan su subconjunto específico del modelo.
​
resolution
"1K" | "2K" | "4K"
Sugerencia de resolución.
​
quality
"low" | "medium" | "high" | "auto"
Sugerencia de calidad cuando el proveedor la admite.
​
outputFormat
"png" | "jpeg" | "webp"
Sugerencia de formato de salida cuando el proveedor la admite.
​
background
"transparent" | "opaque" | "auto"
Sugerencia de fondo cuando el proveedor la admite. Usa transparent con outputFormat: "png" o "webp" para proveedores con capacidad de transparencia.
​
count
number
Número de imágenes que se generarán (1-4).
​
timeoutMs
number
Tiempo de espera opcional de la solicitud al proveedor en milisegundos. Cuando Codex llama a image_generate mediante herramientas dinámicas, este valor por llamada aún anula el valor predeterminado configurado y tiene un límite de 600000 ms.
​
filename
string
Sugerencia de nombre de archivo de salida.
​
openai
object
Sugerencias solo para OpenAI: background, moderation, outputCompression y user.
​
fal.creativity
"raw" | "low" | "medium" | "high"
Control de creatividad de fal Krea 2. El valor predeterminado es medium.
No todos los proveedores admiten todos los parámetros. Cuando un proveedor alternativo admite una opción de geometría cercana en lugar de la solicitada exactamente, OpenClaw reasigna al tamaño, relación de aspecto o resolución compatible más cercana antes del envío. Las sugerencias de salida no admitidas se eliminan para los proveedores que no declaran compatibilidad y se informan en el resultado de la herramienta. Los resultados de la herramienta informan la configuración aplicada; details.normalization captura cualquier traducción de solicitado a aplicado.

​
Configuración

​
Selección de 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 de proveedores

OpenClaw prueba los proveedores en este orden:
  1. Parámetro model de la llamada de herramienta (si el agente especifica uno).
  2. imageGenerationModel.primary de la configuración.
  3. imageGenerationModel.fallbacks en orden.
  4. Detección automática: solo valores predeterminados de proveedor respaldados por autenticación:
    • proveedor predeterminado actual primero;
    • proveedores restantes registrados de generación de imágenes en orden de ID de proveedor.
Si un proveedor falla (error de autenticación, límite de frecuencia, etc.), se prueba automáticamente el siguiente candidato configurado. Si todos fallan, el error incluye detalles de cada intento.
Una anulación de model por llamada prueba solo ese proveedor/modelo y no continúa con el proveedor primario/de reserva configurado ni con proveedores detectados automáticamente.
Un valor predeterminado de proveedor solo entra en la lista de candidatos cuando OpenClaw puede autenticar realmente ese proveedor. Establece agents.defaults.mediaGenerationAutoProviderFallback: false para usar solo entradas explícitas de model, primary y fallbacks.
Establece agents.defaults.imageGenerationModel.timeoutMs para backends de imagen lentos. Un parámetro de herramienta timeoutMs por llamada anula el valor predeterminado configurado, y los valores predeterminados configurados anulan los valores predeterminados de proveedor definidos por plugins. Los proveedores de imágenes alojados de Google y OpenRouter usan valores predeterminados de 180 segundos; la generación de imágenes de Microsoft Foundry MAI, xAI y Azure OpenAI usa 600 segundos. Las llamadas de herramientas dinámicas de Codex usan un valor predeterminado de puente image_generate de 120 segundos y respetan el mismo presupuesto de tiempo de espera cuando está configurado, limitado por el máximo de 600000 ms del puente de herramientas dinámicas de OpenClaw.
Usa action: "list" para inspeccionar los proveedores registrados actualmente, sus modelos predeterminados y las pistas de variables de entorno de autenticación.

​
Edición de imágenes

OpenAI, OpenRouter, Google, DeepInfra, fal, Microsoft Foundry, MiniMax, ComfyUI y xAI admiten la edición de imágenes de referencia. Los modelos Krea 2 en fal usan los mismos campos image / images como referencias de estilo en lugar de entradas de edición. Pasa 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 mediante el parámetro images. fal admite 1 imagen de referencia para Flux de imagen a imagen, hasta 10 para ediciones de GPT Image 2, hasta 10 referencias de estilo para Krea 2 y hasta 14 para ediciones de Nano Banana 2. Microsoft Foundry, MiniMax y ComfyUI admiten 1.

​
Análisis detallado de proveedores

La generación de imágenes de OpenAI usa openai/gpt-image-2 de forma predeterminada. Si hay configurado un perfil OAuth de openai, OpenClaw reutiliza el mismo perfil OAuth usado por los modelos de chat de suscripción de 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 canonicalizan a https://chatgpt.com/backend-api/codex para solicitudes de imagen. OpenClaw no recurre silenciosamente a OPENAI_API_KEY para esa solicitud: para forzar el enrutamiento directo de la API de OpenAI Images, configura models.providers.openai explícitamente con una clave de API, una URL base personalizada o un endpoint de Azure.Los modelos openai/gpt-image-1.5, openai/gpt-image-1 y openai/gpt-image-1-mini aún se pueden seleccionar explícitamente. Usa gpt-image-1.5 para salida PNG/WebP con fondo transparente; la API actual gpt-image-2 rechaza background: "transparent".gpt-image-2 admite tanto generación de texto a imagen como edición con imágenes de referencia mediante la misma herramienta image_generate. OpenClaw reenvía prompt, count, size, quality, outputFormat e imágenes de referencia a OpenAI. OpenAI no recibe aspectRatio ni resolution directamente; cuando es posible, OpenClaw asigna esos valores a un size admitido; de lo contrario, la herramienta los 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 de OpenAI compatible con transparencia. OpenClaw enruta las solicitudes predeterminadas de gpt-image-2 con fondo transparente a gpt-image-1.5. openai.outputCompression se aplica a salidas JPEG/WebP y se ignora para salidas PNG.La pista de nivel superior background es neutral respecto del 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 fondo la 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, consulta endpoints de Azure OpenAI.
La generación de imágenes de Microsoft Foundry usa nombres de implementaciones de imagen MAI desplegadas bajo el prefijo de proveedor microsoft-foundry/. No hay un modelo predeterminado a nivel de proveedor porque la API de MAI espera el nombre de tu implementación en el campo model:
{
  agents: {
    defaults: {
      imageGenerationModel: {
        primary: "microsoft-foundry/<deployment-name>",
        timeoutMs: 600_000,
      },
    },
  },
}
El proveedor usa la API MAI de Microsoft Foundry, no la API de OpenAI Images:
  • Endpoint de generación: /mai/v1/images/generations
  • Endpoint de edición: /mai/v1/images/edits
  • Autenticación: AZURE_OPENAI_API_KEY / clave de API del proveedor, o Entra ID mediante az login
  • Salida: una imagen PNG
  • Tamaño: 1024x1024 predeterminado; el ancho y la altura deben ser de al menos 768 px cada uno, y el total de píxeles debe ser como máximo 1.048.576
  • Ediciones: una imagen de referencia PNG o JPEG, admitida solo por implementaciones MAI-Image-2.5-Flash y MAI-Image-2.5
La generación solo con prompt puede usar un nombre de implementación personalizado con solo el endpoint de Foundry configurado. Las ediciones con nombres de implementación personalizados necesitan incorporación/metadatos de modelo para que OpenClaw pueda verificar que la implementación está respaldada por MAI-Image-2.5-Flash o MAI-Image-2.5.Los modelos de imagen MAI actuales son MAI-Image-2.5-Flash, MAI-Image-2.5, MAI-Image-2e y MAI-Image-2. Consulta Plugin de Microsoft Foundry para la configuración y el comportamiento del modelo de chat.
La generación de imágenes de OpenRouter usa la misma OPENROUTER_API_KEY y se enruta a través de la API de imágenes de chat completions de OpenRouter. Selecciona 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 pistas aspectRatio / resolution compatibles con Gemini a OpenRouter. Los atajos integrados actuales de modelos de imagen de OpenRouter incluyen google/gemini-3.1-flash-image-preview, google/gemini-3-pro-image-preview y openai/gpt-5.4-image-2. Usa action: "list" para ver qué expone tu plugin configurado.
Los modelos Krea 2 en fal usan el esquema nativo Krea de fal en lugar del esquema genérico image_size usado por Flux. OpenClaw envía:
  • aspect_ratio para pistas de relación de aspecto
  • creativity, con valor predeterminado medium
  • image_style_references cuando se suministran image o images
Selecciona Krea 2 Medium para ilustración expresiva más rápida y Krea 2 Large para aspectos fotorrealistas y texturizados más lentos y detallados:
{
  agents: {
    defaults: {
      imageGenerationModel: {
        primary: "fal/krea/v2/medium/text-to-image",
      },
    },
  },
}
Krea 2 actualmente devuelve una imagen por solicitud. Prefiere aspectRatio para Krea; OpenClaw asigna size a la relación de aspecto de Krea compatible más cercana y rechaza resolution para Krea en lugar de descartarla. Usa fal.creativity cuando quieras un nivel de creatividad nativo de Krea:
{
  "model": "fal/krea/v2/medium/text-to-image",
  "prompt": "A cyber zine portrait with risograph texture",
  "aspectRatio": "9:16",
  "fal": {
    "creativity": "high"
  }
}
La generación de imágenes de MiniMax está disponible mediante 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
El proveedor xAI incluido usa /v1/images/generations para solicitudes solo con prompt y /v1/images/edits cuando image o images está presente.
  • Modelos: xai/grok-imagine-image, xai/grok-imagine-image-quality
  • Recuento: hasta 4
  • Referencias: un 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 adjuntos de imagen gestionados por OpenClaw
OpenClaw no expone intencionalmente quality, mask, user nativos de xAI ni relaciones de aspecto adicionales solo nativas hasta que esos controles existan en el contrato compartido entre proveedores image_generate.

​
Ejemplos

/tool image_generate action=generate model=openai/gpt-image-2 prompt="A clean editorial poster for OpenClaw image generation" size=3840x2160 count=1
Las mismas marcas --output-format, --background, --quality y --openai-moderation están disponibles en openclaw infer image edit; --openai-background permanece como alias específico de OpenAI. Los proveedores incluidos distintos de OpenAI no declaran hoy un control explícito del fondo, por lo que background: "transparent" se informa como ignorado para ellos.

​
Relacionado

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