| name | media-codex-image |
| description | codex CLI의 내장 image_gen 도구로 **gpt-image-2** 이미지를 생성합니다 — ChatGPT OAuth 인증으로 **API 키 불필요**, ChatGPT Plus/Team/Enterprise 구독 한도로 동작합니다.
다음과 같은 요청 시 사용하세요:
- "codex로 이미지 만들어줘", "codex 이미지 생성", "codex image"
- "gpt-image-2로 이미지 만들어줘", "GPT Image 2 생성"
- "API 키 없이 이미지 생성해줘"
- "로컬에서 이미지 생성", "ChatGPT 구독 한도로 이미지"
- "/media-codex-image" (직접 호출)
프롬프트가 복잡하거나 한국어 텍스트가 들어가면 `moai-media:media-gpt-image-2-prompt`(6-Block 프롬프트 빌더)로 먼저 프롬프트를 빌드한 뒤 이 스킬로 생성하세요. Higgsfield MCP가 연결돼 있지 않거나 로컬 개발·ChatGPT 구독 한도 재사용이 목적이면 이 스킬을 사용합니다 (프로덕션·CI·멱등은 `media-higgsfield-image` 권장).
|
| version | 1.1.0 |
media-codex-image — codex CLI(gpt-image-2) 이미지 생성기
moai-coworker | 로컬 이미지 생성 (codex CLI OAuth, API 키 불필요)
개요
codex CLI의 내장 image_gen 도구를 호출해 gpt-image-2 모델로 이미지를 생성합니다. 핵심은 OpenAI REST API를 직접 호출하지 않고 codex exec 브릿지를 경유한다는 점 — ChatGPT OAuth 세션 토큰(~/.codex/auth.json)을 이미지 생성 서비스로 라우팅해 API 키(sk-*) 없이 ChatGPT 구독 한도로 동작합니다.
특히 본 스킬은:
- API 키 불필요 —
codex login 1회 OAuth로 ChatGPT 구독(Plus/Team/Enterprise) 한도 사용. OPENAI_API_KEY 관리 부담 없음.
- 6-Block 프롬프트 연동 —
media-gpt-image-2-prompt가 빌드한 OpenAI Cookbook 6-Block 프롬프트(Subject·Action·Scene·Composition·Lighting·Style&Text)를 그대로 codex에 전달.
- 한국어 verbatim 보장 — 이미지 내 한글 텍스트는 따옴표·ALL CAPS·verbatim 지시로 gpt-image-2의 95%+ 텍스트 렌더링 정확도 활용.
- media-higgsfield-image 대체 경로 — 같은 gpt-image-2를 Higgsfield MCP 경로(
media-higgsfield-image)로도 호출 가능. 백엔드 선택은 환경·비용 선호에 따라.
트리거 키워드
codex 이미지 codex image gpt-image-2 생성 GPT Image 2 API 키 없이 이미지 로컬 이미지 생성 ChatGPT 구독 한도 이미지 codex exec image_gen
핵심 인사이트 — OAuth 브릿지 (왜 codex exec인가)
OpenAI의 모든 인증 경로를 테스트한 결과 (참고: wjb127/codex-image MIT):
| 방식 | 동작 | 비고 |
|---|
OPENAI_API_KEY → REST API | ✅ | 표준이지만 API 키 관리 부담 |
| OAuth 토큰 → REST API 직접 | ❌ 401 | OAuth 토큰은 세션 토큰이지 API 키가 아님 |
OAuth 토큰 → codex exec → image_gen | ✅ 본 스킬 | codex exec 내부 브릿지가 OAuth를 이미지 생성 서비스로 라우팅 |
codex login (최초 1회)
→ OAuth 토큰이 ~/.codex/auth.json에 저장
→ codex exec가 토큰을 자동 읽기
→ 내장 image_gen 도구가 OAuth로 인증
→ gpt-image-2가 이미지 생성
→ 프로젝트 디렉토리에 저장
주의: OAuth 토큰으로 OpenAI REST API를 직접 호출하면 HTTP 401. 반드시 codex exec 브릿지를 거쳐야 합니다.
전제 — codex CLI 설치 + 로그인
| 요구사항 | 명령 | 비고 |
|---|
| codex CLI | npm install -g @openai/codex | 이미지 생성 엔진 |
| codex login | codex login | ChatGPT로 최초 1회 OAuth |
codex --version
codex login status
Cowork 환경에서 Bash가 제한되면 codex CLI 호출이 차단될 수 있습니다. 이 스킬은 로컬 Claude Code(터미널) 또는 Bash 허용 Cowork 환경에서 동작합니다. Bash 제한 시 사용자에게 codex 명령어를 안내만 하고 수동 실행을 유도하세요.
워크플로우
1. 컨텍스트 수집 — 주제·화면비·품질·출력 경로·장수
(복잡한 프롬프트/한국어 텍스트 → media-gpt-image-2-prompt로 6-Block 프롬프트 빌드 선행)
↓
2. 인자 조립 — --size · --quality · --out · -n + 프롬프트
↓
3. codex exec 호출 — image_gen 도구가 gpt-image-2로 생성
↓
4. 이미지 수집 — ~/.codex/generated_images/<session>/ → --out 디렉토리로 복사
↓
5. 출력 — 타임스탬프 파일명(codex-image-YYYYMMDD-HHMMSS.png) + 인라인 표시
옵션
| 플래그 | 값 | 기본값 | 설명 |
|---|
--size | 1024x1024 · 1024x1536 · 1536x1024 · auto | 1024x1024 | 이미지 크기 (정사각·세로·가로) |
--quality | low · medium · high · auto | auto | 생성 품질 (높을수록 느리고 비쌈) |
--out | 디렉토리 경로 | 프로젝트 루트 | 저장 위치 |
-n | 1–10 | 1 | 생성 장수 |
호출 패턴
기본 — 자연어 한 줄
codex exec "Use \$imagegen to create a 1024x1024 image: a red apple on white background, studio lighting. Save to ./apple.png"
고품질 + 특정 폴더
codex exec "Use \$imagegen. Generate a 1536x1024 aerial view of jeju island coastline, golden hour. quality high, save to ./public/images/jeju.png"
여러 변형
codex exec "Use \$imagegen. Create 3 logo variations for a tech startup, minimal, geometric. size 1024x1024, save to ./logos/"
구조화 출력 + 파이프라인 통합
codex exec --json --output-last-message ./last.txt \
"Generate a 1536x1024 productivity-visual hero, save under output/imagegen/hero.png"
한국어 텍스트 이미지 (verbatim 보장) ★
gpt-image-2의 한국어 렌더링 정확도를 극대화하려면 따옴표 + verbatim 지시 + 폰트 무게·색·위치 명시:
codex exec "Use \$imagegen. Text (verbatim, 한글): '2026년 분기 실적'. Typography: bold sans 한글, 검정, 상단 중앙. Require verbatim rendering, no extra characters. quality high, size 1536x1024, save to ./slide-q1.png"
한국어 텍스트 정확도 규칙은 moai-media:media-gpt-image-2-prompt의 references/text-rendering.md와 동일한 원칙을 따릅니다.
6-Block 프롬프트 체이닝 (권장)
복잡한 장면이나 에디토리얼 품질이 필요하면 media-gpt-image-2-prompt로 먼저 프롬프트를 빌드하세요:
사용자 자연어 → moai-media:media-gpt-image-2-prompt (6-Block 프롬프트 빌드)
↓ 산출: 6-Block 자연어 단락
moai-media:media-codex-image (해당 프롬프트로 codex exec 호출 → gpt-image-2 생성)
이 흐름은 media-higgsfield-image 경로와 동일한 프롬프트 SSOT를 공유합니다 — 같은 프롬프트로 Higgsfield(GPT Image 2) 또는 codex(gpt-image-2) 백엔드를 선택해 생성할 수 있습니다.
백엔드 선택 — higgsfield vs codex
같은 gpt-image-2·Nano Banana Pro 모델을两条 경로로 호출 가능. 환경·비용·목적에 따라 선택:
| 기준 | media-higgsfield-image (Higgsfield MCP) | media-codex-image (codex CLI) |
|---|
| 인증 | Higgsfield API 키 (MCP) | ChatGPT OAuth (API 키 불필요) |
| 비용 | Higgsfield 크레딧 | ChatGPT 구독 한도 |
| 적합 | 프로덕션·CI·멱등·무인 자동화 | 로컬 개발·구독 한도 재사용·API 키 회피 |
| 모델 범위 | 11종(Soul·Nano Banana Pro·GPT Image 2·Seedream 등) | gpt-image-2 단일 |
| MCP 의존 | 필요 (moai-coworker/.mcp.json) | 불필요 (codex CLI 별도 설치) |
상세 백엔드 정책은 moai-officer:doc-html-slide references/image-backend-policy.md 참조.
출력
이미지는 타임스탬프 파일명으로 저장돼 덮어쓰기를 방지합니다:
codex-image-20260619-143052.png # 단일
codex-image-20260619-143052-1.png # 복수: 첫 번째
codex-image-20260619-143052-2.png # 복수: 두 번째
생성된 이미지는 Claude Code에서 즉시 확인할 수 있도록 인라인으로 표시합니다.
프롬프트 팁
gpt-image-2는 reasoning-driven 모델로 art-director 어조의 자연어 단락이 키워드 나열보다 우수합니다 (OpenAI Cookbook 권장).
- 구조: Scene/backdrop → Subject → Details → Constraints
- 조명 구체화: "warm golden hour side light" > "good lighting"
- 카메라 언어: "shallow depth of field", "aerial view", "close-up macro"
- 스타일 명시: "photorealistic", "oil painting style", "3D render", "concept art"
- 무드/품질: "serene", "8K detail", "ultra detailed"
- 네거티브 프롬프트 미지원 — gpt-image-2는 부정 지시 대신 긍정 묘사로 회피
상세 6-Block 구조는 media-gpt-image-2-prompt의 references/prompt-blocks.md 참조.
주의사항
- Bash 의존 — codex CLI는 터미널 도구. Claude Code 메인 세션 또는 Bash 허용 환경에서만 동작. Bash 제한 Cowork에서는 codex 명령어 안내만 하고 수동 실행 유도.
- 구독 한도 소모 — 이미지 생성 턴은 일반 턴 대비 한도를 3~5배 빨리 소모 (OpenAI 공식). 대량 생성 시 주의.
- 투명 배경 미지원 — gpt-image-2는 투명 PNG 불가. 투명 필요 시 크로마키 폴백.
- 승인 정책 —
--dangerously-bapprovals-and-sandbox는 CI/샌드박스만. 로컬은 -s workspace-write로 범위 제한 권장.
- 텍스트/레이아웃 중심 슬라이드 — HTML/CSS 코드 경로 우선 (imagegen "When not to use" 권고). 인포그래픽 숫자·라벨은 인라인 SVG가 정확.
비용
이미지 생성 비용은 ChatGPT 구독(Plus/Team/Enterprise) 한도로 청구:
| 크기 | 품질 | 대략적 비용 |
|---|
1024x1024 | low | ~$0.02 |
1024x1024 | high | ~$0.04 |
1024x1536 | high | ~$0.06 |
현재 gpt-image-2 요금은 OpenAI 프라이싱 페이지 확인.
보안
- API 키 저장/전송 없음 — OAuth only
- 텔레메트리 없음 — 추적·에러 리포팅 없음
- 이미지 로컬 저장 — 프로젝트 디렉토리에만, 외부 업로드 없음
- 단일 외부 연결 — codex CLI를 통한
api.openai.com만
문제 해결
| 문제 | 해결 |
|---|
NOT_FOUND (codex 없음) | npm install -g @openai/codex |
| 인증 만료 | codex login 재실행 |
| Trust 오류 | 프로젝트를 ~/.codex/config.toml 신뢰 목록 추가 또는 --skip-git-repo-check |
| 타임아웃 (>2분) | --quality low로 속도 향상 |
| 401 on REST API | 예상 동작 — OAuth 토큰은 REST 직접 호출 불가. codex exec 사용. |
image_gen 도구 없음 | npm update -g @openai/codex |
관련 스킬
| 스킬 | 관계 | 설명 |
|---|
| media-gpt-image-2-prompt | before | 6-Block 프롬프트 빌더 — 복잡한 장면·한국어 텍스트 시 선행 |
| media-higgsfield-image | alternative | Higgsfield MCP 경로 (API 키, 프로덕션/CI). 같은 gpt-image-2·Nano Banana Pro 모델 |
| media-gemini-3-image-prompt | sibling | Gemini 어조 프롬프트 (Nano Banana Pro) |
출처
1차 (공식):
참고 스킬 (MIT):
- wjb127/codex-image — Claude Code 스킬, OAuth 브릿지 패턴·옵션·출력 파일명 규약 참고. 본 스킬은 wjb127의 핵심 인사이트(OAuth→REST 401, codex exec 브릿지)를 채택하고 moai-coworker 정책(6-Block 체이닝·한국어 verbatim·higgsfield 백엔드 선택)으로 확장했습니다.
