OpenClaw skill and helper CLI for generating or editing images through the ChatGPT/Codex backend with local OAuth credentials.

By default this follows Codex's current hosted image flow: POST /responses with the native image_generation tool. The standalone typed image endpoints are available for probing with --backend images, but Codex source currently gates that path behind the under-development image-generation extension. The helper also preserves ChatGPT Cloudflare cookies for allowed ChatGPT hosts, matching Codex's restricted request client behavior. It does not start codex app-server, does not require a Codex binary, and does not require OPENAI_API_KEY.

• Node.js 22+
• Existing Codex or OpenClaw openai-codex OAuth credentials on the machine

Supported auth stores:

• OpenClaw auth profiles: ~/.openclaw/agents/main/agent/auth-profiles.json
• OpenClaw agent auth: ~/.openclaw/agents/main/agent/auth.json
• OpenClaw legacy OAuth: ~/.openclaw/credentials/oauth.json
• Codex CLI/Desktop: ~/.codex/auth.json

Check auth without generating:

node scripts/codex-imagen.mjs --smoke

Generate one image:

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

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

node scripts/codex-imagen.mjs --timeout 900 'generate 3 images follow this prompt, no refine: "three distinct ancient ARPG MMO screenshots"'

Normal generation prints one saved PNG path per line. Diagnostics and progress are written to stderr unless --quiet is used.

node scripts/codex-imagen.mjs "prompt" [options]

Prompt options:

• --prompt <text>: prompt text.
• --prompt-file <path>: read UTF-8 prompt text from a file.
• Positional text is accepted when --prompt and --prompt-file are not used.

Reference image options:

• -i, --image <path>: attach local image files. Repeat or comma-separate.
• --input-ref <path|url>: attach local paths, http(s) URLs, or data:image/... URLs. Repeat or comma-separate.
• --image-url <url>: attach an http(s) or data:image/... URL.
• --image-detail <auto|low|high|original>: set the Responses input_image.detail value. Ignored by --backend images. Default: high.

Output options:

• -o, --output <path>: exact PNG path for one image, directory for many, or a path template that is numbered for multiple images.
• --out-dir <path>: output directory when --output is not provided.
• --json: print a machine-readable summary instead of only image paths.

Runtime options:

• --backend <responses|images>: Codex image backend. Default: responses, matching current Codex hosted image_generation. images calls the under-development standalone typed endpoint.
• --model <name>: model slug. Defaults: gpt-5.4 for responses, gpt-image-2 for images.
• --retries <count>: retry transient empty failures this many times. Default: 4, matching Codex's request retry default of 5 total attempts. Retries apply to network failures, HTTP 5xx, backend server_error / overloaded / unavailable responses, dropped/incomplete streams before any image is saved, and typed JSON responses without image data.
• --no-retry: disable transient generation retries.
• --timeout <seconds>: abort after this many seconds per generation attempt. Default: 900, or 300 when an OpenClaw runtime is detected; must be greater than 0. This is the recommended flag for OpenClaw and other agent usage.
• --timeout-seconds <seconds>: alias for --timeout.
• --timeout-ms <ms>: advanced compatibility flag for millisecond timeouts and sub-second tests. Use only one timeout flag per command. After timeout, a hard watchdog forces exit code 124 if the HTTP abort does not settle.
• --no-stream: request a non-streaming Responses response. The images backend is always non-streaming JSON.
• --quiet: suppress progress diagnostics on stderr.
• --verbose or --debug: print request progress, raw Responses event names, and reference image details to stderr.
• --cwd <path>: resolve relative input/output paths from this working directory.
• --base-url <url>: Codex backend base URL. Default: https://chatgpt.com/backend-api/codex.
• --refresh-url <url>: OAuth refresh endpoint. Default: https://auth.openai.com/oauth/token.

Auth options:

• --auth <path>: explicit auth JSON path.
• --auth-profile <id>: OpenClaw profile id, for example openai-codex:hxtxmu@gmail.com.
• --smoke: print redacted auth metadata and exit without generation.
• --force-refresh: refresh OAuth before generating.
• --refresh-only: refresh OAuth and exit. Does not require a prompt.
• --no-refresh: disable proactive refresh and the 401 refresh retry.

Use explicit reference-image flags. Positional arguments are reserved for prompt text.

node scripts/codex-imagen.mjs --input-ref ref1.png --input-ref ref2.jpg --prompt 'generate 3 images of him livestreaming in this world'
node scripts/codex-imagen.mjs -i ref1.png -i ref2.jpg --prompt 'change the main character into a woman'
node scripts/codex-imagen.mjs --image-url 'https://example.com/ref.png' --prompt 'use this image as the environment reference'

Local references are converted to base64 data:image/... input images before sending. Supported local formats are PNG, JPEG, GIF, and WebP. The CLI warns when a base64 reference is large; use smaller JPEG references when high-fidelity pixel detail is not needed.

When no output option is set, the first available directory is used:

1. CODEX_IMAGEN_OUT_DIR
2. OPENCLAW_OUTPUT_DIR
3. OPENCLAW_AGENT_DIR/artifacts/codex-imagen
4. OPENCLAW_STATE_DIR/artifacts/codex-imagen
5. ./codex-imagen-output

Automatic filenames use:

codex-imagen-<timestamp>-<optional-index>-<image-call-id>.png

--output behavior:

• --output image.png with one image writes exactly image.png.
• --output image.png with multiple images writes image-1.png, image-2.png, and so on.
• --output out/ or --output out treats the value as a directory and uses automatic filenames.
• --out-dir out always writes automatic filenames under out.

In the default streaming Responses mode, each image is written as soon as it arrives. If a run times out after partial results, already saved images remain on disk and are still printed. If the hosted Responses stream terminates or closes before response.completed, the command follows Codex semantics: already completed images remain saved, but the command exits with a stream error.

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

Profile selection for OpenClaw auth-profiles.json:

1. --auth-profile
2. CODEX_IMAGEN_AUTH_PROFILE or OPENCLAW_AUTH_PROFILE
3. OpenClaw config auth.order.openai-codex, then configured auth.profiles for openai-codex
4. sibling auth-state.json lastGood.openai-codex
5. best available openai-codex OAuth profile, preferring openai-codex:default, later expiry, email, and account id

Codex CLI is optional. If OpenClaw created the openai-codex OAuth profile through openclaw onboard --auth-choice openai-codex or openclaw models auth login --provider openai-codex, this helper can use that profile directly without installing Codex CLI. The helper reads and refreshes existing credentials; it does not run the first browser login itself.

The CLI refreshes expired or near-expiry OAuth tokens with the OpenAI OAuth refresh endpoint and writes updates back to the same auth file. The default refresh skew is 5 minutes, matching OpenClaw's OAuth usability margin.

When the auth file is OpenClaw's auth-profiles.json, refresh uses the same cross-agent lock path OpenClaw uses for openai-codex OAuth profiles, then locks the auth store before rereading and writing credentials. It also inherits a fresh matching profile from the main OpenClaw agent store when the current agent/workspace auth store is stale. That prevents concurrent agents from racing on one single-use refresh token and causing refresh_token_reused.

When auth is auto-discovered and the first auth file is irrecoverably stale, the CLI tries the next compatible auth source, such as CODEX_HOME/auth.json or ~/.codex/auth.json. Explicit --auth paths are not bypassed.

node scripts/codex-imagen.mjs --refresh-only --json
node scripts/codex-imagen.mjs --force-refresh --smoke --json
node scripts/codex-imagen.mjs --no-refresh --prompt 'generate one image'

Use --no-refresh only when the caller already owns token refresh. For normal standalone/OpenClaw skill usage, leave refresh enabled.

Use --json for the full machine-readable summary:

node scripts/codex-imagen.mjs --json 'generate a small blue lotus icon'

Generation JSON includes:

• request_id, session_id, endpoint, model
• image_count and imageCount
• images[].path and images[].decodedPath
• images[].bytes, sha256, call_id, status, partial, revised_prompt
• seen_event_types
• operation, for example responses image_generation, image generation, or image edit
• response_metadata for typed Images responses
• timed_out
• retry_attempts and retryAttempts when a later retry succeeds
• auth_refresh when refresh happened or was skipped during the run

--smoke --json prints redacted auth metadata. --refresh-only --json prints refresh metadata.

Use the skill directory as an OpenClaw skill:

codex-imagen/
  SKILL.md
  scripts/codex-imagen.mjs

OpenClaw callers should usually rely on the active agent auth store and output directory:

node {baseDir}/scripts/codex-imagen.mjs --json --timeout 300 --prompt 'generate an image'

--timeout 300 means 5 minutes and matches OpenClaw's surrounding exec tool timeout unit. --timeout-ms 300000 is still accepted for older callers and advanced millisecond use.

For prompts that ask for 3 images, prefer --timeout 600, or ask for 2 images when the conversation should return quickly. If a multi-image request times out after saving 1 or 2 images, the helper returns those saved paths with timed_out: true.

By default the helper also retries transient empty failures with --retries 4, so a caller that sets a strict outer OpenClaw exec.timeout should budget for retry time or pass --no-retry. The helper never retries after streaming has saved an image. Timeouts after saved images return the saved paths; broken hosted Responses streams after saved images leave the files on disk but exit with a stream error, matching Codex turn semantics.

Use --cwd <path> when another agent launches this script from an unpredictable working directory.

The helper is plain Node.js 22+ and uses os.homedir(), path, and environment overrides instead of platform-specific shell behavior. It should work on macOS, Linux, and Windows.

In Windows cmd.exe, single quotes are not shell quotes, so use double quotes or --prompt-file:

node scripts\codex-imagen.mjs --prompt-file prompt.txt --out-dir out

PowerShell accepts normal quoted strings, but for long prompts --prompt-file is still safer.

• 0: success
• 1: generation failed, no image returned, or HTTP error
• 2: invalid CLI usage
• 124: timed out before any image was saved, or the hard watchdog forced exit after abort did not settle

Run local static checks:

npm run check

The CI workflow checks syntax and CLI help/version output. It does not call live image generation because that requires local OAuth credentials.

MIT