Complete tutorial for integrating gpt-image-2 with OpenClaw: 2 methods + 10 minutes to get started

The bottom line: There are two ways to integrate gpt-image-2 into OpenClaw. Option A uses APIYI's GPT-Image Skills, which takes about 5 minutes and is perfect for clients that support Skills like Codex CLI or Cursor. Option B uses the OpenAI chat-compatible mode with the reverse-engineered model gpt-image-2-all, which is billed per request ($0.03/request, pre-discount) and is the best choice for OpenClaw users who want to generate images directly via messaging platforms like WhatsApp, Telegram, or Discord.

OpenClaw (github.com/openclaw/openclaw) is one of the most popular open-source autonomous AI Agents of 2026, supporting over 20 messaging platforms including WhatsApp, Telegram, Slack, Discord, iMessage, Feishu, WeChat, and WeCom. It is model-agnostic and connects to third-party API services via the OpenAI-compatible protocol, providing a perfect entry point for top-tier image models like gpt-image-2.

This article covers everything from architectural selection to deployment configuration, explaining the differences between the two integration methods and providing openclaw.json configuration code that you can copy and use directly.

1. Why OpenClaw needs a specific approach for gpt-image-2

Many users' first reaction is: "Doesn't OpenClaw already support OpenAI? Can't I just configure the OpenAI API key?" While this is theoretically correct, there are three unavoidable engineering hurdles in practice.

1.1 Three limitations of using the official OpenAI API directly

🎯 Quick Start Tip: If you've already integrated other models (like Claude) into OpenClaw, you only need to replace the models.providers configuration to make gpt-image-2 available across all messaging platforms supported by OpenClaw (WhatsApp/Telegram/Discord, etc.). We recommend connecting via the APIYI (apiyi.com) platform, which has already addressed the issues above and offers low-latency domestic nodes and a pay-per-use plan.

1.2 Two internal mechanisms for image generation in OpenClaw

OpenClaw has two internal paths for image generation:

Path A: Using the image_generate tool
  - Configuration: models.providers.openai.baseUrl
  - Call: Standard OpenAI Images API (POST /v1/images/generations)
  - Applicable to: gpt-image-2 / gpt-image-1 / DALL-E 3

Path B: Using the chat completions tool
  - Configuration: Custom OpenAI-compatible provider
  - Call: Standard Chat API (POST /v1/chat/completions)
  - Applicable to: Any "conversational image model" that returns images in the chat stream

Key Insight: gpt-image-2-all is a "chat-compatible" version of the image model provided by APIYI. It encapsulates image generation capabilities within the standard chat completions protocol, returning the image URL directly in the response format. This design allows OpenClaw to call it just like a regular conversational model, without needing to switch to a dedicated image API.

1.3 Essential differences between the two options

II. Option A: Integrating gpt-image-2 via APIYI Skills

If your workflow involves generating images while executing tasks via OpenClaw Agent within development tools like Codex CLI, Cursor, OpenCode, or Gemini CLI, the Skills approach is the most elegant way to get started.

2.1 Two Available Models for the Skills Approach

APIYI has open-sourced two Skills on GitHub (Author: wuchubuzai2018, Repository: expert-skills-hub):

2.2 Installing Skills (3-Line Command)

# 1. Install the official proxy version (recommended for commercial use)
npx skills add https://github.com/wuchubuzai2018/expert-skills-hub --skill apiyi-gpt-image-2-gen

# 2. Or install the reverse proxy version (pay-per-use)
npx skills add https://github.com/wuchubuzai2018/expert-skills-hub --skill apiyi-gpt-image-2-all-gen

# 3. Configure environment variables
export APIYI_API_KEY="sk-your-key-from-apiyi-console"

🎯 Getting your API key: After registering, go to the "API Keys" page to create a new key starting with sk-. This key works across all provided services, including both official proxy and reverse proxy models.

2.3 Invoking Installed Skills in OpenClaw

OpenClaw allows you to sub-invoke installed Skills when performing complex tasks via Agent configuration:

# openclaw configuration snippet (example)
agents:
  - id: image-helper
    description: "Image generation assistant"
    skills:
      - apiyi-gpt-image-2-gen
      - apiyi-gpt-image-2-all-gen
    triggers:
      - keyword: "generate image"
      - keyword: "draw a"

In practice, you simply send a message through the platform connected to OpenClaw (e.g., Telegram):

@OpenClawBot Help me generate a cyberpunk-style cafe illustration, 1024x1024

OpenClaw will:

1. Identify the trigger word and activate the image-helper agent.
2. Invoke the apiyi-gpt-image-2-gen Skill.
3. Call gpt-image-2 via the APIYI platform.
4. Return the image URL to the chat.

2.4 Advantages and Limitations of the Skills Approach

Advantages:

• ✅ Reuse community-maintained Skill code; no need to write your own image generation logic.
• ✅ Automatically handles prompt optimization, error retries, and image format conversion.
• ✅ Native compatibility with development tools (Codex CLI/Cursor).

Limitations:

• ❌ OpenClaw's support for Skills depends on specific Agent configurations.
• ❌ Requires a Node.js environment.
• ❌ Not "out-of-the-box" for pure messaging platforms (e.g., WhatsApp-only users).

If your OpenClaw is primarily used for messaging platforms, check out Option B.

III. Option B: OpenAI Compatibility Mode for gpt-image-2-all

This is the most suitable integration method for mainstream OpenClaw scenarios. By modifying the models.providers configuration in OpenClaw, you can register APIYI as a custom OpenAI-compatible provider and then invoke the gpt-image-2-all model, which is designed for chat compatibility.

3.1 Modifying the openclaw.json Configuration

The core configuration file for OpenClaw is located at ~/.openclaw/openclaw.json (macOS/Linux) or %APPDATA%\openclaw\openclaw.json (Windows).

{
  "models": {
    "providers": {
      "apiyi": {
        "api": "openai-completions",
        "baseUrl": "https://api.apiyi.com/v1",
        "apiKey": "sk-your-key-from-apiyi-console",
        "models": [
          {
            "id": "gpt-image-2-all",
            "name": "GPT Image 2 (Chat Compatible)",
            "contextWindow": 8000,
            "maxTokens": 4096,
            "capabilities": ["text", "image_generation"]
          }
        ]
      }
    }
  },
  "gateway": {
    "http": {
      "endpoints": {
        "chatCompletions": {
          "enabled": true
        }
      }
    }
  }
}

🎯 base_url configuration: The baseUrl in the configuration above must end with /v1. The standard endpoint is fully compatible with the official OpenAI API, so no other parameters need to be changed.

3.2 Restarting OpenClaw and Verifying

# Restart the OpenClaw service (depending on your installation)
openclaw restart

# Or via systemd
sudo systemctl restart openclaw

# Verify that the provider is loaded
openclaw models list | grep apiyi

Successful output example:

Provider: apiyi (status: ✓ healthy)
  Models:
    - apiyi/gpt-image-2-all (chat + image_generation)

3.3 Invoking in Messaging Platforms

Once configured, any messaging platform connected to OpenClaw can generate images directly. Taking Telegram as an example:

[User Message]
Draw a picture of a kitten in a spacesuit sitting on the moon's surface, cartoon style

[OpenClaw Response]
🎨 Generating image for you...
[Image] https://files.apiyi.com/generated/xxx.png
✅ Generation complete, cost $0.03

3.4 Complete Chat Completions Invocation Example (For Developers)

If you want to debug at the code level, here is how OpenClaw internally invokes gpt-image-2-all:

import openai

client = openai.OpenAI(
    api_key="sk-your-key",
    base_url="https://api.apiyi.com/v1"
)

response = client.chat.completions.create(
    model="gpt-image-2-all",
    messages=[
        {
            "role": "user",
            "content": "Draw a picture of a kitten in a spacesuit sitting on the moon's surface, cartoon style"
        }
    ]
)

# The response will contain the image URL (in Markdown format)
print(response.choices[0].message.content)
# Output: ![Generated Image](https://files.apiyi.com/generated/xxx.png)

import os
import openai
import logging
from openai import APIError, RateLimitError

client = openai.OpenAI(
    api_key=os.environ["APIYI_API_KEY"],
    base_url="https://api.apiyi.com/v1",
    timeout=120.0  # Image generation requires a longer timeout
)

def generate_image_via_chat(prompt: str, max_retries: int = 3):
    """Invoke gpt-image-2-all via chat completions"""
    for attempt in range(max_retries):
        try:
            response = client.chat.completions.create(
                model="gpt-image-2-all",
                messages=[{"role": "user", "content": prompt}],
                stream=False
            )
            content = response.choices[0].message.content
            return parse_image_url(content)
        except RateLimitError:
            logging.warning(f"Rate limit, retry {attempt+1}/{max_retries}")
            continue
        except APIError as e:
            logging.error(f"API error: {e}")
            if attempt == max_retries - 1:
                raise
    return None


def parse_image_url(content: str) -> str:
    """Extract image URL from Markdown response"""
    import re
    match = re.search(r'!\[.*?\]\((.*?)\)', content)
    return match.group(1) if match else None


if __name__ == "__main__":
    url = generate_image_via_chat(
        "Draw a picture of a kitten in a spacesuit sitting on the moon's surface, cartoon style"
    )
    print(f"Image URL: {url}")

IV. gpt-image-2 vs. gpt-image-2-all: Model Selection Guide

The most common question from OpenClaw users is: should I use the official model or the reverse-engineered one? It really comes down to your specific use case and priorities.

4.1 Key Differences

4.2 Selection Advice

🎯 Hybrid Strategy: For real-world projects, we recommend using gpt-image-2-all during development to keep costs down, then switching to gpt-image-2 for production. On the APIYI (apiyi.com) platform, both models share the same API key, so you just need to update the model field in your request—the migration effort is practically zero.

4.3 Cost Comparison

Assuming an OpenClaw group bot handles 100 image generation requests per day:

Key Insight: For personal or small team OpenClaw deployments, choosing gpt-image-2-all can save you over $5,000 annually, with negligible functional differences for messaging platform use cases.

V. OpenClaw + gpt-image-2 Practical Examples

Now that we've covered the theory and configuration, let's look at some real-world, reproducible scenarios.

5.1 Scenario 1: Telegram Group Image Assistant

Configuration: OpenClaw + Telegram + APIYI custom provider + gpt-image-2-all

User Experience:

[Group Member A]
@OpenClawBot Draw me a cartoon illustration for a Monday morning meeting, featuring a sleepy programmer and a large cup of coffee.

[OpenClawBot]
🎨 Generating, estimated 15 seconds...
[Image Displayed]
✅ Generated ($0.03)
👍 If you like it, send me a ⭐️

Configuration Highlights:

• Add Telegram channel configuration in openclaw.json.
• Set up keyword triggers for image generation: "draw", "generate image", etc.
• Enable rate limiting to prevent abuse.

5.2 Scenario 2: WhatsApp Customer Service Auto-Illustration

Business Context: E-commerce support agents on WhatsApp need to quickly generate product context images for customers.

Configuration:

{
  "agents": {
    "wa-cs-agent": {
      "channel": "whatsapp",
      "model": "apiyi/gpt-image-2-all",
      "system_prompt": "You are an e-commerce support assistant. When a user asks about a product, generate a context image to help explain.",
      "tools": ["image_generate", "knowledge_search"]
    }
  }
}

Conversation Example:

[Customer]
Does this Bluetooth headset look good when worn?

[Agent]
Let me generate a reference image of it being worn for you 👇
[Image: Young person jogging outdoors wearing the Bluetooth headset]
You can use this as a reference. Our headset weighs only 8g, so it won't feel heavy even after long periods of use 🏃

5.3 Scenario 3: Discord Community Content Bot

Business Context: A gaming community Discord where admins want a bot to generate character art based on user descriptions.

Implementation:

• Connect OpenClaw to Discord.
• Use slash command /generate to trigger image generation.
• Implement role-based access (e.g., 5 free generations/day for regular users, unlimited for members).
• Use gpt-image-2-all to save costs.

Discord Command Snippet:

@bot.command(name="generate")
async def generate_image(ctx, *, prompt: str):
    # Check user permissions and daily quota
    if not check_quota(ctx.author):
        await ctx.send("❌ Daily quota reached. Upgrade to member to remove limits.")
        return
    
    # Call OpenClaw's chat completions endpoint
    image_url = await openclaw_client.generate(
        model="apiyi/gpt-image-2-all",
        prompt=prompt
    )
    
    await ctx.send(f"🎨 {ctx.author.mention} Here is your character art:\n{image_url}")
    decrement_quota(ctx.author)

5.4 Scenario 4: Enterprise WeChat + Feishu Internal Tools

Business Context: Internal teams need to quickly generate meeting posters, social media images, and event banners.

OpenClaw Strategy:

• Connect to both Enterprise WeChat and Feishu channels.
• Use gpt-image-2 (official model) for commercial compliance.
• Add keyword filters for brand protection (to avoid generating competitor logos).
• Log all generated images to internal object storage for audit and reuse.

🎯 Enterprise Integration Tip: For enterprise use cases, we recommend the official model (gpt-image-2) to ensure Indemnification coverage. We also suggest using an API proxy service like APIYI (apiyi.com), which supports corporate accounts and monthly invoicing, making financial accounting and compliance audits much easier.

WhatsApp 2.5 billion+ users Telegram 900M+ users Discord Communities Feishu / WeChat Enterprise

gpt-image-2-all Billing Rules (Pre-discount)
─────────────────────────────────
Base generation cost: $0.03 / request
├─ 1024×1024 standard resolution: Included
├─ 1024×1792 (portrait): Included
├─ 1792×1024 (landscape): Included
└─ Failed requests (safety violations): No charge

Additional costs: $0
├─ No token-based billing
├─ No image byte-based billing
└─ No prompt length differentiation

# Configure in the OpenClaw agent hook
async def post_image_generation_hook(image_url: str):
    # Download image locally
    image_data = await download(image_url)
    # Upload to enterprise object storage
    permanent_url = await upload_to_oss(image_data, bucket="ai-images")
    return permanent_url

{
  "rateLimits": {
    "imageGeneration": {
      "perUser": {
        "daily": 50,
        "hourly": 10
      },
      "perChannel": {
        "daily": 500
      }
    }
  }
}

✅ If you're only using OpenClaw + messaging platforms (WhatsApp/Telegram/Discord)
   → Choose Option B: OpenAI-compatible mode + gpt-image-2-all
   Reason: Simplest configuration, most transparent pay-per-use billing, and native compatibility with chat flows.

✅ If you're using Codex CLI / Cursor + OpenClaw for collaborative development
   → Choose Option A: APIYI Skills (apiyi-gpt-image-2-gen)
   Reason: The Skills ecosystem is better suited for development toolchains.

✅ If you're building an enterprise-grade commercial product
   → Choose Option A + gpt-image-2 official proxy
   Reason: Indemnification protection, commercial compliance, and 2K resolution support.