圖片生成

每次呼叫的 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，請明確設定 models.providers.openai，並提供 API 金鑰、自訂基底 URL 或 Azure 端點。

仍可明確選擇 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、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 金鑰設定
• 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 長寬比。