Codex Imagen

Codex Imagen

Generate or edit images by calling the ChatGPT/Codex backend directly with OAuth credentials already stored on the machine. By default this follows Codex's current hosted image flow: POST /responses with the native image_generation tool. The standalone typed image endpoints can be probed with --backend images, but Codex source currently gates that path behind the under-development image-generation extension. It does not start codex app-server, does not need the Codex CLI binary, and does not require OPENAI_API_KEY.

Quick Start

Run the helper through Node for macOS, Linux, and Windows compatibility:

node {baseDir}/scripts/codex-imagen.mjs --timeout 300 'generate image follow this prompt, no refine: "a cinematic fantasy city at sunrise"'

Normal generation prints one generated image path per line. Diagnostics and progress go to stderr.

Use --json when the caller needs machine-readable metadata:

node {baseDir}/scripts/codex-imagen.mjs --json --timeout 300 --prompt 'generate a small blue lotus icon'

Ask for multiple outputs in the prompt. There is no --count flag:

node {baseDir}/scripts/codex-imagen.mjs --timeout 300 -o out/ --prompt 'generate 3 images of a monk mage'

Use --verbose or --debug for request progress, raw Responses event names, and reference image details. Use --quiet when only stdout paths/JSON should be emitted.

Retry Behavior

The helper retries transient empty failures by default: network errors, HTTP 5xx responses, backend server_error / overloaded / unavailable responses, dropped/incomplete streams before any image is saved, and typed JSON responses without image data. Default is --retries 4, meaning 5 total attempts, matching Codex's request retry shape.

Retries are intentionally not used for usage errors, auth errors, policy/input errors, rate limits, generation timeouts, stream errors, or after an image has already been saved. If streaming saves partial images and then times out, the helper returns those saved paths instead of starting a duplicate generation. If the hosted Responses stream terminates or closes before response.completed, already completed images remain saved but the command exits with a stream error, matching Codex turn semantics. The --timeout value applies per generation attempt, so an outer OpenClaw exec.timeout must budget for retries when retries are enabled.

Use --no-retry or --retries 0 when an outer caller owns retry behavior.

Timeout Units

Use --timeout <seconds> for agent-facing calls. This intentionally matches OpenClaw's surrounding exec tool timeout value, which is also in seconds. For a 5 minute OpenClaw call, use --timeout 300.

--timeout-ms <milliseconds> remains available for compatibility and sub-second tests. Do not use --timeout-ms 300 when you mean 5 minutes; that is only 0.3 seconds. Use either --timeout, --timeout-seconds, or --timeout-ms, not more than one in the same command.

Generation Timing

Image generation can be slow, especially when the prompt asks for multiple images. For chat-facing OpenZalo/OpenClaw calls:

• Use --timeout 300 for ordinary one-image requests.
• For prompts that ask for 3 images, prefer --timeout 600, or ask for 2 images when the conversation should return quickly.
• If a 3-image request reaches the timeout after saving 1 or 2 images, the helper returns those saved paths with timed_out: true; this is a usable partial success, not a hang.
• The --timeout value applies per generation attempt. If default retries are enabled, set the outer OpenClaw exec.timeout higher than the helper timeout budget, or reduce retries with --retries 1 / --no-retry.

Auth Discovery

The CLI reads existing OAuth JSON and sends Authorization: Bearer <access>, ChatGPT-Account-Id, originator: codex_cli_rs, Codex-style request metadata, and a Codex-style user agent to https://chatgpt.com/backend-api/codex/responses by default.

The Responses model defaults to gpt-6-luna; the Images backend defaults to gpt-image-2.

Agent headers

originator: codex_cli_rs
version: 0.156.1
user-agent: codex_cli_rs/0.156.1 (<OS> <release>; <arch>) unknown

OS, release, and architecture are detected locally. CODEX_IMAGEN_CODEX_VERSION overrides the version in both headers. The installed Codex CLI and terminal environment do not change these defaults.

Run a local auth check without generating:

node {baseDir}/scripts/codex-imagen.mjs --smoke

Auth lookup order:

1. --auth
2. CODEX_IMAGEN_AUTH_JSON, OPENCLAW_CODEX_AUTH_JSON, CODEX_AUTH_JSON
3. OPENCLAW_AGENT_DIR/auth-profiles.json or PI_CODING_AGENT_DIR/auth-profiles.json
4. OPENCLAW_AGENT_DIR/auth.json or PI_CODING_AGENT_DIR/auth.json
5. ~/.openclaw/agents/main/agent/auth-profiles.json
6. ~/.openclaw/agents/main/agent/auth.json
7. ~/.openclaw/credentials/oauth.json
8. CODEX_HOME/auth.json
9. ~/.codex/auth.json

For OpenClaw, the current auth store is usually:

~/.openclaw/agents/main/agent/auth-profiles.json

Codex CLI is not required at runtime. The skill works with OAuth created by OpenClaw itself, for example openclaw onboard --auth-choice openai-codex or openclaw models auth login --provider openai-codex. It only needs an existing openai-codex OAuth profile; it does not perform the first browser login itself.

Profile selection follows OpenClaw first: explicit --auth-profile, CODEX_IMAGEN_AUTH_PROFILE / OPENCLAW_AUTH_PROFILE, OpenClaw config auth.order.openai-codex or configured auth.profiles, then sibling auth-state.json lastGood.openai-codex. Pass --auth-profile openai-codex:<id> when a specific OpenClaw profile should be used.