告别鉴权报错！Codex Desktop 第三方中转生图手把手教学（附 Win/macOS 一键修复脚本）

导读：Codex Desktop 配好了第三方 OpenAI 兼容中转，文字对话与写代码均正常，但一让它画图就失败（常见表现为：看不到 image_gen 工具、提示鉴权异常、或任务结束却没有输出图片）。

这通常不是因为“图片模型不存在”，而是中转配置、Codex 内置工具以及桌面应用环境变量没有同时对齐。本文基于开源修复项目，为你提供一站式解决方案：

🔗 开源项目地址：xianyu110/codex-imagegen-relay-fix

适用对象：已经在 Codex Desktop 中使用 OpenAI 兼容中转，且中转服务已实现 /v1/models 与 /v1/responses 接口的用户。本文包含 macOS 与 Windows 两套操作指南。

---

💡 一、关键原理解析：生图 ≠ 切换聊天模型

切记：不要把 Codex 的对话主模型直接改成 gpt-image-2！

Codex 的正确工作逻辑是：由支持工具调用（Function Calling）的对话模型判断何时触发内置生图工具：

  【对话主模型】 (例如: gpt-5.4)
          ↓
  【Codex 内置工具】 (image_gen)
          ↓
  【中转站图片模型】 (gpt-image-2)
          ↓
  【本地生成产物】 (图片文件)

因此，能对话并不代表生图链路已通。必须同时满足以下四大要素：

关键要素	说明与要求
1. 接口兼容	中转 Endpoint 必须包含 /v1，且完整支持 Responses API。
2. 模型完备	中转模型列表须同时包含 对话模型（如 gpt-5.4）与生图模型 gpt-image-2。
3. 鉴权解耦	Codex 自定义 Provider 必须配置为从环境变量读取 Key，而非硬编码写死。
4. 变量继承	每次启动 Codex Desktop 的新进程必须能够成功继承 OPENAI_API_KEY。

---

📋 二、操作前准备与自查

在开始配置前，请先核对以下准备条件：

• [x] 已安装并能正常打开 Codex Desktop。
• [x] 已通过正常登录或既有流程使 auth.json 中写入了有效的 OPENAI_API_KEY。
• [x] ~/.codex/config.toml 已指定自定义的 model_provider。
• [x] 你的中转站已支持 GET /v1/models 和 POST /v1/responses 接口。
• [x] 中转服务模型列表中包含 gpt-image-2 以及可调用的对话模型（如 gpt-5.4）。

⚠️ 安全警告：请勿将你的 API Key 粘贴到终端历史、聊天记录、截图或 config.toml 文件中。下文的自动化脚本仅会校验 Key 是否存在，绝对不会打印或泄露 Key 本身。

---

⚙️ 三、最小化配置文件示例

自动化脚本会自动定位当前启用的 model_provider，并仅修改生图链路相关的配置项，最终生效的 ~/.codex/config.toml 核心结构如下：

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

[features]
image_generation = true

📌 关键字段配置说明：

配置字段	正确设定	作用解析
base_url	https://your-relay.com/v1	兼容中转站地址，末尾的 /v1 切勿遗漏。
wire_api	"responses"	强制开启 Responses API 协议支持。
requires_openai_auth	false	关闭 Codex 默认的官方认证检查。
env_key	"OPENAI_API_KEY"	指定通过环境变量读取鉴权密钥。
http_headers	{ "x-openai-actor-authorization" = "local-relay" }	内置工具门控占位 Header（非 API Key，兼容中转会自动忽略）。
image_generation	true	在 [features] 作用域下显式开启生图功能。

💡 冲突提示：若原配置中存在 auth = { command = ... } 或 experimental_bearer_token，会与环境变量鉴权产生冲突。脚本会自动清洗并移除这些冗余字段。

---

🍎 四、macOS：一键接入与验证

打开 macOS 终端（Terminal），依序执行以下命令：

git clone https://github.com/xianyu110/codex-imagegen-relay-fix.git
cd codex-imagegen-relay-fix
chmod 700 fix-codex-imagegen-macos.sh
./fix-codex-imagegen-macos.sh

脚本默认使用示范中转地址 https://momoai.asia/v1。如果你使用自定义中转，无需修改脚本文件，直接通过环境变量覆盖即可：

CODEX_RELAY_BASE_URL='https://relay.example.com/v1' ./fix-codex-imagegen-macos.sh

🔍 macOS 运行机制说明：

脚本会自动从 $CODEX_HOME/auth.json 或 ~/.codex/auth.json 中读取已有 Key，并写入用户级 LaunchAgent。这样可以在用户登录系统时将 Key 注入 launchd 进程，确保后续启动的 Codex Desktop 能完整继承该环境变量。

若控制台打印出如下信息，说明配置与接口校验全部通过：

OPENAI_API_KEY(auth.json)=EXISTS
OPENAI_API_KEY(macOS user launchd)=EXISTS
provider_config=OK
models_http=200
gpt-image-2=AVAILABLE
gpt-5.4=AVAILABLE
responses_http=200
image_generation_config=READY

---

🪟 五、Windows：PowerShell 一键接入与验证

Windows 系统不使用 LaunchAgent，脚本会将 Key 写入当前用户的 Windows 环境变量中，以便后续启动的 Codex Desktop 进程继承。

使用管理员或普通权限打开 PowerShell 窗口，执行命令：

git clone https://github.com/xianyu110/codex-imagegen-relay-fix.git
Set-Location codex-imagegen-relay-fix
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\fix-codex-imagegen-windows.ps1

如需更换中转地址，使用 -RelayBaseUrl 参数：

.\fix-codex-imagegen-windows.ps1 -RelayBaseUrl 'https://relay.example.com/v1'

📌 注意：Set-ExecutionPolicy -Scope Process 仅针对当前 PowerShell 窗口生效，关闭窗口后会自动还原，不会修改系统级安全策略。

Windows 脚本会自动读取 %CODEX_HOME%\auth.json（或 %USERPROFILE%\.codex\auth.json），验证通过后将输出：

OPENAI_API_KEY(auth.json)=EXISTS
OPENAI_API_KEY(windows user environment)=EXISTS
provider_config=OK
models_http=200
gpt-image-2=AVAILABLE
gpt-5.4=AVAILABLE
responses_http=200
image_generation_config=READY

---

🔄 六、终极关键一步：彻底重启 Codex Desktop

🚨 这是最容易导致配置失效的一步！ 环境变量虽然修改成功，但已经处于运行状态的 Codex Desktop 后台进程不会实时刷新环境。

请严格按照以下顺序操作：

1. 彻底退出 Codex Desktop：右键系统托盘/任务栏图标点击退出，确保无后台驻留进程（必要时通过任务管理器/活动监视器结束）。
2. 重新启动 Codex Desktop。
3. 新建一个新的对话 Session（⚠️ 不要在修改前已经创建的旧任务中测试）。
4. 选择支持 Tool Calling 的主对话模型（如 gpt-5.4）。
5. 发送生图指令，例如：“生成一张白色背景、居中蓝色圆形的 PNG 图片”。

此时 Codex 将自动触发内置 image_gen 工具调用图片模型，无需手动切换模型！

---

❓ 七、常见报错与诊断指南

报错提示 / 现象	根因分析	对应解决方法
OPENAI_API_KEY(auth.json)=MISSING	本地认证配置文件中缺失 Key。	先完成 Codex 桌面端的登录或初始化认证流程，确保 auth.json 生成后重新运行脚本。
gpt-image-2=UNAVAILABLE	中转站的 /v1/models 未返回该模型，或当前 Key 权限不足。	联系中转站服务商确认模型路由配置及账户分组权限；修改本地 Codex 配置无法解决服务端缺失问题。
responses_http 非 2xx	中转协议不兼容或模型不可用。	依次检查：① base_url 是否包含 /v1；② 中转站是否支持 /v1/responses；③ 所选对话模型是否正常可用。
脚本成功，但界面无 image_gen	旧进程未刷新或模型选错。	① 彻底杀死 Codex Desktop 后台进程并重启；② 新建 Session；③ 务必选择对话模型（如 gpt-5.4） 而非直接选择 gpt-image-2。

---

🛡️ 八、安全与隐私边界说明

本方案仅用于修复本地客户端配置与接口调用链路，无法替你保证第三方中转站的绝对安全：

1. 隐私安全：在使用第三方中转服务前，请务必了解其日志保留政策、敏感数据处理方式与计费规则。涉及商业机密、私有代码或敏感图片时，请优先使用官方授权服务。
2. 系统权限：macOS 的 Key 会注入当前用户的 launchd 会话，Windows 的 Key 会写入用户环境变量。这意味着同系统用户权限下的其他应用均有可能读取该 Key，多用户共享一台电脑时请注意系统账号权限隔离。

---

📝 总结

Codex 中转站接入后无法生图，其核心链路如下：

$$\text{中转站 } /v1/responses \longrightarrow \text{配置 } env_key = OPENAI_API_KEY \longrightarrow \text{开启 } image_generation \longrightarrow \text{继承系统环境变量} \longrightarrow \text{主模型调用 } image_gen$$

只要严格按照本文的脚本自动化配置、彻底重启桌面客户端并在新会话中测试，就能轻松搞定中转生图功能！

📌 相关资源链接：

• 开源修复工具项目：GitHub - xianyu110/codex-imagegen-relay-fix