메인 콘텐츠로 건너뛰기
image_generate 도구를 사용하면 에이전트가 구성된 공급자를 통해 이미지를 생성하고 편집할 수 있습니다. 채팅 세션에서는 이미지 생성이 비동기적으로 실행됩니다. OpenClaw는 백그라운드 작업을 기록하고, 작업 id를 즉시 반환하며, 공급자가 완료되면 에이전트를 깨웁니다. 완료 에이전트는 세션의 일반적인 표시 응답 모드를 따릅니다. 구성된 경우 자동 최종 응답 전달을 사용하거나, 세션에서 메시지 도구가 필요한 경우 message(action="send")를 사용합니다. 요청자 세션이 비활성 상태이거나 활성 깨우기에 실패했고, 완료 응답에 아직 누락된 생성 이미지가 있으면 OpenClaw는 누락된 이미지만 포함한 멱등 직접 폴백을 보냅니다.
이 도구는 하나 이상의 이미지 생성 공급자를 사용할 수 있을 때만 표시됩니다. 에이전트 도구에 image_generate가 보이지 않으면 agents.defaults.imageGenerationModel을 구성하거나, 공급자 API 키를 설정하거나, OpenAI ChatGPT/Codex OAuth로 로그인하세요.

​
빠른 시작

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,
      },
    },
  },
}
ChatGPT/Codex OAuth는 동일한 openai/gpt-image-2 모델 참조를 사용합니다. openai OAuth 프로필이 구성되어 있으면 OpenClaw는 먼저 OPENAI_API_KEY를 시도하는 대신 해당 OAuth 프로필을 통해 이미지 요청을 라우팅합니다. 명시적인 models.providers.openai 구성(API 키, 사용자 지정/Azure 기본 URL)은 직접 OpenAI Images API 경로를 다시 사용하도록 선택합니다.
3

에이전트에게 요청

“친근한 로봇 마스코트 이미지를 생성해 줘.”에이전트가 image_generate를 자동으로 호출합니다. 도구 허용 목록은 필요하지 않습니다. 공급자를 사용할 수 있으면 기본적으로 활성화됩니다. 도구는 백그라운드 작업 id를 반환한 다음, 준비가 되면 완료 에이전트가 message 도구를 통해 생성된 첨부 파일을 보냅니다.
LocalAI 같은 OpenAI 호환 LAN 엔드포인트의 경우 사용자 지정 models.providers.openai.baseUrl을 유지하고 browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true로 명시적으로 선택하세요. 비공개 및 내부 이미지 엔드포인트는 기본적으로 계속 차단됩니다.

​
일반 경로

목표모델 참조인증
API 청구를 사용하는 OpenAI 이미지 생성openai/gpt-image-2OPENAI_API_KEY
Codex 구독 인증을 사용하는 OpenAI 이미지 생성openai/gpt-image-2OpenAI ChatGPT/Codex OAuth
OpenAI 투명 배경 PNG/WebPopenai/gpt-image-1.5OPENAI_API_KEY 또는 OpenAI Codex OAuth
DeepInfra 이미지 생성deepinfra/black-forest-labs/FLUX-1-schnellDEEPINFRA_API_KEY
fal Krea 2 표현적/스타일 지정 생성fal/krea/v2/medium/text-to-imageFAL_KEY
OpenRouter 이미지 생성openrouter/google/gemini-3.1-flash-image-previewOPENROUTER_API_KEY
LiteLLM 이미지 생성litellm/gpt-image-2LITELLM_API_KEY
Microsoft Foundry MAI 이미지 생성microsoft-foundry/<deployment-name>AZURE_OPENAI_API_KEY 또는 Entra ID
Google Gemini 이미지 생성google/gemini-3.1-flash-image-previewGEMINI_API_KEY 또는 GOOGLE_API_KEY
동일한 image_generate 도구가 텍스트-이미지 생성과 참조 이미지 편집을 처리합니다. 참조가 하나이면 image를, 여러 참조이면 images를 사용하세요. fal의 Krea 2 모델에서는 이러한 참조가 편집 입력 대신 스타일 참조로 전송됩니다. quality, outputFormat, background 같은 공급자 지원 출력 힌트는 사용 가능할 때 전달되며, 공급자가 지원하지 않으면 무시된 것으로 보고됩니다. 번들 투명 배경 지원은 OpenAI 전용입니다. 다른 공급자도 백엔드가 PNG 알파를 내보내는 경우 이를 보존할 수 있습니다.

​
지원되는 공급자

공급자기본 모델편집 지원인증
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
Microsoft Foundry<deployment-name>예(MAI-Image-2.5 모델만)AZURE_OPENAI_API_KEY 또는 Entra ID(az login)
MiniMaximage-01예(주제 참조)MINIMAX_API_KEY 또는 MiniMax OAuth(minimax-portal)
OpenAIgpt-image-2예(최대 이미지 4개)OPENAI_API_KEY 또는 OpenAI ChatGPT/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

​
공급자 기능

기능ComfyUIDeepInfrafalGoogleMicrosoft FoundryMiniMaxOpenAIVydraxAI
생성(최대 개수)워크플로 정의44419414
편집 / 참조이미지 1개(워크플로)이미지 1개Flux: 1; GPT: 10; Krea 스타일 참조: 10; NB2: 14최대 이미지 5개이미지 1개이미지 1개(주제 참조)최대 이미지 5개-최대 이미지 5개
크기 제어-✓✓✓✓-최대 4K--
종횡비--✓✓-✓--✓
해상도(1K/2K/4K)--✓✓----1K, 2K

​
도구 매개변수

​
prompt
string
필수
이미지 생성 프롬프트입니다. action: "generate"에 필요합니다.
​
action
"generate" | "status" | "list"
기본값:"generate"
활성 세션 작업을 확인하려면 "status"를 사용하고, 런타임에 사용 가능한 공급자와 모델을 확인하려면 "list"를 사용하세요.
​
model
string
공급자/모델 재정의입니다(예: openai/gpt-image-2). 투명 OpenAI 배경에는 openai/gpt-image-1.5를 사용하세요.
​
image
string
편집 모드용 단일 참조 이미지 경로 또는 URL입니다.
​
images
string[]
편집 모드 또는 스타일 참조 모델용 여러 참조 이미지입니다(공유 도구를 통해 최대 10개, 공급자별 제한은 계속 적용됨).
​
size
string
크기 힌트: 1024x1024, 1536x1024, 1024x1536, 2048x2048, 3840x2160.
​
aspectRatio
string
종횡비: 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. 공급자는 모델별 하위 집합을 검증합니다.
​
resolution
"1K" | "2K" | "4K"
해상도 힌트입니다.
​
quality
"low" | "medium" | "high" | "auto"
공급자가 지원할 때 사용하는 품질 힌트입니다.
​
outputFormat
"png" | "jpeg" | "webp"
공급자가 지원할 때 사용하는 출력 형식 힌트입니다.
​
background
"transparent" | "opaque" | "auto"
공급자가 지원할 때 사용하는 배경 힌트입니다. 투명도를 지원하는 공급자에서는 outputFormat: "png" 또는 "webp"와 함께 transparent를 사용하세요.
​
count
number
생성할 이미지 수입니다(1-4).
​
timeoutMs
number
선택적 공급자 요청 제한 시간(밀리초)입니다. Codex가 동적 도구를 통해 image_generate를 호출할 때도 이 호출별 값은 구성된 기본값을 재정의하며 600000 ms로 제한됩니다.
​
filename
string
출력 파일 이름 힌트입니다.
​
openai
object
OpenAI 전용 힌트: background, moderation, outputCompression, user.
​
fal.creativity
"raw" | "low" | "medium" | "high"
fal Krea 2 창의성 제어입니다. 기본값은 medium입니다.
모든 공급자가 모든 매개변수를 지원하는 것은 아닙니다. 폴백 공급자가 정확히 요청된 옵션 대신 가까운 지오메트리 옵션을 지원하는 경우, OpenClaw는 제출 전에 가장 가까운 지원 크기, 종횡비 또는 해상도로 다시 매핑합니다. 지원되지 않는 출력 힌트는 지원을 선언하지 않은 공급자에 대해 삭제되며 도구 결과에 보고됩니다. 도구 결과는 적용된 설정을 보고하며, details.normalization은 요청값에서 적용값으로의 모든 변환을 캡처합니다.

​
구성

​
모델 선택

{
  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는 다음 순서로 공급자를 시도합니다:
  1. 도구 호출의 model 매개변수(에이전트가 지정한 경우).
  2. 구성의 imageGenerationModel.primary.
  3. 순서대로 imageGenerationModel.fallbacks.
  4. 자동 감지 - 인증 기반 제공자 기본값만:
    • 현재 기본 제공자를 먼저 사용합니다.
    • 나머지 등록된 이미지 생성 제공자는 제공자 ID 순서대로 사용합니다.
제공자가 실패하면(인증 오류, 속도 제한 등) 다음 구성된 후보가 자동으로 시도됩니다. 모두 실패하면 오류에 각 시도의 세부 정보가 포함됩니다.
호출별 model 재정의는 해당 제공자/모델만 시도하며 구성된 기본/폴백 또는 자동 감지된 제공자로 계속 진행하지 않습니다.
제공자 기본값은 OpenClaw가 해당 제공자를 실제로 인증할 수 있을 때만 후보 목록에 들어갑니다. 명시적인 model, primary, fallbacks 항목만 사용하려면 agents.defaults.mediaGenerationAutoProviderFallback: false를 설정하세요.
느린 이미지 백엔드에는 agents.defaults.imageGenerationModel.timeoutMs를 설정하세요. 호출별 timeoutMs 도구 매개변수는 구성된 기본값을 재정의하며, 구성된 기본값은 Plugin 작성 제공자 기본값을 재정의합니다. Google 및 OpenRouter 호스팅 이미지 제공자는 180초 기본값을 사용하고, Microsoft Foundry MAI, xAI 및 Azure OpenAI 이미지 생성은 600초를 사용합니다. Codex 동적 도구 호출은 120초 image_generate 브리지 기본값을 사용하며, 구성된 경우 동일한 시간 제한 예산을 따르되 OpenClaw의 600000ms 동적 도구 브리지 최대값으로 제한됩니다.
현재 등록된 제공자, 해당 기본 모델, 인증 환경 변수 힌트를 검사하려면 action: "list"를 사용하세요.

​
이미지 편집

OpenAI, OpenRouter, Google, DeepInfra, fal, Microsoft Foundry, 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은 Flux 이미지-투-이미지에 1개의 참조 이미지, GPT Image 2 편집에 최대 10개, Krea 2 스타일 참조에 최대 10개, Nano Banana 2 편집에 최대 14개를 지원합니다. Microsoft Foundry, MiniMax 및 ComfyUI는 1개를 지원합니다.

​
제공자 심층 분석

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에 반환합니다.OpenAI 이미지 생성을 api.openai.com 대신 Azure OpenAI 배포를 통해 라우팅하려면 Azure OpenAI 엔드포인트를 참조하세요.
Microsoft Foundry 이미지 생성은 microsoft-foundry/ 제공자 접두사 아래에 배포된 MAI 이미지 배포 이름을 사용합니다. MAI API는 model 필드에 배포 이름을 기대하므로 제공자 수준 기본 모델은 없습니다.
{
  agents: {
    defaults: {
      imageGenerationModel: {
        primary: "microsoft-foundry/<deployment-name>",
        timeoutMs: 600_000,
      },
    },
  },
}
제공자는 OpenAI Images API가 아니라 Microsoft Foundry의 MAI API를 사용합니다.
  • 생성 엔드포인트: /mai/v1/images/generations
  • 편집 엔드포인트: /mai/v1/images/edits
  • 인증: AZURE_OPENAI_API_KEY / 제공자 API 키 또는 az login을 통한 Entra ID
  • 출력: PNG 이미지 1개
  • 크기: 기본값 1024x1024; 너비와 높이는 각각 최소 768px이어야 하며, 총 픽셀 수는 최대 1,048,576이어야 합니다
  • 편집: PNG 또는 JPEG 참조 이미지 1개, 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 Plugin을 참조하세요.
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가 포함됩니다. 구성된 Plugin이 무엇을 노출하는지 보려면 action: "list"를 사용하세요.
fal의 Krea 2 모델은 Flux에서 사용하는 일반 image_size 스키마 대신 fal의 네이티브 Krea 스키마를 사용합니다. OpenClaw는 다음을 보냅니다.
  • 종횡비 힌트용 aspect_ratio
  • 기본값이 medium인 creativity
  • 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 종횡비로 매핑하고, resolution은 삭제하지 않고 Krea에서 거부합니다. 네이티브 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 인증 경로를 통해 사용할 수 있습니다.
  • API 키 설정용 minimax/image-01
  • OAuth 설정용 minimax-portal/image-01
번들된 xAI 제공자는 프롬프트 전용 요청에는 /v1/images/generations를 사용하고, image 또는 images가 있는 경우 /v1/images/edits를 사용합니다.
  • 모델: xai/grok-imagine-image, xai/grok-imagine-image-quality
  • 개수: 최대 4개
  • 참조: 하나의 image 또는 최대 5개의 images
  • 종횡비: 1:1, 16:9, 9:16, 4:3, 3:4, 2:3, 3:2
  • 해상도: 1K, 2K
  • 출력: OpenClaw 관리 이미지 첨부 파일로 반환됨
OpenClaw는 이러한 컨트롤이 공유 크로스 제공자 image_generate 계약에 존재할 때까지 xAI 네이티브 quality, mask, user 또는 추가 네이티브 전용 종횡비를 의도적으로 노출하지 않습니다.

​
예시

/tool image_generate action=generate model=openai/gpt-image-2 prompt="A clean editorial poster for OpenClaw image generation" size=3840x2160 count=1
동일한 --output-format, --background, --quality, --openai-moderation 플래그를 openclaw infer image edit에서도 사용할 수 있습니다. --openai-background는 OpenAI 전용 별칭으로 유지됩니다. OpenAI 이외의 번들 공급자는 현재 명시적인 배경 제어를 선언하지 않으므로, 해당 공급자에서는 background: "transparent"가 무시된 것으로 보고됩니다.

​
관련

  • 도구 개요 - 사용 가능한 모든 에이전트 도구
  • ComfyUI - 로컬 ComfyUI 및 Comfy Cloud 워크플로 설정
  • fal - fal 이미지 및 동영상 공급자 설정
  • Google (Gemini) - Gemini 이미지 공급자 설정
  • Microsoft Foundry Plugin - Microsoft Foundry 채팅 및 MAI 이미지 설정
  • MiniMax - MiniMax 이미지 공급자 설정
  • OpenAI - OpenAI Images 공급자 설정
  • Vydra - Vydra 이미지, 동영상 및 음성 설정
  • xAI - Grok 이미지, 동영상, 검색, 코드 실행 및 TTS 설정
  • 구성 참조 - imageGenerationModel 구성
  • 모델 - 모델 구성 및 장애 조치