mirror of
https://github.com/openclaw/openclaw.git
synced 2026-05-06 08:20:43 +00:00
docs(openai): clarify codex oauth image generation
This commit is contained in:
Peter Steinberger
@@ -183,14 +183,17 @@ Choose your preferred auth method and follow the setup steps.
|
||||
## Image generation
|
||||
|
||||
The bundled `openai` plugin registers image generation through the `image_generate` tool.
|
||||
It supports both OpenAI API-key image generation and Codex OAuth image
|
||||
generation.
|
||||
|
||||
| Capability | Value |
|
||||
| ------------------------- | ---------------------------------- |
|
||||
| Default model | `openai/gpt-image-2` |
|
||||
| Max images per request | 4 |
|
||||
| Edit mode | Enabled (up to 5 reference images) |
|
||||
| Size overrides | Supported, including 2K/4K sizes |
|
||||
| Aspect ratio / resolution | Not forwarded to OpenAI Images API |
|
||||
| Capability | OpenAI API key | Codex OAuth |
|
||||
| ------------------------- | ---------------------------------- | ---------------------------------- |
|
||||
| Model ref | `openai/gpt-image-2` | `openai-codex/gpt-image-2` |
|
||||
| Auth | `OPENAI_API_KEY` | OpenAI Codex OAuth sign-in |
|
||||
| Max images per request | 4 | 4 |
|
||||
| Edit mode | Enabled (up to 5 reference images) | Enabled (up to 5 reference images) |
|
||||
| Size overrides | Supported, including 2K/4K sizes | Supported, including 2K/4K sizes |
|
||||
| Aspect ratio / resolution | Not forwarded to OpenAI Images API | Mapped to supported size when safe |
|
||||
|
||||
```json5
|
||||
{
|
||||
@@ -202,6 +205,18 @@ The bundled `openai` plugin registers image generation through the `image_genera
|
||||
}
|
||||
```
|
||||
|
||||
Use Codex OAuth instead:
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
imageGenerationModel: { primary: "openai-codex/gpt-image-2" },
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
<Note>
|
||||
See [Image Generation](/tools/image-generation) for shared tool parameters, provider selection, and failover behavior.
|
||||
</Note>
|
||||
@@ -213,7 +228,9 @@ OpenAI image workflows should use `openai/gpt-image-2`.
|
||||
The `openai-codex` provider also exposes `gpt-image-2` for image generation and
|
||||
reference-image editing through OpenAI Codex OAuth. Use
|
||||
`openai-codex/gpt-image-2` when the agent is signed in with Codex OAuth but does
|
||||
not have an `OPENAI_API_KEY`.
|
||||
not have an `OPENAI_API_KEY`. OpenClaw resolves the stored Codex OAuth access
|
||||
token for `openai-codex` and sends image requests through the Codex Responses
|
||||
backend, so this path works without the public OpenAI Images API key.
|
||||
|
||||
Generate:
|
||||
|
||||
@@ -227,6 +244,12 @@ Generate with Codex OAuth:
|
||||
/tool image_generate model=openai-codex/gpt-image-2 prompt="A polished launch poster for OpenClaw on macOS" size=3840x2160 count=1
|
||||
```
|
||||
|
||||
Edit with Codex OAuth:
|
||||
|
||||
```
|
||||
/tool image_generate model=openai-codex/gpt-image-2 prompt="Preserve the object shape, change the material to translucent glass" image=/path/to/reference.png size=1024x1536
|
||||
```
|
||||
|
||||
Edit:
|
||||
|
||||
```
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
---
|
||||
summary: "Generate and edit images using configured providers (OpenAI, Google Gemini, fal, MiniMax, ComfyUI, Vydra, xAI)"
|
||||
summary: "Generate and edit images using configured providers (OpenAI, OpenAI Codex OAuth, Google Gemini, fal, MiniMax, ComfyUI, Vydra, xAI)"
|
||||
read_when:
|
||||
- Generating images via the agent
|
||||
- Configuring image generation providers and models
|
||||
@@ -10,12 +10,12 @@ title: "Image generation"
|
||||
The `image_generate` tool lets the agent create and edit images using your configured providers. Generated images are delivered automatically as media attachments in the agent's reply.
|
||||
|
||||
<Note>
|
||||
The tool only appears when at least one image generation provider is available. If you don't see `image_generate` in your agent's tools, configure `agents.defaults.imageGenerationModel` or set up a provider API key.
|
||||
The tool only appears when at least one image generation provider is available. If you don't see `image_generate` in your agent's tools, configure `agents.defaults.imageGenerationModel`, set up a provider API key, or sign in with OpenAI Codex OAuth.
|
||||
</Note>
|
||||
|
||||
## Quick start
|
||||
|
||||
1. Set an API key for at least one provider (for example `OPENAI_API_KEY` or `GEMINI_API_KEY`).
|
||||
1. Set an API key for at least one provider (for example `OPENAI_API_KEY` or `GEMINI_API_KEY`) or sign in with OpenAI Codex OAuth.
|
||||
2. Optionally set your preferred model:
|
||||
|
||||
```json5
|
||||
@@ -30,6 +30,20 @@ The tool only appears when at least one image generation provider is available.
|
||||
}
|
||||
```
|
||||
|
||||
Use Codex OAuth instead of an OpenAI API key:
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
imageGenerationModel: {
|
||||
primary: "openai-codex/gpt-image-2",
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
3. Ask the agent: _"Generate an image of a friendly lobster mascot."_
|
||||
|
||||
The agent calls `image_generate` automatically. No tool allow-listing needed — it's enabled by default when a provider is available.
|
||||
@@ -59,7 +73,7 @@ Use `action: "list"` to inspect available providers and models at runtime:
|
||||
| ------------- | -------- | ------------------------------------------------------------------------------------- |
|
||||
| `prompt` | string | Image generation prompt (required for `action: "generate"`) |
|
||||
| `action` | string | `"generate"` (default) or `"list"` to inspect providers |
|
||||
| `model` | string | Provider/model override, e.g. `openai/gpt-image-2` |
|
||||
| `model` | string | Provider/model override, e.g. `openai/gpt-image-2` or `openai-codex/gpt-image-2` |
|
||||
| `image` | string | Single reference image path or URL for edit mode |
|
||||
| `images` | string[] | Multiple reference images for edit mode (up to 5) |
|
||||
| `size` | string | Size hint: `1024x1024`, `1536x1024`, `1024x1536`, `2048x2048`, `3840x2160` |
|
||||
@@ -125,9 +139,11 @@ OpenAI, Google, and xAI support up to 5 reference images via the `images` parame
|
||||
|
||||
### OpenAI `gpt-image-2`
|
||||
|
||||
OpenAI image generation defaults to `openai/gpt-image-2`. The older
|
||||
`openai/gpt-image-1` model can still be selected explicitly, but new OpenAI
|
||||
image-generation and image-editing requests should use `gpt-image-2`.
|
||||
OpenAI image generation defaults to `openai/gpt-image-2` with `OPENAI_API_KEY`.
|
||||
Use `openai-codex/gpt-image-2` to generate or edit images with the same Codex
|
||||
OAuth sign-in used by `openai-codex` chat models. The older `openai/gpt-image-1`
|
||||
model can still be selected explicitly, but new OpenAI image-generation and
|
||||
image-editing requests should use `gpt-image-2`.
|
||||
|
||||
`gpt-image-2` supports both text-to-image generation and reference-image
|
||||
editing through the same `image_generate` tool. OpenClaw forwards `prompt`,
|
||||
@@ -153,6 +169,18 @@ Edit one local reference image:
|
||||
/tool image_generate action=generate model=openai/gpt-image-2 prompt="Keep the subject, replace the background with a bright studio setup" image=/path/to/reference.png size=1024x1536
|
||||
```
|
||||
|
||||
Generate with Codex OAuth:
|
||||
|
||||
```
|
||||
/tool image_generate action=generate model=openai-codex/gpt-image-2 prompt="A clean editorial poster for OpenClaw image generation" size=3840x2160 count=1
|
||||
```
|
||||
|
||||
Edit one local reference image with Codex OAuth:
|
||||
|
||||
```
|
||||
/tool image_generate action=generate model=openai-codex/gpt-image-2 prompt="Keep the subject, replace the background with a bright studio setup" image=/path/to/reference.png size=1024x1536
|
||||
```
|
||||
|
||||
Edit with multiple references:
|
||||
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user