Relay Imagegen

解决 Codex 使用中转站生图时，分辨率、比例、提示词记录和输出记录不容易稳定控制的问题。

使用中转站时还在抱怨 Codex 对话内置生图图片比例不对？要求它 16:9，结果它还是输出 1:1？要求它输出 4K，结果输出的还是低分辨率？那你可以试试这个 Skill。

配置和使用极速版：

给 Codex 发：

Codex，帮我安装一下这个 Skill：https://github.com/AwakeFantasy/relay-imagegen

使用：

$relay-imagegen 跑一张 16:9、4K 的风景图看看效果

效果：

为什么会有对话内置生成效果不稳定的问题呢？因为对话里的原生生图更偏“让模型按自然语言理解你的要求”，Codex 不一定会把“4K、16:9、横图”稳定地转换成底层命令参数。它可能只是把这些要求写进 prompt，让模型尽量遵守，但这不等于真的传了 --size 3840x2160。结果就可能被默认尺寸、工具策略或模型理解偏差带歪，跑出低分辨率、方图、比例不准的图。

极简的介绍就到此结束了，下面是这个 Skill 详细的介绍：

Relay Imagegen 是一个 Codex Skill，用于通过兼容 OpenAI 接口的中转站或代理生成、编辑图片，并自动保存提示词和不含密钥的出图记录。

它的目标是让中转站出图流程尽可能简单、可复用、可追溯：

支持为生图单独配置中转站站点和 key
可自动读取 Codex 当前生效的中转站配置
也可以读取当前 ccswitch 的 Codex 供应商配置
没有 ccswitch 时，也支持私有 JSON 配置文件
推荐使用 prompts/*.txt 保存和复用提示词
每次成功生成后自动写入不含密钥的 .meta.json 记录文件
.meta.json 会保存当次提示词快照，方便复盘和复现
默认分辨率：2560x1440
默认模型：gpt-image-2
默认质量：high
默认输出到当前目录下的 generated/
支持上传前自动缩小参考图，减少传图耗时和失败概率

适用场景

当你遇到这些情况时，可以使用这个 Skill：

你使用中转站生成图片，而不是 OpenAI 官方 endpoint
你希望把提示词保存成文件并复用
你希望每次出图都自动保存提示词快照、模型、尺寸、输入图和输出路径
你不希望设置系统级 OPENAI_API_KEY
你当前 Codex 已经通过中转站工作，希望直接复用 Codex 配置
你使用 ccswitch 切换 Codex 中转站，希望在需要时复用其中的 key 和 endpoint
你想用本地参考图进行角色、构图或风格编辑
你希望默认生成较高分辨率图片，例如 2560x1440

工作方式

Relay Imagegen 当前是 Codex 自带图片生成脚本的包装层：

~/.codex/skills/.system/imagegen/scripts/image_gen.py

它负责：

从生图专用私有配置、Codex 当前配置、ccswitch 或其他私有配置文件读取中转站信息。
只在当前子进程运行期间注入 OPENAI_API_KEY 和 OPENAI_BASE_URL。
调用 Codex 自带的 imagegen 脚本生成或编辑图片。
验证输出图片尺寸。
写入不包含密钥的 sidecar 记录文件，并保存当次提示词快照。

真实 key 不会出现在命令行参数、输出日志或 sidecar 中。

环境要求

已安装 Codex，并且带有系统 imagegen Skill
Python 3.10 或更高版本
一个支持图片生成模型的 OpenAI 兼容中转站
可选：ccswitch，用于在 Codex 配置不可用时自动读取当前 Codex provider
可选：Pillow，用于参考图预处理和输出尺寸检查

安装

将整个仓库放到 Codex Skill 目录：

~/.codex/skills/relay-imagegen

Windows 通常为：

C:\Users\<你的用户名>\.codex\skills\relay-imagegen

也可以从 GitHub 克隆：

git clone https://github.com/AwakeFantasy/relay-imagegen.git "$HOME/.codex/skills/relay-imagegen"

安装后，当你在 Codex 中提到中转站出图、保存提示词、出图记录、ccswitch、api_key.json 或 $relay-imagegen 时，Codex 就可以使用这个 Skill。

最快开始

如果你的 Codex 已经通过中转站工作，那么通常不需要额外写入 key。

1. 检查配置

$setup = "$HOME/.codex/skills/relay-imagegen/scripts/setup.py"
python $setup --check

成功时会看到类似输出：

CODEX_CONFIG=C:\Users\you\.codex\config.toml
CODEX_AUTH=C:\Users\you\.codex\auth.json
CODEX_PROVIDER=your-provider
API_KEY=sk-...xxxx
BASE_URL=https://relay.example/v1
MODEL=gpt-image-2

密钥只会脱敏显示。

2. 准备提示词文件

在当前项目下创建：

prompts/test.txt

将你的出图提示词写进去。

3. 先进行 dry-run

$skill = "$HOME/.codex/skills/relay-imagegen/scripts/relay_imagegen.py"
python $skill generate --prompt-file prompts/test.txt --name test --dry-run

--dry-run 不会请求中转站，也不会产生费用，只会显示将要执行的非敏感参数和输出位置。

4. 正式出图

python $skill generate --prompt-file prompts/test.txt --name test --force

默认输出：

generated/test-YYYYMMDD-HHMMSS-2k.png
generated/test-YYYYMMDD-HHMMSS-2k.meta.json

配置方式

Relay Imagegen 支持三种方式：

使用私有 JSON 文件，适合需要为生图单独配置站点和 key 的用户。
自动读取 Codex 当前配置，适合已经用 Codex 中转站的用户。
自动读取 ccswitch 当前 Codex provider，适合依赖 ccswitch 切换中转站的用户。

默认读取顺序

如果没有显式提供 --config，脚本按下列顺序读取配置：

当前 Skill 下的 .secrets/config.json，如果存在且读取成功
Codex 当前配置：~/.codex/config.toml 和 ~/.codex/auth.json
当前 ccswitch 的 codex provider：~/.cc-switch/cc-switch.db
环境变量 RELAY_IMAGEGEN_CONFIG 指向的 JSON 文件
当前项目下的 photo/api_key.json
当前项目下的 .secrets/image_api.json
当前项目下的 .secrets/relay_imagegen.json
Windows 下的 %APPDATA%/relay-imagegen/config.json
~/.config/relay-imagegen/config.json
~/.relay-imagegen.json

如果你传入：

--config C:/path/to/config.json

则会直接使用该配置，不尝试 Codex 或 ccswitch。

使用 Codex 当前配置

这是常用的自动配置来源。如果当前 Skill 下存在可用的 .secrets/config.json，会优先使用该生图专用配置。

脚本会读取：

~/.codex/config.toml
~/.codex/auth.json

其中：

base_url -> config.toml 里的当前 model_provider 对应配置
api_key  -> auth.json 里的 OPENAI_API_KEY
model    -> image_model 字段；如果没有，则默认 gpt-image-2

显式检查 Codex 配置：

python ~/.codex/skills/relay-imagegen/scripts/setup.py --check-codex

强制使用 Codex 配置，失败不回退：

python $skill generate --from-codex --prompt-file prompts/test.txt --name test --force

跳过 Codex 配置：

python $skill generate --no-codex --prompt-file prompts/test.txt --name test --force

指定其他 Codex 配置路径：

python $skill generate --codex-config C:/path/to/config.toml --codex-auth C:/path/to/auth.json --prompt-file prompts/test.txt --name test --force

使用 ccswitch

ccswitch 自动读取什么

默认数据库路径是：

~/.cc-switch/cc-switch.db

Windows 上通常是：

C:\Users\<你的用户名>\.cc-switch\cc-switch.db

脚本会在数据库中读取当前启用的 Codex provider：

providers where app_type = "codex" and is_current = 1

然后读取：

key       -> providers.settings_config.auth.OPENAI_API_KEY
base_url  -> 优先读取 providers.settings_config.config 里的 base_url
fallback  -> 如果 config 里没有 base_url，再读取 provider_endpoints 的第一个 url
model     -> 默认使用 gpt-image-2

注意：ccswitch 的 endpoint 列表可能包含多个节点，最后一个节点不一定是当前可用节点。Relay Imagegen 不会再简单读取最后一个 endpoint，以免误选到失败节点。

如果 ccswitch 中保存的 endpoint 是：

https://relay.example

脚本会自动规范化为：

https://relay.example/v1

检查 ccswitch

普通检查会按默认读取顺序尝试配置，包括生图专用配置、Codex 配置和 ccswitch：

python ~/.codex/skills/relay-imagegen/scripts/setup.py --check

也可以显式只检查 ccswitch：

python ~/.codex/skills/relay-imagegen/scripts/setup.py --check-ccswitch

强制使用 ccswitch

正常情况下不需要写额外参数，因为脚本会按默认读取顺序尝试生图专用配置、Codex 当前配置和 ccswitch。

如果你希望“ccswitch 读取失败就直接报错，不要回退到 JSON 配置”，使用：

python $skill generate --from-ccswitch --prompt-file prompts/test.txt --name test --force

跳过 ccswitch

如果你不想使用当前 ccswitch provider，而是想使用 JSON 配置：

python $skill generate --no-ccswitch --prompt-file prompts/test.txt --name test --force

指定其他 ccswitch 数据库

python $setup --check-ccswitch --ccswitch-db C:/path/to/cc-switch.db
python $skill generate --ccswitch-db C:/path/to/cc-switch.db --prompt-file prompts/test.txt --name test --force

使用 JSON 配置文件

如果你不想复用 Codex 或 ccswitch 的当前配置，或者图片中转站与 Codex 中转站不同，可以使用独立 JSON 配置，为生图单独指定站点和 key。

推荐：用户级配置

运行：

python ~/.codex/skills/relay-imagegen/scripts/setup.py config --scope user

Windows 下会写入：

%APPDATA%\relay-imagegen\config.json

这种方式适合长期使用，而且不会把密钥放进 Skill 仓库中。

Skill 私有配置

如果你只在本机自己使用，也可以写入 Skill 私有目录：

python ~/.codex/skills/relay-imagegen/scripts/setup.py config --scope skill

文件位置为：

~/.codex/skills/relay-imagegen/.secrets/config.json

.secrets/ 已在仓库的 .gitignore 中忽略，不应上传到 GitHub。

这个文件会在默认读取顺序中优先于 Codex 配置。它缺失或读取失败时会被静默跳过，再继续尝试 Codex、ccswitch 和其他私有配置。

手动创建 JSON

配置文件结构如下：

{
  "api_key": "sk-...",
  "base_url": "https://relay.example/v1",
  "model": "gpt-image-2"
}

支持的 key 字段名：

api_key, apiKey, key, token, openai_api_key, OPENAI_API_KEY

支持的 endpoint 字段名：

base_url, baseUrl, baseURL, api_base, endpoint, openai_base_url, OPENAI_BASE_URL

生成图片

使用提示词文件生成图片

$skill = "$HOME/.codex/skills/relay-imagegen/scripts/relay_imagegen.py"
python $skill generate `
  --prompt-file prompts/test.txt `
  --name test `
  --force

默认等价于：

model   = gpt-image-2
size    = 2560x1440
quality = high
output  = generated/

直接传入简短提示词

python $skill generate `
  --prompt "A quiet cinematic room with warm soft lighting." `
  --name room `
  --force

长提示词、中文提示词或希望保留复用的提示词，建议使用 --prompt-file。成功出图后，提示词内容也会写入 .meta.json 的 prompt_snapshot 字段。

使用参考图编辑图片

单张参考图

python $skill edit `
  --image C:/path/to/reference.jpg `
  --prompt-file prompts/edit.txt `
  --name edit-test `
  --prepare-image `
  --force

多张参考图

python $skill edit `
  --image C:/path/to/composition.png `
  --image C:/path/to/character.jpg `
  --prompt-file prompts/edit.txt `
  --name final `
  --prepare-image `
  --force

适合：

一张图作为场景或构图参考
一张图作为人物设定或服装参考
生成“现实照片环境中出现二次元角色”之类的合成画面

参考图预处理

高分辨率参考图可能上传慢、占用更高，或者增加中转站请求失败概率。

使用：

--prepare-image

会在上传前将参考图最长边压缩到默认 2048 像素。

也可以自行指定最大边长：

python $skill edit `
  --image C:/path/to/large-reference.jpg `
  --prompt-file prompts/edit.txt `
  --max-input-edge 1536 `
  --name prepared-edit `
  --force

默认情况下，处理后的上传副本只保存在临时目录中，运行结束后会自动删除，不会污染当前项目。

如果你想保留这些副本用于调试，可以加：

--keep-prepared

此时副本会保存在：

generated/relay_prepared/

原始图片不会被修改。

输出文件和运行记录

如果没有指定 --out，图片默认输出为：

generated/<名称>-YYYYMMDD-HHMMSS-2k.png

例如：

generated/character-chair-20260527-183000-2k.png

每次成功生成后，会自动写入同名记录文件：

generated/character-chair-20260527-183000-2k.meta.json

记录内容包括：

使用的是 generate 还是 edit
模型
请求尺寸和输出尺寸
图片质量
提示词文件位置
当次提示词快照
输入参考图位置
预处理图片尺寸；默认不保留临时预处理图片路径
耗时
配置来源
使用 ccswitch 时的 provider 名称
不含查询参数的 base URL

记录文件不会包含 API key。

常用参数

参数	说明	默认值
`generate` / `edit`	生成新图或使用参考图编辑	必填
`--prompt-file`	从文本文件读取提示词，推荐使用	无
`--prompt`	直接传入简短提示词	无
`--image`	`edit` 模式的参考图，可重复传入	无
`--name`	自动输出文件名的名称部分	根据模式或 prompt 文件生成
`--out`	指定完整输出路径	自动命名
`--output-dir`	自动命名输出目录	`generated`
`--size`	输出分辨率	`2560x1440`
`--quality`	输出质量	`high`
`--timeout`	超时时间，单位为秒	`600`
`--prepare-image`	上传前压缩参考图	关闭
`--max-input-edge`	指定参考图最大边长，同时开启预处理	`2048`
`--keep-prepared`	保留预处理上传副本到 `generated/relay_prepared/`	关闭
`--dry-run`	只检查命令和输出位置，不实际请求	关闭
`--force`	允许覆盖目标输出	关闭
`--config`	显式指定 JSON 配置	自动读取
`--from-codex`	强制使用 Codex 当前配置，失败不回退	关闭
`--no-codex`	不读取 Codex 当前配置	关闭
`--codex-config`	指定 Codex `config.toml` 位置	`~/.codex/config.toml`
`--codex-auth`	指定 Codex `auth.json` 位置	`~/.codex/auth.json`
`--from-ccswitch`	强制使用 ccswitch，失败不回退	关闭
`--no-ccswitch`	不读取 ccswitch	关闭
`--ccswitch-db`	指定 ccswitch 数据库位置	`~/.cc-switch/cc-switch.db`

安全说明

不要把真实 API key 作为命令行参数传入。
不要把真实配置文件提交到 GitHub。
不需要把 OPENAI_API_KEY 永久写入用户或系统环境变量。
Codex 模式只读取当前 config.toml 和 auth.json，不会复制 key 到 Skill 目录。
ccswitch 模式只读取当前 provider，不会复制 key 到 Skill 目录。
JSON 配置模式只在运行时读取 key。
key 只会临时注入子进程环境。
控制台只会显示脱敏后的 key。
.meta.json 运行记录不会包含 key。

故障排查

没有找到配置

运行：

python ~/.codex/skills/relay-imagegen/scripts/setup.py --check

如果 Codex 和 ccswitch 都不可用，创建用户级配置：

python ~/.codex/skills/relay-imagegen/scripts/setup.py config --scope user

不想使用 ccswitch 当前 provider

运行时增加：

--no-ccswitch

然后提供 JSON 配置，或者让脚本自动发现私有配置文件。

ccswitch endpoint 不带 `/v1`

如果读取到的是根地址，例如：

https://relay.example

脚本会自动转换为：

https://relay.example/v1

如果你的中转站使用不同 API 路径，请改用 JSON 配置，明确写入完整 base_url。

输出尺寸不是默认尺寸

默认请求尺寸是：

2560x1440

如果中转站或模型不支持该尺寸，生成请求可能失败，或者尺寸验证不通过。此时需要检查你所用中转站对模型和尺寸的支持情况。

请求时间过长

可以提高超时时间：

python $skill generate --prompt-file prompts/test.txt --timeout 900 --name test --force

仓库结构

relay-imagegen/
  README.md
  README_EN.md
  README/
  SKILL.md
  LICENSE
  agents/
    openai.yaml
  scripts/
    relay_imagegen.py
    setup.py

以下内容不会包含在公开仓库中：

.secrets/config.json
generated/
*.meta.json

License

MIT License

Name		Name	Last commit message	Last commit date
Latest commit History 16 Commits
README		README
agents		agents
scripts		scripts
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
README_EN.md		README_EN.md
SKILL.md		SKILL.md

Folders and files

Latest commit

History

Repository files navigation