Công cụDocumentation Index
Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
Use this file to discover all available pages before exploring further.
image_generate cho phép tác tử tạo và chỉnh sửa ảnh bằng các
nhà cung cấp đã cấu hình của bạn. Ảnh được tạo sẽ tự động được gửi dưới dạng
tệp đính kèm đa phương tiện trong phản hồi của tác tử.
Công cụ này chỉ xuất hiện khi có ít nhất một nhà cung cấp tạo ảnh
khả dụng. Nếu bạn không thấy
image_generate trong công cụ của tác tử,
hãy cấu hình agents.defaults.imageGenerationModel, thiết lập khóa API của nhà cung cấp,
hoặc đăng nhập bằng OpenAI Codex OAuth.Bắt đầu nhanh
Configure auth
Đặt khóa API cho ít nhất một nhà cung cấp (ví dụ
OPENAI_API_KEY,
GEMINI_API_KEY, OPENROUTER_API_KEY) hoặc đăng nhập bằng OpenAI Codex OAuth.Pick a default model (optional)
openai/gpt-image-2. Khi một
hồ sơ OAuth openai-codex được cấu hình, OpenClaw định tuyến các yêu cầu
ảnh qua hồ sơ OAuth đó thay vì thử OPENAI_API_KEY trước. Cấu hình
models.providers.openai tường minh (khóa API, URL cơ sở tùy chỉnh/Azure)
sẽ chọn lại tuyến OpenAI Images API trực tiếp.Các tuyến phổ biến
| Mục tiêu | Tham chiếu mô hình | Xác thực |
|---|---|---|
| Tạo ảnh OpenAI với tính phí API | openai/gpt-image-2 | OPENAI_API_KEY |
| Tạo ảnh OpenAI với xác thực thuê bao Codex | openai/gpt-image-2 | OpenAI Codex OAuth |
| PNG/WebP nền trong suốt của OpenAI | openai/gpt-image-1.5 | OPENAI_API_KEY hoặc OpenAI Codex OAuth |
| Tạo ảnh DeepInfra | deepinfra/black-forest-labs/FLUX-1-schnell | DEEPINFRA_API_KEY |
| Tạo ảnh OpenRouter | openrouter/google/gemini-3.1-flash-image-preview | OPENROUTER_API_KEY |
| Tạo ảnh LiteLLM | litellm/gpt-image-2 | LITELLM_API_KEY |
| Tạo ảnh Google Gemini | google/gemini-3.1-flash-image-preview | GEMINI_API_KEY hoặc GOOGLE_API_KEY |
image_generate xử lý tạo ảnh từ văn bản và chỉnh sửa bằng ảnh
tham chiếu. Dùng image cho một ảnh tham chiếu hoặc images cho nhiều ảnh
tham chiếu. Các gợi ý đầu ra được nhà cung cấp hỗ trợ như quality,
outputFormat, và background sẽ được chuyển tiếp khi khả dụng và được báo
là bị bỏ qua khi nhà cung cấp không hỗ trợ. Hỗ trợ nền trong suốt đi kèm chỉ
dành riêng cho OpenAI; các nhà cung cấp khác vẫn có thể giữ alpha PNG nếu
backend của họ phát ra định dạng đó.
Nhà cung cấp được hỗ trợ
| Nhà cung cấp | Mô hình mặc định | Hỗ trợ chỉnh sửa | Xác thực |
|---|---|---|---|
| ComfyUI | workflow | Có (1 ảnh, cấu hình theo workflow) | COMFY_API_KEY hoặc COMFY_CLOUD_API_KEY cho cloud |
| DeepInfra | black-forest-labs/FLUX-1-schnell | Có (1 ảnh) | DEEPINFRA_API_KEY |
| fal | fal-ai/flux/dev | Có (giới hạn tùy mô hình) | FAL_KEY |
gemini-3.1-flash-image-preview | Có | GEMINI_API_KEY hoặc GOOGLE_API_KEY | |
| LiteLLM | gpt-image-2 | Có (tối đa 5 ảnh đầu vào) | LITELLM_API_KEY |
| MiniMax | image-01 | Có (tham chiếu chủ thể) | MINIMAX_API_KEY hoặc MiniMax OAuth (minimax-portal) |
| OpenAI | gpt-image-2 | Có (tối đa 4 ảnh) | OPENAI_API_KEY hoặc OpenAI Codex OAuth |
| OpenRouter | google/gemini-3.1-flash-image-preview | Có (tối đa 5 ảnh đầu vào) | OPENROUTER_API_KEY |
| Vydra | grok-imagine | Không | VYDRA_API_KEY |
| xAI | grok-imagine-image | Có (tối đa 5 ảnh) | XAI_API_KEY |
action: "list" để kiểm tra các nhà cung cấp và mô hình khả dụng khi chạy:
Khả năng của nhà cung cấp
| Khả năng | ComfyUI | DeepInfra | fal | MiniMax | OpenAI | Vydra | xAI | |
|---|---|---|---|---|---|---|---|---|
| Tạo (số lượng tối đa) | Do workflow xác định | 4 | 4 | 4 | 9 | 4 | 1 | 4 |
| Chỉnh sửa / tham chiếu | 1 ảnh (workflow) | 1 ảnh | Flux: 1; GPT: 10; NB2: 14 | Tối đa 5 ảnh | 1 ảnh (tham chiếu chủ thể) | Tối đa 5 ảnh | - | Tối đa 5 ảnh |
| Kiểm soát kích thước | - | ✓ | ✓ | ✓ | - | Tối đa 4K | - | - |
| Tỷ lệ khung hình | - | - | ✓ | ✓ | ✓ | - | - | ✓ |
| Độ phân giải (1K/2K/4K) | - | - | ✓ | ✓ | - | - | - | 1K, 2K |
Tham số công cụ
Prompt tạo ảnh. Bắt buộc cho
action: "generate".Dùng
"list" để kiểm tra các nhà cung cấp và mô hình khả dụng khi chạy.Ghi đè nhà cung cấp/mô hình (ví dụ
openai/gpt-image-2). Dùng
openai/gpt-image-1.5 cho nền OpenAI trong suốt.Đường dẫn hoặc URL của một ảnh tham chiếu cho chế độ chỉnh sửa.
Nhiều ảnh tham chiếu cho chế độ chỉnh sửa (tối đa 5 trên các nhà cung cấp hỗ trợ).
Gợi ý kích thước:
1024x1024, 1536x1024, 1024x1536, 2048x2048, 3840x2160.Tỷ lệ khung hình:
1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9.Gợi ý độ phân giải.
Gợi ý chất lượng khi nhà cung cấp hỗ trợ.
Gợi ý định dạng đầu ra khi nhà cung cấp hỗ trợ.
Gợi ý nền khi nhà cung cấp hỗ trợ. Dùng
transparent với
outputFormat: "png" hoặc "webp" cho các nhà cung cấp có khả năng hỗ trợ độ trong suốt.Số ảnh cần tạo (1-4).
Thời gian chờ yêu cầu nhà cung cấp tùy chọn, tính bằng mili giây. Khi Codex gọi
image_generate qua công cụ động, giá trị theo lần gọi này vẫn ghi đè
mặc định đã cấu hình và bị giới hạn ở 600000 ms.Gợi ý tên tệp đầu ra.
Gợi ý chỉ dành cho OpenAI:
background, moderation, outputCompression, và user.Không phải tất cả nhà cung cấp đều hỗ trợ mọi tham số. Khi một nhà cung cấp dự phòng hỗ trợ
một tùy chọn hình học gần tương đương thay vì đúng tùy chọn được yêu cầu, OpenClaw ánh xạ lại sang
kích thước, tỷ lệ khung hình, hoặc độ phân giải được hỗ trợ gần nhất trước khi gửi.
Các gợi ý đầu ra không được hỗ trợ sẽ bị loại bỏ đối với những nhà cung cấp không khai báo
hỗ trợ và được báo cáo trong kết quả công cụ. Kết quả công cụ báo cáo các
thiết lập đã áp dụng;
details.normalization ghi lại mọi bản dịch từ yêu cầu sang áp dụng.Cấu hình
Chọn mô hình
Thứ tự chọn nhà cung cấp
OpenClaw thử các nhà cung cấp theo thứ tự này:- Tham số
modeltừ lệnh gọi công cụ (nếu tác tử chỉ định). imageGenerationModel.primarytừ cấu hình.imageGenerationModel.fallbackstheo thứ tự.- Tự động phát hiện - chỉ các mặc định nhà cung cấp có xác thực:
- nhà cung cấp mặc định hiện tại trước;
- các nhà cung cấp tạo ảnh đã đăng ký còn lại theo thứ tự mã định danh nhà cung cấp.
Per-call model overrides are exact
Per-call model overrides are exact
Ghi đè
model theo từng lần gọi chỉ thử nhà cung cấp/mô hình đó và
không tiếp tục sang primary/fallback đã cấu hình hoặc các nhà cung cấp được tự động phát hiện.Auto-detection is auth-aware
Auto-detection is auth-aware
Một mặc định nhà cung cấp chỉ đi vào danh sách ứng viên khi OpenClaw có thể
thực sự xác thực nhà cung cấp đó. Đặt
agents.defaults.mediaGenerationAutoProviderFallback: false để chỉ dùng
các mục model, primary, và fallbacks tường minh.Timeouts
Timeouts
Đặt
agents.defaults.imageGenerationModel.timeoutMs cho các backend ảnh
chậm. Tham số công cụ timeoutMs theo từng lần gọi sẽ ghi đè mặc định
đã cấu hình. Các lệnh gọi công cụ động của Codex tuân theo cùng ngân sách thời gian chờ,
bị giới hạn bởi mức tối đa cầu nối công cụ động 600000 ms của OpenClaw.Inspect at runtime
Inspect at runtime
Dùng
action: "list" để kiểm tra các nhà cung cấp hiện đã đăng ký,
mô hình mặc định của họ, và gợi ý biến môi trường xác thực.Chỉnh sửa ảnh
OpenAI, OpenRouter, Google, DeepInfra, fal, MiniMax, ComfyUI, và xAI hỗ trợ chỉnh sửa ảnh tham chiếu. Truyền đường dẫn hoặc URL của ảnh tham chiếu:images. fal hỗ trợ 1 hình ảnh tham chiếu cho Flux image-to-image, tối đa 10 cho các bản chỉnh sửa GPT Image 2 và tối đa 14 cho các bản chỉnh sửa Nano Banana 2. MiniMax và ComfyUI hỗ trợ 1.
Phân tích chuyên sâu theo nhà cung cấp
OpenAI gpt-image-2 (and gpt-image-1.5)
OpenAI gpt-image-2 (and gpt-image-1.5)
Tạo hình ảnh bằng OpenAI mặc định dùng
openai/gpt-image-2. Nếu một hồ sơ OAuth
openai-codex đã được cấu hình, OpenClaw sẽ tái sử dụng cùng hồ sơ
OAuth mà các mô hình trò chuyện theo gói đăng ký Codex dùng và gửi yêu cầu
hình ảnh qua backend Codex Responses. Các URL cơ sở Codex cũ như
https://chatgpt.com/backend-api được chuẩn hóa thành
https://chatgpt.com/backend-api/codex cho các yêu cầu hình ảnh. OpenClaw
không âm thầm chuyển dự phòng sang OPENAI_API_KEY cho yêu cầu đó -
để buộc định tuyến trực tiếp qua OpenAI Images API, hãy cấu hình
models.providers.openai rõ ràng với khóa API, URL cơ sở tùy chỉnh
hoặc điểm cuối Azure.Các mô hình openai/gpt-image-1.5, openai/gpt-image-1 và
openai/gpt-image-1-mini vẫn có thể được chọn rõ ràng. Dùng
gpt-image-1.5 cho đầu ra PNG/WebP nền trong suốt; API
gpt-image-2 hiện tại từ chối background: "transparent".gpt-image-2 hỗ trợ cả tạo hình ảnh từ văn bản và chỉnh sửa
hình ảnh tham chiếu thông qua cùng công cụ image_generate.
OpenClaw chuyển tiếp prompt, count, size, quality, outputFormat
và hình ảnh tham chiếu đến OpenAI. OpenAI không nhận trực tiếp
aspectRatio hoặc resolution; khi có thể, OpenClaw ánh xạ
các giá trị đó thành một size được hỗ trợ, nếu không công cụ sẽ báo
chúng là các ghi đè bị bỏ qua.Các tùy chọn riêng cho OpenAI nằm trong đối tượng openai:openai.background chấp nhận transparent, opaque hoặc auto;
đầu ra trong suốt yêu cầu outputFormat là png hoặc webp và một
mô hình hình ảnh OpenAI có khả năng xử lý độ trong suốt. OpenClaw định tuyến
các yêu cầu nền trong suốt mặc định của gpt-image-2 sang gpt-image-1.5.
openai.outputCompression áp dụng cho đầu ra JPEG/WebP.Gợi ý background cấp cao nhất là trung lập với nhà cung cấp và hiện ánh xạ
tới cùng trường yêu cầu background của OpenAI khi nhà cung cấp OpenAI
được chọn. Các nhà cung cấp không khai báo hỗ trợ nền sẽ trả về
nó trong ignoredOverrides thay vì nhận tham số không được hỗ trợ.Để định tuyến tạo hình ảnh OpenAI qua một triển khai Azure OpenAI
thay vì api.openai.com, xem
Điểm cuối Azure OpenAI.OpenRouter image models
OpenRouter image models
Tạo hình ảnh bằng OpenRouter dùng cùng OpenClaw chuyển tiếp
OPENROUTER_API_KEY và
định tuyến qua API hình ảnh chat completions của OpenRouter. Chọn
mô hình hình ảnh OpenRouter với tiền tố openrouter/:prompt, count, hình ảnh tham chiếu và
các gợi ý aspectRatio / resolution tương thích với Gemini đến OpenRouter.
Các lối tắt mô hình hình ảnh OpenRouter tích hợp hiện tại bao gồm
google/gemini-3.1-flash-image-preview,
google/gemini-3-pro-image-preview và openai/gpt-5.4-image-2. Dùng
action: "list" để xem Plugin đã cấu hình của bạn cung cấp những gì.MiniMax dual-auth
MiniMax dual-auth
Tạo hình ảnh bằng MiniMax khả dụng qua cả hai đường dẫn xác thực MiniMax
đi kèm:
minimax/image-01cho thiết lập khóa APIminimax-portal/image-01cho thiết lập OAuth
xAI grok-imagine-image
xAI grok-imagine-image
Nhà cung cấp xAI đi kèm dùng
/v1/images/generations cho các yêu cầu
chỉ có prompt và /v1/images/edits khi có image hoặc images.- Mô hình:
xai/grok-imagine-image,xai/grok-imagine-image-pro - Số lượng: tối đa 4
- Tham chiếu: một
imagehoặc tối đa nămimages - Tỷ lệ khung hình:
1:1,16:9,9:16,4:3,3:4,2:3,3:2 - Độ phân giải:
1K,2K - Đầu ra: được trả về dưới dạng tệp đính kèm hình ảnh do OpenClaw quản lý
quality, mask, user riêng của xAI
hoặc các tỷ lệ khung hình bổ sung chỉ dành cho nền tảng gốc cho đến khi
các điều khiển đó tồn tại trong hợp đồng image_generate dùng chung
giữa các nhà cung cấp.Ví dụ
- Generate (4K landscape)
- Generate (transparent PNG)
- Generate (two square)
- Edit (one reference)
- Edit (multiple references)
--output-format và --background tương tự cũng có trên
openclaw infer image edit; --openai-background vẫn là bí danh
riêng cho OpenAI. Các nhà cung cấp đi kèm ngoài OpenAI hiện không khai báo
điều khiển nền rõ ràng, nên background: "transparent" được báo cáo
là bị bỏ qua đối với họ.
Liên quan
- Tổng quan về công cụ - tất cả công cụ agent khả dụng
- ComfyUI - thiết lập quy trình làm việc ComfyUI cục bộ và Comfy Cloud
- fal - thiết lập nhà cung cấp hình ảnh và video fal
- Google (Gemini) - thiết lập nhà cung cấp hình ảnh Gemini
- MiniMax - thiết lập nhà cung cấp hình ảnh MiniMax
- OpenAI - thiết lập nhà cung cấp OpenAI Images
- Vydra - thiết lập hình ảnh, video và giọng nói Vydra
- xAI - thiết lập hình ảnh, video, tìm kiếm, thực thi mã và TTS Grok
- Tham chiếu cấu hình - cấu hình
imageGenerationModel - Mô hình - cấu hình mô hình và chuyển dự phòng