图像生成

该 image_generate 工具通过你已配置的提供商创建和编辑图像。在聊天会话中，它异步运行：原生媒体生成所有者跟踪操作，立即返回任务 ID，并在提供商完成时唤醒代理。完成代理遵循会话当前的可见回复约定，附带一段简短的面向用户的说明文字以及所有结构化生成附件。如果生成失败，代理会改为返回一条简洁的可见失败信息。如果请求方会话处于非活动状态或其活动唤醒失败，OpenClaw 会发送一个幂等的直接回退，附带生成的图像，以免结果丢失。

在 WebChat 和 macOS 应用中，生成的附件会保留在完成回复中，而不会再次出现在单独的纯图像消息中。重放已完成的投递会保持相同的消息和附件标识。

快速入门¶

1. 配置认证

为至少一个提供商设置 API 密钥（例如 OPENAI_API_KEY、GEMINI_API_KEY、OPENROUTER_API_KEY），或使用 OpenAI ChatGPT/Codex OAuth 登录。

2. 选择默认模型（可选）

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

ChatGPT/Codex OAuth 使用相同的 openai/gpt-image-2 模型引用。当配置了 openai OAuth 配置文件时，OpenClaw 会通过该 OAuth 配置文件路由图像请求，而不是先尝试 OPENAI_API_KEY。显式的 models.providers.openai 配置（API 密钥、自定义/Azure 基础 URL）会改回使用直接 OpenAI Images API 路由。

3. 询问代理

"生成一张友好的机器人吉祥物图像。"

代理会自动调用 image_generate。无需工具允许列表——当提供商可用时，它默认启用。该工具返回一个后台任务 ID，然后完成代理在就绪时回复所有生成的附件。

常见路由¶

同一工具可处理文本生成图像和参考图像编辑。使用 image 表示一个参考，使用 images 表示多个参考。对于 fal 上的 Krea 2 模型，这些参考会作为风格参考发送，而不是编辑输入。提供商支持的输出提示（例如 quality、outputFormat 和 background）在可用时会被转发；当提供商未声明支持时，会被报告为已忽略。OpenAI 和 fal GPT Image 2.5 声明支持透明背景。其他提供商如果其后端输出 PNG alpha，仍可能保留 PNG alpha。

OpenAI 支持通过直接 Images API 或 Codex Responses 后端，对文本生成图像和参考图像编辑使用 low 和 auto 审核。对于 CLI 请求，请将 --openai-moderation low|auto 传递给 openclaw infer image generate 或 openclaw infer image edit。

支持的提供商¶

使用 action: "list" 在运行时检查可用的提供商和模型：

/tool image_generate action=list

使用 action: "status" 检查当前会话中活动的图像生成任务：

/tool image_generate action=status

任务状态和重复检测的范围限定在发起请求的聊天中，即使直接聊天共享主会话记录也是如此。完成时会返回给请求图像的对方。

提供商功能¶

工具参数¶

prompt string (path) 必填

图像生成提示词。对于 action: "generate" 为必填项。

action "generate" | "status" | "list" (path) 默认值：generate

使用 "status" 检查活动会话任务，或使用 "list" 在运行时检查可用的提供商和模型。

model string (path)

提供商/模型覆盖（例如 openai/gpt-image-2）。使用 openai/gpt-image-1.5 可获得透明的 OpenAI 背景。

image string (path)

编辑模式的单个参考图像路径或 URL。

images string[] (path)

编辑模式或样式引用模型的多张参考图像（通过共享工具最多 16 张。 仍适用提供商特定限制）。

size string (path)

尺寸提示：1024x1024、1536x1024、1024x1536、2048x2048、3840x2160。

aspectRatio string (path)

宽高比：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。提供商会验证其模型特定的子集。

resolution "1K" | "2K" | "4K" (path)

分辨率提示。

quality "low" | "medium" | "high" | "xhigh" | "max" | "auto" (path)

当模型支持时，质量提示。GPT Image 2.5 通过 OpenAI 和 fal 支持 xhigh 和 max。

outputFormat "png" | "jpeg" | "webp" (path)

当提供商支持时，输出格式提示。

background "transparent" | "opaque" | "auto" (path)

当提供商支持时，背景提示。对于支持透明度的提供商，请使用 transparent 搭配 outputFormat: "png" 或 "webp"。

count number (path)

要生成的图像数量（1-4）。

timeoutMs number (path)

可选的提供商请求超时时间（毫秒）。当 Codex 通过动态工具调用 image_generate 时，此每次调用的值仍会覆盖配置的默认值，并且上限为 600000 毫秒。

filename string（路径）

输出文件名提示。

openai object（路径）

OpenAI 专用提示：background、moderation、outputCompression 和 user。

fal.creativity "raw" | "low" | "medium" | "high"（路径）

fal Krea 2 创意控制。默认值为 medium。

配置¶

模型选择¶

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

提供商选择顺序¶

对于 image_generate，OpenClaw 按以下顺序尝试提供商：

1. 工具调用中的 model 参数。如果已设置，则只尝试该模型。
2. 配置中的 agents.defaults.mediaModels.image.primary。
3. 按顺序使用 agents.defaults.mediaModels.image.fallbacks。
4. 自动检测 - 仅当未配置主模型或回退模型时使用，采用已配置的提供商默认值：
5. 优先使用当前默认提供商。
6. 其余已注册的图像生成提供商按 provider-id 顺序排列。

如果某个提供商失败（认证错误、速率限制等），会自动尝试下一个已配置的候选项。如果全部失败，错误信息将包含每次尝试的详细信息。 对于参考图像请求，无法编辑图像或无法接受所提供参考图像数量的候选项会被跳过。

图像编辑¶

OpenAI、OpenRouter、Google、DeepInfra、fal、Microsoft Foundry、MiniMax、ComfyUI 和 xAI 支持编辑参考图像。fal 上的 Krea 2 模型将相同的 image / images 字段用作风格参考，而不是编辑输入。请传入参考图像路径或 URL：

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

OpenAI、OpenRouter 和 Google 通过 images 参数支持最多 5 张参考图像。xAI 支持最多 3 张。fal 支持 Flux 图生图 1 张参考图像，GPT Image 2.5 编辑最多 16 张，旧版 GPT Image 编辑最多 10 张，Krea 2 风格参考最多 10 张，Nano Banana 2 编辑最多 14 张。Microsoft Foundry、MiniMax 和 ComfyUI 支持 1 张。

提供商深入解析¶

openai/gpt-image-1.5、openai/gpt-image-1 和 openai/gpt-image-1-mini 模型仍可以显式选择。对于透明背景的 PNG/WebP 输出，请使用 gpt-image-1.5。当前 gpt-image-2 API 会拒绝 background: "transparent"。

`gpt-image-2` 通过同一个 `image_generate` 工具同时支持文生图生成和
参考图像编辑。
OpenClaw 会将 `prompt`、`count`、`size`、`quality`、`outputFormat`
以及参考图像转发到 OpenAI。OpenAI 不会直接接收
`aspectRatio` 或 `resolution`。在可能的情况下，OpenClaw 会将
它们映射为受支持的 `size`，否则工具会将它们报告为
被忽略的覆盖项。

对于直接的 OpenAI Images API 请求，`gpt-image-2` 及其
`gpt-image-2-2026-04-21` 快照会保留有效的显式
`WIDTHxHEIGHT` 尺寸，而不是将其对齐到预设值。两个
维度都必须是 16 的倍数，任一维度不得超过 3840 像素，
宽高比不得超过 3:1，并且图像必须包含
655,360 到 8,294,400 个像素。例如，`1024x640` 是
有效的。当仅指定 `aspectRatio` 时，OpenClaw 仍会选择
最接近的受支持尺寸。

OpenAI 特定选项位于 `openai` 对象下：

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

`openai.background` 接受 `transparent`、`opaque` 或 `auto`。
透明输出要求 `outputFormat` 为 `png` 或 `webp`，并且使用
支持透明的 OpenAI 图像模型。OpenClaw 会将默认
`gpt-image-2` 的透明背景请求路由到 `gpt-image-1.5`。
`openai.outputCompression` 适用于 JPEG/WebP 输出，对 PNG 输出会被忽略。

顶层 `background` 提示是提供商中立的，当选择 OpenAI 提供商时，它会映射
到相同的 OpenAI `background` 请求字段。未声明支持背景的提供商会
将其返回到 `ignoredOverrides` 中，而不是接收该不支持的参数。

若要改为通过 Azure OpenAI 部署而不是 `api.openai.com` 路由 OpenAI 图像生成，请参阅
[Azure OpenAI 端点](../providers/openai/azure.md#azure-openai-endpoints)。

{
  agents: {
    defaults: {
      mediaModels: {
        image: {
          primary: "microsoft-foundry/<deployment-name>",
          timeoutMs: 600000,
        },
      },
    },
  },
}

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

{
  agents: {
    defaults: {
      mediaModels: {
        image: {
          primary: "fal/krea/v2/medium/text-to-image",
        },
      },
    },
  },
}

{
  "model": "fal/krea/v2/medium/text-to-image",
  "prompt": "A cyber zine portrait with risograph texture",
  "aspectRatio": "9:16",
  "fal": {
    "creativity": "high"
  }
}

示例¶

/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

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="Low-cost draft poster for a quiet productivity app" quality=low openai='{"moderation":"low"}'

openclaw infer image generate \
  --model openai/gpt-image-2 \
  --quality low \
  --openai-moderation low \
  --prompt "Low-cost draft poster for a quiet productivity app" \
  --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

/tool image_generate action=generate model=fal/krea/v2/medium/text-to-image prompt="An expressive editorial portrait using this color palette and print texture" images='["/path/to/palette.png","/path/to/texture.jpg"]' aspectRatio=9:16 fal='{"creativity":"high"}'

openclaw infer image edit 同样支持 --output-format、--background 和 --quality 标志。--openai-background 仍作为 OpenAI 专用别名保留。在 OpenAI 图像生成和参考图编辑中均可使用 --openai-moderation low|auto。OpenAI Images 直接 API 以及 ChatGPT/Codex OAuth Responses 后端均支持审核提示。OpenAI 和 fal GPT Image 2.5 模型支持显式背景控制。其他内置提供商会将 background: "transparent" 报告为被忽略。

相关¶

• 工具概览 - 所有可用的代理工具
• ComfyUI - 本地 ComfyUI 和 Comfy Cloud 工作流配置
• fal - fal 图像和视频提供商配置
• Google (Gemini) - Gemini 图像提供商配置
• Microsoft Foundry 插件 - Microsoft Foundry 聊天和 MAI 图像配置
• MiniMax - MiniMax 图像提供商配置
• OpenAI - OpenAI Images 提供商配置
• OpenRouter - OpenRouter 图像提供商配置
• Vydra - Vydra 图像、视频和语音配置
• xAI - Grok 图像、视频、搜索、代码执行和 TTS 配置
• 配置参考 - agents.defaults.mediaModels.image 配置
• 模型 - 模型配置和故障转移
• 媒体概览 - 媒体工具如何协同工作