图像生成

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

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

对于较慢的图像后端，设置 agents.defaults.imageGenerationModel.timeoutMs。每次调用的 timeoutMs 工具参数会覆盖已配置默认值。

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

OpenAI 图像生成默认使用 openai/gpt-image-2。如果配置了 openai-codex 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 路由，请使用 API key、自定义基础 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 专属选项位于 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 输出。

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

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

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" 查看你配置的插件暴露了哪些内容。

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-pro
• 数量：最多 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 契约中。