圖片生成

每次呼叫的 model 覆寫只會嘗試該提供者／模型，不會繼續使用已設定的主要、備援或自動偵測到的提供者。

只有當 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 毫秒上限。

使用 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 金鑰、自訂基底 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 提供者時，會對應至相同的 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 金鑰，或透過 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 結構描述，而非 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": "A cyber zine portrait with risograph texture",  "aspectRatio": "9:16",  "fal": {    "creativity": "high"  }}

可透過兩種內建的 MiniMax 驗證路徑使用 MiniMax 影像生成：

• minimax/image-01 用於 API 金鑰設定
• 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 管理的影像附件形式傳回

在共享的跨提供者 image_generate 合約納入這些控制項之前，OpenClaw 刻意不公開 xAI 原生的 quality、mask、user 或 auto 長寬比。