baoyu-image-gen 的 Codex CLI 图片生成方案用 Codex 订阅免 OpenAI API Key 完成图像生成【免费下载链接】baoyu-skills项目地址: https://gitcode.com/gh_mirrors/ba/baoyu-skills导读本文围绕 baoyu-image-gen 技能中的codex-cli图片生成 Provider 展开讲解如何在不持有OPENAI_API_KEY的情况下借助本机已登录的 Codex CLI 及其内置image_gen工具完成文生图、参考图与批量生成。读完本文你将掌握--provider codex-cli的完整调用链、参数映射规则、环境变量配置、错误模型与缓存机制并能在实际 Agent 工作流中准确选择与排障。codex-cli是 baoyu-image-gen 中一条特殊的本地封装路径它不是直接调用某个图片生成 API而是将 baoyu-image-gen 的标准 CLI 参数翻译给仓库自带的scripts/codex-imagegen/main.ts包装器其上游源码位于 packages/baoyu-codex-imagegen由包装器以codex exec --json --sandbox danger-full-access拉起本机 Codex CLI路由到 Codex 内置的image_gen工具。因此它走的是用户的Codex / ChatGPT 订阅权益全程不读取、不发送OPENAI_API_KEY。为什么需要这样一个 ProviderCodex 登录 ≠ OpenAI API Key在深入使用之前先理解它存在的根本原因。在 baoyu-image-gen 的 SKILL.md 中有明确警示--provider openai --model gpt-image-2走的是标准 OpenAI Images API/v1/images/generations或/v1/images/edits必须持有OPENAI_API_KEYCodex 或 ChatGPT 桌面客户端的登录态是另一种授权体系Codex OAuth并不是OPENAI_API_KEY的替代品。把 Codex OAuth Token 塞进OPENAI_API_KEY或者只把OPENAI_BASE_URL指向 Codex 后端都是不可行的做法。如果你的用户有 Codex 订阅、但明确不想管理 OpenAI API Key那么正确的路线是走 Codex 原生后端在 Codex 运行时中使用原生的 imagegen 技能/工具在非 Codex 运行时、但安装了codexCLI 且已登录的环境中使用baoyu-image-gen --provider codex-cli——这是首选方案因为它与其它 Provider 一样享受 baoyu-image-gen 的重试 / 缓存 / 批处理基础设施在具备原生image_generate工具的 Hermes 运行时中可回退到该工具。codex-cliProvider 拥有自己独立的鉴权codex login、路由codex exec、请求形态与测试不会也不应改动openaiProvider 去偷偷消费 Codex OAuth。更详细的论证可参见 references/codex-oauth-vs-openai-api-key.md。前置条件与安装要使用codex-cliProvider需要先准备本机环境npm install -g openai/codex codex login # 使用用户的 OpenAI / Codex 账号登录 codex --version # 确认版本 0.130另外需要说明的是底层包装器scripts/codex-imagegen/main.ts携带#!/usr/bin/env bun这一 shebang因此运行包装器必须要有bun。如果运行环境中没有bun可以用npx -y bun作为降级方案再不行可提示安装brew install oven-sh/bun/bun这是 SKILL.md 中BUN_X的解析顺序优先bun其次npx -y bun。选择机制永不自动选中只能显式指定这是codex-cli与其它 Provider 最关键的差异之一codex-cli永远不会被自动选中。在 SKILL.md 的 Provider Selection 一节中可以看到自动检测逻辑detectProvider只会在出现--ref参考图、显式--provider、或仅有一个可用 API Key 等场景下自动选择 Google / OpenAI / Azure / OpenRouter / DashScope / Z.AI / MiniMax / Replicate / Jimeng / Seedream / Agnes唯独codex-cli被排除在外。你必须显式地在命令行传--provider codex-cli或在 EXTEND.md 中设置default_provider: codex-cliEXTEND.md 的查找路径与 schema 见 references/config/first-time-setup.md 与 references/config/preferences-schema.md。这种设计是刻意的codex exec是一个沉重的单进程工作流且其鉴权依赖用户的交互式 Codex 登录态不适合在无感知的情况下被隐式触发。何时选择它用户拥有 Codex 订阅且明确不想管理 OpenAI API Key需要 Codex 特有的image_gen行为或质量。何时避免它对延迟敏感的场景——Codex CLI 通常比直接调用 OpenAI / Google API 慢 510 倍缓存命中时除外。最小可用示例在 baoyu-image-gen 的 SKILL.md 中给出了 Codex CLI 的最小调用示例bun {baseDir}/scripts/main.ts --prompt A cat --image out.png --provider codex-cli --ar 16:9{baseDir}即本技能 SKILL.md 所在目录主入口脚本为scripts/main.ts。这一行命令会依次完成参数校验 → 生成临时 prompt 文件 → 调用codex-cliProvider → 拉起scripts/codex-imagegen/main.ts→ 执行codex exec→ 校验输出 PNG → 返回字节流。参数映射baoyu-image-gen CLI 与包装器的对应关系codex-cliProvider 接收 baoyu-image-gen 的标准参数并映射为包装器的 CLI 参数。完整映射如下baoyu-image-gen 参数行为--prompt text/--promptfiles files必填。Provider 会把 prompt 写入临时文件再以--prompt-file传给包装器--image path必填。最终输出 PNG 的位置Provider 先写到临时目录成功后拷贝回目标路径--ar ratio映射为包装器的--aspect。Codex 支持1:1默认、16:9、9:16、4:3、2.35:1--ref files...映射为包装器的重复--ref。Codex 的image_gen接受参考图用于风格 / 构图引导--n必须为1。validateArgs在n 1时直接抛错因为 Codeximage_gen每次调用只返回一张图--imageApiDialect不适用。设置为非默认值非openai-native时抛错Codex 不走 OpenAI Images API 方言--size、--imageSize、--quality静默忽略——Codex 根据宽高比自行决定像素尺寸--model、-m仅作逻辑标签。包装器不会向 Codex 传递模型选择器底层引擎是 Codeximage_gen当前所用的模型。默认标签codex-image-gen参数校验的源码依据以上约束在 scripts/providers/codex-cli.ts 的validateArgs中实现并有对应的单元测试 scripts/providers/codex-cli.test.ts 覆盖getDefaultModel()返回codex-image-gengetDefaultOutputExtension()返回.pngCodex 只产出 PNGn 1抛错codex-cli provider supports only n1 (Codex image_gen returns a single image per call).imageApiDialect非openai-native抛错参考图--ref是允许的测试中明确验证了多参考图场景不抛错。这些测试同时证明了codex-cli是一个有独立契约的 Provider模型标签、输出扩展名、参数约束、参考图支持各有明确的语义。环境变量完整配置清单codex-cliProvider 的行为由一组BAOYU_CODEX_IMAGEGEN_*环境变量控制Provider 端和一批BAOYU_IMAGE_GEN_CODEX_CLI_*环境变量控制批处理端环境变量作用BAOYU_CODEX_IMAGEGEN_BIN覆盖包装器路径。默认是随技能分发的scripts/codex-imagegen/main.ts相对本技能安装位置解析。可接受.ts文件用bun拉起或遗留的.sh/ 二进制直接执行。若设置了不存在的路径Provider 会抛出Invalid BAOYU_CODEX_IMAGEGEN_BIN错误BAOYU_CODEX_IMAGEGEN_CACHE_DIR启用包装器的幂等缓存。默认关闭建议在高价值复用场景下设置为如~/.cache/baoyu-codex-imagegenBAOYU_CODEX_IMAGEGEN_TIMEOUT_MS单次codex exec的超时时间毫秒。默认3000005 分钟。网络慢或 prompt 很大时建议调高BAOYU_CODEX_IMAGEGEN_RETRIES包装器侧对可重试错误的尝试次数。默认2即总共最多 3 次尝试BAOYU_CODEX_IMAGEGEN_LOG_FILE追加写结构化 JSONL 诊断日志排障timeout或agent_refused时非常有用BAOYU_IMAGE_GEN_CODEX_CLI_CONCURRENCY批处理模式下codex-cli的并发度。默认1——codex exec是沉重的单进程工作流调高并发通常没有收益BAOYU_IMAGE_GEN_CODEX_CLI_START_INTERVAL_MS批处理模式下任务的最小启动间隔。默认2000msProvider 端如何消费这些变量在 scripts/providers/codex-cli.ts 的generateImage中可以看到明确的消费逻辑resolveWrapperPath()优先读取BAOYU_CODEX_IMAGEGEN_BIN校验存在性否则回退到随包分发的scripts/codex-imagegen/main.tsprompt 被写入tmpdir()/baoyu-image-gen-codex-cli/prompt-token.md输出先写到tmpdir()/baoyu-image-gen-codex-cli/out-token.png成功后再读回字节流finally中会清理这两个临时文件只有环境变量存在且为正整数时才会追加--timeout/--retriesparsePositiveInt--cache-dir与--log-file则要求非空字符串。底层工作原理包装器如何驱动 Codex 的 image_gen 工具codex-cliProvider 是薄封装真正的复杂逻辑在包装器 scripts/codex-imagegen/main.ts上游镜像为 packages/baoyu-codex-imagegen/src/main.ts。它的执行流程如下解析参数并做路径安全校验。parseArgs把所有文件系统路径统一解析为绝对路径使行为与调用方 cwd 无关然后用assertSafePath拒绝包含 shell 元字符;|$\n\r()等的--image/--ref路径。原因在源码注释中写明输出路径与参考图路径会被**原样插值**进发给codex exec --sandbox danger-full-access 的指令文本若路径含 shell 元字符Agent 的 shell 在拷贝结果时可能误读与其赌 Agent 会正确引号化不如提前拒绝。构造指令文本。buildInstruction生成一段完整的自然语言指令明确要求 Agent必须最先调用内部工具image_gen按给定 PROMPT 与 ASPECT RATIO 生成图片将$CODEX_HOME/generated_images/...下该次调用产出的图片仅移动/拷贝到指定输出路径用ls -la验证后仅回复一行 JSON{status:ok,path:...,bytes:size}并附上硬性约束不得复用历史图片、不得在调用image_gen前扫描generated_images目录、不得使用 curl/wget/Python 等外部 API、不得用 bash 伪造图片。执行codex exec。在 packages/baoyu-codex-imagegen/src/spawn.ts 中以spawn(codex, [...])拉起进程参数为exec --json --sandbox danger-full-access --skip-git-repo-check参考图通过重复--image传入指令通过 stdin 写入。--skip-git-repo-check的作用是允许包装器从非 git 目录运行如/tmp或安装于~/.claude/plugins/...的技能目录否则 Codex 会以 Not inside a trusted directory 拒绝执行。超时通过定时器实现到点先SIGTERM2 秒后再SIGKILL并抛timeout错误。解析事件流。parseEventStreamparser.ts逐行解析codex exec --json输出的 JSONL从中提取thread.started事件的thread_id、item.started/item.completed的工具调用shell、agent_message、image_gen等以及turn.completed的 token 用量。双重验证。这是本方案最精妙的部分之一。validator.ts 做了两层校验是否真的调用了 image_genCodex 的image_gen工具并不会作为流事件暴露因此真正的证据是该线程的$CODEX_HOME/generated_images/threadId/目录下出现了 PNG 文件verifyImageGenWasInvoked流内出现image_gen事件仅作为前向兼容的补充信号。这样设计可以精准拦截从历史图片中拷一张顶替的捷径——历史图片位于不同的 thread id 目录下两个信号都拿不到输出文件是否有效verifyOutput检查输出文件存在、大小不低于 1000 字节、且文件头 8 字节匹配 PNG 魔数89 50 4E 47 0D 0A 1A 0A。结果输出。无论成败包装器只在 stdout 输出一行 JSON。失败时形如{status:error,path:...,bytes:0,error:...,error_kind:...}成功时形如{status:ok,path:...,bytes:12345,elapsed_seconds:42,thread_id:...,attempts:1,cached:false}Provider 侧parseWrapperJson只取 stdout 最后一行做 JSON 解析容忍包装器此前可能有的日志输出并校验进程退出码与statusok的一致性。重试与幂等缓存在 main.ts 的generate中还有两个值得注意的机制重试内部按opts.retries 1次尝试循环对可重试错误按retryDelayMs * 2^(attempt-1)指数退避基值 1500ms等待后重试不可重试错误立即终止幂等缓存当设置--cache-dir时cache.ts 会以sha256(prompt|aspect|sorted(refs))的前 16 位十六进制为 keycacheKey命中后直接copyFile命中项到输出路径elapsed_seconds记 0、cached: true零延迟返回文件锁同一时刻只允许一个codex exec实例运行。锁文件位于$CACHE_DIR/codex-exec.lock未启用缓存时位于~/.cache/baoyu-codex-imagegen/codex-exec.lock通过openSync(lockPath, wx)原子创建带 60 秒获取超时与 10 分钟陈旧锁判定获取失败抛lock_busy。这正是为什么文档建议并发调用方设置各自独立的--cache-dir。错误模型error_kind 全表与处置建议codex-cliProvider 会把包装器的每个错误重新抛为Invalid codex-cli result (error_kind): message。这里的Invalid 前缀是有意为之的它会触发 baoyu-image-gen 外层重试循环中的isRetryableGenerationError将该错误标记为不可重试——因为包装器内部已经按BAOYU_CODEX_IMAGEGEN_RETRIES完成过重试main.ts 再重新拉起 Codex 只会成倍放大延迟而无助于结果。需要了解的error_kind取值Kind原因建议处置codex_not_installedcodex不在PATH中或不可读也可能代表会话过期npm install -g openai/codex然后codex logininvalid_args调用方式层面的编程错误检查 Provider 源码通常是路径注入守卫shell 元字符校验触发prompt_file_missing临时 prompt 文件在调用中途消失重试一次检查$TMPDIR权限spawn_failed操作系统 / 进程启动失败确认bun或npx已安装检查文件系统权限timeoutcodex exec超出--timeout调高BAOYU_CODEX_IMAGEGEN_TIMEOUT_MS检查网络no_image_gen_tool_useCodex Agent 回复了但没有调用image_gen多为偶发重试即可若持续出现则优化 promptoutput_missing/invalid_pngAgent 报告成功但文件缺失或不是有效 PNG重试检查磁盘空间agent_refusedCodex Agent 拒绝策略或内容调整 prompt把拒绝原因如实告知用户lock_busy另有codex-imagegen实例持有文件锁等待或为并发调用方设置不同的--cache-dir可重试的 error_kind 集合RETRYABLE定义在 packages/baoyu-codex-imagegen/src/types.tsspawn_failed、timeout、no_image_gen_tool_use、output_missing、invalid_png、agent_refused而codex_not_installed、invalid_args、prompt_file_missing、lock_busy等被明确标记为不可重试。批处理与并发为什么默认并发是 1当使用--batchfile batch.json --jobs N批量生成时codex-cli的并发行为由两个环境变量控制BAOYU_IMAGE_GEN_CODEX_CLI_CONCURRENCY默认1。文档明确说明Codex exec 是沉重的单进程工作流调高并发通常没有帮助。再加上包装器自身的文件锁机制同一时刻只会有一个codex exec在跑多个并发调用反而会互相撞锁lock_busyBAOYU_IMAGE_GEN_CODEX_CLI_START_INTERVAL_MS默认2000ms控制批处理任务的最小启动间隔。对于一次要生成多张图的场景更推荐的做法是先把 prompt 固化为文件用scripts/build-batch.ts从outline.md prompts/组装 batch 文件再统一提交从而复用共享的限流 / 重试 / 缓存机制参见 SKILL.md 的 Generation Mode 一节。权衡与注意事项使用codex-cliProvider 前应知晓以下特性慢相比直接调用 OpenAI / Google API延迟通常高 510 倍缓存命中除外不适合对延迟敏感的任务使用条款从 baoyu-image-gen 以编程方式调用与交互式codex exec属于同一使用类别需遵守相同服务条款有状态依赖codex login处于活跃状态会话过期时症状可能表现为codex_not_installed或agent_refused排障时不要只盯着 PATH 检查输出固定为 PNGProvider 的默认输出扩展名就是.png模型不可指定--model只是标签实际引擎跟随 Codeximage_gen当前使用的模型这意味着你无法像其它 Provider 那样锁定某个特定模型版本。总结与延伸阅读codex-cliProvider 用约百行 Provider 代码加上一个独立包装器把 Codex CLI 这一交互式工具完整纳入 baoyu-image-gen 的标准生成管线使无 OpenAI API Key 的 Codex 订阅用户也能享受统一的参数校验、参考图、缓存、重试与批处理体验。其核心价值在于鉴权复用Codex login、结果可验证双重重校验 PNG 魔数、错误可诊断结构化 error_kind JSONL 日志、成本可控制幂等缓存 文件锁。与本主题强相关的延伸文档references/codex-oauth-vs-openai-api-key.md深入解释为什么 Codex OAuth 不能与OPENAI_API_KEY混用references/codex-image2-fallback.mdopenaiProvider 因缺少凭据失败时何时回退到codex-clipackages/baoyu-codex-imagegen/README.md包装器作为独立命令行工具时的完整用法--prompt/--prompt-file/--aspect/--ref/--timeout/--retries/--retry-delay/--cache-dir/--log-fileskills/baoyu-image-gen/SKILL.mdbaoyu-image-gen 的总入口包含全部 Provider 的选型、参数与错误处理总览。【免费下载链接】baoyu-skills项目地址: https://gitcode.com/gh_mirrors/ba/baoyu-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考