Codex CLI (--provider codex-cli)
Read when the user picks --provider codex-cli, sets default_provider: codex-cli, or asks for "Codex image generation without an OpenAI API key". This provider is a thin baoyu-image-gen wrapper around the bundled scripts/codex-imagegen/main.ts (synced from packages/baoyu-codex-imagegen), which spawns codex exec --json --sandbox danger-full-access and routes the request to Codex CLI's built-in image_gen tool. The Codex CLI uses the user's Codex / ChatGPT subscription — no OPENAI_API_KEY is read or sent.
Prerequisites
npm install -g @openai/codex
codex login # signs in with the user's OpenAI / Codex account
codex --version # confirm >= 0.130bun is required for running the underlying wrapper (scripts/codex-imagegen/main.ts, carrying #!/usr/bin/env bun). If bun is missing from the runtime, npx -y bun works as a fallback.
Selection
- Never auto-selected.
detectProvideronly pickscodex-cliwhen it is pinned explicitly: pass--provider codex-clior setdefault_provider: codex-cliin EXTEND.md. - Choose this provider when:
- The user has a Codex subscription and explicitly does not want to manage an OpenAI API key.
- You need Codex's specific
image_genbehavior or quality. - Avoid this provider when latency matters — Codex CLI is typically 5–10× slower than direct OpenAI / Google API calls (except on cache hits).
Supported flags
| Flag | Behavior |
|---|---|
--prompt <text> / --promptfiles <files> | Required. Written to a temp file and passed to the wrapper as --prompt-file. |
--image <path> | Required. Final output PNG location. |
--ar <ratio> | Mapped to wrapper's --aspect. Supported by Codex: 1:1 (default), 16:9, 9:16, 4:3, 2.35:1. |
--ref <files...> | Mapped to wrapper's repeated --ref. Codex's image_gen accepts reference images for style/composition guidance. |
--n | Must be 1. validateArgs throws if n > 1 because Codex image_gen returns a single image per call. |
--imageApiDialect | Not applicable. Throws if set to a non-default value. |
--size, --imageSize, --quality | Silently ignored — Codex picks pixel dimensions from the aspect ratio. |
--model, -m | Logical label only. The wrapper does not forward a model selector to Codex; the underlying engine is whichever model Codex's image_gen currently uses. Default label: codex-image-gen. |
Environment variables
| Variable | Effect |
|---|---|
BAOYU_CODEX_IMAGEGEN_BIN | Override the wrapper path. Default: bundled scripts/codex-imagegen/main.ts resolved relative to this skill's installed location. Accepts a .ts file (spawned with bun) or a legacy .sh/binary (spawned directly). |
BAOYU_CODEX_IMAGEGEN_CACHE_DIR | Enable the wrapper's idempotency cache. Disabled by default; set to e.g. ~/.cache/baoyu-codex-imagegen for high-value reuse. |
BAOYU_CODEX_IMAGEGEN_TIMEOUT_MS | Per-attempt codex exec timeout in ms. Default: 300000 (5 min). Raise for slow networks or large prompts. |
BAOYU_CODEX_IMAGEGEN_RETRIES | Wrapper-side retry attempts on retryable errors. Default: 2 (3 total attempts). |
BAOYU_CODEX_IMAGEGEN_LOG_FILE | Append a structured JSONL diagnostic log. Useful when triaging timeouts or agent_refused errors. |
BAOYU_IMAGE_GEN_CODEX_CLI_CONCURRENCY | Batch-mode concurrency for the codex-cli provider. Default: 1 — Codex exec is a heavy single-process workflow; raising this rarely helps. |
BAOYU_IMAGE_GEN_CODEX_CLI_START_INTERVAL_MS | Batch-mode minimum start-gap. Default: 2000 ms. |
Error model
The wrapper emits a single JSON line on stdout. On failure:
{"status":"error","path":"...","bytes":0,"error":"...","error_kind":"..."}The provider re-throws each wrapper error as Invalid codex-cli result (<error_kind>): <message>. The "Invalid " prefix triggers isRetryableGenerationError to mark it non-retryable in baoyu-image-gen's outer retry loop — the wrapper has already retried internally per BAOYU_CODEX_IMAGEGEN_RETRIES, so re-spawning Codex from main.ts would only multiply latency without changing the outcome.
error_kind values to expect:
| Kind | Cause | Action |
|---|---|---|
codex_not_installed | codex not on PATH or unreadable | npm install -g @openai/codex, then codex login. |
invalid_args | Programmer error in the spawn invocation | Inspect provider source; usually a path-injection guard fired. |
prompt_file_missing | Temp prompt file vanished mid-call | Retry once; check $TMPDIR permissions. |
spawn_failed | OS / process-launch failure | Verify bun or npx is installed; check filesystem permissions. |
timeout | codex exec exceeded --timeout | Raise BAOYU_CODEX_IMAGEGEN_TIMEOUT_MS; check network. |
no_image_gen_tool_use | Codex agent answered without calling image_gen | Often transient — retry. If persistent, refine the prompt. |
output_missing / invalid_png | Agent reported success but file is absent or not a valid PNG | Retry; check disk space. |
agent_refused | Codex agent refused (policy or content) | Adjust the prompt; surface the refusal to the user. |
lock_busy | Another codex-imagegen invocation holds the file lock | Wait or set a distinct --cache-dir per concurrent caller. |
Trade-offs
- Slow: 5–10× direct OpenAI API latency (except cache hits).
- Subject to the same TOS as interactive
codex execuse — programmatic invocation from baoyu-image-gen is the same usage class. - Stateful: requires
codex loginto be live; an expired session manifests ascodex_not_installedoragent_refused.
See also
references/codex-oauth-vs-openai-api-key.md— why Codex OAuth is not interchangeable withOPENAI_API_KEY.references/codex-image2-fallback.md— when to fall back tocodex-clifrom a failedopenaiprovider call.