图像生成

image_generate 工具允许代理使用您配置的提供商创建和编辑图像。生成的图像会作为媒体附件自动在代理的回复中发送。

快速开始

为至少一个提供商设置 API 密钥（例如 OPENAI_API_KEY 或 GEMINI_API_KEY）。
（可选）设置您的首选模型：

{
  agents: {
    defaults: {
      imageGenerationModel: "openai/gpt-image-1",
    },
  },
}

向代理提问：“生成一张友好的龙虾吉祥物图片。”

代理会自动调用 image_generate。无需将工具加入允许列表 —— 当提供商可用时，它默认处于启用状态。

支持的提供商

提供商	默认模型	编辑支持	API 密钥
OpenAI	`gpt-image-1`	否	`OPENAI_API_KEY`
Google	`gemini-3.1-flash-image-preview`	是	`GEMINI_API_KEY` 或 `GOOGLE_API_KEY`
fal	`fal-ai/flux/dev`	是	`FAL_KEY`
MiniMax	`image-01`	是（主体参考）	`MINIMAX_API_KEY`

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

/tool image_generate action=list

工具参数

参数	类型	描述
`prompt`	string	图像生成提示词（`action: "generate"` 必需）
`action`	string	`"generate"`（默认）或 `"list"` 以检查提供商
`model`	string	提供商/模型覆盖，例如 `openai/gpt-image-1`
`image`	string	用于编辑模式的单个参考图像路径或 URL
`images`	string[]	用于编辑模式的多个参考图像（最多 5 张）
`size`	字符串	尺寸提示：`1024x1024`、`1536x1024`、`1024x1536`、`1024x1792`、`1792x1024`
`aspectRatio`	字符串	宽高比：`1:1`、`2:3`、`3:2`、`3:4`、`4:3`、`4:5`、`5:4`、`9:16`、`16:9`、`21:9`
`resolution`	字符串	分辨率提示：`1K`、`2K` 或 `4K`
`count`	数字	要生成的图片数量（1–4）
`filename`	字符串	输出文件名提示

并非所有提供商都支持所有参数。该工具会传递各提供商支持的内容，并忽略其余参数。

配置

模型选择

{
  agents: {
    defaults: {
      // String form: primary model only
      imageGenerationModel: "google/gemini-3-pro-image-preview",

      // Object form: primary + ordered fallbacks
      imageGenerationModel: {
        primary: "openai/gpt-image-1",
        fallbacks: ["google/gemini-3.1-flash-image-preview", "fal/fal-ai/flux/dev"],
      },
    },
  },
}

提供商选择顺序

生成图片时，OpenClaw 会按以下顺序尝试提供商：

工具调用中的 model 参数（如果代理指定了一个）
配置中的 imageGenerationModel.primary
按顺序排列的 imageGenerationModel.fallbacks
自动检测 — 查询所有已注册提供商的默认设置，优先顺序为：已配置的主提供商，然后是 OpenAI，接着是 Google，最后是其他

如果提供商失败（认证错误、速率限制等），系统会自动尝试下一个候选者。如果全部失败，错误信息将包含每次尝试的详细信息。

图像编辑

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

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

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

提供商功能

功能	OpenAI	Google	fal	MiniMax
生成	是（最多 4 张）	是（最多 4 张）	是（最多 4 张）	是（最多 9 张）
编辑/参考	否	是（最多 5 张图片）	是（1 张图片）	是（1 张图片，主体参考）
尺寸控制	是	是	是	否
宽高比	否	是	是（仅限生成）	是
分辨率（1K/2K/4K）	否	是	是	否

图像生成

图像生成

快速开始

支持的提供商

工具参数

配置

模型选择

提供商选择顺序

图像编辑

提供商功能

相关