图像生成

image_generate 工具允许 agent 使用你配置的提供方来创建和编辑图像。生成的图像会作为媒体附件自动发送到 agent 的回复中。

只有在至少有一个图像生成提供方可用时，该工具才会显示。如果你在 agent 的工具中看不到 image_generate，请配置 agents.defaults.imageGenerationModel，设置提供方 API 密钥，或者使用 OpenAI Codex OAuth 登录。

快速开始

配置认证

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

选择默认模型（可选）

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

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

让 agent 执行

“生成一张友好机器人吉祥物的图片。”agent 会自动调用 image_generate。不需要工具白名单——只要有可用的提供方，它就会默认启用。

对于 OpenAI 兼容的 LAN 端点，例如 LocalAI，请保留自定义的 models.providers.openai.baseUrl，并显式启用 browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true。默认情况下，私有和内部图像端点仍会被阻止。

常用路由

目标	模型引用	认证
使用 API 计费进行 OpenAI 图像生成	`openai/gpt-image-2`	`OPENAI_API_KEY`
使用 Codex 订阅认证进行 OpenAI 图像生成	`openai/gpt-image-2`	OpenAI Codex OAuth
OpenAI 透明背景 PNG/WebP	`openai/gpt-image-1.5`	`OPENAI_API_KEY` 或 OpenAI Codex OAuth
DeepInfra 图像生成	`deepinfra/black-forest-labs/FLUX-1-schnell`	`DEEPINFRA_API_KEY`
OpenRouter 图像生成	`openrouter/google/gemini-3.1-flash-image-preview`	`OPENROUTER_API_KEY`
LiteLLM 图像生成	`litellm/gpt-image-2`	`LITELLM_API_KEY`
Google Gemini 图像生成	`google/gemini-3.1-flash-image-preview`	`GEMINI_API_KEY` 或 `GOOGLE_API_KEY`

同一个 image_generate 工具既可以处理文本生成图像，也可以处理参考图像编辑。单个参考图像使用 image，多个参考图像使用 images。当提供方支持时，诸如 quality、outputFormat 和 background 等输出提示会被转发；如果提供方不支持，这些提示会被报告为已忽略。内置的透明背景支持是 OpenAI 特有的；其他提供方如果其后端输出了 PNG alpha 通道，仍可能保留该通道。

支持的提供方

提供方	默认模型	编辑支持	认证
ComfyUI	`workflow`	支持（1 张图像，按工作流配置）	`COMFY_API_KEY` 或云端使用 `COMFY_CLOUD_API_KEY`
DeepInfra	`black-forest-labs/FLUX-1-schnell`	支持（1 张图像）	`DEEPINFRA_API_KEY`
fal	`fal-ai/flux/dev`	支持	`FAL_KEY`
Google	`gemini-3.1-flash-image-preview`	支持	`GEMINI_API_KEY` 或 `GOOGLE_API_KEY`
LiteLLM	`gpt-image-2`	支持（最多 5 张输入图像）	`LITELLM_API_KEY`
MiniMax	`image-01`	支持（主体参考）	`MINIMAX_API_KEY` 或 MiniMax OAuth（`minimax-portal`）
OpenAI	`gpt-image-2`	支持（最多 4 张图像）	`OPENAI_API_KEY` 或 OpenAI Codex OAuth
OpenRouter	`google/gemini-3.1-flash-image-preview`	支持（最多 5 张输入图像）	`OPENROUTER_API_KEY`
Vydra	`grok-imagine`	不支持	`VYDRA_API_KEY`
xAI	`grok-imagine-image`	支持（最多 5 张图像）	`XAI_API_KEY`

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

/tool image_generate action=list

提供方能力

能力	ComfyUI	DeepInfra	fal	Google	MiniMax	OpenAI	Vydra	xAI
生成（最大数量）	工作流定义	4	4	4	9	4	1	4
编辑 / 参考	1 张图像（工作流）	1 张图像	1 张图像	最多 5 张图像	1 张图像（主体参考）	最多 5 张图像	—	最多 5 张图像
尺寸控制	—	✓	✓	✓	—	最多 4K	—	—
宽高比	—	—	✓（仅生成）	✓	✓	—	—	✓
分辨率（1K/2K/4K）	—	—	✓	✓	—	—	—	1K, 2K

工具参数

prompt

string

required

图像生成提示词。action: "generate" 时必填。

action

"generate" | "list"

default:"generate"

使用 "list" 在运行时检查可用的提供方和模型。

model

string

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

image

string

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

images

string[]

用于编辑模式的多个参考图像（支持的提供方最多 5 张）。

size

string

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

aspectRatio

string

宽高比：1:1、2:3、3:2、3:4、4:3、4:5、5:4、9:16、16:9、21:9。

resolution

"1K" | "2K" | "4K"

分辨率提示。

quality

"low" | "medium" | "high" | "auto"

当提供方支持时使用的质量提示。

outputFormat

"png" | "jpeg" | "webp"

当提供方支持时使用的输出格式提示。

background

"transparent" | "opaque" | "auto"

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

count

number

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

timeoutMs

number

可选的提供方请求超时时间，单位毫秒。

filename

string

输出文件名提示。

openai

object

仅适用于 OpenAI 的提示：background、moderation、outputCompression 和 user。

并非所有提供方都支持所有参数。当回退提供方支持一个与请求不完全相同但相近的几何选项时，OpenClaw 会在提交前映射到最接近的受支持尺寸、宽高比或分辨率。不受支持的输出提示会被对不声明支持的提供方丢弃，并在工具结果中报告。工具结果会报告已应用的设置；details.normalization 会记录任何从请求到实际应用的转换。

配置

模型选择

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

提供方选择顺序

OpenClaw 会按以下顺序尝试提供方：

model 参数，来自工具调用（如果 agent 指定了）。
imageGenerationModel.primary，来自配置。
imageGenerationModel.fallbacks，按顺序。
自动检测 —— 仅限有认证支持的提供方默认值：
- 当前默认提供方优先；
- 其余已注册的图像生成提供方按 provider-id 顺序。

如果某个提供方失败（认证错误、速率限制等），会自动尝试下一个已配置的候选项。如果全部失败，错误信息会包含每次尝试的详细信息。

单次调用的模型覆盖是精确的

单次调用的 model 覆盖只会尝试该提供方/模型，不会继续使用已配置的 primary/fallback 或自动检测到的提供方。

自动检测会感知认证

只有当 OpenClaw 实际能够认证该提供方时，该提供方默认值才会进入候选列表。将 agents.defaults.mediaGenerationAutoProviderFallback: false 设置为仅使用显式的 model、primary 和 fallbacks 条目。

超时

为较慢的图像后端设置 agents.defaults.imageGenerationModel.timeoutMs。单次调用的 timeoutMs 工具参数会覆盖已配置的默认值。

运行时检查

使用 action: "list" 检查当前已注册的提供方、它们的默认模型以及认证环境变量提示。

图像编辑

OpenAI、OpenRouter、Google、DeepInfra、fal、MiniMax、ComfyUI 和 xAI 支持编辑参考图像。传入参考图像路径或 URL：

"将这张照片生成水彩风格版本" + image: "/path/to/photo.jpg"

OpenAI、OpenRouter、Google 和 xAI 通过 images 参数支持最多 5 张参考图像。fal、MiniMax 和 ComfyUI 支持 1 张。

提供商深度解析

OpenAI gpt-image-2（以及 gpt-image-1.5）

OpenAI 图像生成默认使用 openai/gpt-image-2。如果配置了 openai-codex OAuth 配置文件，OpenClaw 会复用 Codex 订阅聊天模型所使用的同一 OAuth 配置文件，并通过 Codex Responses 后端发送图像请求。诸如 https://chatgpt.com/backend-api 之类的旧版 Codex 基础 URL 会在图像请求中规范化为 https://chatgpt.com/backend-api/codex。OpenClaw 不会为该请求静默回退到 OPENAI_API_KEY——如果要强制直接走 OpenAI Images API 路由，请显式配置 models.providers.openai，提供 API key、自定义基础 URL 或 Azure 端点。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 特定选项位于 openai 对象下：

{
  "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 输出。顶层的 background 提示是与提供商无关的，目前在选择 OpenAI 提供商时会映射到相同的 OpenAI background 请求字段。对于不声明支持背景的提供商，会将其作为 ignoredOverrides 返回，而不会接收不支持的参数。若要通过 Azure OpenAI 部署而不是 api.openai.com 来路由 OpenAI 图像生成，请参阅 Azure OpenAI 端点。

OpenRouter 图像模型

OpenRouter 图像生成使用相同的 OPENROUTER_API_KEY，并通过 OpenRouter 的聊天补全图像 API 路由。使用带有 openrouter/ 前缀的 OpenRouter 图像模型：

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

OpenClaw 会将 prompt、count、参考图像，以及与 Gemini 兼容的 aspectRatio / resolution 提示转发给 OpenRouter。当前内置的 OpenRouter 图像模型快捷方式包括 google/gemini-3.1-flash-image-preview、 google/gemini-3-pro-image-preview 和 openai/gpt-5.4-image-2。使用 action: "list" 查看你的已配置插件暴露了哪些内容。

MiniMax 双重认证

MiniMax 图像生成可通过以下两个内置的 MiniMax 认证路径使用：

minimax/image-01 用于 API key 配置
minimax-portal/image-01 用于 OAuth 配置

xAI grok-imagine-image

内置的 xAI 提供商在仅提示词请求时使用 /v1/images/generations，当存在 image 或 images 时使用 /v1/images/edits。

模型：xai/grok-imagine-image、xai/grok-imagine-image-pro
数量：最多 4
参考图：一个 image 或最多五个 images
宽高比：1:1、16:9、9:16、4:3、3:4、2:3、3:2
分辨率：1K、2K
输出：作为由 OpenClaw 管理的图像附件返回

在共享的跨提供商 image_generate 合同中尚未具备这些控制项之前，OpenClaw 有意不暴露 xAI 原生的 quality、mask、 user，或额外的仅原生支持的宽高比。

示例

生成（4K 横版）
生成（透明 PNG）
生成（两个正方形）
编辑（一个参考图）
编辑（多个参考图）

/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：

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

--output-format 和 --background 标志同样可用于 openclaw infer image edit；--openai-background 仍然作为 OpenAI 特定的别名保留。除 OpenAI 之外的内置提供商目前不声明显式的背景控制，因此 background: "transparent" 会被报告为它们的忽略项。

概览

插件

技能

自动化与任务

工具

智能体协作

快速开始

常用路由

支持的提供方

提供方能力

工具参数

配置

模型选择

提供方选择顺序

图像编辑

提供商深度解析

示例

相关内容

概览

插件

技能

自动化与任务

工具

智能体协作

Documentation Index

​快速开始

​常用路由

​支持的提供方

​提供方能力

​工具参数

​配置

​模型选择

​提供方选择顺序

​图像编辑

​提供商深度解析

​示例

​相关内容

快速开始

常用路由

支持的提供方

提供方能力

工具参数

配置

模型选择

提供方选择顺序

图像编辑

提供商深度解析

示例

相关内容