图像生成

单次调用的 model 覆盖只会尝试该提供商/模型， 不会继续使用已配置的 primary/fallback 或自动检测到的提供商。

只有当 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 ms 动态工具桥接最大值。

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

OpenAI 图像生成默认使用 openai/gpt-image-2。如果配置了 openai OAuth 配置档，OpenClaw 会复用 Codex 订阅聊天模型使用的 同一个 OAuth 配置档，并通过 Codex Responses 后端发送图像请求。 旧版 Codex 基础 URL（例如 https://chatgpt.com/backend-api） 会针对图像请求规范化为 https://chatgpt.com/backend-api/codex。OpenClaw 不会 为该请求静默回退到 OPENAI_API_KEY - 如需强制直接通过 OpenAI Images API 路由，请显式配置 models.providers.openai，并提供 API key、自定义基础 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，否则工具会把它们报告为被忽略的覆盖项。

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 schema， 而不是 Flux 使用的通用 image_size schema。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 提供商对仅提示词请求使用 /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、2:3、3:2
• 分辨率：1K、2K
• 输出：作为 OpenClaw 管理的图像附件返回

OpenClaw 有意不暴露 xAI 原生的 quality、mask、user 或额外的仅原生宽高比，直到这些控制项存在于共享的跨提供商 image_generate 契约中。