跳转到内容
OpenClaw Docs

图像生成

image_generate 工具允许代理使用您配置的提供商创建和编辑图像。在聊天会话中，图像生成是异步运行的：OpenClaw 记录后台任务，立即返回任务 ID，并在提供商完成时唤醒代理。完成代理必须通过 message 工具发送生成的图像；OpenClaw 不会自动发送私有最终回复作为后备。

快速开始

Section titled “快速开始”

  1. 配置身份验证

    为至少一个提供商设置 API 密钥（例如 OPENAI_API_KEY、 GEMINI_API_KEY、OPENROUTER_API_KEY）或使用 OpenAI Codex OAuth 登录。

  2. 选择默认模型（可选）

    {
      agents: {
        defaults: {
          imageGenerationModel: {
            primary: "openai/gpt-image-2",
            timeoutMs: 180_000,
          },
        },
      },
    }
    ```OAuth
    

    Codex OAuth 使用相同的 `openai/gpt-image-2` 模型引用。当配置了
    `openai-codex`OAuthOpenClawOAuth OAuth 配置文件时，OpenClaw 将图像请求通过该 OAuth 配置文件
    路由，而不是首先尝试 `OPENAI_API_KEY`。显式的 `models.providers.openai`APIOpenAIAPI 配置（API 密钥、
    自定义/Azure 基础 URL）会选择回退到直接使用 OpenAI Images API
    路由。

  3. 询问智能体

    “生成一个友好的机器人吉祥物图像。”

    智能体会自动调用 image_generate。不需要工具允许列表—— 当有提供商可用时，该工具默认启用。该工具返回一个后台任务 ID，然后完成智能体 会在准备好时通过 message 工具发送生成的附件。

常用路由

Section titled “常用路由”
目标模型引用身份验证
使用 OpenAI 计费的 API 图像生成openai/gpt-image-2OPENAI_API_KEY
通过 OpenAI 订阅身份验证进行 OpenAI 图像生成openai/gpt-image-2OpenAI Codex OAuth
OpenAI 透明背景 PNG/WebPopenai/gpt-image-1.5OPENAI_API_KEYOpenAIOAuth 或 OpenAI Codex OAuth
DeepInfra 图像生成deepinfra/black-forest-labs/FLUX-1-schnellDEEPINFRA_API_KEY
OpenRouter 图像生成openrouter/google/gemini-3.1-flash-image-previewOPENROUTER_API_KEY
LiteLLM 图像生成litellm/gpt-image-2LITELLM_API_KEY
Google Gemini 图像生成google/gemini-3.1-flash-image-previewGEMINI_API_KEY 或 GOOGLE_API_KEY

同一个 image_generate 工具处理文生图和参考图像编辑。使用 image 处理单个参考或使用 images 处理多个参考。提供商支持的输出提示（如 quality、outputFormat 和 background）在可用时会被转发，并在提供商不支持时报告为已忽略。捆绑的透明背景支持是 OpenAI 特有的；如果其他提供商的后端生成，它们可能仍然保留 PNG alpha 通道。

支持的提供商

Section titled “支持的提供商”
提供商默认模型编辑支持认证
ComfyUIworkflow是（1 张图像，工作流配置）COMFY_API_KEY 或 COMFY_CLOUD_API_KEY 用于云端
DeepInfrablack-forest-labs/FLUX-1-schnell是（1 张图像）DEEPINFRA_API_KEY
falfal-ai/flux/dev是（特定模型的限制）FAL_KEY
Googlegemini-3.1-flash-image-preview是GEMINI_API_KEY 或 GOOGLE_API_KEY
LiteLLMgpt-image-2是（最多 5 张输入图像）LITELLM_API_KEY
MiniMaximage-01是（主题参考）MINIMAX_API_KEY 或 MiniMax OAuth (minimax-portal)
OpenAIgpt-image-2是（最多 4 张图片）OPENAI_API_KEY 或 OpenAI Codex OAuth
OpenRoutergoogle/gemini-3.1-flash-image-preview是（最多 5 张输入图片）OPENROUTER_API_KEY
Vydragrok-imagine否VYDRA_API_KEY
xAIgrok-imagine-image是（最多 5 张图片）XAI_API_KEY

使用 action: "list" 在运行时检查可用的提供商和模型：

/tool image_generate action=list

使用 action: "status" 检查当前会话的活动图像生成任务：

/tool image_generate action=status

提供商能力

Section titled “提供商能力”
能力ComfyUIDeepInfrafalGoogleMiniMaxOpenAIVydraxAI
生成（最大数量）工作流定义4449414
编辑 / 参考1 张图像（工作流）1 张图片Flux: 1; GPT: 10; NB2: 14最多 5 张图像1 张图像（主题参考）最多 5 张图像-最多 5 张图像
尺寸控制-✓✓✓-最高 4K--
宽高比--✓✓✓--✓
分辨率 (1K/2K/4K)--✓✓---1K, 2K

工具参数

Section titled “工具参数”
图像生成提示词。`action: "generate"` 必需。 使用 `"status"` 检查活动会话任务，或使用 `"list"` 在运行时检查 可用的提供商和模型。 提供商/模型覆盖（例如 `openai/gpt-image-2`）。请使用 `openai/gpt-image-1.5` 以实现透明的 OpenAI 背景。 编辑模式的单张参考图像路径或 URL。 编辑模式的多张参考图像（支持的提供商最多 5 张）。 尺寸提示：`1024x1024`、`1536x1024`、`1024x1536`、`2048x2048`、`3840x2160`。 宽高比：`1:1`、`2:3`、`3:2`、`3:4`、`4:3`、`4:5`、`5:4`、`9:16`、`16:9`、`21:9`。 分辨率提示。 当提供商支持时的质量提示。 当提供商支持时的输出格式提示。 当提供商支持时的背景提示。对于支持透明度的提供商，请使用 `transparent` 配合 `outputFormat: "png"` 或 `"webp"`。 要生成的图像数量 (1-4)。 可选的提供商请求超时时间（以毫秒为单位）。当 Codex 通过动态工具调用 `image_generate` 时，此每次调用的值仍会覆盖 配置的默认值，且上限为 600000 毫秒。 输出文件名提示。 OpenAI 专用提示：`background`、`moderation`、`outputCompression` 和 `user`。

配置

Section titled “配置”

模型选择

Section titled “模型选择”
{
  agents: {
    defaults: {
      imageGenerationModel: {
        primary: "openai/gpt-image-2",
        timeoutMs: 180_000,
        fallbacks: ["openrouter/google/gemini-3.1-flash-image-preview", "google/gemini-3.1-flash-image-preview", "fal/fal-ai/flux/dev"],
      },
    },
  },
}

提供商选择顺序

Section titled “提供商选择顺序”

OpenClaw 按以下顺序尝试提供商：

  1. model 参数（如果代理指定了一个）。
  2. imageGenerationModel.primary（来自配置）。
  3. imageGenerationModel.fallbacks（按顺序）。
  4. 自动检测 - 仅限基于身份验证的提供商默认值：
    • 首先是当前默认提供商；
    • 其余已注册的图像生成提供商按提供商 ID 顺序排列。

如果提供商失败（身份验证错误、速率限制等），系统将自动尝试下一个配置的候选项。如果全部失败，错误信息将包含每次尝试的详细信息。

每次调用的模型覆盖是精确的

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

自动检测具有身份验证感知能力

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

Timeouts

为缓慢的图像后端设置 agents.defaults.imageGenerationModel.timeoutMs。每次调用的 timeoutMs 工具参数会覆盖配置的默认值。Google、OpenRouter 和 xAI 托管的图像提供商使用 180 秒的默认值；Azure OpenAI 图像生成使用 600 秒。Codex 动态工具调用使用 120 秒的 image_generate 网桥默认值，并在配置时遵守相同的超时预算，受 OpenClaw 的 600000 毫秒动态工具网桥最大值限制。

Inspect at runtime

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

图像编辑

Section titled “图像编辑”

OpenAI、OpenRouter、Google、DeepInfra、fal、MiniMax、ComfyUI 和 xAI 支持编辑参考图像。传递参考图像路径或 URL：

"Generate a watercolor version of this photo" + image: "/path/to/photo.jpg"

OpenAI、OpenRouter、Google 和 xAI 通过 images 参数支持最多 5 张参考图像。fal 支持一张参考图像用于 Flux 图生图，GPT Image 2 编辑最多支持 10 张，Nano Banana 2 编辑最多支持 14 张。MiniMax 和 ComfyUI 支持 1 张。

提供程序深入探究

Section titled “提供程序深入探究”
OpenAIOpenAI gpt-image-2（以及 gpt-image-1.5）

OpenAI 图像生成默认为 openai/gpt-image-2。如果配置了 openai-codexOAuthOpenClawOAuth OAuth 配置文件，OpenClaw 将重用 Codex 订阅聊天模型使用的相同 OAuth 配置文件，并通过 Codex Responses 后端发送 图像请求。传统的 Codex 基本 URL（例如 https://chatgpt.com/backend-api）会被规范化为 https://chatgpt.com/backend-api/codexOpenClaw 用于图像请求。OpenClaw 不会针对该请求自动静默回退到 OPENAI_API_KEYOpenAIAPI —— 要强制直接使用 OpenAI Images API 路由，请使用 API 密钥、自定义基本 URL 或 Azure 端点显式配置 models.providers.openaiAPI。

仍然可以显式选择 openai/gpt-image-1.5、openai/gpt-image-1 和 openai/gpt-image-1-mini 模型。使用 gpt-image-1.5 生成透明背景的 PNG/WebP 输出；当前的 gpt-image-2API API 会拒绝 background: "transparent"。

gpt-image-2 通过同一个 image_generateOpenClaw 工具支持文生图生成 和参考图像编辑。 OpenClaw 会将 prompt、count、size、quality、outputFormatOpenAIOpenAI 和参考图像转发给 OpenAI。OpenAI 不会直接 接收 aspectRatio 或 resolutionOpenClaw；如果可能，OpenClaw 会将 其映射到支持的 sizeOpenAI，否则该工具会将其报告为 已忽略的覆盖参数。

OpenAI 特定选项位于 openai 对象下：

{
  "quality": "low",
  "outputFormat": "jpeg",
  "openai": {
    "background": "opaque",
    "moderation": "low",
    "outputCompression": 60,
    "user": "end-user-42"
  }
}

openai.background 接受 transparent、opaque 或 auto； 透明输出需要 outputFormat png 或 webpOpenAIOpenClaw 以及 支持透明的 OpenAI 图像模型。OpenClaw 将默认的 gpt-image-2 透明背景请求路由到 gpt-image-1.5。 openai.outputCompression 适用于 JPEG/WebP 输出。

顶层 backgroundOpenAI 提示是提供商中立的，当选择 OpenAI 提供商时，当前映射到相同的 OpenAI backgroundOpenAI 请求字段。未声明背景支持的提供商 会将其在 ignoredOverridesOpenAIOpenAI 中返回，而不是接收不支持的参数。

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

OpenRouterOpenRouter 图像模型

OpenRouter 图像生成使用相同的 OPENROUTER_API_KEYOpenRouter 并通过 OpenRouter 的聊天补全图像 APIOpenRouter 进行路由。使用 openrouter/ 前缀选择 OpenRouter 图像模型：

{
  agents: {
    defaults: {
      imageGenerationModel: {
        primary: "openrouter/google/gemini-3.1-flash-image-preview",
      },
    },
  },
}
```OpenClaw


OpenClaw 会将 `prompt`、`count`、参考图像以及 Gemini 兼容的 `aspectRatio` / `resolution`OpenRouterOpenRouter 提示转发给 OpenRouter。当前内置的 OpenRouter 图像模型快捷方式包括 `google/gemini-3.1-flash-image-preview`、`google/gemini-3-pro-image-preview` 和 `openai/gpt-5.4-image-2`。使用 `action: "list"` 查看您配置的插件所暴露的内容。
MiniMaxMiniMax 双重认证

MiniMax 图像生成可通过两种捆绑的 MiniMax 认证路径使用：

  • minimax/image-01API 用于 API 密钥设置
  • minimax-portal/image-01OAuth 用于 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、2:3、3:2
  • 分辨率：1K、2K
  • 输出：作为 OpenClaw 托管的图像附件返回

OpenClaw 故意不公开 xAI 原生的 quality、mask、 user 或额外的仅原生纵横比，直到这些控件存在于共享的跨提供商 image_generate 协定中。

示例

Section titled “示例”
/tool image_generate action=generate model=openai/gpt-image-2 prompt="A clean editorial poster for OpenClaw image generation" size=3840x2160 count=1

openclaw infer image edit 上也提供相同的 --output-format 和 --background 标志；--openai-background 仍作为 OpenAI 特定的别名。除 OpenAI 以外的内置提供商目前不声明显式的背景控制，因此对于它们，background: "transparent" 被报告为已忽略。

相关

Section titled “相关”
  • 工具概述 - 所有可用的代理工具
  • ComfyUI - 本地 ComfyUI 和 Comfy Cloud 工作流设置
  • fal - fal 图像和视频提供商设置
  • Google (Gemini) - Gemini 图像提供商设置
  • MiniMax - MiniMax 图像提供商设置
  • OpenAI - OpenAI 图像提供商设置
  • Vydra - Vydra 图像、视频和语音设置
  • xAI - Grok 图像、视频、搜索、代码执行和 TTS 设置
  • 配置参考 - imageGenerationModel 配置
  • 模型 - 模型配置和故障转移