codex-image-gen

Codex Image Gen

目标：把“本机已登录的 Codex OAuth 生图能力”封装成一个零私有依赖的跨 Agent Skill。

它不依赖任何私有模块；任何能执行 python3 的 Agent，只要宿主机已经装好 Codex CLI 并执行过 codex auth login，就能直接调用 scripts/codex_image.py 生图或做图像编辑。

前置条件

必须同时满足：

1. 本机已安装 Codex CLI
2. 已执行过 codex auth login
3. ~/.codex/auth.json 存在且可读
4. 机器可访问：
   • https://chatgpt.com/backend-api/codex/responses
   • https://auth.openai.com/oauth/token

如果 ~/.codex/auth.json 不存在，不要猜测或绕过。直接提示用户先运行：

codex auth login

这个 skill 能做什么

• 文生图
• 配图 / 插图 / 封面图生成
• image-to-image / 编辑
• 用 --image 与 --reference-image 显式区分主编辑画布和身份/风格参考，避免多图角色混淆
• 每次生成自动保存可审计、可继续编辑的 manifest；可用 --continue-from 接着上一轮返修
• 把本地参考图编码成 data:image/...;base64,... 后发给 Codex Responses API
• 自动检查 access token 是否过期
• access token 过期时自动用 refresh token 刷新，并写回 ~/.codex/auth.json
• 从 SSE 流里提取图片 base64，保存为本地 PNG

核心脚本

相对路径：scripts/codex_image.py

典型调用方式：

python3 scripts/codex_image.py \
  --prompt "极简科技感课程封面，无文字" \
  --aspect landscape

如果 Agent 不是在 skill 根目录执行，就显式传 skill 相对路径或绝对路径，例如：

python3 .claude/skills/codex-image-gen/scripts/codex_image.py \
  --prompt "商业文章封面插图，克制，干净，无文字" \
  --aspect landscape \
  --quality high \
  --out-dir ./outputs

CLI 参数

必填

二选一：

• --prompt "..."
• --prompt-file /path/to/prompt.txt

可选

• --quality low|medium|high：默认 medium
• --aspect landscape|square|portrait：选择后端母版方向，默认 square
• --out-dir /path/to/output-dir：默认当前目录
• --image /path/to/image.png：主编辑图 / 输入图
• --reference-image /path/to/ref.png：参考图，可重复传入
• --model gpt-image-2：默认 gpt-image-2
• --response-model gpt-6-astra：负责理解 prompt、图片区分和调度生图工具的外层模型，默认 gpt-6-astra
• --continue-from /path/to/previous.png.manifest.json：自动把上一张成图作为主编辑图，并复用上一轮可复用参考图
• --manifest-out /path/to/run.json：自定义 manifest 路径；默认与最终图片同名并追加 .manifest.json
• --name 基础名：输出 <基础名>.png 与 <基础名>.png.manifest.json；同名已存在时不覆盖，自动改为 <基础名>-2、-3。不传则用默认随机文件名

Codex 通道目前在服务端把尺寸与质量改为 auto（2026-10 实测，见 references/api-notes.md），请求的方向常被忽略；需要横版或竖版时在 prompt 里写清画幅。脚本会把实际 PNG 原样保存，并在 manifest 中记录 aspect 与实际尺寸；不做扩边、裁切或缩放。若比例偏离，直接返修或重生成。