圖片生成

image_generate 工具讓代理程式使用您設定的提供者建立和編輯圖片。在聊天工作階段中，圖片產生會非同步執行：OpenClaw 記錄一個背景任務，立即傳回任務 ID，並在提供者完成時喚醒代理程式。完成代理程式會遵循工作階段的正常可見回覆模式：若已設定則自動傳送最終回覆，或在工作階段需要訊息工具時傳送 message(action="send")。如果請求者工作階段已停用或其主動喚醒失敗，且完成回覆中仍缺少部分產生的圖片，OpenClaw 會傳送一個僅包含缺失圖片的等幕直接後備回應。

快速入門

設定驗證
為至少一個提供者設定 API 金鑰（例如 OPENAI_API_KEY、 GEMINI_API_KEY、OPENROUTER_API_KEY）或使用 OpenAI Codex OAuth 登入。
選擇預設模型 (可選)
```
{
  agents: {
    defaults: {
      imageGenerationModel: {
        primary: "openai/gpt-image-2",
        timeoutMs: 180_000,
      },
    },
  },
}
```
ChatGPT/Codex OAuth 使用相同的 openai/gpt-image-2 模型參考。當設定 openai OAuth 設定檔時，OpenClaw 會透過該 OAuth 設定檔傳送圖片請求，而非先嘗試 OPENAI_API_KEY。明確的 models.providers.openai 設定 (API 金鑰、自訂/Azure 基礎 URL) 會選回直接 OpenAI Images API 路由。
要求代理
「生成一張友善的機器人吉祥物圖片。」

代理會自動呼叫 image_generate。不需要工具允許清單（allow-listing）——當有提供者可用時，此工具預設為啟用。該工具會傳回一個背景任務 ID，然後完成代理會在準備好時透過 message 工具傳送生成的附件。

常見路由

目標	模型參照	認證
透過 API 計費進行 OpenAI 圖片生成	`openai/gpt-image-2`	`OPENAI_API_KEY`
使用 Codex 訂閱驗證進行 OpenAI 影像生成	`openai/gpt-image-2`	OpenAI ChatGPT/Codex OAuth
OpenAI 透明背景 PNG/WebP	`openai/gpt-image-1.5`	`OPENAI_API_KEY` 或 OpenAI Codex OAuth
DeepInfra 圖片生成	`deepinfra/black-forest-labs/FLUX-1-schnell`	`DEEPINFRA_API_KEY`
fal Krea 2 表達/風格導向生成	`fal/krea/v2/medium/text-to-image`	`FAL_KEY`
OpenRouter 圖片生成	`openrouter/google/gemini-3.1-flash-image-preview`	`OPENROUTER_API_KEY`
LiteLLM 圖片生成	`litellm/gpt-image-2`	`LITELLM_API_KEY`
Google Gemini 圖片生成	`google/gemini-3.1-flash-image-preview`	`GEMINI_API_KEY` 或 `GOOGLE_API_KEY`

同一個 image_generate 工具處理文字轉圖片和參考圖片編輯。對於單一參考請使用 image，或對於多個參考使用 images。對於 fal 上的 Krea 2 模型，這些參考會作為風格參考發送，而不是編輯輸入。當提供者支援時，提供者支援的輸出提示（如 quality、outputFormat 和 background）會被轉發，當提供者不支援時則會回報為已忽略。內建的透明背景支援是 OpenAI 專屬的；如果他們的後端輸出 PNG alpha 通道，其他提供者可能仍會保留它。

支援的提供者

提供者	預設模型	編輯支援	驗證
ComfyUI	`workflow`	是（1 張圖片，工作流程設定）	`COMFY_API_KEY` 或 `COMFY_CLOUD_API_KEY` 用於雲端
DeepInfra	`black-forest-labs/FLUX-1-schnell`	是（1 張圖片）	`DEEPINFRA_API_KEY`
fal	`fal-ai/flux/dev`	是（模型特定限制）	`FAL_KEY`
Google	`gemini-3.1-flash-image-preview`	是	`GEMINI_API_KEY` 或 `GOOGLE_API_KEY`
LiteLLM	`gpt-image-2`	是（最多 5 張輸入圖片）	`LITELLM_API_KEY`
MiniMax	`image-01`	是（主體參考）	`MINIMAX_API_KEY` 或 MiniMax OAuth (`minimax-portal`)
OpenAI	`gpt-image-2`	是（最多 4 張圖片）	`OPENAI_API_KEY` 或 OpenAI ChatGPT/Codex OAuth
OpenRouter	`google/gemini-3.1-flash-image-preview`	是（最多 5 張輸入圖片）	`OPENROUTER_API_KEY`
Vydra	`grok-imagine`	否	`VYDRA_API_KEY`
xAI	`grok-imagine-image`	是（最多 5 張圖片）	`XAI_API_KEY`

使用 action: "list" 來檢查執行時可用的供應商與模型：

/tool image_generate action=list

使用 action: "status" 來檢查目前工作階段的活躍圖像生成任務：

/tool image_generate action=status

供應商功能

功能	ComfyUI	DeepInfra	fal	Google	MiniMax	OpenAI	Vydra	xAI
生成（最大數量）	工作流程定義	4	4	4	9	4	1	4
編輯 / 參考	1 張圖片（工作流程）	1 張圖片	Flux: 1; GPT: 10; Krea style refs: 10; NB2: 14	最多 5 張圖片	1 張圖片（主體參考）	最多 5 張圖片	-	最多 5 張圖片
尺寸控制	-	✓	✓	✓	-	最高 4K	-	-
長寬比	-	-	✓	✓	✓	-	-	✓
解析度 (1K/2K/4K)	-	-	✓	✓	-	-	-	1K, 2K

工具參數

圖像生成提示詞。`action: "generate"` 必填。使用 `"status"` 檢查作用中階段任務，或使用 `"list"` 在執行時檢查可用的提供者和模型。提供者/模型覆寫（例如 `openai/gpt-image-2`）。使用 `openai/gpt-image-1.5` 以取得透明的 OpenAI 背景。編輯模式的單一參考圖片路徑或 URL。編輯模式或樣式參考模型的參考圖片（透過共用工具最多 10 張；提供者特定的限制仍然適用）。尺寸提示：`1024x1024`、`1536x1024`、`1024x1536`、`2048x2048`、`3840x2160`。長寬比：`1:1`、`2:3`、`3:2`、`2.35:1`、`3:4`、`4:3`、`4:5`、 `5:4`、`9:16`、`16:9`、`21:9`、`4:1`、`1:4`、`8:1`、`1:8`。提供者會驗證其模型特定的子集。解析度提示。當提供者支援時的品質提示。當提供者支援時的輸出格式提示。當提供者支援時的背景提示。對於支援透明度的提供者，請將 `transparent` 與 `outputFormat: "png"` 或 `"webp"` 搭配使用。要生成的圖片數量 (1-4)。選用的提供者請求逾時時間（毫秒）。當 Codex 透過動態工具呼叫 `image_generate` 時，此單次呼叫值仍會覆寫設定的預設值，並上限為 600000 毫秒。輸出檔名提示。僅限 OpenAI 的提示：`background`、`moderation`、`outputCompression` 和 `user`。 fal Krea 2 創意控制。預設為 `medium`。

設定

模型選擇

{
  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"],
      },
    },
  },
}

提供者選擇順序

OpenClaw 會依此順序嘗試提供者：

工具呼叫中的 model 參數（如果代理程式指定了一個）。
來自設定的 imageGenerationModel.primary。
依順序排列的 imageGenerationModel.fallbacks。
自動偵測 - 僅限具備認證支援的提供者預設值：
- 首先是目前的預設提供者；
- 其餘已註冊的圖像生成提供者依提供者 ID 順序排列。

如果提供者失敗（認證錯誤、速率限制等），會自動嘗試下一個設定的候選者。如果全部失敗，錯誤會包含每次嘗試的詳細資訊。

每次呼叫的模型覆寫是精確的

每次呼叫的 model 覆寫僅嘗試該提供者/模型，而不會繼續嘗試設定的主要/後備或自動偵測的提供者。

自動偵測具備認證感知能力

只有當 OpenClaw 實際上能對該提供者進行驗證時，提供者預設值才會進入候選清單。設定 agents.defaults.mediaGenerationAutoProviderFallback: false 以僅使用明確的 model、primary 和 fallbacks 項目。

Timeouts

針對緩慢的影像後端設定 agents.defaults.imageGenerationModel.timeoutMs。每次呼叫的 timeoutMs 工具參數會覆寫設定的預設值，而設定的預設值會覆寫外掛撰寫的提供者預設值。Google 和 OpenRouter 託管的影像提供者使用 180 秒的預設值；xAI 和 Azure OpenAI 影像生成使用 600 秒。Codex 動態工具呼叫使用 120 秒的 image_generate 橋接預設值，且在設定時遵守相同的逾時預算，以 OpenClaw 的 600000 毫秒動態工具橋接最大值為上限。

Inspect at runtime

使用 action: "list" 來檢查目前註冊的提供者、其預設模型以及 auth env-var 提示。

影像編輯

OpenAI、OpenRouter、Google、DeepInfra、fal、MiniMax、ComfyUI 和 xAI 支援編輯參考影像。fal 上的 Krea 2 模型使用相同的 image / images 欄位作為風格參考，而非編輯輸入。請傳入參考影像路徑或 URL：

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

OpenAI、OpenRouter、Google 和 xAI 透過 images 參數支援最多 5 張參考影像。fal 支援 1 張用於 Flux 影像轉影像的參考影像，GPT Image 2 編輯最多 10 張，Krea 2 最多 10 個風格參考，Nano Banana 2 編輯最多 14 張。MiniMax 和 ComfyUI 支援 1 張。

提供者深度解析

OpenAI gpt-image-2 (及 gpt-image-1.5)

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 路由，請使用 API 金鑰、自訂基礎 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 輸出，並會被 PNG 輸出忽略。

頂層 background 提示為提供者中立，當選取 OpenAI 提供者時，目前會對應至相同的 OpenAI background 請求欄位。未宣告背景支援的提供者會將其包含在 ignoredOverrides 中，而不是接收不支援的參數。

若要透過 Azure OpenAI 部署來路由 OpenAI 影像生成而非 api.openai.com，請參閱 Azure OpenAI endpoints。

OpenRouter 影像模型

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 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 驗證途徑使用：

用於 API 金鑰設定的 minimax/image-01
用於 OAuth 設定的 minimax-portal/image-01

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 合約中。

範例

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

/tool image_generate action=generate model=openai/gpt-image-1.5 prompt="A simple red circle sticker on a transparent background" outputFormat=png background=transparent

等效 CLI：

openclaw infer image generate \
  --model openai/gpt-image-1.5 \
  --output-format png \
  --background transparent \
  --prompt "A simple red circle sticker on a transparent background" \
  --json

/tool image_generate action=generate model=openai/gpt-image-2 prompt="Two visual directions for a calm productivity app icon" size=1024x1024 count=2

/tool image_generate action=generate model=openai/gpt-image-2 prompt="Keep the subject, replace the background with a bright studio setup" image=/path/to/reference.png size=1024x1536

/tool image_generate action=generate model=openai/gpt-image-2 prompt="Combine the character identity from the first image with the color palette from the second" images='["/path/to/character.png","/path/to/palette.jpg"]' size=1536x1024

/tool image_generate action=generate model=fal/krea/v2/medium/text-to-image prompt="An expressive editorial portrait using this color palette and print texture" images='["/path/to/palette.png","/path/to/texture.jpg"]' aspectRatio=9:16 fal='{"creativity":"high"}'

openclaw infer image edit 上也提供相同的 --output-format 和 --background 標誌；--openai-background 仍作為 OpenAI 專用的別名。OpenAI 以外的打包提供者目前未宣告明確的背景控制，因此會將 background: "transparent" 回報為已忽略。