Codex 图像任务
通过运行器执行每个项目或批量图像任务。不要手动对这些任务调用 codex exec 或 codex-imagegen。
python scripts/codex_image.py "<提示文本或 @提示.txt>" out.png [--ref 参考.jpg] [--size 1536x1024] [--force]
该脚本会打印输出文件的绝对路径。给 Bash 调用的超时时间应高于运行器自身的 --timeout（默认 420 秒）。
| 退出码 | 含义 | 操作 |
|---|---|---|
| 0 | 已保存 | 查看图像 |
| 1 | 用法错误，例如输出文件已存在 | 修正调用；--force 可替换输出文件，但绝不会替换其自身的参考文件 |
| 2 | Codex 结束但未生成图像 | 阅读打印的输出，修复原因，然后重试一次 |
| 3 | 图像调用遗漏了参考，因此未保存任何内容 | 使用相同命令重试一次 |
| 124 | 未获取到会话或超时前无图像 | 检查 codex login status 和网络 |
规则
- 对照需求查看每个输出。 退出码 0 仅证明本会话生成了一张图像，并不代表图像正确。
- 链式编辑时一次只改动一个方面： 每个输出成为下一个
--ref。每一步都写入一个新文件。 - 保持场景： 指出哪些不应改变（相机、几何、开口），并在存在两个或更多参考时说明每个参考的角色。最多支持 4 个参考。
- 计算配额。 一次运行消耗一张图像配额，且多个运行可并行执行，但在大批量任务前应说明配额数，并先确保第一张图像正常。
- 带透明通道的 PNG 参考： 传递
--keep-png-refs，因为转换为 JPG 会压平透明通道。
为什么需要运行器
使用 codex-cli 0.164.0 于 2026-11-04 测量，基于 30 次图像运行的会话日志。
| 故障模式 | 原因 | 运行器采取的措施 |
|---|---|---|
| 挂起直至超时 | codex exec 等待打开的 stdin 管道：使用管道时 45 秒（被超时终止），关闭管道时 4 秒 | 通过 stdin 发送提示，然后关闭它 |
| 图像命名错误 | 被告知保存后，Codex 搜索共享的 ~/.codex/generated_images，取最新的并复制另一个运行的图片 | Codex 从不保存；运行器仅读取 generated_images/<其会话 ID>/ |
| 一次输出最多 7 次图像调用 | Codex 找不到保存方式，因此重新生成 | 在第一个完整图像时停止 Codex |
| 参考被忽略，房间被发明 | 图像工具仅在调用设置了 num_last_images_to_include 时才能看到附件 | 命名该参数，读取会话日志，如果遗漏则退出码 3 |
| 链式传递中丢失场景 | 每次家具传递输入的 PNG 都会丢失场景；使用 JPG 并命名参数可保留场景（相关关系，非确凿原因） | 当 ffmpeg 在 PATH 中时将 PNG 参考转换为 JPG |
同一天使用真实 CLI 验证：三次编辑，其中两次在 PNG 参考上并行执行，每次约 25 秒和一次图像调用，每项修改都保留了各自的颜色变化。
如果必须使用插件的 codex-imagegen
codex-bridge 1.2.0 存在以下故障。调用时请使用 </dev/null，每次一个任务，使用 JPG 参考，并在提示中加入“仅调用图像工具一次，且设置 num_last_images_to_include:1”，然后查看结果。