diff --git a/docs/providers/openai.md b/docs/providers/openai.md index d438220cc5f..a0099b1a267 100644 --- a/docs/providers/openai.md +++ b/docs/providers/openai.md @@ -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" }, + }, + }, +} +``` + See [Image Generation](/tools/image-generation) for shared tool parameters, provider selection, and failover behavior. @@ -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: ``` diff --git a/docs/tools/image-generation.md b/docs/tools/image-generation.md index f679bed6621..dd192f72620 100644 --- a/docs/tools/image-generation.md +++ b/docs/tools/image-generation.md @@ -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. -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. ## 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: ```