Codex Imagen

通过调用已存储在本地机器上的 OAuth 凭据，直接连接 ChatGPT/Codex 后端生成或编辑图像。该功能调用原生 Responses image_generation 工具，无需启动 codex app-server，无需 Codex CLI 二进制文件，也不需要 OPENAI_API_KEY。

快速开始

使用 Node 运行以确保 macOS、Linux 和 Windows 兼容性：

node {baseDir}/scripts/codex-imagen.mjs --timeout 300 'generate image follow this prompt, no refine: "a cinematic fantasy city at sunrise"'

常规生成模式每行输出一个生成的图像路径，诊断信息和进度输出到 stderr。

当调用方需要机器可读的元数据时，请使用 --json：

node {baseDir}/scripts/codex-imagen.mjs --json --timeout 300 --prompt 'generate a small blue lotus icon'

在提示中要求生成多个输出。本工具不提供 --count 参数：

node {baseDir}/scripts/codex-imagen.mjs --timeout 300 -o out/ --prompt 'generate 3 images of a monk mage'

使用 --verbose 或 --debug 获取事件级别的进度信息；使用 --quiet 仅输出 stdout 中的路径或 JSON 内容。

重试行为

默认情况下，助手会对临时性的空响应失败进行重试：网络错误、HTTP 5xx 响应、后端 server_error / 负载过重 / 不可用响应，以及在完整图像到达前中断或不完整的流。默认重试次数为 --retries 4，即总共尝试 5 次，与 Codex 的请求重试策略一致。

重试机制不会用于以下情况：使用错误、认证错误、策略或输入错误、速率限制、生成超时，或在图像已保存后。如果流式传输过程中已保存部分图像但随后超时，助手将返回已保存的路径，而不会重新发起生成。--timeout 值适用于每次生成尝试，因此启用重试时，外部 OpenClaw exec.timeout 必须为重试预留足够时间。

当外部调用者负责重试逻辑时，可使用 --no-retry 或 --retries 0。

超时单位

使用 --timeout <秒数> 用于面向代理的调用。此设置有意与 OpenClaw 的 exec 工具 timeout 值保持一致，单位均为秒。例如，5 分钟的 OpenClaw 调用应使用 --timeout 300。

--timeout-ms <毫秒数> 仍保留以保证兼容性，并用于亚秒级测试。请勿在表示 5 分钟时使用 --timeout-ms 300（这仅表示 0.3 秒）。同一命令中只能使用 --timeout、--timeout-seconds 或 --timeout-ms 之一。

生成耗时

图像生成可能较慢，尤其是当提示要求生成多张图像时。对于面向聊天的 OpenZalo/OpenClaw 调用：

• 普通单图请求建议使用 --timeout 300。
• 若提示要求生成 3 张图像，建议使用 --timeout 600，或在希望快速返回时改为请求 2 张图像。
• 若 3 图像请求在超时前已保存 1 或 2 张图像，助手将返回已保存的路径，并标记 timed_out: true；这是一种可用的部分成功，而非卡死。
• --timeout 值应用于每次生成尝试。若启用默认重试，应将外部 OpenClaw exec.timeout 设置得高于助手的超时预算，或通过 --retries 1 / --no-retry 减少重试次数。

认证发现

CLI 会读取现有的 OAuth JSON 文件，并向 https://chatgpt.com/backend-api/codex/responses 发送 Authorization: Bearer <access> 与 ChatGPT-Account-Id 头部。

可在不生成图像的情况下运行本地认证检查：

node {baseDir}/scripts/codex-imagen.mjs --smoke

认证查找顺序如下：

1. --auth
2. CODEX_IMAGEN_AUTH_JSON、OPENCLAW_CODEX_AUTH_JSON、CODEX_AUTH_JSON
3. OPENCLAW_AGENT_DIR/auth-profiles.json 或 PI_CODING_AGENT_DIR/auth-profiles.json
4. OPENCLAW_AGENT_DIR/auth.json 或 PI_CODING_AGENT_DIR/auth.json
5. ~/.openclaw/agents/main/agent/auth-profiles.json
6. ~/.openclaw/agents/main/agent/auth.json
7. ~/.openclaw/credentials/oauth.json
8. CODEX_HOME/auth.json
9. ~/.codex/auth.json

对于 OpenClaw，当前认证存储位置通常是：

~/.openclaw/agents/main/agent/auth-profiles.json

运行时不需要 Codex CLI。该技能可使用 OpenClaw 自身创建的 OAuth，例如 openclaw onboard --auth-choice openai-codex 或 openclaw models auth login --provider openai-codex。它仅需一个已存在的 openai-codex OAuth 配置文件，自身不会执行首次浏览器登录。

配置文件选择遵循 OpenClaw 优先原则：显式指定的 --auth-profile、CODEX_IMAGEN_AUTH_PROFILE / OPENCLAW_AUTH_PROFILE、OpenClaw 配置中的 auth.order.openai-codex 或已配置的 auth.profiles，然后是同级的 auth-state.json 中的 lastGood.openai-codex。如需指定特定 OpenClaw 配置文件，可使用 --auth-profile openai-codex:<id>。

输出路径

当调用方需要指定输出位置时，请使用 --out-dir 或 -o/--output：

node {baseDir}/scripts/codex-imagen.mjs --out-dir ./openclaw-images --prompt 'generate three UI icon variants'
node {baseDir}/scripts/codex-imagen.mjs -o out/ --prompt 'generate 3 images of a monk mage'

--output image.png 将精确写入该路径（仅限单图）。若收到多张图像，输出将按编号命名：image-1.png、image-2.png 等。若 --output 无扩展名或以 / 结尾，则视为目录。未设置 --out-dir 时，系统将自动选择首个可用位置：

1. CODEX_IMAGEN_OUT_DIR
2. OPENCLAW_OUTPUT_DIR
3. OPENCLAW_AGENT_DIR/artifacts/codex-imagen
4. OPENCLAW_STATE_DIR/artifacts/codex-imagen
5. ./codex-imagen-output

默认启用流式传输，并在每张图像到达后立即保存。若运行在部分结果后超时，已接收的图像将被保留并输出。面向聊天的 OpenClaw 调用建议使用 --timeout 300，除非用户明确要求更长运行时间；或使用 --no-stream 请求非流式响应。

参考图像

Skill: Codex Imagen

Version: 0.2.6

Chunk: 2/2

请显式附加参考图像。不要使用位置路径指定图像；位置参数仅用于提示文本。

node {baseDir}/scripts/codex-imagen.mjs --input-ref ref1.png --input-ref ref2.jpg --prompt '生成 3 张他在这个世界中直播的图像'
node {baseDir}/scripts/codex-imagen.mjs -i ref1.png -i ref2.jpg --prompt '将主角改为女性'
node {baseDir}/scripts/codex-imagen.mjs --image-url 'https://example.com/ref.png' --prompt '将此图像用作世界参考'

本地图像会被转换为 data:image/...;base64,... 格式，并作为 input_image 项发送。--input-ref 支持本地路径、http(s) URL 和 data:image/... URL。-i/--image 仅支持本地文件，--image-url 仅支持 URL 或 data-URL。支持的本地格式包括 PNG、JPEG、GIF 和 WebP。当模型需要接收更低或更高的图像细节时，请使用 --image-detail auto|low|high|original；默认值为 high。若不需要高保真像素细节，可使用较小尺寸的 JPEG 参考图像。

OAuth 刷新

CLI 通过 https://auth.openai.com/oauth/token 自动刷新过期或即将过期的 OAuth 令牌，并将更新后的令牌写回同一认证文件。默认的 OAuth 刷新偏移时间为 5 分钟，与 OpenClaw 的 OAuth 使用容差一致。对于 OpenClaw 的 auth-profiles.json，刷新过程采用 OpenClaw 兼容的跨代理 OAuth 刷新锁机制，先锁定认证存储，再重新读取并写入凭证。当当前代理/工作区的认证存储已过期时，还会从主 OpenClaw 代理存储中继承一个匹配的新配置文件，以避免多个 OpenClaw 或代理进程共享同一个 openai-codex 配置文件时出现 refresh_token_reused 竞态问题。

当自动发现认证信息且首个认证文件无法恢复时，CLI 会尝试下一个兼容的认证源，例如 CODEX_HOME/auth.json 或 ~/.codex/auth.json。显式指定的 --auth 路径不会被跳过。

如需控制行为，可使用以下选项：

node {baseDir}/scripts/codex-imagen.mjs --refresh-only --json
node {baseDir}/scripts/codex-imagen.mjs --force-refresh --smoke --json
node {baseDir}/scripts/codex-imagen.mjs --no-refresh --prompt '生成一张图像'

对于并发运行的 OpenClaw 进程，建议使用活跃 OpenClaw 代理的 auth-profiles.json，以确保所有调用方使用相同的配置文件身份。仅在调用方已自行管理 OAuth 刷新并希望此辅助工具直接使用提供的访问令牌时，才使用 --no-refresh。

--base-url 仅用于兼容的 Codex 后端，--refresh-url 仅用于兼容的 OAuth 刷新端点。

跨平台说明

该辅助工具基于纯 Node.js 22+，无原生依赖。它使用 os.homedir() 并结合环境变量覆盖，适用于 Windows、Linux 和 macOS。在 cmd.exe 中，单引号不是 shell 引号；应使用双引号，或把 UTF-8 文本写入文件后使用：

node {baseDir}/scripts/codex-imagen.mjs --prompt-file prompt.txt

当其他代理从不可预测的工作目录启动此脚本时，请使用 --cwd <path> 指定工作目录。