Codex GPT Image Skill

English Skill

一个面向 OpenClaw / Claude Code / Codex / Hermes Agent 的 SKILL.md 生图 skill：通过 Codex OAuth / ChatGPT 登录态 调用 gpt-image-2，不需要 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 生图
  • 已经有 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，支持 low、medium、high、auto 质量参数
  • 支持文本生图和多参考图编辑
  • 支持 gpt-image-2 合法尺寸校验
  • 支持官方 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 不支持透明背景；保持默认 background=auto，或显式使用 opaque。
  • Codex OAuth token 可能过期；遇到 401/403 时先重新登录 Codex。
  • 不要把 ~/.codex/auth.json 提交到任何仓库。

许可证

MIT