codex-image — AI Image Generation via Codex OAuth

Generate images using OpenAI's gpt-image-2 model through Codex CLI. No API key required — uses Codex OAuth (ChatGPT login) authentication.

OpenAI Codex CLI의 내장 image_gen 도구를 통해 gpt-image-2 모델로 이미지를 생성한다. API 키 불필요 — Codex OAuth(ChatGPT 로그인) 인증 사용.

How it works / 동작 원리

User prompt → Claude Code (/codex-image)
  → codex exec (OAuth token auto-managed)
    → built-in image_gen tool (gpt-image-2)
      → ~/.codex/generated_images/<session>/
        → copy to project root

Important: OAuth tokens cannot call OpenAI REST API directly (returns 401). Must go through codex exec which handles auth internally.

OAuth 토큰으로 OpenAI REST API 직접 호출 불가 (401 반환). 반드시 codex exec 경유 — Codex가 내부적으로 인증 처리.

Step 1 — Verify Codex CLI & Auth / Codex CLI 및 인증 확인

which codex 2>/dev/null && codex --version 2>/dev/null || echo "NOT_FOUND"

If NOT_FOUND, stop:

"Codex CLI not installed. Run npm install -g @openai/codex then codex login." "Codex CLI 없음. npm install -g @openai/codex 후 codex login 실행해."

codex login status 2>&1

If not "Logged in":

"Codex login required. Run codex login in terminal. OAuth login enables image generation without API key." "Codex 로그인 필요. 터미널에서 codex login 실행. OAuth 로그인하면 API 키 없이 이미지 생성 가능."

Step 2 — Parse Arguments / 인자 파싱

Extract from $ARGUMENTS:

Remaining text → image prompt / 나머지 텍스트 → 이미지 프롬프트

If prompt is empty, ask via AskUserQuestion:

"What image should I generate? Enter a prompt." "어떤 이미지를 생성할까? 프롬프트를 입력해줘."

Step 3 — Determine Save Path / 저장 경로 결정

_PROJECT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
_OUT_DIR="${_PROJECT_ROOT}"
_TIMESTAMP=$(date +%Y%m%d-%H%M%S)
_FILENAME="codex-image-${_TIMESTAMP}"

• If --out specified, use that path / --out 지정 시 해당 경로 사용
• Single image: codex-image-<timestamp>.png
• Multiple (-n > 1): codex-image-<timestamp>-1.png, -2.png, ...
• Never overwrite existing files / 기존 파일 덮어쓰기 금지

Step 4 — Generate Image / 이미지 생성

codex exec "Perform the following tasks:
1. Use the built-in image_gen tool to generate an image.
2. Prompt: '${_PROMPT}'
3. Size: ${_SIZE}
4. Quality: ${_QUALITY}
5. Count: ${_N}
6. Copy the generated image to '${_OUT_DIR}/${_FILENAME}.png'. For multiple images use -1.png, -2.png suffix.
7. Print the saved file path and size." \
  -C "${_PROJECT_ROOT}" \
  -s workspace-write \
  -c 'model_reasoning_effort="medium"' \
  --skip-git-repo-check \
  2>&1

timeout: 120000ms (2 min)

Required flags / 필수 플래그

• -s workspace-write — file write permission / 파일 쓰기 권한
• --skip-git-repo-check — works outside git repos / git 레포 외부에서도 실행 가능

Internal flow (Codex side) / 내부 동작 흐름

1. Codex calls built-in image_gen tool (gpt-image-2)
2. Image saved to ~/.codex/generated_images/<session-id>/ig_*.png
3. Codex copies file to specified project path
4. Reports file path and size

Step 5 — Display Result / 결과 출력

═══════════════════════════════════════════════
IMAGE GENERATED / 이미지 생성 완료
═══════════════════════════════════════════════
Prompt: <prompt used>
Size: <size>
Quality: <quality>
Count: <n>
Auth: OAuth (ChatGPT)
───────────────────────────────────────────────
<saved file path(s)>
═══════════════════════════════════════════════

Always display the generated image using the Read tool. 생성된 이미지를 반드시 Read 도구로 표시한다.

Step 6 — Follow-up / 후속 안내

• "Run /codex-image again to generate another image."
• For Next.js projects: suggest moving to public/images/ if needed.

Error Handling / 에러 처리

Rules / 규칙

• Always use the Read tool to display generated images / 생성된 이미지는 반드시 Read로 표시
• Never overwrite existing files — always use timestamped filenames / 기존 파일 덮어쓰기 금지
• OAuth only — do not attempt direct REST API calls with OAuth token (returns 401) / OAuth 토큰으로 REST API 직접 호출 금지
• Verify prompt intent before generating / 생성 전 프롬프트 의도 확인