OpenClaw 的 image_generate 工具支持通过 OpenAI、Google、fal、MiniMax、ComfyUI、DeepInfra、OpenRouter、LiteLLM、xAI、Vydra 等多个 Provider 生成和编辑图片。配置至少一个 Provider 的 API Key 后自动启用，无需手动授权。通过 imageGenerationModel.primary + fallbacks 设置主备链，运行时使用 action="list" 查看可用 Provider。编辑模式传入 image 参数即可，不同 Provider 对参考图数量和支持的编辑能力有差异。如果没看到工具，检查 agents.defaults.imageGenerationModel 配置或 Provider 认证是否生效。

OpenClaw 图片生成配置：Provider选型、参数与问题排查指南

image_generate 工具让 Agent 通过配置好的 Provider 创建和编辑图片。在聊天会话中，图片生成是异步执行的：OpenClaw 创建一个后台任务，立即返回 task id，等 Provider 完成后唤醒 Agent。完成后的 Agent 必须通过 message 工具把生成的图片发到会话里。如果请求方会话已不活跃且部分生成图片还没通过 message 工具送达，OpenClaw 会幂等地直接回退，只补发缺失的图片。

INFO

工具只在至少一个图片生成 Provider 可用时才出现。如果 Agent 工具列表里看不到 image_generate，配置 agents.defaults.imageGenerationModel 或设置 Provider API Key，或者用 OpenAI Codex OAuth 登录。

怎么配置图片生成

配置认证

为至少一个 Provider 设置 API Key（例如 `OPENAI_API_KEY`、`GEMINI_API_KEY`、`OPENROUTER_API_KEY`），或者用 OpenAI Codex OAuth 登录。

选择默认模型（可选）

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

Codex OAuth 使用同样的 `openai/gpt-image-2` 模型 ref。配置了 `openai-codex` OAuth 后，OpenClaw 会把图片请求路由到那个 OAuth 配置，而不是优先尝试 `OPENAI_API_KEY`。如果要强制走 OpenAI Images API，显式配置 `models.providers.openai`（带 API Key、自定义 base URL 或 Azure 端点）。

让 Agent 生成图片

直接说："生成一张友好机器人吉祥物的图片。"

Agent 会自动调用 `image_generate`，不需要放到工具白名单里——只要 Provider 可用就默认启用。工具返回后台 task id，完成时 Agent 通过 `message` 工具把生成的附件发过来。

WARNING

对于 OpenAI 兼容的局域网端点（如 LocalAI），要保留自定义的 models.providers.openai.baseUrl，并且显式设置 browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true。默认会拦截私有和内网图片端点。

常用路由

目的	模型 ref	认证方式
OpenAI API 计费的图片生成	`openai/gpt-image-2`	`OPENAI_API_KEY`
OpenAI Codex 订阅认证的图片生成	`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。Provider 支持的输出 hint（如 quality、outputFormat、background）在可用时会被转发，不被支持时报告为 ignored。透明背景支持是 OpenAI 特有的，其他 Provider 如果后端输出 PNG alpha 层，可能也会保留。

支持的 Provider

Provider	默认模型	编辑支持	认证方式
ComfyUI	`workflow`	是（1 张图，workflow 配置）	`COMFY_API_KEY` 或 `COMFY_CLOUD_API_KEY`
DeepInfra	`black-forest-labs/FLUX-1-schnell`	是（1 张图）	`DEEPINFRA_API_KEY`
fal	`fal-ai/flux/dev`	是（model 特定限制）	`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" 查看当前可用的 Provider 和模型：

text

/tool image_generate action=list

用 action: "status" 查看当前会话的活跃图片生成任务：

text

/tool image_generate action=status

Provider 能力对比

能力	ComfyUI	DeepInfra	fal	Google	MiniMax	OpenAI	Vydra	xAI
最大生成张数	workflow 定义	4	4	4	9	4	1	4
编辑/参考图	1 张（workflow）	1 张	Flux:1；GPT:10；NB2:14	最多 5 张	1 张（主题参考）	最多 5 张	-	最多 5 张
尺寸控制	-	✓	✓	✓	-	最多 4K	-	-
宽高比	-	-	✓	✓	✓	-	-	✓
分辨率（1K/2K/4K）	-	-	✓	✓	-	-	-	1K，2K

工具参数

prompt string (必填)

图片生成提示词。action: "generate" 时必须。

action

用 "status" 查看当前会话的活跃任务，"list" 查看运行时可用的 Provider 和模型。

model string

Provider/模型覆盖（如 openai/gpt-image-2）。透明背景用 openai/gpt-image-1.5。

image string

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

images string[]

编辑模式的多张参考图（支持 Provider 上限 5 张）。

size string

尺寸 hint：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

quality

Provider 支持时的质量 hint。

outputFormat

Provider 支持时的输出格式 hint。

background

Provider 支持时的背景 hint。用 transparent 配合 outputFormat: "png" 或 "webp"，适用于支持透明度的 Provider。

count number

timeoutMs number

可选的 Provider 请求超时（毫秒）。Codex 通过动态工具调用 image_generate 时，这个值仍然会覆盖配置的默认值，上限 600000 ms。

filename string

openai object

OpenAI 特有 hint：background、moderation、outputCompression 和 user。

INFO

不是所有 Provider 都支持所有参数。当回退 Provider 支持接近但不完全匹配的几何选项时，OpenClaw 会在提交前映射到最接近的尺寸、宽高比或分辨率。不支持的输出 hint 对未声明支持的 Provider 会丢弃，并在工具结果中报告。工具结果会报告应用的设置，details.normalization 记录从请求到应用的映射变化。

配置与 Provider 选择策略

模型选择

json5

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

Provider 选择顺序

OpenClaw 按以下顺序尝试 Provider：

工具调用中的 model 参数（Agent 指定时）。
配置中的 imageGenerationModel.primary。
imageGenerationModel.fallbacks 按顺序尝试。
自动检测：只从已认证的 Provider 默认中选取：
- 当前默认 Provider 优先；
- 剩余已注册的图片生成 Provider 按 provider-id 顺序。

如果某个 Provider 失败（鉴权错误、限速等），自动尝试下一个；全部失败时错误信息包含每次尝试的详细内容。

每次调用 model 覆盖是精确的

每次调用传入 `model` 参数后，只会尝试那个 Provider/model，不会继续尝试配置的 primary/fallback 或自动检测的 Provider。

自动检测依赖认证

只有 OpenClaw 能实际认证某个 Provider 时，其默认才会进入候选列表。设置 `agents.defaults.mediaGenerationAutoProviderFallback: false` 可以只使用显式的 `model`、`primary` 和 `fallbacks`。

超时配置

设置 `agents.defaults.imageGenerationModel.timeoutMs` 应对慢速图片后端。每次调用传入 `timeoutMs` 参数会覆盖配置的默认值，配置的默认值会覆盖插件作者提供的 Provider 默认值。Google 和 OpenRouter 托管的图片 Provider 默认 180 秒，xAI 和 Azure OpenAI 图片生成默认 600 秒。Codex 动态工具调用使用 120 秒的 `image_generate` 桥接默认值，配置超时后仍尊重新配置，但受 OpenClaw 的 600000 ms 动态工具桥接上限约束。

运行时查看

用 `action: "list"` 查看当前已注册的 Provider、它们的默认模型和认证环境变量提示。

图片编辑

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

text

"把这张照片换成水彩风格" + image: "/path/to/photo.jpg"

OpenAI、OpenRouter、Google 和 xAI 通过 images 参数支持最多 5 张参考图。fal 对 Flux image-to-image 支持 1 张，对 GPT Image 2 编辑支持最多 10 张，对 Nano Banana 2 编辑支持最多 14 张。MiniMax 和 ComfyUI 支持 1 张。

Provider 深度配置

OpenAI gpt-image-2 和 gpt-image-1.5

OpenAI 图片生成默认使用 `openai/gpt-image-2`。如果配置了 `openai-codex` OAuth，OpenClaw 会复用 Codex 订阅聊天模型用的 OAuth，把图片请求发给 Codex Responses 后端。遗留的 Codex base URL（如 `https://chatgpt.com/backend-api`）会被规范化成 `https://chatgpt.com/backend-api/codex`。OpenClaw **不会**静默回退到 `OPENAI_API_KEY`——要强制走 OpenAI Images API，显式配置 `models.providers.openai`，带上 API Key、自定义 base URL 或 Azure 端点。

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

`gpt-image-2` 同时支持文生图和参考图编辑，都在同一个 `image_generate` 工具里。OpenClaw 会把 `prompt`、`count`、`size`、`quality`、`outputFormat` 和参考图转发给 OpenAI。OpenAI **不**直接接收 `aspectRatio` 或 `resolution`，OpenClaw 在可能时会把它们映射成支持的 `size`，否则工具报告为 ignored overrides。

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 输出。

顶层的 `background` hint 是 Provider 中立的，在选用 OpenAI Provider 时会映射到 OpenAI 的 `background` 请求字段。未声明背景支持的 Provider 会返回 `ignoredOverrides`，不会收到这个参数。

要把 OpenAI 图片生成路由到 Azure OpenAI Deployment 而不是 `api.openai.com`，请参考 [Azure OpenAI 端点](/ai/ai-tools/openclaw/providers/openai#azure-openai-endpoints)。

OpenRouter 图片模型

OpenRouter 图片生成使用同样的 `OPENROUTER_API_KEY`，通过 OpenRouter 的 chat completions 图片 API 路由。用 `openrouter/` 前缀选择 OpenRouter 图片模型：

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

OpenClaw 会把 `prompt`、`count`、参考图以及 Gemini 兼容的 `aspectRatio` / `resolution` hint 转发给 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/image-01`：API Key 方式
- `minimax-portal/image-01`：OAuth 方式

xAI grok-imagine-image

内置的 xAI Provider 对纯提示词请求使用 `/v1/images/generations`，传了 `image` 或 `images` 时使用 `/v1/images/edits`。

- 模型：`xai/grok-imagine-image`、`xai/grok-imagine-image-quality`
- 张数：最多 4 张
- 参考图：单张 `image` 或最多 5 张 `images`
- 宽高比：`1:1`、`16:9`、`9:16`、`4:3`、`3:4`、`2:3`、`3:2`
- 分辨率：`1K`、`2K`
- 输出：作为 OpenClaw 管理的图片附件返回

OpenClaw 目前不暴露 xAI 原生的 `quality`、`mask`、`user` 或额外原生宽高比，直到这些控制项进入跨 Provider 的 `image_generate` 统一接口。

示例

生成（4K 横图）

text

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

生成（透明 PNG）

text

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

bash

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

生成（两张方形图）

text

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

编辑（单张参考图）

text

/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

编辑（多张参考图）

text

/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 外的内置 Provider 没有显式声明背景控制，所以 background: "transparent" 对它们会报告为 ignored。

常见问题

Agent 工具列表里没有 image_generate 怎么办

至少需要一个有效的图片生成 Provider。检查是否设置了 OPENAI_API_KEY、GEMINI_API_KEY 或 FAL_KEY 等环境变量，或者配置了 agents.defaults.imageGenerationModel.primary。运行时用 /tool image_generate action=list 确认当前有哪些 Provider 可用。

OpenAI 透明背景图片怎么出

显式选择 openai/gpt-image-1.5 模型，设置 outputFormat 为 png 或 webp，并传入 background: "transparent"。当前的 gpt-image-2 会拒绝 background: "transparent"，OpenClaw 会自动把这类请求路由到 gpt-image-1.5。

某些参数被报告为 `ignoredOverrides` 是什么意思

表示当前 Provider 不支持这些参数（如 aspectRatio 或 resolution）。工具结果会列出被丢弃的参数。不同 Provider 的能力差异见上方的 Provider 能力对比表。

OpenClaw 图片生成配置：Provider选型、参数与问题排查指南 ​

怎么配置图片生成 ​

常用路由 ​

支持的 Provider ​

Provider 能力对比 ​

工具参数 ​

配置与 Provider 选择策略 ​

模型选择 ​

Provider 选择顺序 ​

图片编辑 ​

Provider 深度配置 ​

示例 ​

相关文档 ​

常见问题 ​

Agent 工具列表里没有 image_generate 怎么办 ​

OpenAI 透明背景图片怎么出 ​

某些参数被报告为 ignoredOverrides 是什么意思 ​

OpenClaw 图片生成配置：Provider选型、参数与问题排查指南

怎么配置图片生成

常用路由

支持的 Provider

Provider 能力对比

工具参数

配置与 Provider 选择策略

模型选择

Provider 选择顺序

图片编辑

Provider 深度配置

示例

相关文档

常见问题

Agent 工具列表里没有 image_generate 怎么办

OpenAI 透明背景图片怎么出

某些参数被报告为 `ignoredOverrides` 是什么意思