Codex GPT Image Skill

一个面向 OpenClaw / Claude Code / Codex / Hermes Agent 的 SKILL.md 生图 skill：通过 Codex OAuth / ChatGPT 登录态 调用 gpt-image-2.5-flare，不需要 OPENAI_API_KEY。

它读取本机 ~/.codex/auth.json，请求 Codex Images 后端 https://chatgpt.com/backend-api/codex/images/generations 或 https://chatgpt.com/backend-api/codex/images/edits，让 agent 复用已有 Codex / ChatGPT 订阅权限生成图片。

适合谁用

• 想在 OpenClaw / Claude Code / Codex / Hermes Agent 里直接用 gpt-image-2.5-flare 生图
• 已经有 Codex / ChatGPT OAuth 登录态，不想再配置 OpenAI API key
• 想把同一套 GPT Image skill 复用到多个支持 SKILL.md 的 agent
• 需要文本生图、参考图编辑，或在用户明确要求时指定合法输出尺寸

特点

• OpenClaw skill / Claude Code skill / Codex skill / Hermes Agent skill
• Codex OAuth：读取 ~/.codex/auth.json，不要求 OpenAI API key
• 默认使用 gpt-image-2.5-flare，支持 low、medium、high、xhigh、max、auto 质量参数
• 支持文本生图和多参考图编辑
• 支持 gpt-image-2.5-flare 合法尺寸校验
• 支持官方 Images API 的常用参数：background、moderation、output_format、output_compression、mask
• 纯 Python 标准库脚本，便于在任意 agent 环境里调用

目录结构

codex-gpt-image/
├── README.md
├── README_en.md
├── LICENSE
├── CHANGELOG.md
├── AGENTS.md
└── skills/
    └── codex-gpt-image/
        ├── SKILL.md
        ├── references/
        │   └── openai-images-api-parameters.md
        └── scripts/
            └── codex_gpt_image.py

安装

推荐使用 skills CLI 一次安装到当前 agent 的全局 skills 目录：

npx -y skills@latest add ningzimu/codex-gpt-image \
  --global

这个仓库目前只包含 codex-gpt-image 一个 skill。安装完成后，重启当前 agent 让新 skill 生效。

本地开发时可以用软链接：

mkdir -p ~/.codex/skills
ln -s /path/to/codex-gpt-image/skills/codex-gpt-image ~/.codex/skills/codex-gpt-image

前置条件

首选路径是本机已经登录 Codex，并存在可读的 Codex OAuth 文件：

codex login
test -f ~/.codex/auth.json

这个 skill 不读取也不需要 OPENAI_API_KEY。如果你想指定另一个 Codex auth 文件：

export CODEX_AUTH_FILE=/path/to/auth.json

device-code 登录 fallback 默认使用官方 Codex 登录工具同一个公开 OAuth client id；如需覆盖：

export CODEX_APP_SERVER_LOGIN_CLIENT_ID=your-client-id

如果机器上还没有 Codex 登录态，也可以直接用本 skill 的 device-code 登录流程。它参考官方 Codex device-code 登录流程：先生成浏览器 URL 和短 code，用户在浏览器中确认后，脚本把 access/refresh token 写入 ~/.codex/auth.json。

python3 skills/codex-gpt-image/scripts/codex_gpt_image.py login --open-browser

在远程服务器或 Claude Code 终端里，可以不加 --open-browser，手动复制 URL 到本地浏览器：

python3 skills/codex-gpt-image/scripts/codex_gpt_image.py login

使用方式

检查 Codex OAuth：

python3 skills/codex-gpt-image/scripts/codex_gpt_image.py auth-status

如果缺少 auth，可以让检查命令自动进入 device-code 登录：

python3 skills/codex-gpt-image/scripts/codex_gpt_image.py auth-status --login-if-missing

生成图片：

python3 skills/codex-gpt-image/scripts/codex_gpt_image.py generate \
  --prompt "A polished launch poster for a terminal AI image tool" \
  --out output/codex-gpt-image/poster.png

生成命令也支持 --login-if-missing，适合 agent 第一次使用时自动引导登录：

python3 skills/codex-gpt-image/scripts/codex_gpt_image.py generate \
  --login-if-missing \
  --prompt "A polished launch poster for a terminal AI image tool" \
  --out output/codex-gpt-image/poster.png

使用参考图编辑：

python3 skills/codex-gpt-image/scripts/codex_gpt_image.py generate \
  --image /path/to/reference.png \
  --prompt "Preserve the layout, turn it into a clean editorial illustration" \
  --out output/codex-gpt-image/edited.png

使用 mask 局部编辑：

python3 skills/codex-gpt-image/scripts/codex_gpt_image.py generate \
  --image /path/to/source.png \
  --mask /path/to/mask.png \
  --prompt "Replace the masked area with a flamingo float" \
  --out output/codex-gpt-image/masked-edit.png

注意

• 这不是 OpenAI API key 方案，不使用 OPENAI_API_KEY 计费。
• 这不是 OpenAI 官方推荐的 API 集成方式；Codex Images 后端接口可能随时变更或失效，也可能受到账号、产品权限或用量规则影响。
• 请求会发到 Codex Images 后端：https://chatgpt.com/backend-api/codex/images/generations 或 https://chatgpt.com/backend-api/codex/images/edits。
• GPT Image 2.5 支持透明背景：使用 --background transparent 并选择 PNG 或 WebP；旧模型 gpt-image-2 仍不支持。
• Codex OAuth token 可能过期；遇到 401/403 时先重新登录 Codex。
• 不要把 ~/.codex/auth.json 提交到任何仓库。

GPT Image 2.5 模型选择

默认使用 gpt-image-2.5-flare；精确编辑可用 --model gpt-image-2.5-sunburst。两款模型及其日期快照支持 xhigh、max 质量档位。可通过 CODEX_GPT_IMAGE_MODEL 覆盖默认模型，或显式选择旧模型 --model gpt-image-2。OAuth 可用性取决于账号和后端开放情况。

实测边界：2026-09-11 的 Codex OAuth 测试中，两款 2.5 模型名均返回图片，编辑与透明 PNG 也成功；但不存在的模型名同样成功，响应未提供实际模型 ID，且实际尺寸与请求尺寸不一致。因此这些结果只证明链路可用，不能证明后端遵循模型或质量选择。CLI 会区分请求模型和后端报告模型。

许可证

MIT