---
slug: "codex-gpt-image"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/ningzimu/codex-gpt-image@main/README.md"
repo: "https://github.com/ningzimu/codex-gpt-image"
source_file: "README.md"
branch: "main"
---
# Codex GPT Image Skill

[![English](https://img.shields.io/badge/docs-English-blue)](README_en.md) [![Skill](https://img.shields.io/badge/skill-codex--gpt--image-cd3b35)](skills/codex-gpt-image)

一个面向 **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 环境里调用

## 目录结构

```text
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 目录：

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

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


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

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

## 前置条件

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

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

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

```bash
export CODEX_AUTH_FILE=/path/to/auth.json
```

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

```bash
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`。

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

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

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

## 使用方式

检查 Codex OAuth：

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

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

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

生成图片：

```bash
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 第一次使用时自动引导登录：

```bash
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
```

使用参考图编辑：

```bash
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 局部编辑：

```bash
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