Codex Image

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:

Parsing note for --reference: The flag may appear zero or more times. Initialize an empty array before parsing: _REFERENCES=(). Append each value with _REFERENCES+=("$value"). Path validation and error handling happen in Step 4's bash block — do not re-validate here.

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 / 이미지 생성

# Build -i argument array for references (zero or more).
# Array form avoids eval, so paths containing spaces, backticks, or $(...) are
# passed as literal file paths — no shell re-parsing, no injection surface.
_REF_ARGS=()
for ref in "${_REFERENCES[@]}"; do
  if [ ! -f "$ref" ]; then
    echo "ERROR: Reference image not found: $ref" >&2
    exit 1
  fi
  _REF_ARGS+=(-i "$ref")
done

# Include reference hint in the prompt if any references are attached
_REFERENCE_HINT=""
if [ "${#_REF_ARGS[@]}" -gt 0 ]; then
  _REFERENCE_HINT=" Use the attached image(s) as strong style references for tone, color palette, typography, and layout."
fi

_BACKGROUND_LINE=""
if [ -n "${_BACKGROUND}" ] && [ "${_BACKGROUND}" != "auto" ]; then
  _BACKGROUND_LINE="
6. Background: ${_BACKGROUND} — pass background='${_BACKGROUND}' as a parameter to the image_gen tool. When transparent, the saved PNG MUST include an alpha channel (RGBA, color type 6); do not flatten onto white. Verify after generation that the corners of the output are transparent before reporting success."
fi

_CODEX_PROMPT="Perform the following tasks:
1. Use the built-in image_gen tool to generate an image.${_REFERENCE_HINT}
2. Prompt: ${_PROMPT}
3. Size: ${_SIZE}
4. Quality: ${_QUALITY}
5. Count: ${_N}${_BACKGROUND_LINE}
7. Copy the generated image to '${_OUT_DIR}/${_FILENAME}.png'. For multiple images use -1.png, -2.png suffix.
8. Print the saved file path and size."

if [ "${#_REF_ARGS[@]}" -gt 0 ]; then
  # With references: -i flags on command line, prompt on stdin.
  # `codex exec -i <FILE>...` is variadic and would swallow a trailing prompt
  # positional arg as another file path, so the prompt must go to stdin.
  codex exec "${_REF_ARGS[@]}" \
    -C "${_PROJECT_ROOT}" \
    -s workspace-write \
    -c 'model_reasoning_effort="medium"' \
    --skip-git-repo-check \
    <<<"${_CODEX_PROMPT}" 2>&1
else
  # Without references: existing behavior — prompt as positional argument.
  codex exec "${_CODEX_PROMPT}" \
    -C "${_PROJECT_ROOT}" \
    -s workspace-write \
    -c 'model_reasoning_effort="medium"' \
    --skip-git-repo-check \
    2>&1
fi

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 / 생성 전 프롬프트 의도 확인