codex-image2-skill介绍与使用教程
引言：为什么需要这个工具
如果你经常使用 API 中转服务来驱动 Codex（OpenAI 的命令行编程助手），可能已经注意到一个问题：不少中转站已经把 gpt-image-2 从常规模型列表中移出。这导致 Codex 无法像以前那样自动发现并调用生图模型，原本"一句话生成配图"的流畅体验就此中断。
codex-image2-skill 正是为解决这一痛点而生的开源项目。它的思路非常直接：既然 Codex 发现不了模型，那就通过一个自定义 Skill，绕过模型列表，用自定义的 API 地址和密钥直接调用 OpenAI 兼容的图片接口，把生图能力"手动接回来"。
值得一提的是，该项目在近期（2026 年 7 月 15 日）完成了一次重要重构：用 Go 语言编写的原生可执行文件替换了原来的 Python CLI。这意味着普通用户不再需要安装 Python、Node.js、Go 或任何依赖，下载即用，开箱体验大幅改善。
项目简介
codex-image2-skill 是一个面向 Codex 的 Skill（技能插件），其核心原理可以概括为四步：
从环境变量读取用户配置的 API 地址（
CODEX_API_URL）和密钥（CODEX_API_KEY）；直接调用 OpenAI 兼容的图片生成接口（
/v1/images/generations）或编辑接口（/v1/images/edits）；将返回的图片保存到当前项目中；
让 Codex 检查图片质量并展示最终结果。
仓库内置了 Windows x64/ARM64 与 macOS Intel/Apple Silicon 四个平台的原生可执行文件，且源码只使用 Go 标准库，没有第三方依赖，构建产物干净轻量。
项目地址：https://github.com/fengfengzhidao/codex-image2-skill
作者：fengfengzhidao ｜ 开源协议：MIT
核心功能特性
在安全性设计上，该项目有几个值得肯定的细节：密钥只从环境变量读取、绝不要求用户在聊天中粘贴密钥；报错时不会暴露 Authorization 请求头；对于认证失败、参数校验等普通 4xx 错误不做无意义重试，避免放大问题。
详细使用教程
下面分四个层次介绍使用方法：快速安装 → 配置密钥 → 日常使用 → 高级 CLI 操作。
方式一：让 Codex 帮你安装（最简单）
直接把仓库地址发给 Codex，一句话即可：
请帮我安装这个 Skill：
https://github.com/fengfengzhidao/codex-image2-skill
配置一下环境变量
中转站URL：https://example.com/v1
中转站API：sk-shskfdofyh...方式二：手动安装
Windows（PowerShell）：
git clone https://github.com/fengfengzhidao/codex-image2-skill.git
Copy-Item codex-image2-skill\codex-image2 "$HOME\.codex\skills\codex-image2" -Recurse
macOS / Linux：
git clone https://github.com/fengfengzhidao/codex-image2-skill.git
cp -R codex-image2-skill/codex-image2 ~/.codex/skills/codex-image2
macOS 用户注意：如果可执行文件丢失执行权限，需要运行：
chmod +x codex-image2/bin/codex-image2-darwin-*
Skill 通过两个环境变量工作：
CODEX_API_URL：你的 API 服务地址（既可以填服务根地址，也可以填以/v1结尾的地址，Skill 会自动整理接口路径；未设置时默认为https://apinebula.com）CODEX_API_KEY：你的 API 密钥（必填）
Windows（PowerShell，永久写入当前用户环境变量）：
[Environment]::SetEnvironmentVariable("CODEX_API_URL", "你的API地址", "User")
[Environment]::SetEnvironmentVariable("CODEX_API_KEY", "你的API密钥", "User")
macOS / Linux（写入 shell 配置文件，如 ~/.zshrc 或 ~/.bashrc）：
export CODEX_API_URL="你的API地址"
export CODEX_API_KEY="你的API密钥"
重要提示：配置完成后，需要完全退出并重新启动 Codex。已经运行的 Codex 进程不会自动读取新的用户环境变量，这是"配置后仍提示没有 API Key"的最常见原因。
在 Codex 中指定 Skill 生图
重启 Codex 后，只需在请求中带上 /codex-image2 即可。
文生图示例：
使用 $codex-image2 生成一张图片：
一只戴着宇航员头盔的橘猫站在月球表面，远处可以看到地球，电影感灯光。
图片编辑示例：
使用 $codex-image2 修改这张图片：
只把背景替换成雪山，人物、服装、姿势和构图保持不变。
Skill 内部遵循一套规范的工作流：先判断任务是新建图片、编辑还是批量变体；然后按需整理提示词（保留详细提示词，只适度补全笼统提示词，不虚构品牌、人物或标语）；执行生成后逐张检查主体、构图、文字准确性和可见瑕疵；如需修改，每轮只调整一个目标方面，最后汇报输出路径、提示词、尺寸、质量和模型信息。
（可选）：CLI 高级用法
日常使用不需要手动执行 CLI，但以下命令适合调试或自动化场景。
1. 选择与你系统匹配的可执行文件：
2. 生成单张图片：
& "codex-image2/bin/codex-image2-windows-amd64.exe" generate `
--prompt "A tiny blue nebula inside a glass bottle" `
--size 1024x1024 `
--quality auto `
--out "output/imagegen/nebula.png"
常用参数：--prompt（长提示词可改用 --prompt-file）、--size（默认 1024x1024）、--quality（默认 auto）、--n（同一提示词生成多张变体）、--out（输出路径）、--dry-run（不发网络请求、仅校验参数）、--force（显式授权覆盖已有文件）。
3. 编辑图片：
& "codex-image2/bin/codex-image2-windows-amd64.exe" edit `
--image "input.png" `
--prompt "Replace only the background with a warm studio backdrop" `
--out "output/imagegen/edited.png"
重复传入 --image 可使用多张参考图；搭配 --mask mask.png 可进行局部编辑。注意：编辑结果始终写入新的输出路径，不要覆盖原图。
4. JSONL 批量生图：
先准备任务文件（每行一个 JSON 对象，支持 prompt、size、quality、n、out、model 字段）：
{"prompt":"A blue ceramic mug on white","out":"mug.png"}
{"prompt":"A red paper kite in a clear sky","size":"1536x1024","quality":"low","n":2,"out":"kite.png"}
然后执行批量命令：
& "codex-image2/bin/codex-image2-windows-amd64.exe" generate-batch `
--input "tmp/imagegen/jobs.jsonl" `
--out-dir "output/imagegen" `
--concurrency 2
批量命令会输出 JSON 格式的汇总结果，任一任务失败时以非零状态码退出，便于接入脚本化流水线。当 n 大于 1 时，CLI 会自动在扩展名前添加 -1、-2 等序号。
常见问题（FAQ）
Q1：配置后仍提示没有 API Key？
完全退出 Codex 再重新启动。已打开的进程不会读取新设置的用户环境变量。
Q2：接口返回 524 或超时？
通常表示中转服务的图片生成耗时超过了网关限制。可尝试降低质量（--quality low）、使用 1024x1024 尺寸、减少批量并发数，或稍后重试。
Q3：是否支持所有中转站？
中转服务需兼容 POST /v1/images/generations 和 POST /v1/images/edits 两个接口，并提供 gpt-image-2 模型。不同服务的参数支持和稳定性可能存在差异。
安全建议
不要把真实 API Key 提交到 GitHub 或任何公开仓库；
不要把 Key 写进 Skill 文件、提示词、截图或聊天消息；
建议为不同服务使用独立密钥，并定期轮换；
本 Skill 只从
CODEX_API_KEY环境变量读取密钥，不会主动保存密钥——也请使用者保持这一习惯。
总结
codex-image2-skill 是一个目标明确、实现干净的小工具：它用不到一个标准库 Go 程序的重量，解决了"中转站隐藏 gpt-image-2 后 Codex 无法生图"这一实际问题。零依赖的原生二进制、规范的安全实践（密钥脱敏、覆盖保护、有界重试）、完善的批量能力，使其既可以作为日常生图入口，也能嵌入自动化工作流。
参考资料：
Skill 详细说明：codex-image2/SKILL.md
批量任务格式：codex-image2/references/batch-format.md