이미지 생성
image_generate 도구를 사용하면 에이전트가 구성된 공급자를 사용해 이미지를 생성하고 편집할 수 있습니다. 생성된 이미지는 에이전트의 응답에 미디어 첨부파일로 자동 전달됩니다.
이 도구는 하나 이상의 이미지 생성 공급자를 사용할 수 있을 때만 표시됩니다. 에이전트의 도구에 image_generate가 보이지 않으면 agents.defaults.imageGenerationModel을 구성하거나 공급자 API 키를 설정하세요.
빠른 시작
- 하나 이상의 공급자에 대해 API 키를 설정합니다(예:
OPENAI_API_KEY 또는 GEMINI_API_KEY).
- 필요하면 선호하는 모델을 설정합니다.
{
agents: {
defaults: {
imageGenerationModel: {
primary: "openai/gpt-image-1",
},
},
},
}
- 에이전트에게 요청합니다: “친근한 바닷가재 마스코트 이미지를 생성해 줘.”
에이전트는 image_generate를 자동으로 호출합니다. 도구 허용 목록은 필요하지 않습니다. 공급자를 사용할 수 있으면 기본적으로 활성화됩니다.
지원되는 공급자
| 공급자 | 기본 모델 | 편집 지원 | API 키 |
|---|
| OpenAI | gpt-image-1 | 예(최대 5개 이미지) | OPENAI_API_KEY |
| Google | gemini-3.1-flash-image-preview | 예 | GEMINI_API_KEY 또는 GOOGLE_API_KEY |
| fal | fal-ai/flux/dev | 예 | FAL_KEY |
| MiniMax | image-01 | 예(주제 참조) | MINIMAX_API_KEY 또는 MiniMax OAuth (minimax-portal) |
| ComfyUI | workflow | 예(1개 이미지, 워크플로 구성 기반) | 클라우드용 COMFY_API_KEY 또는 COMFY_CLOUD_API_KEY |
| Vydra | grok-imagine | 아니요 | VYDRA_API_KEY |
action: "list"를 사용하세요.
/tool image_generate action=list
도구 매개변수
| 매개변수 | 유형 | 설명 |
|---|
prompt | string | 이미지 생성 프롬프트(action: "generate"일 때 필수) |
action | string | 공급자를 확인하기 위한 "generate"(기본값) 또는 "list" |
model | string | 공급자/모델 재정의. 예: openai/gpt-image-1 |
image | string | 편집 모드를 위한 단일 참조 이미지 경로 또는 URL |
images | string[] | 편집 모드를 위한 여러 참조 이미지(최대 5개) |
size | string | 크기 힌트: 1024x1024, 1536x1024, 1024x1536, 1024x1792, 1792x1024 |
aspectRatio | string | 화면비: 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9 |
resolution | string | 해상도 힌트: 1K, 2K, 또는 4K |
count | number | 생성할 이미지 수(1–4) |
filename | string | 출력 파일명 힌트 |
size, aspectRatio, resolution 값은 실제로 전송된 값을 반영하며, details.normalization은 요청값에서 적용값으로의 변환을 담습니다.
모델 선택
{
agents: {
defaults: {
imageGenerationModel: {
primary: "openai/gpt-image-1",
fallbacks: ["google/gemini-3.1-flash-image-preview", "fal/fal-ai/flux/dev"],
},
},
},
}
공급자 선택 순서
이미지를 생성할 때 OpenClaw는 다음 순서로 공급자를 시도합니다.
- 도구 호출의
model 매개변수(에이전트가 지정한 경우)
- 구성의
imageGenerationModel.primary
- 순서대로
imageGenerationModel.fallbacks
- 자동 감지 — 인증 기반 공급자 기본값만 사용:
- 현재 기본 공급자를 먼저
- 나머지 등록된 이미지 생성 공급자를 공급자 ID 순서대로
공급자가 실패하면(인증 오류, 속도 제한 등) 다음 후보를 자동으로 시도합니다. 모두 실패하면 오류에 각 시도의 세부 정보가 포함됩니다.
참고:
- 자동 감지는 인증 인식 방식입니다. OpenClaw가 실제로 해당 공급자를 인증할 수 있을 때만 공급자 기본값이 후보 목록에 들어갑니다.
- 자동 감지는 기본적으로 활성화되어 있습니다. 이미지 생성이 명시적인
model, primary, fallbacks 항목만 사용하도록 하려면 agents.defaults.mediaGenerationAutoProviderFallback: false로 설정하세요.
- 현재 등록된 공급자, 해당 기본 모델, 인증 환경 변수 힌트를 확인하려면
action: "list"를 사용하세요.
이미지 편집
OpenAI, Google, fal, MiniMax, ComfyUI는 참조 이미지 편집을 지원합니다. 참조 이미지 경로 또는 URL을 전달하세요.
"이 사진을 수채화 버전으로 생성해 줘" + image: "/path/to/photo.jpg"
images 매개변수를 통해 최대 5개의 참조 이미지를 지원합니다. fal, MiniMax, ComfyUI는 1개를 지원합니다.
MiniMax 이미지 생성은 번들된 두 MiniMax 인증 경로 모두에서 사용할 수 있습니다.
- API 키 설정용
minimax/image-01
- OAuth 설정용
minimax-portal/image-01
공급자 기능
| 기능 | OpenAI | Google | fal | MiniMax | ComfyUI | Vydra |
|---|
| 생성 | 예(최대 4개) | 예(최대 4개) | 예(최대 4개) | 예(최대 9개) | 예(워크플로 정의 출력) | 예(1개) |
| 편집/참조 | 예(최대 5개 이미지) | 예(최대 5개 이미지) | 예(1개 이미지) | 예(1개 이미지, 주제 참조) | 예(1개 이미지, 워크플로 구성 기반) | 아니요 |
| 크기 제어 | 예 | 예 | 예 | 아니요 | 아니요 | 아니요 |
| 화면비 | 아니요 | 예 | 예(생성만) | 예 | 아니요 | 아니요 |
| 해상도(1K/2K/4K) | 아니요 | 예 | 예 | 아니요 | 아니요 | 아니요 |
관련 문서
