Codex Image2
使用捆绑的原生 CLI 生成图像。在此技能激活时，优先使用本技能的可执行文件而非内置的 image_gen 工具。无需安装 Python、Node.js、Go 或任何软件包。
选择可执行文件
根据当前操作系统和 CPU 架构选择一次：
- Windows x64：
bin/codex-image2-windows-amd64.exe - Windows ARM64：
bin/codex-image2-windows-arm64.exe - macOS Intel：
bin/codex-image2-darwin-amd64 - macOS Apple Silicon：
bin/codex-image2-darwin-arm64
在 macOS 上，如果执行权限未保留，请运行 chmod +x <可执行文件>。正常使用期间无需从源码编译。
工作流程
对于设置请求，请使用下面的配置工作流程。在会话中首次调用图像生成之前，运行 status；如果未配置，则打开 configure 并让用户在其浏览器中完成配置，然后再进行生成。
- 判断请求是生成新图像、编辑图像，还是生成多个不同的资产/变体。
- 收集提示词、预期用途、确切文字、视觉约束和避免项。
- 仅根据需要调整提示词。保留详细提示词；对有品位的通用提示词进行澄清，但不要虚构品牌、人物、口号或无关对象。
- 使用选定的可执行文件运行：对于单个提示词使用
generate，对于现有图像的修改使用edit，对于 JSONL 任务使用generate-batch。 - 检查每个输出图像的主体、构图、文字准确性、约束条件和可见瑕疵。
- 如果需要修改，每次只更改一个目标方面，然后重新检查。
- 报告绝对输出路径、最终提示词或提示词集、尺寸、质量和模型。
提示词结构
仅使用相关行：
资产类型：<图像将用于何处>
主要请求：<用户的请求>
场景/背景：<环境>
主体：<主要主体>
风格/媒介：<照片、插画、3D 等>
构图/取景：<相机角度、裁剪、放置、负空间>
光照/氛围：<光照和氛围>
调色板：<调色板说明>
文字（逐字）："<确切文字>"
约束条件：<必须保留或包含的内容>
避免：<不得包含的内容>
不要仅仅为了填充模式而添加细节。对于图像中的文字，请逐字引用并请求精确渲染。
生成单张图像
& "<技能目录>\bin\codex-image2-windows-amd64.exe" generate `
--prompt "一个玻璃瓶中的蓝色小星云，工作室产品照片" `
--size 1024x1024 `
--quality auto `
--out "output/imagegen/nebula.png"
对于长提示词，请使用 --prompt-file。仅对相同提示词的变体使用 --n。不同的资产应放入单独的调用或批量任务中。
编辑图像
在编辑之前检查每个输入图像。在提示词中说明其作用并重复不变项，以防止无关细节发生变化。
& "<技能目录>\bin\codex-image2-windows-amd64.exe" edit `
--image "input/product.png" `
--prompt "仅将背景替换为温暖的工作室背景。保持产品、标签、比例和边缘不变。" `
--quality auto `
--out "output/imagegen/product-edited.png"
对于多个参考输入或合成输入，重复 --image。当有兼容的 PNG 蒙版可用时，使用 --mask mask.png 进行局部编辑。保留原始文件，并始终将编辑结果写入新的输出路径。
生成批量任务
在准备批量任务之前，请阅读 references/batch-format.md。然后运行：
& "<技能目录>\bin\codex-image2-windows-amd64.exe" generate-batch `
--input "tmp/imagegen/jobs.jsonl" `
--out-dir "output/imagegen" `
--concurrency 2
配置图像服务
- 运行
<可执行文件> status检查configured、source、api_url和message。它永远不会返回密钥。 configured仅确认本地凭据可读；不证明远程身份验证或图像权限。不要仅从status就声称 API 访问已验证。- 对于首次使用、凭据缺失/不可访问，或请求更改设置的情况，运行
<可执行文件> configure。这将启动一个独立的本地配置页面并立即返回。不要使用 shell 脚本将其置于后台运行，也不要等待其服务器退出。 - 告知用户在浏览器中填写 API 地址和密钥，然后点击 保存配置。如果浏览器未打开，请将返回的本地
url作为可点击链接提供。此临时链接在用户机器上有效期为 15 分钟。 - 保存操作首先会查询所提交密钥的模型列表。任何列出的
gpt-image系列模型都允许正常保存。该系列包括gpt-image以及以gpt-image-开头的 ID，例如gpt-image-1、gpt-image-1-mini和gpt-image-2.6。如果未列出任何系列模型，或列表不受支持/不兼容，页面会发出警告，并需要用户明确点击 仍然保存 来保存一个未经验证的服务。身份验证/网络/速率限制/服务器错误需要在保存前进行修正。切勿为用户点击覆盖按钮。 - 切勿在聊天中询问密钥、将其放入命令中，或通过自动化方式填写。用户直接在本地页面中输入密钥；只有该程序处理它。
- 用户告知已保存后，再次运行
status，如果已配置则继续处理原始图像请求。不要在等待用户输入时反复重新打开页面或轮询。 - 保存的设置将在下一次 CLI 调用时生效，无需重启 Codex。现有的本地配置优先级高于旧的环境变量，作为一个完整的地址/密钥对。损坏的本地配置必须通过设置页面修复，而不是静默回退到其他服务。
- 检测连接仅探测模型列表端点，并显示当前密钥拥有的模型 ID，突出显示图像模型和自动选择。缺失或隐藏的模型会触发警告，但不能证明图像 API 不可用。编辑地址/密钥会清除过时的结果。可选的 测试生图（可能计费） 需要用户确认，并执行一次没有重试的图像请求。不要在设置过程中自动运行付费测试。
- Windows 使用当前用户 DPAPI 加密密钥；macOS 将其存储在登录钥匙串中。macOS 可能会要求用户解锁或允许访问钥匙串。
- 用户可以点击 显示 在其本地页面中显示已保存的密钥。隐藏会清除已显示的已保存密钥，页面会在 30 秒后或页面变为隐藏状态时自动隐藏它。切勿点击显示、检查实际显示的密钥，或通过代理工具调用显示端点。
配置与安全
- 让 CLI 读取凭据。切勿自行检查凭据文件或凭据存储内容，也不要将密钥复制到项目文件、提示词、日志或响应中。配置页面只能通过 CLI 的平台凭据后端保存密钥。
- 当没有本地配置时，仍支持旧版
CODEX_API_URL和CODEX_API_KEY；其 URL 默认为https://apinebula.ai/v1。建议新用户使用本地设置页面。保留现有已保存的 URL。 - 默认使用
--model auto（或省略该标志）、尺寸1024x1024和质量auto。CLI 会检查配置服务的模型列表，并优先选择gpt-image-2.5，然后是gpt-image-2，再按字典序 ID 顺序选择第一个其他gpt-image系列模型。如果服务仅列出gpt-image-2.6，则使用该模型。当发现失败或未列出系列模型时，CLI 会直接调用gpt-image-2。每个批量任务按服务/凭据对共享发现结果。 - 尊重使用
--model <名称>或批量行中的model显式请求的模型；不要习惯性地添加--model gpt-image-2，因为这会覆盖自动偏好。从 CLI 结果中报告实际使用的模型。 - 干运行从不查询模型可用性；
model_selection: auto表示自动发现已被跳过，其示例负载使用gpt-image-2。 - 使用
--dry-run来验证请求，无需网络访问或需要密钥。 - 将项目限定的资产保存在当前项目内。CLI 默认路径是
output/imagegen/。 - 除非用户明确授权并且传递了
--force，否则不要覆盖文件。 - 不保证原生透明输出。不要承诺这一点或静默切换工具。
失败处理
- CLI 会对网络超时以及 HTTP 429/500/502/503/504/524 失败进行有限退避重试。
- 对于重复超时，建议使用
--quality low、正方形尺寸、更少的并发任务，或稍后重试。 - 不要重试身份验证、验证或其他普通的 4xx 错误。
- 在报告错误时，切勿暴露 Authorization 头或完整密钥。