Codex Imagen

Generate or edit raster images by calling the ChatGPT/Codex Responses image_generation tool directly with local Codex or OpenClaw OAuth credentials, then sav...

Security Scan

The skill appears to do what it claims (generate images using local Codex/OpenClaw OAuth), but it accesses and can modify highly sensitive local OAuth stores and exposes options (base/refresh URLs) that could be abused — review before installing.

Purpose & Capability

The name/description (image generation via Codex/ChatGPT Responses using local OAuth) matches the code and SKILL.md: the CLI reads local OAuth profiles and calls the Codex Responses image_generation endpoint. Requiring node and having helper scripts is proportionate.

Instruction Scope

The runtime instructions and CLI intentionally enumerate many local auth file locations (OpenClaw/Codex paths), read those files, perform OAuth refreshes, and save generated images to disk. All of these actions are within scope for a tool that uses local OAuth to call the Responses backend, but the instructions/CLI also allow reading/writing multiple agent-wide auth stores (e.g., ~/.openclaw/agents/.../auth-profiles.json), which is broad and sensitive.

Install Mechanism

There is no network install; the package is instruction + included Node scripts. No arbitrary remote downloads or extract operations are present in the manifest. This is lower-risk from an install perspective.

Credentials

Although no required env vars are declared, the CLI reads many env vars/path candidates and will read and write local OAuth credentials across many locations and can perform token refreshes. It also accepts overridable --base-url and --refresh-url flags (and env overrides), which could be used to send tokens to arbitrary endpoints if an attacker can control arguments or environment. Access/modification of user OAuth tokens is high privilege and should be justified and limited.

Persistence & Privilege

always:false (good). The tool will modify auth stores (refresh tokens written back) and uses cross-process locking when touching OpenClaw auth files. Writing/updating OAuth credentials is normal for a refresh-capable helper, but it is a significant privilege; ensure you trust the skill and its author before allowing it to run with access to shared auth stores.

Scan Findings in Context

[pre-scan-injection-signals] expected: No pre-scan injection signals were detected. The code legitimately makes HTTP calls and reads/writes local auth files for its stated purpose.

What to consider before installing

This helper legitimately needs access to local Codex/OpenClaw OAuth profiles to call the Responses image_generation endpoint and to refresh tokens. Before installing: 1) Review the scripts (they are included) yourself or a trusted reviewer to confirm they only call the expected endpoints; 2) Only run it with a dedicated OAuth profile (not your primary account) if possible; 3) Be cautious because the CLI will read and write auth files (it can refresh tokens) — back up important auth files first; 4) Avoid passing or allowing untrusted agents to set --base-url or --refresh-url (these default to chatgpt.com and auth.openai.com but can be overridden), as that could redirect tokens to arbitrary endpoints; 5) Prefer running the tool in an isolated environment or container if you don't fully trust the skill owner; 6) Verify the skill's provenance (repository/homepage/owner) — registry metadata shows no homepage/source URL, so confirm the upstream source before trusting. If you want, I can point out the exact code paths that read/write auth files and where the refresh and network calls occur.

Generate or edit images by calling the ChatGPT/Codex backend directly with OAuth credentials already stored on the machine. This calls the native Responses image_generation tool, 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 event-level progress, and --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, and dropped/incomplete streams that end before a completed image arrives. 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, 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. 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> plus ChatGPT-Account-Id to https://chatgpt.com/backend-api/codex/responses.

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.

Output Paths

Use --out-dir or -o/--output when the caller needs a specific artifact location:

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. 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 response.

Reference Images

Attach reference images explicitly. Do not use positional image paths; positional arguments are reserved for prompt text.

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 input_image items. --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:

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:

node {baseDir}/scripts/codex-imagen.mjs --prompt-file prompt.txt

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