moai-coworker | Local image generation (codex CLI OAuth, no API key required)
Overview
codex CLI's built-in image_gen tool to gpt-image-2 model to generate images. The key point is without directly calling the OpenAI REST API, codex exec via a bridge. It routes the ChatGPT OAuth session token (~/.codex/auth.json) to the image generation service, API 키(sk-*) without ChatGPT subscription limitsto operate.
In particular, this skill:
- No API key required —
codex loginUse ChatGPT subscription (Plus/Team/Enterprise) limits with a single OAuth.OPENAI_API_KEYNo management burden. - 6-Block prompt integration —
media-gpt-image-2-promptpasses the OpenAI Cookbook 6-Block prompt (Subject·Action·Scene·Composition·Lighting·Style&Text) built by directly to codex. - Korean verbatim guaranteed — Korean text in images leverages gpt-image-2's 95%+ text rendering accuracy through quotes, ALL CAPS, and verbatim instructions.
- media-higgsfield-image alternative path — the same gpt-image-2 can also be called via the Higgsfield MCP path (
media-higgsfield-image). Backend choice depends on environment and cost preference.
Trigger keywords
codex image codex image gpt-image-2 generate GPT Image 2 without API key image local image generation ChatGPT subscription limit image codex exec image_gen
Key insight — OAuth bridge (why codex exec)
After testing all of OpenAI's authentication paths (reference: wjb127/codex-image MIT):
| Method | Behavior | Notes |
|---|---|---|
OPENAI_API_KEY → REST API |
✅ | Standard but with API key management burden |
| OAuth token → REST API directly | ❌ 401 | OAuth token is a session token, not an API key |
OAuth token → codex exec → image_gen |
✅ This skill | codex exec's internal bridge routes OAuth to the image generation service |
codex login (최초 1회)
→ OAuth 토큰이 ~/.codex/auth.json에 저장
→ codex exec가 토큰을 자동 읽기
→ 내장 image_gen 도구가 OAuth로 인증
→ gpt-image-2가 이미지 생성
→ 프로젝트 디렉토리에 저장
Caution: Calling the OpenAI REST API directly with an OAuth token results in HTTP 401. You must go through the
codex execbridge.
Prerequisites — codex CLI installation + login
| Requirements | Command | Notes |
|---|---|---|
| codex CLI | npm install -g @openai/codex |
Image generation engine |
| codex login | codex login |
One-time OAuth with ChatGPT |
# 설치·인증 확인
codex --version # OpenAI Codex v0.1xx.x
codex login status # "Logged in using ChatGPT"
If Bash is restricted in the Cowork environment, codex CLI calls may be blocked. This skill works in local Claude Code (terminal) or a Bash-permitted Cowork environment. If Bash is restricted, just guide the user with the codex command and prompt them to run it manually.
Workflow
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) + 인라인 표시
Options
| Flags | 값 | Default | Description |
|---|---|---|---|
--size |
1024x1024 · 1024x1536 · 1536x1024 · auto |
1024x1024 |
Image size (square·portrait·landscape) |
--quality |
low · medium · high · auto |
auto |
Generation quality (higher is slower and more expensive) |
--out |
Directory path | Project root | Save location |
-n |
1–10 | 1 |
Number of images to generate |
Invocation patterns
Basic — one natural-language line
codex exec "Use \$imagegen to create a 1024x1024 image: a red apple on white background, studio lighting. Save to ./apple.png"
High quality + specific folder
codex exec "Use \$imagegen. Generate a 1536x1024 aerial view of jeju island coastline, golden hour. quality high, save to ./public/images/jeju.png"
Multiple variants
# -n 3 처럼 루프 — codex exec를 3회 호출하거나 한 턴에 3장 지시
codex exec "Use \$imagegen. Create 3 logo variations for a tech startup, minimal, geometric. size 1024x1024, save to ./logos/"
Structured output + pipeline integration
codex exec --json --output-last-message ./last.txt \
"Generate a 1536x1024 productivity-visual hero, save under output/imagegen/hero.png"
Korean text image (verbatim guaranteed) ★
To maximize gpt-image-2's Korean rendering accuracy, quotes + verbatim instruction + font weight·color·position specify:
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"
The Korean text accuracy rules follow
moai-media:media-gpt-image-2-prompt의references/text-rendering.mdthe same principles as .
6-Block prompt chaining (recommended)
If you need complex scenes or editorial quality, media-gpt-image-2-promptfirst build the prompt with :
사용자 자연어 → moai-media:media-gpt-image-2-prompt (6-Block 프롬프트 빌드)
↓ 산출: 6-Block 자연어 단락
moai-media:media-codex-image (해당 프롬프트로 codex exec 호출 → gpt-image-2 생성)
This flow shares the same prompt SSOT as the media-higgsfield-image path — the same prompt can be used to select the Higgsfield (GPT Image 2) or codex (gpt-image-2) backend for generation.
Backend selection — higgsfield vs codex
The same gpt-image-2 and Nano Banana Pro models can be called via two paths. Choose according to environment, cost, and purpose:
| Criteria | media-higgsfield-image (Higgsfield MCP) |
media-codex-image (codex CLI) |
|---|---|---|
| Authentication | Higgsfield API 키 (MCP) | ChatGPT OAuth (no API key required) |
| Cost | Higgsfield credits | ChatGPT subscription limit |
| Best suited for | Production·CI·idempotent·unattended automation | Local development·reusing subscription limits·avoiding API keys |
| Model scope | 11종(Soul·Nano Banana Pro·GPT Image 2·Seedream 등) | gpt-image-2 only |
| MCP dependency | Required (moai-coworker/.mcp.json) |
Not required (codex CLI installed separately) |
For detailed backend policy, see moai-officer:doc-html-slide references/image-backend-policy.md .
Output
Images are saved with timestamped filenames to prevent overwriting:
codex-image-20260619-143052.png # 단일
codex-image-20260619-143052-1.png # 복수: 첫 번째
codex-image-20260619-143052-2.png # 복수: 두 번째
Generated images are displayed inline so they can be checked immediately in Claude Code.
Prompt tips
gpt-image-2 is a reasoning-driven model, so natural-language paragraphs in an art-director toneare superior to keyword lists (recommended by the OpenAI Cookbook).
- Structure: Scene/backdrop → Subject → Details → Constraints
- Lighting specification: "warm golden hour side light" > "good lighting"
- Camera language: "shallow depth of field", "aerial view", "close-up macro"
- Style specification: "photorealistic", "oil painting style", "3D render", "concept art"
- Mood/quality: "serene", "8K detail", "ultra detailed"
- Negative prompts not supported — gpt-image-2 avoids via positive description instead of negative instructions
For the detailed 6-Block structure, see media-gpt-image-2-prompt의 references/prompt-blocks.md .
Cautions
- Bash dependency — codex CLI is a terminal tool. It works only in the Claude Code main session or an environment where Bash is allowed. In Cowork where Bash is restricted, only guide with codex commands and prompt manual execution.
- Subscription limit consumption — Image generation turns consume limits 3–5x faster than regular turns (per OpenAI official). Be careful with bulk generation.
- Transparent background not supported — gpt-image-2 cannot do transparent PNG. If transparency is needed, use chroma key fallback.
- Approval policy —
--dangerously-bapprovals-and-sandboxis CI/sandbox only. Locally,-s workspace-writerecommended to limit scope to. - Text/layout-focused slides — prefer the HTML/CSS code path (imagegen "When not to use" recommendation). For infographic numbers and labels, inline SVG is accurate.
Cost
Image generation costs are billed against the ChatGPT subscription (Plus/Team/Enterprise) limit:
| Size | Quality | Approximate cost |
|---|---|---|
1024x1024 |
low |
~$0.02 |
1024x1024 |
high |
~$0.04 |
1024x1536 |
high |
~$0.06 |
For current gpt-image-2 pricing, check the OpenAI pricing page.
Security
- No API key storage/transmission — OAuth only
- No telemetry — no tracking or error reporting
- Images stored locally — only in the project directory, no external upload
- Single external connection — via the codex CLI
api.openai.com만
Troubleshooting
| Problem | Solution |
|---|---|
NOT_FOUND (no codex) |
npm install -g @openai/codex |
| Auth expired | codex login rerun |
| Trust error | Add the project to the ~/.codex/config.toml trusted list, or --skip-git-repo-check |
| Timeout (>2 min) | --quality lowto speed up |
| 401 on REST API | Expected behavior — OAuth tokens cannot be used for direct REST calls. codex exec Use. |
image_gen No tool |
npm update -g @openai/codex |
Related skills
| Skill | Relationship | Description |
|---|---|---|
| media-gpt-image-2-prompt | before | 6-Block prompt builder — use first for complex scenes and Korean text |
| media-higgsfield-image | alternative | Higgsfield MCP path (API key, production/CI). Same gpt-image-2 and Nano Banana Pro models |
| media-gemini-3-image-prompt | sibling | Gemini tone prompt (Nano Banana Pro) |
Sources
Primary (official):
- OpenAI Codex CLI — GitHub — codex CLI official,
image_genbuilt-in tool - OpenAI Cookbook — GPT Image Generation Models Prompting Guide — 6-Block prompt structure
Reference skill (MIT):
- wjb127/codex-image — Claude Code skill; referenced the OAuth bridge pattern, options, and output filename conventions. This skill adopts wjb127's core insights (OAuth→REST 401, codex exec bridge) and extends them with the moai-coworker policy (6-Block chaining, Korean verbatim, higgsfield backend selection).