图像生成

每次调用的 model 覆盖只会尝试该提供商和模型，不会继续尝试已配置的主要模型、回退模型或自动检测到的提供商。

仅当 OpenClaw 确实能够对提供商进行身份验证时，该提供商的默认值才会进入候选列表。将 agents.defaults.mediaGenerationAutoProviderFallback: false 设为仅使用显式的 model、primary 和 fallbacks 条目。

对于速度较慢的图像后端，请设置 agents.defaults.imageGenerationModel.timeoutMs。每次调用的 timeoutMs 工具参数会覆盖已配置的默认值，而已配置的默认值会覆盖插件定义的提供商默认值。Google 和 OpenRouter 托管的图像提供商默认超时时间为 180 秒；Microsoft Foundry MAI、xAI 和 Azure OpenAI 图像生成的默认超时时间为 600 秒。Codex 动态工具调用使用 120 秒的 image_generate 桥接默认值，并在已配置时遵循相同的超时预算，但受 OpenClaw 动态工具桥接 600000 毫秒上限的约束。

使用 action: "list" 检查当前已注册的提供商、其默认模型以及身份验证环境变量提示。

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 key、自定义基础 URL 或 Azure 端点显式配置 models.providers.openai。

仍可显式选择 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 输出，对 PNG 输出会被忽略。

顶层 background 提示与提供商无关；选择 OpenAI provider 时，它目前会映射到同一个 OpenAI background 请求字段。未声明支持背景的提供商不会接收这个不受支持的参数，而是将其返回到 ignoredOverrides 中。

要通过 Azure OpenAI 部署而不是 api.openai.com 路由 OpenAI 图像生成，请参阅 Azure OpenAI 端点。

Microsoft Foundry 图像生成使用 microsoft-foundry/ 提供商前缀下已部署的 MAI 图像部署名称。没有提供商级默认模型，因为 MAI API 要求在 model 字段中填写你的部署名称：

{  agents: {    defaults: {      imageGenerationModel: {        primary: "microsoft-foundry/<deployment-name>",        timeoutMs: 600_000,      },    },  },}

该提供商使用 Microsoft Foundry 的 MAI API，而不是 OpenAI Images API：

• 生成端点：/mai/v1/images/generations
• 编辑端点：/mai/v1/images/edits
• 身份验证：AZURE_OPENAI_API_KEY / 提供商 API key，或通过 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_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" 查看你配置的插件公开了哪些模型。

fal 上的 Krea 2 模型使用 fal 原生的 Krea 模式，而不是 Flux 使用的通用 image_size 模式。OpenClaw 会发送：

• 用于宽高比提示的 aspect_ratio
• creativity，默认为 medium
• 提供 image 或 images 时使用 image_style_references

如果需要更快、更具表现力的插画，请选择 Krea 2 Medium；如果需要速度较慢但细节更丰富、更加逼真且纹理更细腻的效果，请选择 Krea 2 Large：

{  agents: {    defaults: {      imageGenerationModel: {        primary: "fal/krea/v2/medium/text-to-image",      },    },  },}

Krea 2 当前每个请求返回一张图像。对于 Krea，优先使用 aspectRatio；OpenClaw 会将 size 映射为最接近的受支持 Krea 宽高比，并会拒绝 Krea 的 resolution，而不是直接丢弃它。需要使用 Krea 原生创意级别时，请使用 fal.creativity：

{  "model": "fal/krea/v2/medium/text-to-image",  "prompt": "A cyber zine portrait with risograph texture",  "aspectRatio": "9:16",  "fal": {    "creativity": "high"  }}

可以通过两种内置 MiniMax 身份验证路径使用 MiniMax 图像生成：

• minimax/image-01，用于 API key 设置
• minimax-portal/image-01，用于 OAuth 设置

内置 xAI provider 对仅提示词请求使用 /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 契约。