用 Codex 的 imagegen Skill 在编码流程里生成位图素材

大模型Skills imagegen Codex Agent Skill 图像生成 AI编程 2026-08-12 189 阅读

前言

写前端、做小游戏、搭落地页时，经常会卡在「缺一张图」：Hero 背景、产品 Mockup、精灵图、透明抠图。以前常见做法是切到独立绘图工具生成，再下载、重命名、拷进仓库；或者先用 SVG/HTML 占位，后期再换真图。流程一长，文案、布局和素材就容易脱节。

OpenAI 把图像生成能力封装成了 Agent Skill：imagegen。它挂在 Codex 的 .system 技能目录下，最新版 Codex 会自动安装。核心思路很直接——在对话里说明要什么位图，由内置 image_gen 工具（或显式启用的 CLI）产出 PNG 等光栅资源，再按规则落到项目目录。本文依据官方仓库中的 SKILL.md 与 CLI 参考整理其能力、启用方式与典型用法。

这是什么

imagegen 是面向 Codex 的系统级 Skill，官方路径为：

https://github.com/openai/skills/tree/main/skills/.system/imagegen

定位可以概括为一句：在任务需要 AI 生成的位图（照片、插画、纹理、精灵图、Mockup、透明抠图等）时，用结构化流程生成或编辑图像；若更适合改仓库里已有的 SVG/矢量/HTML/CSS，则不要走这条路径。

仓库 README 写明：skills/.system/ 下的技能会随最新版 Codex 自动安装，一般不需要再用 $skill-installer 单独装。Skill 本体是标准的 SKILL.md + scripts/ + references/ 目录结构，符合 Agent Skills 开放格式；但内置 image_gen 工具与 $CODEX_HOME 保存约定是 Codex 侧能力，使用时以 Codex 环境为准。

两种工作模式

官方文档写得很清楚，Skill 只有两层顶层模式：

  1. 默认：内置 image_gen 工具（推荐）
    用于日常生成与编辑，不需要设置 OPENAI_API_KEY。

  2. 回退：scripts/image_gen.py CLI（仅显式使用）
    只有用户明确要求走 CLI 时才用。需要 OPENAI_API_KEY 与网络访问。提供三个子命令：generate、edit、generate-batch。

规则要点：

  • 正常请求一律走内置工具，不要自动切到 CLI。
  • 内置失败或不可用时，应告知用户存在 CLI 回退且依赖 API Key；只有用户明确同意后再走 CLI。
  • 走 CLI 时使用技能自带的 scripts/image_gen.py，不要临时写一套 SDK 脚本；也不要擅自修改该脚本。

核心能力与边界

适合做什么

官方列出的典型场景包括：

  • 从零生成：概念图、产品图、封面、网站 Hero 等
  • 带参考图生成：用一张或多张图约束风格、构图或氛围
  • 编辑已有图：局部重绘、光照/天气变换、换背景、去物体、合成、透明背景
  • 同一任务产出多张素材或变体

生成侧还按用途做了分类 slug（如 product-mockup、ui-mockup、photorealistic-natural、illustration-story 等）；编辑侧则有 precise-object-edit、background-extraction、style-transfer、compositing 等。写提示词时保持 slug 一致，便于 Agent 按同一套模板扩写。

不适合做什么

官方同样划了边界，避免「什么图都生」：

  • 扩展或对齐仓库里已有的 SVG/矢量图标、Logo 体系、插画库
  • 用 SVG、HTML/CSS、canvas 就能更好完成的简单图形、示意图、线框、图标
  • 源文件本身已是可编辑的原生格式，只需小改
  • 用户明确要确定性的代码侧输出，而不是生成位图

简单说：位图资产用 imagegen；矢量与代码原生视觉继续改仓库里的文件。

安装与启用

在最新版 Codex 中，.system 下的 imagegen 会自动安装。确认技能是否可用，可在 Codex 中查看已加载 Skills，或检查本机技能目录（默认 CODEX_HOME 为 ~/.codex）：

export CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
ls "$CODEX_HOME/skills/.system/imagegen"

目录中通常包含 SKILL.md、scripts/image_gen.py、references/ 等。安装或更新技能后，按 Codex 文档要求重启会话，以便重新加载。

若内置工具不可用、且你明确要走 CLI 回退，先准备依赖与密钥：

# 官方推荐在 uv 管理的环境中安装
uv pip install openai
# 仅在需要缩小输出图时可选
uv pip install pillow

# 在本机环境变量中配置，不要把完整 Key 贴进对话
export OPENAI_API_KEY="你的密钥"

CLI 入口可固定为：

export IMAGE_GEN="$CODEX_HOME/skills/.system/imagegen/scripts/image_gen.py"

密钥可在 OpenAI 平台创建：https://platform.openai.com/api-keys

说明：openai/skills 仓库 README 目前标注该仓已 deprecated，新示例转向 OpenAI Plugins 仓库；但 .system/imagegen 的 SKILL.md 仍是当前公开一手说明，且 Codex 侧仍按系统技能自动安装。写作与实践以该目录内容为准。

内置模式：保存路径约定

内置模式下，Codex 默认把生成结果写到 $CODEX_HOME/*（常见为 $CODEX_HOME/generated_images/...），不要把系统临时目录当成默认落点，也不要依赖内置工具的「目标路径参数」。需要固定位置时，流程是：先生成，再把选定文件移动/复制到目标路径。

优先级官方约定如下：

  1. 用户指定了目标路径 → 移到该路径
  2. 图要进当前项目 → 结束前拷进工作区，并更新引用
  3. 仅预览/头脑风暴 → 可内联展示，文件留在 $CODEX_HOME/*

注意：

  • 项目真正引用的资源，不能只留在 $CODEX_HOME 默认目录。
  • 除非用户明确要求覆盖，否则不要覆盖已有资产；可用 hero-v2.png、item-icon-edited.png 这类兄弟文件名。

编辑语义上，内置编辑面向「对话上下文里已经可见」的图（附件或本轮早先生成的图）。若要改本地文件，需先用内置 view_image 载入上下文，再编辑；不要承诺内置工具能直接按任意文件系统路径做带 mask 等精细控制——那种能力属于显式 CLI 回退。

提示词怎么写

官方建议把用户意图整理成结构化规格，而不是盲目加戏。共享模板大致如下：

Use case: <taxonomy slug>
Asset type: <where the asset will be used>
Primary request: <user's main prompt>
Input images: <Image 1: role; Image 2: role> (optional)
Scene/backdrop: <environment>
Subject: <main subject>
Style/medium: <photo/illustration/3D/etc>
Composition/framing: <wide/close/top-down; placement>
Lighting/mood: <lighting + mood>
Color palette: <palette notes>
Materials/textures: <surface details>
Text (verbatim): "<exact text>"
Constraints: <must keep/must avoid>
Avoid: <negative constraints>

扩充原则：

  • 用户已经写得很细 → 只做规范化，不擅自加创意需求
  • 用户写得很泛 → 可以补充构图、用途、光影等「能实质提升结果」的信息
  • 不要擅自加未暗示的人物/物体、品牌 slogan、无关叙事
  • 编辑时反复写清不变量，例如「只改背景，主体与边缘不变」

生成示例（Hero / 产品图）：

Use case: product-mockup
Asset type: landing page hero
Primary request: a minimal hero image of a ceramic coffee mug
Style/medium: clean product photography
Composition/framing: wide composition with usable negative space for page copy if needed
Lighting/mood: soft studio lighting
Constraints: no logos, no text, no watermark

编辑示例（只换背景）：

Use case: precise-object-edit
Asset type: product photo background replacement
Primary request: replace only the background with a warm sunset gradient
Constraints: change only the background; keep the product and its edges unchanged; no text; no watermark

在 Codex 对话里，也可以直接用自然语言描述需求，例如：「给落地页生成一张陶瓷马克杯的极简产品 Hero，留出文案负空间，不要 Logo 和文字」，Agent 应按 Skill 规则走内置 image_gen，并把最终可用文件放进项目。

CLI 回退示例（显式启用时）

以下命令来自官方 references/cli.md，仅在用户明确要求 CLI 时使用。

干跑（不调 API、不需 openai 包）：

python "$IMAGE_GEN" generate \
  --prompt "Test" \
  --out output/imagegen/test.png \
  --dry-run

生成：

python "$IMAGE_GEN" generate \
  --prompt "A cozy alpine cabin at dawn" \
  --size 1024x1024 \
  --out output/imagegen/alpine-cabin.png

编辑：

python "$IMAGE_GEN" edit \
  --image input.png \
  --prompt "Replace only the background with a warm sunset" \
  --out output/imagegen/sunset-edit.png

带质量与输入保真度的编辑（CLI 专有参数，不是内置工具参数）：

python "$IMAGE_GEN" edit \
  --image input.png \
  --prompt "Change only the background" \
  --quality high \
  --input-fidelity high \
  --out output/imagegen/background-edit.png

官方 CLI 默认值包括：模型 gpt-image-1.5（GPT Image 系列）、尺寸 1024x1024、质量 auto、输出格式 png。支持尺寸为 1024x1024、1536x1024、1024x1536 或 auto。透明背景需要输出格式为 png 或 webp。中间文件建议放 tmp/imagegen/，成品放 output/imagegen/；目标文件已存在时需加 --force 才会覆盖。

批量多提示词可用 generate-batch（必须指定 --out-dir）：

mkdir -p tmp/imagegen output/imagegen/batch
cat > tmp/imagegen/prompts.jsonl << 'EOF'
{"prompt":"Cavernous hangar interior with a compact shuttle parked near the center","use_case":"stylized-concept","size":"1536x1024"}
{"prompt":"Gray wolf in profile in a snowy forest","use_case":"photorealistic-natural","size":"1024x1024"}
EOF

python "$IMAGE_GEN" generate-batch \
  --input tmp/imagegen/prompts.jsonl \
  --out-dir output/imagegen/batch \
  --concurrency 5

适用场景与注意事项

比较适合：

  • 在 Codex 编码会话中同步产出网站/游戏/UI 位图素材
  • 需要参考图约束风格，或对现有位图做局部编辑
  • 预览阶段快速出图，再把选定结果落入仓库

需要注意：

  • 默认路径是内置工具；CLI 是显式回退，不要混用参数语义（例如 CLI 的 --quality、--mask、--input-fidelity 不是内置工具参数）。
  • 本地文件编辑：内置路径先 view_image；要路径级控制、mask 等再考虑 CLI。
  • 项目引用的最终文件必须进工作区，并回报最终路径、最终提示词以及用的是内置还是 CLI。
  • 迭代时一次只改一个点，并重复不变量，减少漂移。
  • 若目标是对齐现有 SVG/图标体系，应直接改矢量或代码，而不是强行生成位图。

小结

imagegen 把「在编码对话里要一张位图」收成可重复的 Skill：默认用内置 image_gen（无需 API Key），必要时再显式走 scripts/image_gen.py；配合结构化提示词与明确的保存规则，减少占位图与素材来回搬运。它解决的是光栅资产生产，而不是替代仓库里的矢量与代码原生视觉。

官方地址：

https://github.com/openai/skills/tree/main/skills/.system/imagegen

更完整的提示词原则与示例见同目录下的 references/prompting.md、references/sample-prompts.md；CLI 细节见 references/cli.md。

相关文章

实测 Z-Image：6B 参数的高效图像生成模型 2025-12-19 在 DeepSeek Harness 对话里直接生图：dsh-image-gen 插件上手 2026-08-25 dsh-codex-tools：为 DeepSeek Harness 增加 Codex 搜索、生图与识图工具 2026-08-30 Cursor 3 多 Agent 架构：Planner/Worker 分工最高降本 15 倍 2026-07-29 600 亿美元收购 Cursor：SpaceX/xAI 要重塑 AI 编程工具格局？ 2026-07-31
羽毛球分组比赛记分
小程序二维码

欢迎使用《羽毛球分组比赛记分》微信小程序

小夜