Codex 中转站生图教程：配置 imagegen，用上 gpt-image-2

Codex 0.165.0 在自定义 provider 上默认不给模型生图工具。要打开它，provider 配置里要加一条名为 x-openai-actor-authorization 的 http_headers，值非空即可，同时 requires_openai_auth 保持默认的 false。这样 Codex 会把生图请求发到中转站的 /images/generations，模型是 gpt-image-2，PNG 存进 ~/.codex/generated_images/。2026 年 10 月 29 日我们跑出 1024×1024 的 PNG，耗时 29.0 秒。去掉那行 header 的对照运行，连工具都没有。

测试环境是 macOS 上的 Codex CLI 0.165.0。自定义 provider 用 OmniaKey，也就是我们自己的 API 网关。

为什么自定义 provider 上 imagegen 会消失

Codex 0.165.0 靠两样东西决定要不要把生图工具交给模型：你的 provider 配置，和它存下来的登录状态。判断只在一个函数里：image_generation_available。

requires_openai_auth = false，不加 actor header：没有生图工具。我们用这个配置跑过一次，Codex 翻完工具列表后回答："I don’t have a built-in image generation tool available in this session."（这次会话里没有内置的图片生成工具。）
requires_openai_auth = false 再加上 x-openai-actor-authorization：工具出现。我们加了 header 的三次运行（新图、改图、透明贴纸）都调到了它。
requires_openai_auth = true 并用 API key 登录：没有生图工具。这条来自 Codex 0.165.0 的源码：这个判断要的是 ChatGPT 登录，API key 登录不算。

这道门后面还有两个小条件，同样写在 Codex 0.165.0 的源码里。第一，Codex 里存着免费 ChatGPT 套餐的登录时，自定义 provider 上也会藏起工具。第二，聊天模型要能接受图片输入。Codex 对自己不认识的模型名，默认按文字加图片处理。

工具不在时，你会看到两种提示之一。Codex 直接说它没有内置生图工具，像我们不加 header 的那次一样；或者 imagegen skill 提示还有 CLI 备用方案，那个方案要 OPENAI_API_KEY。

打开 imagegen 的 config.toml

打开 ~/.codex/config.toml。在中转站的 provider 块里加上 http_headers 这一行，并确认 requires_openai_auth 是 false（它的默认值）。

toml

model = "gpt-6.1-sol"            # 你的中转站提供的聊天模型
model_provider = "relay"

[model_providers.relay]
name = "My relay"
base_url = "https://api.omniakey.com/v1"
env_key = "RELAY_API_KEY"
wire_api = "responses"
requires_openai_auth = false
http_headers = { "x-openai-actor-authorization" = "local-relay" }

[features]
image_generation = true          # Codex 0.165.0 已默认开启

model 和 model_provider 是顶层键，必须写在第一个 [section] 行之前。TOML 会把 [section] 之后的每一行都算进那一节。

requires_openai_auth = false 让 Codex 用你自己的 key，也就是 env_key 指的那个环境变量。OpenAI 的鉴权文档（2026 年 10 月 29 日核对）写得很直接："When requires_openai_auth = true, Codex ignores env_key."（设成 true 时，Codex 不看 env_key。）
http_headers 放的就是这条 header。OpenAI 的配置参考把它称作 "Static HTTP headers added to provider requests"，意思是加在 provider 请求上的固定 header。Codex 只检查它的值非空（见 Codex 源码里的这项检查），所以 "local-relay" 是占位符，不是密码。
[features] image_generation = true 在 0.165.0 里可以不写。这个功能已经稳定、默认开启，codex features list 会打出 image_generation stable true。我们几次运行都没写这两行。
wire_api = "responses"。OpenAI 的配置参考只支持这一个值。

设好 key，启动 Codex：

bash

export RELAY_API_KEY="your-relay-key"
codex

Codex 已经在跑的话，先退掉再开一个新会话，它才会读到新配置。

跑一张图，找到文件

下面是 2026 年 10 月 29 日我们经自定义 provider 跑的三次出图，每次存下一张 1024×1024 的 PNG。第 2 次是不加 header 的对照，没有出图，所以不在表里。时间只算生图那一次调用，不算整轮对话。

次数	我们让它做什么	生图耗时
1	一个新应用图标	29.0 s
3	改第 1 次的图	37.6 s
4	一个透明贴纸	19.8 s

第 1 次只给了一句提示词：

Create an app icon for a note-taking app called Inkwell: a fountain pen nib over a deep blue gradient, flat vector style, no text. Generate it with your image tool, then tell me where the file was saved.

Codex 自己先打开了 imagegen skill，提示词里并没有 $imagegen。然后它才调工具。生图用了 29.0 秒，整轮最后得到一个 1024×1024 的 PNG。

文件落在 ~/.codex/generated_images/<session id>/<call id>.png，其中 ~/.codex 是 CODEX_HOME 的默认位置。路径是 Codex 打在回答里的，因为提示词让它说。图要给项目用，就在提示词里写明目的地，skill 会叫 Codex 把它移过去或复制过去。

修改已有图片

我们把第 1 次的图复制到工作目录，命名 inkwell.png，然后问：

Edit the image ./inkwell.png: change the background to a warm orange gradient and keep the pen nib as it is. Use your built-in image tool, then tell me where the edited file was saved.

Codex 把文件放进 referenced_image_paths，请求于是发到了 /images/edits。生图用了 37.6 秒。原来的 inkwell.png 一点没动。OpenAI 的生图页面（2026 年 10 月 29 日核对）说："When editing an existing image, say exactly what should change and what must stay the same."（改图时要说清哪里要变、哪里必须保持不变。）提示词的其余写法，可以看 GPT-Image 2 提示词指南。

新图

改过一次

两张图都来自 2026 年 10 月 29 日 Codex CLI 0.165.0 的内置生图工具，走的是自定义 provider。改图只要求换背景，笔尖的形状、大小和位置都没变。

透明背景

第 4 次要一张贴纸：

Create a PNG sticker of a single fountain pen nib on a fully transparent background (no backdrop at all), flat vector style, no text. Generate it with your built-in image tool, then tell me where the file was saved.

Codex 把 transparent_background 设成了 true。生图用了 19.8 秒，存下来的 PNG 有 85.0% 的像素完全透明。OpenAI 的 Images API 文档把 gpt-image-2 的透明背景列为 "in preview"（预览中）。我们这次跑通了，但它仍是预览功能。

2026 年 10 月 29 日的第 4 次运行：一张透明背景的 PNG，放在棋盘格上才看得出透明区域。它 85.0% 的像素完全透明。

中转站必须返回什么（gpt-image-2、b64_json）

新图走 POST <base_url>/images/generations，改图走 POST <base_url>/images/edits，都是 JSON。模型固定为 gpt-image-2，也就是中转站必须列出的 GPT-Image 2 模型。质量和尺寸都传 "auto"，background 传 "opaque" 或 "transparent"。请求里既没有 response_format 也没有 n。改图会把原图作为 data URL 放进 JSON，不做文件上传，所以中转站要接得住这种形式。这些请求用的 base URL 和 key，跟聊天请求一模一样。

Codex 读的回复要有 created 和一个 data 列表，第一项里带 b64_json。别的字段一概不看，images.rs 就是这么解析的。解析失败时，报错以 "failed to decode image generation response:" 开头。

不装 Codex 也能查中转站。把下面这段存成 relay-check.sh：

bash

curl -s https://api.omniakey.com/v1/images/generations \
  -H "Authorization: Bearer $RELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-image-2", "prompt": "a red apple on a white table", "background": "opaque", "quality": "auto", "size": "auto"}' \
  | python3 -c 'import json,sys; r=json.load(sys.stdin); print(r.get("error") or sorted(r["data"][0]))'

把 base URL 换成你中转站的，key 导出成 RELAY_API_KEY。2026 年 10 月 29 日我们拿它查自己的网关，HTTP 200，25.0 秒后打出：

text

['asset_id', 'b64_json', 'expires_at', 'revised_prompt', 'url']

列表里没有 b64_json，Codex 拿到同样的回复就会失败。中转站返回错误时，脚本打出来的就是那个错误。

有些中转站坏在把图片当文件存。同一份 Images API 文档（2026 年 10 月 29 日核对）写明，response_format 是 "Legacy response format parameter for retired image models. Unsupported for GPT image models, which always return base64-encoded images"，意思是旧版返回格式参数，GPT 图像模型不支持，它们总是返回 base64。b64_json 则是 "Returned by default for GPT image models"，GPT 图像模型默认返回。原样转发 OpenAI 回复的中转站，正好给 Codex 它要的东西。只回一个链接的中转站，Codex 一定失败。

OmniaKey 的网关在 2026 年 10 月 29 日修好之前就是这个毛病。修复记录里写着 Codex 报 "missing field b64_json"。现在除非调用方要 URL，网关都会保留 b64_json。

你手上的中转站过不了这项检查的话，OmniaKey 一个 key 就能同时调 gpt-image-2 和 gpt-6.1-sol 这类聊天模型。它的图片回复里带 b64_json，就是上面那次检查的结果。把 base_url = "https://api.omniakey.com/v1" 写进那个 provider 块，env_key 指向的变量里放 OmniaKey 的 key。文件其余部分照 Codex CLI 接入指南写，当前价格在价格页。

报错与修复

Codex 说没有生图工具

第 1 节里某个条件没满足，Codex 就没把工具交给模型。补上 http_headers 那行，保留 requires_openai_auth = false 和 env_key，再开一个新会话。还不行就跑 codex login status。如果登录的是免费 ChatGPT 套餐，用 codex logout 清掉这份登录。只靠 env_key 里的中转站 key 就够了。

Codex 向你要 OPENAI_API_KEY

内置工具不可用，imagegen skill 于是提出 CLI 备用方案 scripts/image_gen.py。它要 OPENAI_API_KEY。正确做法是照上面的配置把内置工具修好，内置模式下 key 来自 env_key。

failed to decode image generation response: missing field b64_json

中转站的回复里没有 b64_json，多半换成了一个指向文件的链接。用第 4 节那段检查脚本查一次，把结果发给中转站的运维。Codex 要的是 data 第一项里那段 base64 字符串。

生图请求报 model_not_found

你的 key 在中转站上没有 gpt-image-2 这个模型。Codex 固定发这个名字，没有地方能改。我们拿网关不提供的图像模型去请求时，HTTP 503，错误码 model_not_found。换一个列出 gpt-image-2 的 key 和中转站。

Reconnecting... 1/5（stream disconnected before completion）

连中转站的聊天请求断了，Codex 自己重试，计数器显示的是五次里的第几次。第 1 次运行时出现一次："Concurrency limit exceeded for account, please retry later"（账号并发超限，请稍后重试）。第 3 次运行时出现一次，是传输错误。两次都在重试后跑完。它反复出现就查中转站的限额；跟图片无关的聊天问题，可以看 Codex 兼容性手册。

常见问题

用 imagegen 要 OPENAI_API_KEY 吗？

不用。内置模式下，key 来自 env_key 指定的那个变量。只有 skill 的 CLI 备用方案读 OPENAI_API_KEY。

能换别的生图模型、尺寸或质量吗？

Codex 0.165.0 里不能。工具固定发 gpt-image-2，质量和尺寸都传 "auto"，config.toml 里没有对应开关，我们几次出的图全是 1024×1024。要别的尺寸或模型，直接调中转站的图像接口。

一定要手打 $imagegen 吗？

不用。我们几次运行里，Codex 都是自己打开 imagegen skill。OpenAI 的文档说，在提示词里写 $imagegen 是显式调用，Codex 没自己想到时可以这样点它一下。

Codex 桌面版能用吗？

我们只测了 CLI，桌面版没有测。社区的修复仓库说，正在运行的 Codex Desktop 读不到新的环境变量。它的 macOS 脚本装一个 LaunchAgent，之后你要把 Codex 完全退出，再开一个新任务。

核对过的来源

创建 OmniaKey API Key 查看 GPT-Image 2