图像生成
image_generate 工具通过你配置的提供方创建和编辑图像。在聊天会话中,它以异步方式运行:原生媒体生成所有者会跟踪操作,立即返回任务 ID,并在提供方完成后唤醒智能体。完成智能体按照会话当前的可见回复契约,回复一条面向用户的简短说明以及所有结构化的生成附件。如果生成失败,智能体会改为返回一条简洁的可见失败信息。如果请求方会话处于非活动状态,或其主动唤醒失败,OpenClaw 会发送一条幂等的直接回退消息并附带生成的图像,以确保结果不会丢失。
你可以在完成智能体仍在工作时发送后续消息。新的回合会等待完成及其投递稳定后再开始。
在 WebChat 和 macOS 应用中,生成的附件会保留在完成回复上,而不会再次出现在单独的仅图像消息中。交互式 WebChat 请求会将其完成保留在该会话中,即使之前的频道对话在该会话中留下了外部投递路由。重放已完成的投递会保持相同的消息和附件标识。
Note
该工具仅在至少有一个图像生成提供方可用时出现。如果你在智能体的工具中没有看到 image_generate,请配置 agents.defaults.mediaModels.image、设置提供方的 API 密钥,或使用 OpenAI ChatGPT/Codex OAuth 登录。
快速开始¶
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 base URL)会重新选择直接使用 OpenAI Images API 路由。
3. 请求智能体
"Generate an image of a friendly robot mascot."
智能体会自动调用 image_generate。无需工具白名单——当提供方可用时,它默认启用。该工具返回后台任务 ID,然后完成智能体在准备好时回复所有生成的附件。
Warning
对于 OpenAI 兼容的局域网端点(如 LocalAI),请保留自定义的 models.providers.openai.baseUrl,并通过 browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true 明确选择启用。私有和内部图像端点默认仍会被阻止。
常见路由¶
| 目标 | 模型引用 | 身份验证 |
|---|---|---|
| OpenAI 图像生成(API 计费) | openai/gpt-image-2 |
OPENAI_API_KEY |
| OpenAI GPT Image 2.5 | openai/gpt-image-2.5-flare 或 openai/gpt-image-2.5-sunburst |
显式 OpenAI API 密钥路由 |
| OpenAI 图像生成(ChatGPT/Codex OAuth) | openai/gpt-image-2 |
OpenAI ChatGPT/Codex OAuth |
| OpenAI 透明背景 PNG/WebP | openai/gpt-image-1.5 |
OPENAI_API_KEY 或 OpenAI ChatGPT/Codex OAuth |
| DeepInfra 图像生成 | deepinfra/black-forest-labs/FLUX-1-schnell |
DEEPINFRA_API_KEY |
| fal Krea 2 表现力/风格导向生成 | fal/krea/v2/medium/text-to-image |
FAL_KEY |
| fal GPT Image 2.5 | fal/openai/gpt-image-2.5/flare/text-to-image 或 fal/openai/gpt-image-2.5/sunburst/text-to-image |
FAL_KEY |
| OpenRouter 图像生成 | openrouter/google/gemini-3.1-flash-image-preview |
OPENROUTER_API_KEY |
| LiteLLM 图像生成 | litellm/gpt-image-2 |
LITELLM_API_KEY |
| Microsoft Foundry MAI 图像生成 | microsoft-foundry/<deployment-name> |
AZURE_OPENAI_API_KEY 或 Entra ID |
| Google Gemini 图像生成 | google/gemini-3.1-flash-image |
GEMINI_API_KEY 或 GOOGLE_API_KEY |
同一个工具同时处理文生图和参考图像编辑。使用 image 传入单个参考,或使用 images 传入多个参考。对于 fal 上的 Krea 2 模型,这些参考会作为风格参考发送,而不是编辑输入。提供方支持的输出提示,如 quality、outputFormat 和 background,在可用时会被转发;如果提供方未声明支持,则会被报告为已忽略。OpenAI 和 fal GPT Image 2.5 声明支持透明背景。其他提供方如果其后端会输出 PNG alpha,则仍可能保留该 alpha 通道。
OpenAI 支持通过直接 Images API 或 Codex Responses 后端,对文本生成图像和参考图像编辑使用 low 和 auto 审核。对于 CLI 请求,请向 openclaw infer image generate 或 openclaw infer image edit 传递 --openai-moderation low|auto。
支持的提供商¶
| 提供商 | 默认模型 | 编辑支持 | 身份验证 |
|---|---|---|---|
| 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 |
gemini-3.1-flash-image |
是(最多 5 张图像) | GEMINI_API_KEY 或 GOOGLE_API_KEY |
|
| LiteLLM | gpt-image-2 |
是(最多 5 张输入图像) | LITELLM_API_KEY |
| Microsoft Foundry | <deployment-name> |
是(仅限 MAI-Image-2.5 模型) | AZURE_OPENAI_API_KEY 或 Entra ID(az login) |
| MiniMax | image-01 |
是(主体参考) | MINIMAX_API_KEY 或 MiniMax OAuth(minimax-portal) |
| OpenAI | gpt-image-2 |
是(最多 5 张图像) | OPENAI_API_KEY 或 OpenAI ChatGPT/Codex OAuth |
| OpenRouter | google/gemini-3.1-flash-image-preview |
是(最多 5 张输入图像) | OPENROUTER_API_KEY |
| Vydra | grok-imagine |
否 | VYDRA_API_KEY |
| xAI | grok-imagine-image |
是(最多 3 张图像) | XAI_API_KEY |
使用 action: "list" 在运行时检查可用的提供商和模型:
使用 action: "status" 检查当前会话中活动的图像生成任务:
任务状态和重复检测的范围限定在发起请求的聊天中,即使直接聊天共享主会话记录也是如此。完成会返回给请求图像的对话方。
提供商能力¶
| 能力 | ComfyUI | DeepInfra | fal | Microsoft Foundry | MiniMax | OpenAI | Vydra | xAI | |
|---|---|---|---|---|---|---|---|---|---|
| 生成(最大数量) | 1 | 4 | 4 | 4 | 1 | 9 | 4 | 1 | 4 |
| 编辑 / 参考 | 1 张图像(工作流) | 1 张图像 | Flux: 1; GPT: 10; GPT 2.5: 16; Krea 风格参考: 10; NB2: 14 | 最多 5 张图像 | 1 张图像 | 1 张图像(主体参考) | 最多 5 张图像 | - | 最多 3 张图像 |
| 尺寸控制 | - | ✓ | ✓ | ✓ | ✓ | - | 最多 4K | - | - |
| 宽高比 | - | - | ✓ | ✓ | - | ✓ | - | - | ✓ |
| 分辨率(1K/2K/4K) | - | - | ✓ | ✓ | - | - | - | - | 1K, 2K |
工具参数¶
promptstring (path) 必填- 图像生成提示词。
action: "generate"必填。 action"generate" | "status" | "list" (path) 默认值:generate- 使用
"status"检查活动会话任务,或使用"list"在运行时检查可用的提供商和模型。 modelstring (path)- 提供商/模型覆盖(例如
openai/gpt-image-2)。使用openai/gpt-image-1.5获取透明的 OpenAI 背景。 imagestring (path)- 编辑模式下单个参考图像路径或 URL。
imagesstring[] (path)- 编辑模式或风格参考模型的多张参考图像(通过共享工具最多 16 张。仍适用提供商特定限制)。
sizestring (path)- 尺寸提示:
1024x1024,1536x1024,1024x1536,2048x2048,3840x2160。 aspectRatiostring (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"。 countnumber (path)- 要生成的图像数量(1-4)。
timeoutMsnumber (path)- 可选的提供商请求超时时间(毫秒)。当 Codex 通过动态工具调用
image_generate时,此每次调用的值仍会覆盖已配置的默认值, 并且上限为 600000 ms。 filenamestring (path)- 输出文件名提示。
openaiobject (path)- 仅限 OpenAI 的提示:
background、moderation、outputCompression和user。 fal.creativity"raw" | "low" | "medium" | "high" (path)- fal Krea 2 创意控制。默认为
medium。
Note
并非所有提供商都支持所有参数。当回退提供商支持的是相近的几何选项,
而不是精确请求的选项时,OpenClaw 会在提交前重新映射到最接近的支持尺寸、
宽高比或分辨率。对于未声明支持的提供商,不支持的输出提示会被丢弃,
并在工具结果中报告。工具结果会报告已应用的设置。
details.normalization 会捕获任何从请求到应用的转换。
配置¶
模型选择¶
{
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 按以下顺序尝试提供商:
- 来自工具调用的
model参数。设置后,仅尝试该模型。 - 来自配置的
agents.defaults.mediaModels.image.primary。 - 按顺序使用
agents.defaults.mediaModels.image.fallbacks。 - 自动检测 - 仅当未配置主模型或回退模型时,使用已配置的提供商默认值:
- 首先使用当前默认提供商。
- 其余已注册的图像生成提供商按 provider-id 顺序。
如果某个提供商失败(认证错误、速率限制等),会自动尝试下一个已配置的候选项。 如果全部失败,错误信息将包含每次尝试的详细信息。 对于参考图像请求,无法编辑图像或无法接受所提供参考图像数量的候选项会被跳过。
每次调用的模型覆盖是精确的
每次调用的 model 覆盖仅尝试该提供商/模型,不会继续尝试已配置的主/回退提供商
或自动检测到的提供商。
自动检测使用已配置的提供商
自动检测会考虑其就绪状态或认证检查通过的提供商默认值。 显式的图像模型配置会将回退限制为已配置的列表。 OpenClaw 不会追加自动检测到的提供商。
超时
对于较慢的图像后端,请设置 agents.defaults.mediaModels.image.timeoutMs。
每次调用的 timeoutMs 工具参数会覆盖已配置的默认值,而已配置的默认值会覆盖
插件编写的提供商默认值。Google 和 OpenRouter 托管的图像提供商使用 180 秒默认值。
Microsoft Foundry MAI、xAI 和 Azure OpenAI 图像生成使用 600 秒。
Codex 动态工具调用使用 120 秒的 image_generate 桥接默认值,
并在配置时遵循相同的超时预算,上限为 OpenClaw 的 600000 ms 动态工具桥接最大值。
在运行时检查
使用 action: "list" 检查当前已注册的提供商、其默认模型以及认证环境变量提示。
图像编辑¶
OpenAI、OpenRouter、Google、DeepInfra、fal、Microsoft Foundry、MiniMax、
ComfyUI 和 xAI 支持编辑参考图像。fal 上的 Krea 2 模型使用与样式参考相同的
image / images 字段,而不是编辑输入。传入参考图像路径或 URL:
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 或 fal 使用 GPT Image 2.5
请显式选择任一版本。现有提供商默认值不会改变:
- OpenAI:
openai/gpt-image-2.5-flare或openai/gpt-image-2.5-sunburst - fal:
fal/openai/gpt-image-2.5/flare/text-to-image或fal/openai/gpt-image-2.5/sunburst/text-to-image
两个版本都支持生成、编辑、xhigh 和 max 质量、
PNG/JPEG/WebP 输出,以及使用 PNG 或 WebP 的透明背景。
通过 OpenClaw,OpenAI 接受最多 5 张参考图像。fal 接受 16 张。
使用参考图像时,fal 会将 /text-to-image 替换为 /edit。
显式的 fal /edit 路径保持不变。
对于直接的 GPT Image 2.5 请求,请使用显式 OpenAI API 密钥路由。
仅导出 OPENAI_API_KEY 不会覆盖现有的 OAuth 配置文件。
这些示例不会建立 GPT Image 2.5 订阅访问权限。
使用 size: "auto" 或有效的 WIDTHxHEIGHT 尺寸。
两个维度都必须能被 16 整除,且任一边不超过 3840 像素。
总像素数必须为 655,360-8,294,400,宽高比从 1:3 到 3:1。
fal 会将宽高比提示转换为有效尺寸,例如将 3:2 转换为 1536x1024。
无效的显式尺寸会以尺寸错误失败。fal 不接受这些模型的 resolution 覆盖,
也不会从编辑输入中推断分辨率。
OpenAI gpt-image-2(以及 gpt-image-1.5)
OpenAI 图像生成默认为 openai/gpt-image-2。如果配置了 openai 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,请显式使用 API 密钥、自定义基础 URL
或 Azure 端点配置 models.providers.openai。
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,否则工具会将它们报告为
被忽略的覆盖项。
对于直接的 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 对象下:
{
"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 端点。
Microsoft Foundry MAI 图像模型
Microsoft Foundry 图像生成使用 microsoft-foundry/ 提供商前缀下的已部署 MAI 图像部署名称。
没有提供商级别的默认模型,因为 MAI API 期望在 model 字段中提供你的部署名称:
{
agents: {
defaults: {
mediaModels: {
image: {
primary: "microsoft-foundry/<deployment-name>",
timeoutMs: 600000,
},
},
},
},
}
该提供商使用 Microsoft Foundry 的 MAI API,而不是 OpenAI Images API:
- 生成端点:
/mai/v1/images/generations - 编辑端点:
/mai/v1/images/edits - 身份验证:
AZURE_OPENAI_API_KEY/ 提供商 API 密钥,或通过az login使用 Entra ID - 输出:一张 PNG 图像
- 尺寸:默认
1024x1024。宽度和高度都必须至少为 768 px, 总像素数最多为 1,048,576 - 编辑:一张 PNG 或 JPEG 参考图像,仅由
MAI-Image-2.5-Flash和MAI-Image-2.5部署支持
仅提示词生成可以在仅配置 Foundry 端点的情况下使用自定义部署名称。
使用自定义部署名称的编辑需要接入/模型元数据,以便 OpenClaw 可以验证该部署
由 MAI-Image-2.5-Flash 或 MAI-Image-2.5 支持。
当前 MAI 图像模型包括 MAI-Image-2.5-Flash、MAI-Image-2.5、
MAI-Image-2e 和 MAI-Image-2。有关设置和聊天模型行为,请参阅
Microsoft Foundry 插件。
OpenRouter 图像模型
OpenRouter 图像生成使用相同的 OPENROUTER_API_KEY,
并通过 OpenRouter 专用的 /api/v1/images 端点路由标准请求。
已配置的自定义 OpenRouter 基础 URL 会保留现有的
chat-completions 图像路由,以兼容代理。使用 openrouter/ 前缀选择
OpenRouter 图像模型:
{
agents: {
defaults: {
mediaModels: {
image: {
primary: "openrouter/google/gemini-3.1-flash-image-preview",
},
},
},
},
}
OpenClaw 会将 prompt、count、参考图像以及
Gemini 兼容的 aspectRatio / resolution 提示转发到 OpenRouter。
当前内置的 OpenRouter 图像模型快捷方式包括
google/gemini-3.1-flash-image、
google/gemini-3-pro-image 和 openai/gpt-5.4-image-2。使用
action: "list" 查看你配置的插件暴露的内容。
fal Krea 2
fal 上的 Krea 2 模型使用 fal 的原生 Krea schema,而不是
Flux 使用的通用 image_size schema。OpenClaw 会发送:
- 用于宽高比提示的
aspect_ratio - 默认为
medium的creativity - 当提供
image或images时发送image_style_references
选择 Krea 2 Medium 以获得更快的表现力插图,选择 Krea 2 Large 以获得更慢、更细致的照片级真实和纹理效果:
{
agents: {
defaults: {
mediaModels: {
image: {
primary: "fal/krea/v2/medium/text-to-image",
},
},
},
},
}
Krea 2 每次请求返回一张图像。对于 Krea,优先使用
aspectRatio。OpenClaw 会将 size 映射到最接近的受支持 Krea 宽高比,
并且对于 Krea 会拒绝 resolution,而不是将其丢弃。当你想要
原生 Krea 创造力级别时,使用 fal.creativity:
MiniMax 双认证
MiniMax 图像生成可通过两种内置 MiniMax 认证路径使用:
minimax/image-01用于 API 密钥配置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-quality - 数量:最多 4 个
- 参考图:一个
image或最多三个images - 宽高比:
1:1、16:9、9:16、4:3、3:4、3:2、2:3、2:1、1:2、19.5:9、9:19.5、20:9、9:20 - 分辨率:
1K、2K - 输出:作为由 OpenClaw 管理的图像附件返回
OpenClaw 有意不暴露 xAI 原生的 quality、mask、user 或 auto 宽高比,直到这些控制项存在于共享的跨提供商 image_generate 契约中。
示例¶
/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:
/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"}'
等效 CLI:
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配置 - 模型 - 模型配置和故障转移
- 媒体概览 - 媒体工具如何协同工作
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw