导读
这份教程解决什么问题？
| 问题 | 解决方式 |
|---|---|
| Codex App 里想生成图片 | 安装 gpt-image skill，让 Codex 调用 gpt-image-2 |
| Codex CLI 想直接生图 | 使用 gpt-image 命令或 skill 里的 scripts/generate.py |
| 想参考已有图片再生成 | 使用 -i 传入参考图 |
| 想局部修补图片 | 使用 -i 加 -m 传入原图和 mask |
简单理解：Codex 负责理解你的需求和组织提示词，gpt-image skill 负责真正调用 gpt-image-2 生成图片。
1. 适用场景
适合：
- 让 Codex 帮你生成教程配图、流程图、海报草稿。
- 让 Codex 根据已有截图或参考图做风格延展。
- 在 Codex CLI 里批量生成图片素材。
- 给飞书文档、培训材料、产品说明补图。
不适合：
- 生成包含公司敏感信息的图片。
- 上传客户隐私、未公开产品图、内部商业数据。
- 把 API 密钥写进提示词或截图里。
2. 前置条件
使用前确认 3 件事：
- 已经能正常使用 Codex App 或 Codex CLI。
- 电脑上有 Python 3.11+。
- 有
uv或uvx，或者已经安装了gpt-imageCLI。
可以在终端里检查：
python3 --version
uv --version
uvx --version3. 安装 gpt-image skill
在 Codex 里推荐直接使用 $skill-installer 安装。
你可以在 Codex App 里输入类似下面的话：
$skill-installer 安装 https://github.com/wuyoscar/gpt_image_2_skill/tree/main/skills/gpt-image安装完成后，一般会放在：
~/.codex/skills/gpt-image安装后重启 Codex App，让新 skill 生效。
4. 配置 API 密钥
gpt-image CLI 会读取环境变量里的 OPENAI_API_KEY。
如果你使用公司 Coding Hub 分发的密钥，需要确保当前终端或运行环境里能读到这个变量。
macOS / Linux 示例（临时配置）：
export OPENAI_BASE_URL=https://coding-hub.yeelight.com/v1
export OPENAI_API_KEY="你的 Coding Hub API 密钥"如果需要永久配置，推荐你在 macOS 上这样配
如果你是 macOS，直接在终端执行：
cat >> ~/.zshrc <<'EOF'
# OpenAI / Coding Hub
export OPENAI_BASE_URL="https://coding-hub.yeelight.com/v1"
export OPENAI_API_KEY="你的 Coding Hub API 密钥"
EOF
source ~/.zshrc然后验证：
echo $OPENAI_BASE_URL
echo $OPENAI_API_KEYWindows PowerShell 示例：
[Environment]::SetEnvironmentVariable("OPENAI_BASE_URL", "https://coding-hub.yeelight.com/v1", "User")
[Environment]::SetEnvironmentVariable("OPENAI_API_KEY", "你的 Coding Hub API 密钥", "User")
[Environment]::GetEnvironmentVariable("OPENAI_BASE_URL", "User")
[Environment]::GetEnvironmentVariable("OPENAI_API_KEY", "User")*注意：Windows配置好后，你需要完全退出并重启Codex App, Windows直接关闭是不行的，需要在任务管理器里杀掉全部codex 服务；或者你可以重启电脑。*
5. 在 Codex App 里怎么用？
安装 skill 并重启 Codex App 后，你可以直接用自然语言让 Codex 画图。
提示词参考： youmind.com
示例：
请使用 gpt-image skill，生成一张 16:9 的 Yeelight 智能照明培训封面图，风格干净、科技感、适合放在飞书文档开头。也可以说得更具体：
用 gpt-image-2 生成一张中文信息图，主题是“AI 工具使用流程”，包含 4 个步骤：申请密钥、安装工具、配置模型、开始使用。要求中文清晰可读，横版。Codex 会根据 skill 规则：
- 判断是文本生图、参考图编辑，还是局部修补。
- 选择合适的尺寸和质量。
- 调用
gpt-image-2。 - 返回生成图片的本地路径。
6. 在 Codex CLI / 终端里怎么用？
如果系统里已经有 gpt-image 命令，可以直接这样生成：
gpt-image -p "一张现代智能家居海报，Yeelight 风格，干净高级，横版 16:9" -f output.png --size landscape --quality high如果没有全局 gpt-image 命令，也可以用 skill 自带脚本：
uv run ~/.codex/skills/gpt-image/scripts/generate.py \
-p "一张现代智能家居海报，Yeelight 风格，干净高级，横版 16:9" \
-f output.png \
--size landscape \
--quality high生成成功后，会输出图片文件路径。
7. 常用命令示例
7.1 文本生成图片
gpt-image -p "一张中文培训封面图，标题是 AI 工具入门，清爽科技风" -f cover.png --size landscape --quality high7.2 用参考图生成
gpt-image -p "参考这张图的构图，生成一张更适合教程首页的封面" -i reference.png -f cover-v2.png --size landscape --quality high7.3 多张参考图
gpt-image -p "结合这两张参考图的风格，生成一张统一风格的说明图" -i ref1.png -i ref2.png -f merged-style.png --size landscape --quality high7.4 局部修补
gpt-image -p "只把空白区域补成柔和的智能家居背景，其他部分保持不变" -i input.png -m mask.png -f fixed.png --quality highmask 是一张带透明区域的 PNG。通常透明区域表示需要修补的位置。
8. 常用参数怎么选？
| 参数 | 常用值 | 说明 |
|---|---|---|
--size | landscape | 横版配图、文档封面 |
--size | portrait | 竖版海报、小红书图 |
--size | square | 方图、头像、卡片 |
--quality | medium | 日常草稿 |
--quality | high | 最终配图、中文信息图、海报 |
-f | xxx.png | 指定输出文件 |
-i | ref.png | 传入参考图 |
-m | mask.png | 传入修补 mask |
9. 提示词怎么写更容易出好图？
建议按这个结构写：
用途 + 画面主题 + 风格 + 尺寸 + 必须出现的文字 + 不要出现什么示例：
生成一张飞书教程封面图，主题是“Codex 也能画图”，现代科技插画风，横版 16:9。
画面包含一个人在 Codex App 里输入需求，旁边生成一张图片预览。
必须清晰显示中文标题“Codex 也能画图”。
不要出现真实 API 密钥，不要出现真实公司内部信息。如果图片里有中文，记得明确说：
中文文字要清晰、准确、可读，不要乱码。10. 常见问题
1. Codex 说找不到 gpt-image skill
先确认是否安装在：
~/.codex/skills/gpt-image如果刚安装完，重启 Codex App。
2. 终端提示 OPENAI_API_KEY 缺失
说明当前终端没有读到 API 密钥。重新设置环境变量后再试。
3. 没有全局 gpt-image 命令
可以用：
uv run ~/.codex/skills/gpt-image/scripts/generate.py -p "画一张测试图" -f test.png4. 生成中文海报时文字不清楚
把提示词写得更明确：
中文大标题必须清晰可读，字体端正，文字不要乱码，不要错别字。同时建议使用：
--quality high5. 可以把密钥写到文档里吗？
不可以。密钥只放在本机环境变量或安全配置里，不要放到文档、截图、代码仓库、聊天记录里。
遇到问题可以直接点击当前文档右上角的飞书AI询问，也可参考如下常见问题。
交互式命令生成器
按飞书文档里的 CLI 用法填写参数。生成器会根据模式自动拼接文本生图、参考图编辑、多图参考和局部修补命令。