Codex CLI 이미지 생성 가이드

OpenAI Codex CLI(터미널 코딩 에이전트)에 내장된 image_generation 기능으로 ChatGPT 구독 인증만으로 AI 이미지 생성/편집이 가능하다. 2026-04-27 실제 검증 완료.

핵심 사실 (검증됨)

항목	값
버전	Codex CLI v0.125.0
feature flag	`image_generation` (stable, 기본 true)
모델	`gpt-image-2` (built-in) / `gpt-image-1.5` (CLI fallback, 투명 PNG용)
인증	ChatGPT Plus/Pro/Team 로그인만으로 OK — `OPENAI_API_KEY` 불필요
출력 기본 위치	`~/.codex/generated_images/{session-id}/ig_*.png`
워크플로 폴더 저장	명시적으로 요청해야 함 (자동 X)

설치 / 로그인

npm install -g @openai/codex
codex login        # ChatGPT 계정으로 로그인
codex login status # "Logged in using ChatGPT" 확인

검증된 호출 패턴 (Windows bash)

단일 이미지 편집 (참조 첨부)

# 1. 출력 폴더 생성
mkdir -p "D:/claude/content/codex-test"
 
# 2. 프롬프트를 파일로 저장 (한글 안전)
cat > "D:/claude/content/codex-test/_prompt.txt" << 'EOF'
참조 이미지와 동일한 캐릭터·복장·배경 그대로 유지하되,
표정만 '수줍음'으로 바꿔서 새로 그려줘.
결과 PNG를 expr_yena_shy_nobg.png 로 저장해.
EOF
 
# 3. Codex 호출 (stdin으로 프롬프트, -i로 참조 이미지)
cat "D:/claude/content/codex-test/_prompt.txt" | codex exec \
  --full-auto \
  --skip-git-repo-check \
  -C "D:/claude/content/codex-test" \
  -i "D:/claude/content/remotion/public/images/characters/expr_yena_happy_nobg.png" \
  -

주요 플래그

플래그	역할
`--full-auto`	승인 프롬프트 없이 sandboxed 자동 실행
`--skip-git-repo-check`	git repo 아닌 폴더에서도 실행 허용 (필수)
`-C <DIR>`	작업 폴더 (Codex가 파일 저장할 위치)
`-i <FILE>`	참조 이미지 첨부 (반복 가능)
`-`	프롬프트를 stdin에서 읽기
`-m gpt-image-2`	모델 명시 (기본은 자동)

주의: 인자로 프롬프트 직접 넘기면 실패

# ❌ 안 됨 (한글/멀티라인에서 stdin 모드로 빠짐)
codex exec --full-auto "프롬프트 텍스트..."
 
# ✅ stdin 사용
echo "프롬프트" | codex exec --full-auto -
# 또는 파일에서
cat prompt.txt | codex exec --full-auto -

동작 흐름

Codex가 imagegen 시스템 스킬 자동 로드 (~/.codex/skills/.system/imagegen/SKILL.md)
빌트인 image_gen 툴 호출 → 이미지 생성
결과를 ~/.codex/generated_images/{session-id}/ig_{hash}.png에 저장
(스킬 규칙) 사용자가 작업 폴더에 저장하라고 했으면 PowerShell Copy-Item으로 복사
최종 경로 보고

검증된 사용 사례

✅ 캐릭터 표정 변형 (편집)

참조 이미지 첨부 → 캐릭터 동일성 매우 높게 유지됨
헤어/복장/명찰/소품까지 잘 보존
예: expr_yena_happy_nobg.png → expr_yena_shy_nobg.png (예나샘 수줍은 표정)

✅ 알파 PNG (Chroma-key) — 검증 완료 (2026-04-27)

진짜 RGBA PNG 생성 가능. 프롬프트에 “투명 배경 / chroma-key 워크플로” 명시하면 Codex가 자동 처리
결과: 모드 RGBA, 알파 0~255, 네 모서리 완전 투명, 가장자리 페더링 자연스러움
머리카락/명찰 텍스트 디테일 보존 우수

✅ 한글 매거진 커버 — 검증 완료 (2026-04-28, macOS)

gpt-image-2의 한글 텍스트 렌더링 품질 매우 우수
검증 케이스: “도시살롱 VOL.42 / 2026 APRIL” 잡지 커버 (1122×1402)
- 마스트헤드(굵은 산세리프 한글), 메인 카피(“봄, 다시 걷기로 했다” 명조), 사이드 카피 3줄, 가격+URL 모두 정확
- 받침/쌍자음/쉼표 위치까지 자연스러움
- 비주얼(북촌 한옥 골목 + 트렌치코트 여성 뒷모습 + 골든아워) 동시에 잘 잡음
결론: 잡지/책 표지/포스터 등 한글 활자가 디자인 일부로 들어가는 작업에 실전 투입 가능
출력: ~/jin9/codex-test/korean-typography/magazine_cover_test.png

🟠 메뉴판/리스트 = Codex가 PIL로 우회할 수 있음 (2026-04-28)

텍스트 비중이 압도적으로 높은 디자인(메뉴판, 표, 가격 리스트)을 요청하면 Codex 에이전트가 이미지 모델이 아니라 Python PIL + 로컬 한글 폰트로 PNG를 합성하는 경로를 선택할 수 있음
똑똑한 선택이지만 “AI 모델의 한글 표현력” 테스트 의도와 다름 → 모델 직접 그림이 필요하면 프롬프트에 다음을 명시:

“반드시 image_gen 툴(gpt-image-2)을 사용해서 직접 생성할 것. PIL/Pillow/matplotlib 같은 코드로 합성하지 마.”
반대로 정확한 가격·작은 글씨·표 정렬이 중요한 실제 메뉴판/명함은 PIL 우회 쪽이 더 안전

🟡 한계 / 주의점

gpt-image-2는 transparent 미지원: chroma-key 워크플로 우회는 됨. 진짜 native transparent는 gpt-image-1.5 CLI fallback 필요 (OPENAI_API_KEY 별도)
그림체 차이: gpt-image-2는 기존 ComfyUI(z-image-turbo) 산출물과 그림체가 다름. 같은 캐릭터라도 직접 섞으면 시각적 불일치 → 별도 폴더 분리 정책 필수 (아래 참고)

투명 배경(Chroma-key) 워크플로

# 1. 녹색 #00ff00 배경으로 생성 요청 (프롬프트에 명시)
# 2. 결과를 작업 폴더로 복사
# 3. 헬퍼 스크립트로 알파 변환
python "${CODEX_HOME:-$HOME/.codex}/skills/.system/imagegen/scripts/remove_chroma_key.py" \
  --input source.png \
  --out final_nobg.png \
  --auto-key border \
  --soft-matte \
  --transparent-threshold 12 \
  --opaque-threshold 220 \
  --despill

VN/캐릭터 작업 활용 시나리오

시나리오	추천
새 표정 추가 (기존 캐릭터)	Codex + 참조 이미지 첨부 → 매우 우수
새 캐릭터 디자인	NotebookLM/ComfyUI가 일관성 측면에서 더 안정적
VN 배경/소품 1회성	Codex 빠르게 시도 가능
대량 생성	ComfyUI (배치/시드 제어 우위)
빠른 반복(iteration)	Codex (자연어로 “이거 더 밝게” 식 수정 쉬움)
한글 활자 매거진/포스터	Codex + image_gen 강제 → 매우 우수 (2026-04-28 검증)
정확 가격 메뉴판/표	Codex의 PIL 우회 경로가 더 안전 (작은 글씨/숫자)

실제 검증 결과 (2026-04-27)

1차 — 흰 배경 (built-in image_gen)

입력: expr_yena_happy_nobg.png (참조)
출력: D:\claude\content\codex-test\expr_yena_shy_nobg.png (1.75MB, RGB 흰 배경)
결과: ✅ 캐릭터 일관성·표정 정확도 우수, 단 진짜 알파는 아님
소요: 67,440 tokens / 약 30초

2차 — 알파 PNG (chroma-key 워크플로)

동일 참조 + “투명 배경 chroma-key” 명시 프롬프트
중간 파일: expr_yena_shy_green.png (#00ff00 배경 1차 생성물)
최종: D:\claude\content\codex-test\expr_yena_shy_alpha.png (1.4MB, RGBA)
검증 (PIL):
- 모드 RGBA, 알파 (0,255), 네 모서리 [0,0,0,0]
- 투명 픽셀 821,209 / 1,573,155 (52%)
- 반투명 에지 11,309 (0.7%)
Codex 자동 처리: 생성 → Copy-Item → remove_chroma_key.py --auto-key border --soft-matte --despill → PIL 검증
소요: 74,089 tokens

실제 검증 결과 (2026-04-28, macOS)

환경

macOS / /opt/homebrew/bin/codex (codex-cli 0.125.0)
설치: npm install -g @openai/codex → codex login (ChatGPT)
인증 토큰: ~/.codex/auth.json

1차 — 한식 메뉴판 (Codex가 PIL 우회 선택)

프롬프트: “달빛한식당 2026 봄 코스 메뉴”, 한글 6개 메뉴 + 가격, 한지 질감
Codex 판단: 이미지 모델 호출 대신 generate_korean_menu.py(PIL + Apple SD Gothic Neo) 작성하여 합성
결과: ✅ 한글 100% 정확 / ❌ 단 AI 모델 직접 렌더링은 아님
시사점: 작은 글씨·정확한 가격·표 형태는 PIL 경로가 안전

2차 — 한글 매거진 커버 (image_gen 강제 → 모델 직접 렌더링)

프롬프트에 “반드시 image_gen 툴 사용, PIL/코드 합성 금지” 명시
컨셉: “도시살롱 VOL.42 / 2026 APRIL”, 메인 카피 “봄, 다시 걷기로 했다”, 북촌 한옥 골목 + 트렌치코트 여성 뒷모습 + 골든아워, 1024×1280 세로형 요청
출력: magazine_cover_test.png (1122×1402, RGB) — Codex 기본 폴더에 생성 후 작업 폴더로 복사
결과:
- ✅ 마스트헤드 “도시살롱” 굵은 산세리프 자모 균형 정확
- ✅ 메인 카피 명조 느낌·받침·쉼표 위치 자연스러움
- ✅ 사이드 카피 3줄(서울의 골목길 12곳 / 카페 인사이드 가이드 / 인터뷰: 가수 김현수) 모두 정확
- ✅ 통화 기호+영문 URL “₩12,000 / www.dosisalon.kr” OK
- ✅ 비주얼: 한옥 골목 + 남산타워 실루엣 + 벚꽃까지 보너스로 추가됨
소요: 66,699 tokens
결론: gpt-image-2의 한글 활자 렌더링은 매거진/포스터/책 표지 수준에서 실전 투입 가능

캐릭터 폴더 구조 (그림체 분리 정책)

Codex(gpt-image-2) 산출물은 기존 ComfyUI 산출물과 그림체가 달라서 반드시 별도 서브폴더에 보관한다.

D:\claude\content\remotion\public\images\characters\
├─ expr_yena_*_nobg.png        ← ComfyUI (z-image-turbo, 기본)
├─ expr_mirae_*_nobg.png       ← ComfyUI
├─ expr_ongi_*_nobg.png        ← ComfyUI
├─ expr_sosik_*_nobg.png       ← ComfyUI
└─ codex/                       ← Codex(gpt-image-2) 산출물 전용
    └─ expr_yena_shy_nobg.png

규칙:

ComfyUI 결과: characters/ 루트에 그대로 저장 (기본)
Codex 결과: characters/codex/ 서브폴더에 저장 (파일명은 같은 규칙 expr_{char}_{expr}_nobg.png 유지)
같은 캐릭터·표정도 그림체 다르면 같이 두지 말고, Remotion 영상 단위로 한 그림체만 사용
새 그림체 추가 시 같은 패턴: characters/{source}/ (예: characters/midjourney/, characters/nlm/)

트러블슈팅

증상	해결
`Not inside a trusted directory`	`--skip-git-repo-check` 추가
`No prompt provided via stdin`	프롬프트를 인자로 넘기지 말고 stdin (`-` + pipe) 사용
결과가 작업 폴더에 없음	Codex 기본 폴더 `~/.codex/generated_images/{session-id}/` 확인 후 수동 복사. 또는 프롬프트에 “결과를 X 폴더에 저장해” 명시
`Logged in using ChatGPT` 안 뜸	`codex login` 재실행
텍스트 위주 디자인에서 Codex가 PIL 코드로 우회	프롬프트에 “반드시 image_gen 툴 사용, PIL/Pillow/matplotlib 등 코드 합성 금지” 명시
ChatGPT 사이트는 로그인했는데 `Not logged in`	사이트 로그인은 무관. 터미널에서 `codex login` 직접 실행해야 OAuth → `~/.codex/auth.json` 토큰 저장

탐색기

Codex CLI 이미지 생성 가이드

핵심 사실 (검증됨)

설치 / 로그인

검증된 호출 패턴 (Windows bash)

단일 이미지 편집 (참조 첨부)

주요 플래그

주의: 인자로 프롬프트 직접 넘기면 실패

동작 흐름

검증된 사용 사례

✅ 캐릭터 표정 변형 (편집)

✅ 알파 PNG (Chroma-key) — 검증 완료 (2026-04-27)

✅ 한글 매거진 커버 — 검증 완료 (2026-04-28, macOS)

🟠 메뉴판/리스트 = Codex가 PIL로 우회할 수 있음 (2026-04-28)

🟡 한계 / 주의점

투명 배경(Chroma-key) 워크플로

VN/캐릭터 작업 활용 시나리오

실제 검증 결과 (2026-04-27)

1차 — 흰 배경 (built-in image_gen)

2차 — 알파 PNG (chroma-key 워크플로)

실제 검증 결과 (2026-04-28, macOS)

환경

1차 — 한식 메뉴판 (Codex가 PIL 우회 선택)

2차 — 한글 매거진 커버 (image_gen 강제 → 모델 직접 렌더링)

캐릭터 폴더 구조 (그림체 분리 정책)

트러블슈팅

관련 자료

그래프 뷰

목차

백링크