codex-imagen
Generate or edit raster images by calling the ChatGPT/Codex hosted image_generation flow with local Codex or OpenClaw OAuth credentials, then save decoded image files for OpenClaw and other agent workflows.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/darkamenosa--codex-imagen)HTML
<a href="/listings/darkamenosa--codex-imagen"><img src="/api/listings/darkamenosa--codex-imagen/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
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.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 165 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- ---
- name: codex-imagen
- description: Generate or edit raster images by calling the ChatGPT/Codex hosted image_generation flow with local Codex or OpenClaw OAuth credentials, then save decoded image files for OpenClaw and other agent workflows.
- metadata:
- openclaw:
- emoji: "🖼️"
- requires:
- bins: ["node"]
- ---
- # 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:
- ```bash
- 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:
- ```bash
- 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:
- ```bash
- 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
- ```http
- 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:
- ```bash
- 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:
- ```text
- ~/.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.
- ## Output Paths
- Use `--out-dir` or `-o/--output` when the caller needs a specific artifact location:
- ```bash
- node {baseDir}/scripts/codex-imagen.mjs --out-dir ./openclaw-images --prompt 'generate three UI icon variants'
- node {baseDir}/scripts/codex-imagen.mjs -o out/ --prompt 'generate 3 images of a monk mage'
- ```
- `--output image.png` writes exactly that path for one image. If multiple images arrive, outputs are numbered as `image-1.png`, `image-2.png`, and so on. If `--output` has no extension or ends in `/`, it is treated as a directory. Without `--output`, automatic names use `codex-imagen-<timestamp>-<optional-index>-<image-call-id>.png`.
- When `--out-dir` is not set, the script chooses the first available location:
- 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`
- Streaming is enabled by default and saves each image as soon as it arrives. If a run times out after partial results, already received images remain saved and are printed. If the stream breaks before `response.completed`, already completed images remain saved but the command fails with a stream error. Use `--timeout 300` for chat-facing OpenClaw calls unless the user explicitly asks for a longer run, or `--no-stream` to request a non-streaming Responses response.
- ## Reference Images
- Attach reference images explicitly. Do not use positional image paths; positional arguments are reserved for prompt text.
- ```bash
- node {baseDir}/scripts/codex-imagen.mjs --input-ref ref1.png --input-ref ref2.jpg --prompt 'generate 3 images of him livestreaming in this world'
- node {baseDir}/scripts/codex-imagen.mjs -i ref1.png -i ref2.jpg --prompt 'change the main character into a woman'
- node {baseDir}/scripts/codex-imagen.mjs --image-url 'https://example.com/ref.png' --prompt 'use this image as the world reference'
- ```
- Local images are converted to `data:image/...;base64,...` and sent as Responses `input_image` items by default. `--input-ref` accepts local paths, `http(s)` URLs, and `data:image/...` URLs. `-i/--image` is local-only, and `--image-url` is URL/data-URL only. Supported local formats are PNG, JPEG, GIF, and WebP. Use `--image-detail auto|low|high|original` when the model should receive lower or higher image detail; default is `high`. Use smaller JPEG references when high-fidelity pixel detail is not needed.
- ## OAuth Refresh
- The CLI refreshes expired or near-expiry OAuth tokens through `https://auth.openai.com/oauth/token` and writes the updated token back to the same auth file. The default OAuth refresh skew is 5 minutes, matching OpenClaw's OAuth usability margin. For OpenClaw `auth-profiles.json`, refresh uses OpenClaw-compatible cross-agent OAuth refresh locking, 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. This avoids `refresh_token_reused` races when multiple OpenClaw or agent processes share one `openai-codex` profile.
- 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.
- Use these controls when needed:
- ```bash
- node {baseDir}/scripts/codex-imagen.mjs --refresh-only --json
- node {baseDir}/scripts/codex-imagen.mjs --force-refresh --smoke --json
- node {baseDir}/scripts/codex-imagen.mjs --no-refresh --prompt 'generate one image'
- ```
- For concurrent OpenClaw processes, prefer the active OpenClaw agent's `auth-profiles.json` so every caller uses the same profile identity. Use `--no-refresh` only when the caller already owns OAuth refresh and wants this helper to use the provided access token as-is.
- Use `--base-url` only for a compatible Codex backend, and `--refresh-url` only for a compatible OAuth refresh endpoint.
- ## Cross-Platform Notes
- The helper is plain Node.js 22+ with no native dependencies. It uses `os.homedir()` and environment overrides for Windows, Linux, and macOS. In `cmd.exe`, single quotes are not shell quotes; use double quotes or write UTF-8 text to a file and use:
- ```bash
- node {baseDir}/scripts/codex-imagen.mjs --prompt-file prompt.txt
- ```
- Use `--cwd <path>` when another agent launches this script from an unpredictable working directory.
README.md · README · 248 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # Codex Imagen
- [](https://github.com/darkamenosa/codex-imagen/actions/workflows/ci.yml)
- 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`.
- ## Requirements
- - 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`
- ## Quick Start
- Check auth without generating:
- ```bash
- node scripts/codex-imagen.mjs --smoke
- ```
- Generate one image:
- ```bash
- 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.
- ```bash
- 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.
- ## CLI Usage
- ```bash
- 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-6-luna` 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.
- ## Reference Images
- Use explicit reference-image flags. Positional arguments are reserved for prompt text.
- ```bash
- 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.
- ## Output Paths
- 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:
- ```text
- 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.
- ## Auth Lookup
- 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.
- ## OAuth Refresh
- 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.
- ```bash
- 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.
- ## JSON Output
- Use `--json` for the full machine-readable summary:
- ```bash
- 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.
- ## OpenClaw Usage
- Use the skill directory as an OpenClaw skill:
- ```text
- codex-imagen/
- SKILL.md
- scripts/codex-imagen.mjs
- ```
- OpenClaw callers should usually rely on the active agent auth store and output directory:
- ```bash
- 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.
- ## Cross-Platform Notes
- 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`:
- ```bat
- 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.
- ## Exit Codes
- - `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
- ## Development
- Run local static checks:
- ```bash
- 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.
- ## License
- MIT
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.