Native image generation với GPT Image 2 qua Codex OAuth

01Vấn đề trước PR #1002

create_image cũ chỉ chạy được với API key

Trước PR #1002, tool create_image trong GoClaw tìm provider thông qua credentialProvider interface — tức provider phải có 2 method APIKey() string và APIBase() string. CodexProvider dùng OAuth flow nên cố ý không implement 2 method này: token được rotate qua refresh_token grant (xem internal/oauth/token.go), còn backend URL default https://chatgpt.com/backend-api (constant DefaultProviderAPIBase) chỉ dùng nội bộ — không nằm trong credential surface mà tool layer được phép đụng.

Hệ quả: subscription ChatGPT Plus/Pro có gpt-image-2 trong quota — gọi được trên web chatgpt.com/images, gọi được trong Codex CLI, nhưng agent của GoClaw không gọi được vì tool create_image bị chặn ở bước kiểm tra APIKey()/APIBase(). User phải đi đường API key song song. Path phổ biến là Gemini Nano Banana 2 qua OpenRouter vì:

• Chất lượng ổn cho hầu hết use case (poster, thumbnail, illustration).
• OpenRouter cho phép dùng 1 key duy nhất cho nhiều image gen model, không phải quản lý API key OpenAI / Google riêng biệt.
• Tính phí theo từng ảnh, không phát sinh subscription thứ hai.

Chain mặc định imageGenModelDefaults của GoClaw ánh xạ mỗi provider sang 1 model: openai → gpt-image-1.5, openrouter → google/gemini-2.5-flash-image (Nano Banana 2), gemini → gemini-2.5-flash-image, minimax → image-01, dashscope → wan2.6-image, byteplus → seedream-5-0-260128. Thứ tự ưu tiên provider là openrouter → gemini → openai → minimax → dashscope → byteplus. Tất cả đều cần API key tương ứng.

Vấn đề: user đã trả ChatGPT Plus/Pro hằng tháng cho coding workflow, gpt-image-2 là một trong các model tạo ảnh chất lượng cao — nhưng quota đó nằm yên, không xài được trong agent.

Prompt engineering phân tán

Cộng đồng gpt-image-2 chia sẻ prompt template trên X/Twitter khá rời rạc. EvoLinkAI có repo awesome-gpt-image-2-prompts (~370 cases), nhưng dữ liệu nằm ở dạng README + tweet links, chưa có search engine. Agent muốn tận dụng phải tự đọc và lọc thủ công.

02Kiến trúc native image cho OAuth

PR #1002 thêm interface mới ở internal/providers/native_image.go. Tổng quan luồng xử lý như diagram bên dưới:

Code thực tế gồm interface ngắn:

type NativeImageProvider interface {
    GenerateImage(ctx context.Context, req NativeImageRequest) (*NativeImageResult, error)
}

Tool create_image tìm provider qua MediaProviderChain. Khi chain entry là Codex OAuth, raw provider object được đưa vào params["_native_provider"]. Trong callProvider:

if rawProvider, ok := params["_native_provider"]; ok {
    if np, ok := rawProvider.(providers.NativeImageProvider); ok {
        // Native path — không cần APIKey/APIBase
        return np.GenerateImage(ctx, ...)
    }
}
if cp == nil {
    return error("provider does not expose API credentials")
}
// Credential path cho openai, gemini, minimax, dashscope, byteplus, openrouter

Native check chạy trước cp == nil guard. OAuth provider cố ý không công khai credential; nếu đảo thứ tự, request sẽ fail với lỗi trỏ nhầm hướng — user thấy "thiếu credential" và đi config credential, trong khi nguyên nhân thật là sai native path.

2 tier gate

Tool image_generation chỉ được gắn vào request khi cả 2 điều kiện thoả:

1. Provider capability: provider implement CapabilitiesAware và Capabilities().ImageGeneration == true. Codex provider hardcode true vì OpenAI Responses API hỗ trợ tool image_generation.
2. Agent config: field AllowImageGeneration trong AgentConfig, mặc định true. Admin có thể set other_config.allow_image_generation: false để cấm sinh ảnh.

Logic trong loop_tool_filter.go::buildFilteredTools:

if l.allowImageGeneration {
    if aware, ok := l.provider.(providers.CapabilitiesAware); ok {
        if aware.Capabilities().ImageGeneration {
            toolDefs = append(toolDefs, imageGenToolDef)
        }
    }
}

imageGenToolDef chỉ là cờ {Type: "image_generation"} — không có name, không có schema parameters. Với function calling thường, client phải định nghĩa đầy đủ (vd {type: "function", function: {name, description, parameters}}) để LLM biết truyền args. Ở đây, image_generation là built-in tool của Codex Responses API — server tự gắn schema, tự chạy handler, client chỉ cần bật bằng sentinel.

03Codex Responses API wire format

Endpoint: POST {apiBase}/codex/responses

map[string]any{
    "model":        "gpt-5.4",  // parent LLM, không phải image model
    "stream":       true,        // mandatory — false bị reject HTTP 400
    "store":        false,
    "instructions": "Generate an image matching the user's description using the image_generation tool. Return only the image; do not describe it in text.",
    "input":        []any{...user message...},
    "tools": []map[string]any{{
        "type":          "image_generation",
        "action":        "generate",
        "model":         "gpt-image-2",   // image model nằm ở đây
        "output_format": "png",
        "size":          "1024x1024",
    }},
    "tool_choice": map[string]any{"type": "image_generation"},  // force tool call
}

Các điểm cần lưu ý:

• stream: true bắt buộc — non-streaming bị reject với Stream must be set to true.
• instructions phải có giá trị non-empty và rõ ràng. Để trống → model có thể trả text mô tả thay vì gọi tool.
• tool_choice phải force image_generation, nếu không model có thể bỏ qua tool.
• Có 2 model trong cùng request: model (parent — gpt-5.4) và tools[0].model (image — gpt-image-2). Nhầm 2 cái → API error mơ hồ.

Parse response

Path chính là SSE stream vì stream:true là bắt buộc. Luồng end-to-end:

Code vẫn có fallback để parse JSON non-streaming. Nếu server bất ngờ trả raw JSON object (không phải các dòng data:), parseNativeImageResponse sẽ duyệt output[], tìm type == "image_generation_call", rồi base64 decode result. Không thể trigger path này bằng cách set stream:false vì request sẽ bị reject 400 trước.

SSE path: scan data: lines, ưu tiên 2 event:

• response.output_item.done — image item ready, lấy event.Item.Result (base64) + OutputFormat.
• response.completed — final usage tokens, walk event.Response.Output[] lần 2 nếu chưa thấy item.

for line := range bytes.SplitSeq(data, []byte("\n")) {
    if !bytes.HasPrefix(line, []byte("data: ")) { continue }
    payload := line[len("data: "):]
    if bytes.Equal(payload, []byte("[DONE]")) { break }
    // ... unmarshal event, switch event.Type
}

04Model whitelist + chain config

Whitelist server-side

var allowedImageModels = map[string]bool{
    "gpt-image-2":   true, // default — latest quality
    "gpt-image-1.5": true, // legacy fallback
}

ValidateImageModel reject mọi value khác (vd dall-e-3) ngay tại provider — không để upstream reject âm thầm. User chọn model qua chain entry param image_model; value này được truyền vào NativeImageRequest.ImageModel, kiểm tra hợp lệ, rồi gắn vào tools[0].model của Responses API request.

Chain config

MediaProviderChainEntry mặc định:

Timeout    int  // seconds, default 600 (10 min — image/video gen is slow)
MaxRetries int  // default 1 (image gen rarely succeeds on retry)

Timeout được tăng từ 120s lên 600s vì gpt-image-2 thực tế có thể mất 30–180s. Nếu timeout giữa chừng, request phía upstream vẫn có thể tiếp tục chạy, nên retry thường không giúp gì. Vì vậy MaxRetries được giảm từ 2 xuống 1 để lỗi hiện ra sớm hơn thay vì bị che bởi retry loop.

Phần UI dùng schema trong ui/web/src/pages/builtin-tools/media-provider-params-schema.ts để render form cấu hình, nên admin có thể tinh chỉnh theo từng tenant và từng tool.

05Provenance: PNG tEXt chunk + caption UI

Khi create_image lưu file, pngEmbedPrompt sẽ rewrite byte stream của PNG và chèn một tEXt chunk Description vào trước IEND. Function này nằm trong tools/png_embed.go để tránh import cycle tools→agent:

Description = <prompt user gửi>

Format chuẩn của PNG tEXt chunk và vị trí chèn trong byte stream:

Function tự bỏ qua nếu input không có PNG signature (8 byte magic) hoặc không tìm thấy IEND chunk. Failure mode: trả nguyên bytes cũ, không báo lỗi.

Hệ quả: prompt gốc đi theo file download. Đọc lại bằng exiftool image.png (field Description) hoặc PNG metadata viewer. Audit, tái tạo ảnh tương tự, debug prompt đều dễ hơn.

UI render caption dưới ảnh trong MediaGallery: muted italic, line-clamp 2 dòng, hover tooltip hiển thị full prompt. File được lưu theo path: {workspace}/generated/{YYYY-MM-DD}/image_{hint}_{timestamp}.png.

06Skill gpt-image-2-pro-max: prompt registry qua Skill system

Skill gpt-image-2-pro-max do Richard Ng — contributor của GoClaw — open-source, code license MIT. Riêng 3,000+ prompt template trong corpus thuộc creators trên Twitter/X; skill chỉ index lại để search nhanh hơn, mỗi prompt khi trả về đều cite tác giả gốc, và corpus ghi credit upstream cho repo EvoLinkAI/awesome-gpt-image-2-prompts. Skill được package theo Claude Code skill convention; GoClaw có Skill system tương thích, nên cùng 1 skill dir chạy được trên cả hai.

Anatomy

Kho 3,238 prompt mẫu đã qua sàng lọc cộng đồng, host tại https://gpt-image-2-prompts.goclawoffice.com. Tags được suy ra qua 10 facet: subjects, styles, lighting, cameras, moods, palettes, compositions, mediums, techniques, usecases. Mỗi record có prompt body, Twitter/X attribution, reference image. Endpoint có rate limit theo IP và fair-use friendly.

CLI surface mà agent gọi:

python scripts/search.py "luxury shoe ecommerce ad cream pastel" -n 5
python scripts/search.py "perfume bottle" --shape ecommerce -n 3
python scripts/search.py "neon ui" --persist plans/neon-refs.md

Sample output cho query đầu tiên (rút gọn 3 hit, trim prompt body):

#1  bm25=-10.76  shape=ecommerce  source=None
  id    : 64dp29km
  title : E-commerce Main Image - Luxury Perfume Ad on Marble Vanity
  author: @MiguelMaestroIA
  tweet : https://x.com/MiguelMaestroIA/status/2047555836252151831
  image : https://gpt-image-2-prompts.goclawoffice.com/img/64dp29km_0
  imgid : 64dp29km_0
  tags  : cameras=1-1 | compositions=negative-space | moods=dreamy,edgy,elegant,intense,luxurious,minimal | palettes=crimson-burgundy,duotone,monochrome | styles=cinematic,editorial | subjects=product | techniques=parameterised-template,text-overlay-explicit | usecases=ecommerce-main-image,poster-flyer
  prompt:
    A luxury cosmetics advertisement poster featuring a single upright {argument name="product type" default="lipstick"} centered on a glossy black cube pedestal against a rich monochrome {argument name="background color" default="deep crimson red"} studio background. The product is a bold satin-finish {argument name="product shade" default="true red"} lipstick with the bullet fully extended, dramatic...

#2  bm25=-9.85  shape=  source=None
  id    : z9q36mnc
  title : Futuristic Bionic Super Shoe
  author: @Ericool 🇲🇾
  tweet : https://x.com/EricoolWong/status/2048353098897453286
  image : https://gpt-image-2-prompts.goclawoffice.com/img/z9q36mnc_0
  imgid : z9q36mnc_0
  tags  : cameras=low-angle | moods=energetic,futuristic,intense,luxurious | palettes=gold-black | styles=cinematic | subjects=fashion-item,product | techniques=parameterised-template
  prompt:
    Extreme futuristic {argument name="subject" default="cheetah bionic super shoe"}, hybrid of supercar and running sneaker, aggressive mechanical structure, layered carbon fiber, glowing energy core, dynamic speed trails, {argument name="colors" default="black gold"} luxury finish, dramatic low angle, cinematic lighting, high-end sports ad, ultra detailed, 8k

#3  bm25=-9.82  shape=ecommerce  source=None
  id    : 0zjvnji7
  title : Vitamin C Skincare Ad
  author: @Gem Alpha
  tweet : https://x.com/Gemalpha_88/status/2046796479562678589
  image : https://gpt-image-2-prompts.goclawoffice.com/img/0zjvnji7_0
  imgid : 0zjvnji7_0
  tags  : cameras=1-1 | moods=dreamy,edgy,elegant,luxurious,minimal,warm-emotional | palettes=earth-tones | styles=photorealistic | subjects=abstract,product | techniques=aspect-explicit,parameterised-template
  prompt:
    Create a clean luxury skincare product advertisement in a square 1:1 layout with a warm beige studio background and strong natural sunlight casting soft palm-leaf shadows across the wall. Place 1 amber glass dropper bottle on the left-center, standing upright on a round cream stone pedestal. The bottle has a glossy gold collar and a matte white rubber dropper top. Add a white rectangular label wit...

(3 matched, showing 3)

Output được rank bằng BM25, gồm prompt_body, tags.{moods,palettes,subjects,...}, author, tweet, image. Các filter chính: --shape, --has-image, -n, --full, --persist.

07Setup qua Web Dashboard

GoClaw có Web Dashboard với sidebar phân nhóm Core / Capabilities / System. Setup này cần 4 mục: Agents (Core), Skills (Capabilities), Providers + Builtin Tools (System). Setup tối thiểu chỉ cần 1 agent — mọi agent đều dùng được tool create_image nhờ Provider Chain global ở Step 2a (Step 2b cấu hình read_image là optional, model có vision native skip được).

Step 1 — Connect Codex provider

Sidebar → System / Providers → nút Add Provider. Trong modal Add Provider, chọn ChatGPT Subscription (OAuth), giữ hoặc sửa Account Alias (vd openai-codex), nhập Display Name nếu cần, rồi bấm Connect OpenAI Account. System mở tab OAuth mới để đăng nhập tài khoản ChatGPT (Plus / Pro / Team / Enterprise đều được) và grant access.

Sau khi sign-in xong, browser redirect về callback dạng http://localhost:1455/auth/callback?code=...&state=.... Nếu chạy remote/VPS và browser báo không mở được localhost, copy full URL trên address bar, paste vào ô callback trong modal, rồi bấm Submit. Khi Providers list hiển thị provider mới với status Connected là hoàn tất.

Step 2a — Bật + cấu hình create_image

Sidebar → System / Builtin Tools (route /builtin-tools) → tab Media → mục Create Image. Cờ Enabled mặc định OFF (xem seed data ở cmd/gateway_builtin_tools.go:55) — bật toggle bên phải lên ON trước, đây là master switch cho toàn tenant. Sau đó bấm Configure để vào modal Provider Chain.

Modal Create Image — Provider Chain cho phép xếp thứ tự các provider fallback; provider đầu tiên đang enabled sẽ được thử trước. Setup tối thiểu: thêm 1 entry Codex Plus, model GPT-5.4, Timeout 600s (image gen có thể chạy lâu khi prompt phức tạp), Retries 1, và quan trọng nhất — Image model chọn Default · gpt-image-2 (recommended). Bấm Save. Có thể bấm Add Provider để thêm fallback (vd OpenAI API key) nếu muốn graceful degradation khi OAuth quota cạn.

Step 2b — Bật + cấu hình read_image (optional)

Bỏ qua nếu model chính của agent đã có vision native (Qwen3.6-Plus, ...) — runtime fallback inline mode, attach binary ảnh vào message cho LLM tự đọc. Cần config nếu dùng model text-only hoặc muốn tách biệt vision provider khỏi model reasoning để optimize cost/latency.

Cùng trang /builtin-tools → tab Media → mục Read Image. Bật toggle Enabled ON (default OFF). Để ý badge req kế tên tool — viết tắt của "requires", dependency của tool. Hover sẽ thấy yêu cầu vision_provider: phải có ít nhất 1 provider có vision capability đăng ký ở Step 1 (vd Gemini, OpenAI, Anthropic, OpenRouter, dashscope qwen-vl) thì bật toggle mới có ý nghĩa — nếu không, tool throw lỗi "No vision provider configured" lúc runtime.

Sau khi bật, bấm Configure → modal Read Image — Provider Chain. Setup ví dụ trong screenshot: 1 entry OpenRouter, model google/gemini-2.5-flash-image, Timeout 120s (vision call thường nhanh, không cần 600s như image gen), Retries 3 (vision call cheap, retry an toàn nếu provider chập chờn). Đây là chain RIÊNG cho read_image, không dùng chung với create_image.

Step 3 — Tạo Agent

Sidebar → Core / Agents → New Agent. Các field tối thiểu: Name, Provider, Model (vd Tiểu Hổ + qwen3.6-plus, hoặc bất kỳ model nào đủ thông minh để đọc ảnh và chạy skill). Save → agent xuất hiện trong list. Vai trò của agent này là chạy reasoning: phân tích brief, đọc ảnh, search corpus, refactor prompt, rồi gọi tool create_image.

Step 4 — Upload skill gpt-image-2-pro-max

Clone + zip skill từ upstream:

git clone https://github.com/therichardngai-code/gpt-image-2-pro-max /tmp/g2pm
cd /tmp/g2pm/.claude/skills/gpt-image-2-pro-max
zip -r ~/Desktop/gpt-image-2-pro-max.zip .

git clone https://github.com/therichardngai-code/gpt-image-2-pro-max $env:TEMP\g2pm
Set-Location $env:TEMP\g2pm\.claude\skills\gpt-image-2-pro-max
Compress-Archive -Path * -DestinationPath $HOME\Desktop\gpt-image-2-pro-max.zip -Force

Sidebar → Capabilities / Skills → Upload Skill → drop file zip → Dashboard parse SKILL.md frontmatter, lấy name + description, rồi lưu skill record vào DB (version là số nguyên do DB tự gán, increment mỗi lần upload — không lấy từ frontmatter). Skill xuất hiện trong list với toggle Enabled.

Cuối cùng, grant skill cho agent vừa tạo: mở Agent detail → section Skills → toggle gpt-image-2-pro-max sang granted. Loader đưa SKILL.md vào system prompt của agent từ turn kế tiếp, không cần restart. Skill này là prompt-engineering pipeline — dạy agent cách diagnose brief, search corpus 3,238 prompt mẫu, pick template phù hợp mood, refactor và resolve slot, rồi mới gọi create_image với prompt đã polished.

Trace 1 turn (post-setup)

User brief: "poster cao điểm Tết với cáo đỏ Việt Nam, style infographic"

Visual trace detail từ run thật: PR #1002 · UX trace.

08Workflow minh họa: tạo ảnh trong GoClaw

"Anh em xài GoClaw tha hồ gen ảnh với GPT Image 2 chỉ trong 1 prompt. Upload ảnh base lên → Agent tối ưu prompt → Gen ảnh ngay trong GoClaw.

P.S. Mình setup Main model Qwen3.6-Plus (+ read_image) và GPT_Image_2 (create_image)." — tác giả (Richard Ng)

Đây là workflow do chính tác giả chia sẻ: chỉ cần upload ảnh muốn làm + gõ vài keyword mô tả (ví dụ: "tạo ảnh ads poster ecommerce"). Agent tự làm phần còn lại — toàn bộ chỉ cần một lần upload.

Setup tối thiểu trong GoClaw

Workflow: brief → ảnh hoàn chỉnh

09Best practices

2 tips quan trọng nhất khi chạy combo này:

1. Brief càng chi tiết, agent search càng trúng. Khi user chỉ gõ "con cáo đỏ", agent sẽ search "red fox" và nhận về đủ loại template không liên quan (cáo trong rừng, cáo cartoon, cáo realistic…). Thêm vào brief các keyword về shape (poster / infographic / portrait / ad…), mood (festive / moody / minimal…), và palette (red-gold / pastel / neon…) thì kết quả search bám sát ý định hơn nhiều. Vd: "poster Tết cáo đỏ Việt Nam style infographic, palette đỏ-vàng festive" → search query của agent có đủ infographic festive red-gold để filter ra template phù hợp.
2. Đừng giảm timeout xuống dưới 600s. Sinh ảnh phức tạp (vd infographic nhiều text trong ảnh) bình thường mất 4–8 phút server xử lý — đó không phải lỗi, là realistic. Default cũ 120s × 2 retries hay bị cắt giữa chừng (context deadline exceeded) làm hỏng việc. PR #1002 đổi thành 600s × 1 retry: chờ lâu hơn nhưng đủ thời gian; chỉ retry 1 lần vì retry sau timeout tốn gấp đôi tiền mà hiếm khi qua được. Operator có quyền đặt lại nếu cần, nhưng đừng đặt thấp hơn 600s — gần như chắc chắn sẽ gặp lại lỗi cũ.

10Tóm tắt kỹ thuật

File references

Skill backend

Skill upload qua Dashboard (xem Section 07 · Step 4). scripts/search.py gọi corpus host bên ngoài; BM25 + tag boost ranking nằm bên server, không phải GoClaw core.