| name | codex-image |
| description | 用 codex 订阅额度生成/编辑位图图片（照片、插画、产品图、海报主视觉、概念图、纹理、透明切图），走 codex 内置 image_gen 工具，无需 OPENAI_API_KEY、不计 API 费用。Use when 用户要生成图片/配图/插画/产品图/概念图/网页或海报底图、要"用 codex/gpt-image 生图""白嫖订阅额度出图""批量出图变体""把这张图改成…"。NOT for 纯 SVG/矢量图标、用代码/HTML/canvas 能直接画的简单图形、需要精确可编辑文字排版的海报（用 poster-toolkit）。 |
codex-image
让 Claude Code 稳定地用 codex 的订阅额度生成图片：CC 把需求写成结构化提示词，脚本驱动 codex exec 调用内置 image_gen 工具出图，吃 ChatGPT 订阅额度，不需要 API key、不计 API 费用。
原理（一张图说清）
用户需求
└─ CC 写成结构化提示词 (references/prompt-recipes.md)
└─ scripts/codex_image.py
└─ codex exec --sandbox workspace-write ← 内置 image_gen 工具
└─ 自动存到 $CODEX_HOME/generated_images/<session>/ig_*.png
└─ 复制到你指定的 --out，校验是真 PNG
订阅额度计费（rate-limit id codex），不碰 OPENAI_API_KEY。实测 Plus 纯出图：每张 ≈2% 的 5h 窗口 / ≈0.5% 的 7d 窗口 → 约 50 张/5h、~30 张/天（周额度封顶，和写代码共用）。
稳定生图的三个支点
- 强制真工具 — 提示词带固定契约头：必须调内置 image_gen，严禁用代码/PowerShell/SVG/canvas 画。脚本自动加，不靠运气。
- 结构化提示词 — 按
references/prompt-recipes.md 的 spec 把需求写清楚（用途→主体→细节→约束），质量才稳。
- 明确产出 + 校验 — 提示词写死输出绝对路径；脚本在
generated_images 兜底定位、复制、解析 PNG 头校验尺寸。
前置检查（第一次用先确认）
codex --version 能跑。codex login 已用 ChatGPT 订阅账号登录（不是 API key 模式）——否则不吃订阅额度。- 细节见
references/boundaries.md 的「前置条件」。
工作流
1. 把需求写成提示词 body
读 references/prompt-recipes.md，按结构化 spec 写。原则：
- 用户需求已经很具体 → 只规整，不乱加。
- 笼统 → 补能实质提升质量的细节（构图、光线、用途、配色）。
- 写进一个文件（放 scratchpad），避免 shell 转义。
2. 调脚本出图（后台跑，约 30–90 秒/图）
python "~/.claude/skills/codex-image/scripts/codex_image.py" \
--out "<绝对输出路径>.png" \
--prompt-file "<scratchpad/prompt.txt>" \
--size "1536x1024"
--size 见 references/boundaries.md 尺寸表（不传则模型自定；尺寸只能靠提示词引导，工具不收尺寸参数）。--workdir 默认取输出文件所在目录；一般不用传。- 透明切图加
--transparent（色键抠图，需 Pillow，见下）。
- 脚本输出一段 JSON：
ok / out / width / height / bytes / source。
3. 校验（必做，不要直接信「成功」）
看脚本 JSON：
ok: true 且 width/height 合理 → 成。必要时把图读出来肉眼看主体/风格/文字对不对。ok: false → 看 error 和 codex_stdout_tail：
- 没产出/模型在问问题 → 提示词更明确，重试一次。
- 不是有效 PNG / 尺寸极小 → 模型可能用代码画了，重试并强化「严禁代码绘制」。
- 重试最多一次就换思路或找用户，别空转烧额度。
多图 / 变体
一资产一次调用，每次不同 --out（内置工具不能一次出多张）。批量时循环调脚本。并发安全：脚本按本次 codex session-id 定位产出（generated_images/<session-id>/），就算别的 codex session（兄弟 CC 项目 / 桌面 App）同时在生图也只拿自己那张——因为 codex 自己的复制逻辑是「取最新的图」、跨 session 共享会串图（已实证）。另有 courtesy 文件锁礼让旧版进程，等不到也不报错。
透明背景切图
--transparent：生成纯 #00ff00 色键背景 → 脚本调 codex 自带 remove_chroma_key.py 抠成 alpha PNG。
- 需要 Pillow：
python -m pip install pillow。
- 适合边缘清晰的实心主体（图标/贴纸/产品切图）。
- 毛发/烟雾/玻璃/反光等复杂主体色键抠不干净——这类真透明只能走 CLI gpt-image-1.5（要 API key，违背订阅初衷，不做）。详见
references/boundaries.md。
编辑已有图
内置编辑只作用于 codex 上下文里的图。改本地文件时，提示词要先让 codex view_image 加载该文件再改，并逐轮重申不变量（只改 X，保持 Y 不变）。脚本默认走生成路径；编辑场景可直接用 codex exec 手写提示词，或把编辑指令写进 body 让模型先 view_image 再生成。
关键边界（详见 references/boundaries.md）
- 尺寸/分辨率：实测固定 ~1.57MP（≈1536×1024，按长宽比重排），最大边 ~1672px——不是 4K。doc 里 ≤3840/16倍数那套是 CLI+API 规格，不适用订阅路径。
- 质量：扁平插画↔照相写实都强；长文字/精确排版不可靠（用 poster-toolkit）。
- 透明：无原生透明，靠色键抠图。
- 计费：订阅额度，无 API 费用。
参考文件
references/prompt-recipes.md — 结构化提示词模板、用途分类、样例、PPVI 浅色配图小抄。references/boundaries.md — 尺寸/质量/透明/编辑/计费/失败排查/前置条件。scripts/codex_image.py — 执行器。--help 看全部参数；--print-prompt 可只打印最终提示词调试。
