Chuyển đến nội dung chính

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.

Công cụ 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

1

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.
2

Pick a default model (optional)

{
  agents: {
    defaults: {
      imageGenerationModel: {
        primary: "openai/gpt-image-2",
        timeoutMs: 180_000,
      },
    },
  },
}
Codex OAuth sử dụng cùng tham chiếu mô hình 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.
3

Ask the agent

“Tạo ảnh một linh vật robot thân thiện.”Tác tử tự động gọi image_generate. Không cần danh sách cho phép công cụ
  • công cụ này được bật theo mặc định khi có nhà cung cấp khả dụng.
Đối với các điểm cuối LAN tương thích OpenAI như LocalAI, hãy giữ models.providers.openai.baseUrl tùy chỉnh và chọn tham gia tường minh bằng browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true. Các điểm cuối ảnh riêng tư và nội bộ vẫn bị chặn theo mặc định.

Các tuyến phổ biến

Mục tiêuTham chiếu mô hìnhXác thực
Tạo ảnh OpenAI với tính phí APIopenai/gpt-image-2OPENAI_API_KEY
Tạo ảnh OpenAI với xác thực thuê bao Codexopenai/gpt-image-2OpenAI Codex OAuth
PNG/WebP nền trong suốt của OpenAIopenai/gpt-image-1.5OPENAI_API_KEY hoặc OpenAI Codex OAuth
Tạo ảnh DeepInfradeepinfra/black-forest-labs/FLUX-1-schnellDEEPINFRA_API_KEY
Tạo ảnh OpenRouteropenrouter/google/gemini-3.1-flash-image-previewOPENROUTER_API_KEY
Tạo ảnh LiteLLMlitellm/gpt-image-2LITELLM_API_KEY
Tạo ảnh Google Geminigoogle/gemini-3.1-flash-image-previewGEMINI_API_KEY hoặc GOOGLE_API_KEY
Cùng công cụ 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ấpMô hình mặc địnhHỗ trợ chỉnh sửaXác thực
ComfyUIworkflowCó (1 ảnh, cấu hình theo workflow)COMFY_API_KEY hoặc COMFY_CLOUD_API_KEY cho cloud
DeepInfrablack-forest-labs/FLUX-1-schnellCó (1 ảnh)DEEPINFRA_API_KEY
falfal-ai/flux/devCó (giới hạn tùy mô hình)FAL_KEY
Googlegemini-3.1-flash-image-previewGEMINI_API_KEY hoặc GOOGLE_API_KEY
LiteLLMgpt-image-2Có (tối đa 5 ảnh đầu vào)LITELLM_API_KEY
MiniMaximage-01Có (tham chiếu chủ thể)MINIMAX_API_KEY hoặc MiniMax OAuth (minimax-portal)
OpenAIgpt-image-2Có (tối đa 4 ảnh)OPENAI_API_KEY hoặc OpenAI Codex OAuth
OpenRoutergoogle/gemini-3.1-flash-image-previewCó (tối đa 5 ảnh đầu vào)OPENROUTER_API_KEY
Vydragrok-imagineKhôngVYDRA_API_KEY
xAIgrok-imagine-imageCó (tối đa 5 ảnh)XAI_API_KEY
Dùng action: "list" để kiểm tra các nhà cung cấp và mô hình khả dụng khi chạy:
/tool image_generate action=list

Khả năng của nhà cung cấp

Khả năngComfyUIDeepInfrafalGoogleMiniMaxOpenAIVydraxAI
Tạo (số lượng tối đa)Do workflow xác định4449414
Chỉnh sửa / tham chiếu1 ảnh (workflow)1 ảnhFlux: 1; GPT: 10; NB2: 14Tối đa 5 ảnh1 ả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
string
bắt buộc
Prompt tạo ảnh. Bắt buộc cho action: "generate".
action
"generate" | "list"
mặc định:"generate"
Dùng "list" để kiểm tra các nhà cung cấp và mô hình khả dụng khi chạy.
model
string
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.
image
string
Đường dẫn hoặc URL của một ảnh tham chiếu cho chế độ chỉnh sửa.
images
string[]
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ợ).
size
string
Gợi ý kích thước: 1024x1024, 1536x1024, 1024x1536, 2048x2048, 3840x2160.
aspectRatio
string
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.
resolution
"1K" | "2K" | "4K"
Gợi ý độ phân giải.
quality
"low" | "medium" | "high" | "auto"
Gợi ý chất lượng khi nhà cung cấp hỗ trợ.
outputFormat
"png" | "jpeg" | "webp"
Gợi ý định dạng đầu ra khi nhà cung cấp hỗ trợ.
background
"transparent" | "opaque" | "auto"
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.
count
number
Số ảnh cần tạo (1-4).
timeoutMs
number
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.
filename
string
Gợi ý tên tệp đầu ra.
openai
object
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

{
  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",
        ],
      },
    },
  },
}

Thứ tự chọn nhà cung cấp

OpenClaw thử các nhà cung cấp theo thứ tự này:
  1. Tham số model từ lệnh gọi công cụ (nếu tác tử chỉ định).
  2. imageGenerationModel.primary từ cấu hình.
  3. imageGenerationModel.fallbacks theo thứ tự.
  4. 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.
Nếu một nhà cung cấp thất bại (lỗi xác thực, giới hạn tốc độ, v.v.), ứng viên đã cấu hình tiếp theo sẽ được thử tự động. Nếu tất cả đều thất bại, lỗi sẽ bao gồm chi tiết từ từng lần thử.
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.
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.
Đặ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.
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:
"Tạo một phiên bản màu nước của ảnh này" + image: "/path/to/photo.jpg"
OpenAI, OpenRouter, Google và xAI hỗ trợ tối đa 5 hình ảnh tham chiếu qua tham số 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

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-1openai/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:
{
  "quality": "low",
  "outputFormat": "jpeg",
  "openai": {
    "background": "opaque",
    "moderation": "low",
    "outputCompression": 60,
    "user": "end-user-42"
  }
}
openai.background chấp nhận transparent, opaque hoặc auto; đầu ra trong suốt yêu cầu outputFormatpng 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.
Tạo hình ảnh bằng OpenRouter dùng cùng 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/:
{
  agents: {
    defaults: {
      imageGenerationModel: {
        primary: "openrouter/google/gemini-3.1-flash-image-preview",
      },
    },
  },
}
OpenClaw chuyển tiếp 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-previewopenai/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ì.
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-01 cho thiết lập khóa API
  • minimax-portal/image-01 cho thiết lập OAuth
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 image hoặc tối đa năm images
  • 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ý
OpenClaw chủ ý không phơi bày 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ụ

/tool image_generate action=generate model=openai/gpt-image-2 prompt="A clean editorial poster for OpenClaw image generation" size=3840x2160 count=1
Các cờ --output-format--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