图像生成
image_generate 工具让智能体能够使用你已配置的提供商创建和编辑图像。生成的图像会自动作为媒体附件随智能体的回复一并发送。
只有在至少有一个图像生成提供商可用时，此工具才会显示。如果你在智能体的工具中看不到 image_generate，请配置 agents.defaults.imageGenerationModel 或设置提供商 API 密钥。
快速开始
- 为至少一个提供商设置 API 密钥（例如
OPENAI_API_KEY 或 GEMINI_API_KEY）。
- 可选：设置你偏好的模型：
{
agents: {
defaults: {
imageGenerationModel: {
primary: "openai/gpt-image-1",
},
},
},
}
- 向智能体提问：“生成一张友好的龙虾吉祥物图像。”
智能体会自动调用 image_generate。无需将工具加入允许列表——当有可用提供商时，它默认启用。
支持的提供商
| 提供商 | 默认模型 | 编辑支持 | API 密钥 |
|---|
| OpenAI | gpt-image-1 | 是（最多 5 张图像） | 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 或 MiniMax OAuth（minimax-portal） |
| ComfyUI | workflow | 是（1 张图像，由工作流配置） | 云端使用 COMFY_API_KEY 或 COMFY_CLOUD_API_KEY |
| Vydra | grok-imagine | 否 | VYDRA_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 | string | 尺寸提示：1024x1024、1536x1024、1024x1536、1024x1792、1792x1024 |
aspectRatio | string | 宽高比：1:1、2:3、3:2、3:4、4:3、4:5、5:4、9:16、16:9、21:9 |
resolution | string | 分辨率提示：1K、2K 或 4K |
count | number | 要生成的图像数量（1–4） |
filename | string | 输出文件名提示 |
size、aspectRatio 和 resolution 值会反映实际发送的内容，而 details.normalization 会记录从请求值到应用值的转换。
模型选择
{
agents: {
defaults: {
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
- 自动检测 —— 仅使用基于认证的提供商默认值：
- 先使用当前默认提供商
- 然后按提供商 ID 顺序使用其余已注册的图像生成提供商
如果某个提供商失败（认证错误、速率限制等），系统会自动尝试下一个候选项。如果全部失败，错误中会包含每次尝试的详细信息。
说明：
- 自动检测会感知认证状态。只有当 OpenClaw 实际能够验证该提供商时，
该提供商默认值才会进入候选列表。
- 自动检测默认启用。如果你希望图像生成仅使用显式的
model、primary 和 fallbacks
条目，请设置
agents.defaults.mediaGenerationAutoProviderFallback: false。
- 使用
action: "list" 可查看当前已注册的提供商、它们的
默认模型以及认证环境变量提示。
图像编辑
OpenAI、Google、fal、MiniMax 和 ComfyUI 支持编辑参考图像。传入参考图像路径或 URL：
"把这张照片生成为水彩风格版本" + image: "/path/to/photo.jpg"
images 参数最多支持 5 张参考图像。fal、MiniMax 和 ComfyUI 支持 1 张。
MiniMax 图像生成可通过两种内置的 MiniMax 认证路径使用：
minimax/image-01，用于 API 密钥配置minimax-portal/image-01，用于 OAuth 配置
提供商能力
| 能力 | OpenAI | Google | fal | MiniMax | ComfyUI | Vydra |
|---|
| 生成 | 是（最多 4 张） | 是（最多 4 张） | 是（最多 4 张） | 是（最多 9 张） | 是（输出由工作流定义） | 是（1 张） |
| 编辑/参考 | 是（最多 5 张图像） | 是（最多 5 张图像） | 是（1 张图像） | 是（1 张图像，主体参考） | 是（1 张图像，由工作流配置） | 否 |
| 尺寸控制 | 是 | 是 | 是 | 否 | 否 | 否 |
| 宽高比 | 否 | 是 | 是（仅生成） | 是 | 否 | 否 |
| 分辨率（1K/2K/4K） | 否 | 是 | 是 | 否 | 否 | 否 |
相关内容
