codex-imagen：复用本地凭证，无缝集成OpenClaw的AI图像生成工具

1. 项目概述与核心思路拆解

最近在折腾一个挺有意思的项目，叫codex-imagen。简单来说，这是一个命令行工具，它能让你绕过官方的 OpenAI API，直接利用你本地已经登录的 ChatGPT/Codex 账户来生成或编辑图片。这听起来可能有点“野路子”，但对于那些已经在使用 OpenClaw 这类 AI 代理框架，或者本地装有 Codex 桌面客户端的开发者来说，它提供了一个非常直接、无需额外配置 API Key 的图片生成通道。

这个工具的核心价值在于“复用现有凭证”。很多深度 AI 用户可能已经在本地通过 OAuth 方式登录了 ChatGPT 或 Codex，codex-imagen就是去读取这些现成的认证信息（比如~/.codex/auth.json或 OpenClaw 的auth-profiles.json），然后直接调用后端服务的image_generation工具。这意味着你不需要去申请、付费和管理独立的OPENAI_API_KEY，也无需启动笨重的codex app-server二进制程序。整个过程更轻量，更像是直接与后端服务“对话”。

我之所以对这个项目感兴趣，是因为在实际的 AI 工作流自动化中，经常需要将文本生成、代码执行和图像生成串联起来。如果每一步都需要不同的认证方式和 API 端点，整个流程就会变得支离破碎。codex-imagen通过统一认证源（即你已经在用的那个 ChatGPT/Codex 账户），让图片生成可以无缝嵌入到现有的自动化脚本或 OpenClaw Skill 中，大大提升了工作流的连贯性。

2. 环境准备与认证机制深度解析

2.1 基础运行环境搭建

要让codex-imagen跑起来，门槛其实很低。首先，你需要一个 Node.js 22 或更高版本的环境。我建议直接使用 Node 官方提供的版本管理工具nvm来安装和管理版本，这样可以避免系统全局 Node 版本冲突的问题。

# 使用 nvm 安装并切换到 Node.js 22 nvm install 22 nvm use 22

接下来，获取项目代码。通常你需要将darkamenosa/codex-imagen这个仓库克隆到本地。

git clone https://github.com/darkamenosa/codex-imagen.git cd codex-imagen

项目本身是纯 JavaScript/ES Module 的，没有复杂的构建步骤，所以不需要运行npm install（实际上项目里可能连package.json都没有）。核心功能都集中在scripts/codex-imagen.mjs这一个文件里。这种设计非常“Unix 哲学”，一个脚本搞定一件事，依赖极少，部署和运行都极其简单。

2.2 认证源查找逻辑与优先级

这是整个工具最核心也最容易出问题的部分。codex-imagen支持多种认证存储位置，它会按照一个明确的优先级顺序去查找你的 OAuth 凭证。理解这个顺序，对于排查“为什么它说找不到认证”这类问题至关重要。

工具的认证查找优先级从高到低依次是：

1. 显式指定 (--auth): 通过命令行参数--auth /path/to/your/auth.json直接告诉工具认证文件在哪。这是最直接、优先级最高的方式。
2. 环境变量: 工具会检查一系列环境变量，包括CODEX_IMAGEN_AUTH_JSON、OPENCLAW_CODEX_AUTH_JSON、CODEX_AUTH_JSON。如果你在 OpenClaw 等自动化环境中使用，通过环境变量传递路径是最佳实践。
3. OpenClaw Agent 目录: 工具会尝试在 OpenClaw 的 Agent 工作目录下寻找auth-profiles.json或auth.json文件。具体路径由OPENCLAW_AGENT_DIR或PI_CODING_AGENT_DIR环境变量决定。
4. OpenClaw 默认路径: 如果上述没找到，会回退到 OpenClaw 的默认全局存储路径，即~/.openclaw/agents/main/agent/下的认证文件。
5. OpenClaw 旧版 OAuth 存储: 检查~/.openclaw/credentials/oauth.json。
6. Codex 环境变量路径: 检查CODEX_HOME环境变量指向的目录下的auth.json。
7. Codex CLI/Desktop 默认路径: 最后，回退到 Codex 桌面客户端或 CLI 的默认认证存储位置~/.codex/auth.json。

实操心得：如何快速确定当前有效的认证源？在真正开始生成图片前，强烈建议先使用--smoke参数进行一次“烟雾测试”。这个命令不会真的去调用生成接口，而是会执行完整的认证查找流程，并打印出它最终使用的是哪个认证文件、对应的账户邮箱（会脱敏处理）以及令牌的有效期等信息。这能帮你快速确认工具是否找到了正确的凭证，避免在生成时才发现认证失败。

node scripts/codex-imagen.mjs --smoke

2.3 OpenClaw Profile 选择策略

如果你的认证源是 OpenClaw 的auth-profiles.json（这是一个可以管理多个不同服务商、多个账户的配置文件），那么工具还需要决定使用哪一个具体的 Profile。其选择策略同样有优先级：

1. 命令行指定 (--auth-profile): 例如--auth-profile openai-codex:[e-mail]。
2. 环境变量:CODEX_IMAGEN_AUTH_PROFILE或OPENCLAW_AUTH_PROFILE。
3. OpenClaw 配置: 读取 OpenClaw 的配置文件，看auth.order.openai-codex指定了哪个 Profile，或者auth.profiles中为openai-codex服务商配置的默认项。
4. 上次成功记录: 查找同目录下的auth-state.json文件，使用其中lastGood.openai-codex记录的 Profile ID。
5. 智能回退: 如果以上都未指定，工具会从所有可用的openai-codex类型 Profile 中，优先选择名为openai-codex:default的，然后选择过期时间最晚的，最后再根据邮箱和账户 ID 进行排序，选出一个“最佳”的 Profile 使用。

这个设计非常贴心，它意味着在大多数 OpenClaw 环境中，你不需要额外配置，工具就能自动找到并使用那个最近登录过、且有效期最长的 ChatGPT/Codex 账户。

3. 核心功能使用详解与参数剖析

3.1 基础图片生成命令

一切就绪后，生成图片的命令非常简单。最基本的用法就是提供一个描述性的提示词（Prompt）。

node scripts/codex-imagen.mjs "a serene landscape with mountains and a lake"

默认情况下，这会使用gpt-5.4模型（具体可用模型取决于你的账户权限），生成一张图片，并以一个包含时间戳和唯一 ID 的自动生成文件名保存在默认输出目录下。生成过程中，进度信息会输出到标准错误流（stderr），而成功保存的图片文件路径则会打印到标准输出流（stdout），每行一个路径。这种设计非常利于在脚本中捕获输出结果。

如果你想生成多张图片，不需要使用--count这样的参数（工具本身没有这个参数）。正确的方式是在提示词中直接“要求”生成多张。后端的图像生成模型在理解自然语言指令方面非常强大。

node scripts/codex-imagen.mjs "generate 3 distinct concept arts of a cyberpunk samurai"

3.2 关键命令行参数解析

codex-imagen提供了丰富的参数来满足不同场景的需求，下面我挑几个最常用和最重要的进行深度解析。

1. 输出控制 (-o, --output,--out-dir,--json)

• -o, --output <path>: 这是最灵活的输出控制参数。
  • 如果只生成一张图，并且路径以.png结尾，它会直接使用你指定的完整路径和文件名。例如-o ./my-artwork.png。
  • 如果生成多张图，但指定了一个像image.png这样的具体文件名，工具会自动将其转换为image-1.png,image-2.png这样的序列。这个行为很实用，避免了文件名冲突。
  • 如果指定的是一个目录（以/结尾或路径不存在且看起来像目录），工具会在该目录下使用自动生成的文件名。
• --out-dir <path>: 明确指定一个输出目录，工具一定会使用自动生成的文件名。当你只想控制输出位置，不关心具体文件名时，用这个更清晰。
• --json: 这个参数改变了整个工具的输出行为。启用后，所有输出（包括错误信息）都会以 JSON 格式打印到 stdout。这对于将工具集成到其他程序（如 Python 脚本、OpenClaw Skill）中至关重要。JSON 里包含了请求 ID、会话 ID、生成的图片数量、每张图片的保存路径、SHA256 校验和、修订后的提示词等完整元数据。

2. 运行时控制 (--timeout,--retries,--no-stream)

• --timeout <seconds>:这是集成到自动化工作流中最重要的参数之一。它设置了单次生成尝试的超时时间（单位：秒）。默认值是 900 秒（15分钟），但当工具检测到运行在 OpenClaw 环境中时，会自动调整为 300 秒（5分钟），以匹配 OpenClawexec工具的默认超时单位。务必根据你的提示词复杂度和预期生成数量来合理设置此值。一个简单的图标生成可能只需要 30 秒，而一个要求生成 4 张高细节场景图的复杂提示可能需要 600 秒以上。
• --retries <count>: 网络请求难免失败。这个参数控制对“瞬态故障”的重试次数，例如网络错误、HTTP 5xx 服务器错误、后端返回server_error或overloaded等。默认重试 4 次，加上首次请求，总共是 5 次尝试，这与 Codex 后端自身的重试策略保持一致。注意：一旦流式响应开始并成功保存了哪怕一张图片，重试就会被禁用，这是为了防止在部分成功的情况下重复生成。
• --no-stream: 默认情况下，工具使用流式响应（streaming），图片数据是一块一块传回来的，每收到一张完整的图片就立刻保存到磁盘。使用--no-stream会改为请求非流式响应，后端会一次性返回所有图片数据。在绝大多数情况下，保持默认的流式模式即可，这样即使超时或中断，已经传回的图片也能被保存下来。

3. 认证与调试参数 (--force-refresh,--verbose,--quiet)

• --force-refresh: 强制在生成前刷新 OAuth 访问令牌，即使当前令牌尚未过期。这在令牌临近过期或者你怀疑当前令牌有问题时使用。
• --verbose/--debug: 打印详细的请求进度和原始事件名称到 stderr。当生成失败，你需要排查是网络问题、认证问题还是后端问题时，首先应该加上这个参数运行一次。
• --quiet: 与--verbose相反，它禁止所有进度和诊断信息输出到 stderr，只保留最终的图片路径或 JSON 输出到 stdout。在安静的批处理脚本中使用。

3.3 使用参考图进行图像编辑

codex-imagen不仅支持文生图，也支持图生图（编辑）。你可以通过多种方式附加参考图片。

• -i, --image <path>: 附加本地图片文件。可以重复使用该参数，也可以用逗号分隔多个路径。
• --input-ref <path|url>: 功能更强大的参数，支持本地路径、HTTP/HTTPS 图片 URL，甚至是内联的data:image/...Base64 URL。
• --image-url <url>: 专门用于附加一个网络图片 URL。

一个典型的图像编辑命令如下：

node scripts/codex-imagen.mjs -i original_photo.jpg --prompt "make it look like a vintage oil painting"

当你附加了参考图后，还可以通过--image-detail参数来控制后端处理参考图时的细节程度。可选值有auto,low,high,original，默认是high。设置为low可以降低传输和处理的负载，适合当参考图仅用于提供大致构图和色彩，而不需要精确细节时。

注意事项：参考图的大小与格式本地图片会被工具自动编码为 Base64 字符串并嵌入请求中。如果图片很大（比如超过 5MB），工具会在控制台给出警告。虽然后端可能支持，但过大的图片会导致请求缓慢甚至失败。对于编辑任务，通常不需要原图尺寸的全分辨率，建议先将参考图缩放或裁剪到一个合理的尺寸（例如 1024x1024 像素），并以 JPEG 格式保存来减小体积。支持的本地图片格式包括 PNG, JPEG, GIF, WebP。

4. 集成到 OpenClaw Skill 的实战指南

4.1 Skill 目录结构与配置

将codex-imagen作为 OpenClaw 的一个 Skill 来使用，能最大化其价值。集成方式非常直观。

首先，在你的 OpenClaw 技能目录（例如~/openclaw/skills/）下，为codex-imagen创建一个子目录，并将项目文件放进去。一个最小化的 Skill 结构如下：

codex-imagen/ ├── SKILL.md # 技能说明文档（可选，但推荐） └── scripts/ └── codex-imagen.mjs # 核心脚本

SKILL.md里可以简单描述这个技能的功能和调用示例，方便团队其他成员使用。核心就是那个codex-imagen.mjs脚本。

4.2 在 OpenClaw 任务中调用

在 OpenClaw 的 Agent 配置或任务计划中，你可以通过exec工具来调用这个脚本。一个关键点是工作目录（cwd）和超时控制。

由于 OpenClaw Agent 可能在任意目录下运行，直接使用相对路径./scripts/codex-imagen.mjs可能会找不到文件。更可靠的做法是使用{baseDir}这个 OpenClaw 提供的变量，它指向当前技能所在的根目录。

# 在 OpenClaw 任务配置中的一个示例步骤 - uses: exec with: command: node args: - "{baseDir}/scripts/codex-imagen.mjs" - "--json" - "--timeout" - "300" - "--prompt" - "generate an icon for a database management app, minimalist style" cwd: "{baseDir}" # 确保脚本在执行时，其相对路径（如读取本地文件）是相对于技能目录的

参数设置要点：

1. --json: 在自动化中必加。这样你的 OpenClaw Agent 可以轻松地解析 JSON 输出，提取图片路径，并将这个路径用于后续步骤（比如上传到某个地方，或者插入到报告里）。
2. --timeout 300: 如前所述，这匹配了 OpenClawexec工具默认的 5 分钟超时单位。对于生成单张图片，5分钟通常足够。如果你在提示词中要求生成多张（例如“generate 4 images...”），则需要根据经验调大这个值，或者改用--timeout-ms指定毫秒数。
3. --cwd: 显式设置工作目录是一个好习惯，能避免因当前工作目录不同而导致的路径解析问题。

4.3 处理超时与部分成功

在自动化流程中，超时是需要妥善处理的边界情况。codex-imagen对此有明确的设计：

• 如果超时发生在任何一张图片被成功保存之前，工具会以退出码124结束。
• 如果超时发生在流式传输过程中，且已成功保存了至少一张图片，工具会以退出码0（成功）结束，并在输出（或 JSON）中包含已保存图片的路径，同时设置"timed_out": true标志。

这个设计非常合理。在 OpenClaw 中，你可以检查退出码和 JSON 输出中的timed_out字段来决定后续动作。例如，即使超时，只要拿到了至少一张图片，整个任务可能仍被视为部分成功，继续执行后续步骤（如处理已生成的图片），而不是完全失败。

{ "request_id": "req_abc123...", "image_count": 2, "timed_out": true, "images": [ {"path": "/tmp/codex-imagen-123456-1-a1b2c3.png", "status": "saved"}, {"path": "/tmp/codex-imagen-123456-2-d4e5f6.png", "status": "saved"} // 提示词要求生成4张，但超时前只收到了2张 ] }

4.4 认证在 OpenClaw 环境下的无缝继承

这是集成中最优雅的部分。OpenClaw Agent 在运行时，通常已经通过openclaw onboard或openclaw models auth login命令完成了openai-codex的 OAuth 登录，并将凭证保存在其 Agent 工作目录的auth-profiles.json中。

codex-imagen能够自动发现并使用这个凭证。它不仅仅读取文件，还继承了 OpenClaw 的 OAuth 刷新锁机制。当多个 Agent 或进程可能同时使用同一个刷新令牌（refresh token）时，该机制能防止出现refresh_token_reused错误。这意味着你可以安全地在并行的 OpenClaw 任务中调用codex-imagen，而不用担心认证冲突。

5. 高级技巧、故障排查与跨平台注意事项

5.1 OAuth 令牌刷新机制详解

工具内置了 OAuth 令牌刷新逻辑，以确保凭证长期有效。其刷新策略如下：

1. 主动刷新（Proactive Refresh）: 在每次执行生成任务前，工具会检查访问令牌（access token）的过期时间。如果令牌将在未来5分钟内过期（这个“5分钟”是 OpenClaw 定义的可用性边界），工具会主动调用 OpenAI 的 OAuth 刷新端点获取新令牌，并写回原认证文件。
2. 被动刷新（Reactive Refresh）: 如果请求因令牌过期被后端返回 401 错误，工具也会自动尝试刷新令牌并重试请求（除非使用了--no-refresh参数）。
3. 刷新专用命令: 你可以使用--refresh-only参数来手动刷新令牌而不进行生成，或者结合--smoke --json来查看刷新后的令牌信息。

实操心得：何时使用--no-refresh？这个参数应该谨慎使用。仅当调用codex-imagen的上层程序（例如一个自定义的守护进程）已经统一管理并刷新了 OAuth 令牌时，才需要使用--no-refresh来禁用工具自身的刷新逻辑，避免重复刷新和潜在的竞争条件。在绝大多数独立运行或作为 OpenClaw Skill 运行的场景下，不要使用--no-refresh，让工具自己管理令牌是最省心的。

5.2 常见问题与排查清单

即使工具设计得再完善，在实际使用中还是会遇到各种问题。下面是我总结的一个排查清单：

问题现象	可能原因	排查步骤与解决方案
报错No usable OAuth credentials found	1. 从未在本地登录过 Codex/ChatGPT。 2. 认证文件不在工具查找的路径中。 3. 认证文件格式错误或已损坏。	1. 运行--smoke查看工具最终查找了哪些路径，确认是否有有效文件。 2. 确保你已通过 Codex Desktop、CLI 或openclaw onboard成功完成 OAuth 登录。 3. 使用--auth参数显式指定一个已知正确的auth.json文件路径。
生成失败，HTTP 错误 401/403	1. OAuth 令牌已过期且刷新失败。 2. 账户没有图片生成权限。 3. 认证文件对应的是错误账户。	1. 使用--force-refresh --smoke --json尝试强制刷新并查看结果。 2. 确认你使用的 ChatGPT/Codex 账户订阅是否包含图像生成功能。 3. 检查--smoke输出的脱敏邮箱是否是你预期的账户。
命令执行后长时间无输出，最后超时	1. 提示词过于复杂或要求生成图片太多，后端处理超时。 2. 网络连接问题。 3. 后端服务临时过载。	1. 首先使用一个非常简单的提示词（如“a red circle”）和较短的--timeout 30测试连通性。 2. 添加--verbose参数查看请求是否已发出、是否收到响应事件。 3. 逐步增加--timeout值，或简化提示词、减少要求生成的图片数量。
生成的图片数量少于提示词要求	1. 请求超时，只收到了部分图片。 2. 后端模型未能完全理解“生成N张”的指令。	1. 检查 JSON 输出中的"timed_out"字段和"image_count"。 2. 在提示词中更明确地强调数量，例如“Generate EXACTLY 3 images of...”。对于重要任务，可以先生成一张，确认效果后再用循环脚本生成多张。
在 Windows 上运行，提示词解析错误	在cmd.exe中，单引号不是有效的引号字符。	1. 在cmd.exe中，对提示词使用双引号：--prompt "a cat"。 2. 或将提示词写入文件，使用--prompt-file prompt.txt。 3. 推荐在 PowerShell 中运行，它支持单引号字符串。

5.3 跨平台兼容性说明

codex-imagen使用纯 Node.js 编写，核心文件系统路径操作使用path模块，用户目录获取使用os.homedir()，环境变量读取使用process.env。这些 API 都是跨平台的，因此理论上在 macOS、Linux 和 Windows 上都能运行。

主要的差异在于 shell 环境：

• Linux/macOS (Bash/Zsh): 可以直接使用单引号或双引号包裹提示词。
• Windows CMD: 必须使用双引号来包裹参数，因为 CMD 不将单引号视为字符串界定符。
• Windows PowerShell: 行为与 Bash 类似，支持单引号字符串。但对于包含特殊字符（如$,`,"）的复杂提示词，使用--prompt-file从文件读取是最安全、最可靠的方式，可以避免所有 shell 转义问题。

5.4 性能与稳定性优化建议

1. 合理设置超时: 不要一味使用默认的 900 秒。根据任务复杂度设置一个合理的超时。在 OpenClaw 中，结合外层exec的超时，可以设置一个稍短于外层超时的值，让codex-imagen能更早地报告超时并输出部分结果。
2. 利用重试机制: 默认的--retries 4对于应对临时的网络抖动或后端高负载很有帮助。除非你在一个要求极低延迟且失败后立即有备用方案的场景，否则不要禁用重试。
3. 流式传输的优势: 坚持使用默认的流式模式。它提供了更快的首张图片到达时间，并且在超时或中断时能保留已生成的部分结果，提高了任务的鲁棒性。
4. 输出目录管理: 对于长期运行的自动化任务，建议通过--out-dir或CODEX_IMAGEN_OUT_DIR环境变量，将输出定向到一个有定期清理策略的目录（如/tmp或专用的临时目录），避免磁盘空间被不断累积的图片占满。