图像生成

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

只有当 OpenClaw 确实能够对提供商进行身份验证时，该提供商的默认值 才会进入候选列表。始终启用经过身份验证的提供商之间的自动回退； 每次调用的 model 始终具有最终决定权。

对于较慢的图像后端，请设置 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 图像生成默认使用 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 部署路由 OpenAI 图像生成，而不是使用 api.openai.com，请参阅 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、google/gemini-3-pro-image 和 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": "带有孔版印刷纹理的赛博杂志肖像",
  "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、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 合约。