# Codex 无法生成图片怎么解决？四种原因逐一排查（2026）

- 原文：[https://news.qiniu.com/archives/1787215108340](https://news.qiniu.com/archives/1787215108340)
- 发布时间：2026-08-21
- 分类：教程与实践
- 标签：AI 图片生成、Codex

> 发布日期：2026-08-20 | 适用场景：Codex Cloud / Codex Desktop / Codex CLI 图片生成失败 | 数据来源：OpenAI 官方文档 + GitHub Issues（2026-08-20）

Codex 图片生成失败不是一个问题，而是四个不同原因叠加在同一个报错信息上——网络被沙箱拦截、Responses API 的模型字段填错、Codex Desktop 的已知端点 bug、以及第三方 API 提供商未映射 `gpt-image-2`。搞清楚自己是哪种情况，解决方案截然不同。本文按照"最高频原因优先"的顺序逐一拆解，每种情况都给出可操作的验证步骤。

* * *

## 先确认：你的报错信息是哪种？

不同错误信息对应不同根因，先对号入座：

| 报错信息 | 最可能原因 |
|---|---|
| `image generation failed: network error` | Codex 沙箱屏蔽网络（最常见） |
| `The model gpt-image-2 does not exist` | API 调用方式错误 或 第三方代理未映射 |
| `error sending request for url (...codex/images/generations)` | Codex Desktop 端点 bug（已知问题） |
| 图片生成请求挂起数分钟后超时 | 同上，Codex Desktop 2026-07-09 更新后引入 |
| 生成成功但图片不显示 | 渲染/权限问题，非生成失败 |

* * *

## 原因一（最常见）：Codex Cloud 沙箱默认阻断网络

Codex Cloud 的 Agent 运行阶段默认**完全阻断互联网访问**。图片生成需要调用 `api.openai.com`，而这个域名**不在预设的 Common dependencies 白名单**中，请求在沙箱层面直接被拒绝，表现为 network error。

这是 Codex Cloud 的安全设计，不是 bug——Setup 脚本阶段（安装依赖时）保留网络访问，Agent 执行阶段默认关闭。

### 解决方法：手动将 api.openai.com 加入白名单

1. 打开 Codex Cloud 控制台，进入 **Settings → Environments**（或对应仓库的环境配置页）
2. 找到 **Internet Access** 设置，当前默认为 **Off** 或 **Common dependencies**
3. 在域名白名单中手动添加：
   
   ```
    api.openai.com
   ```
4. HTTP 方法限制：图片生成需要 `POST`，确认未设置"仅允许 GET/HEAD"
5. 保存配置后重新触发任务

> ⚠️ 安全提示：官方文档警告启用外网访问后存在"prompt injection from untrusted web content"风险。建议只添加确实需要的域名，不要直接选择"All (unrestricted)"。

* * *

## 原因二：Responses API 的图片生成调用方式写错了

如果你在代码里直接调用图片生成，常见的错误是把 `model` 字段填成了 `gpt-image-2`，或者混淆了两种不同的 API。

**OpenAI 有两种完全不同的图片生成接口：**

### 方式 A：Image API（直接调用，模型字段填 gpt-image-2）

```python
from openai import OpenAI
client = OpenAI()

response = client.images.generate(
    model="gpt-image-2",
    prompt="a white cat sitting on a table",
    size="1024x1024",
    quality="high",
    n=1,
)
print(response.data[0].url)
```

**使用场景**：直接在代码中生成图片，不经过对话流程。

### 方式 B：Responses API + image\_generation 工具（主模型字段填对话模型）

```python
response = client.responses.create(
    model="gpt-5.6",          # ← 这里填对话模型，不要填 gpt-image-2
    input="生成一张白色猫咪坐在桌子上的图片",
    tools=[{"type": "image_generation"}],
)
```

**常见错误**：在 Responses API 的 `model` 字段填了 `gpt-image-2`，导致"模型不存在"报错。`gpt-image-2` 只用于 Image API，不用于 Responses API 的 `model` 字段。

### 验证 API 是否可以正常访问

```bash
curl https://api.openai.com/v1/images/generations \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-image-2", "prompt": "a test image", "size": "1024x1024"}'
```

- 返回 200 → API 本身正常，问题在 Codex 层（看原因一或原因三）
- 返回 403 / 404 → 检查 API Key 权限范围和组织配置
- 返回"model does not exist" → 看原因四

* * *

## 原因三：Codex Desktop 已知端点 bug（2026-07-09 更新后）

2026 年 7 月 9 日 Codex Desktop 更新后，内置 `image_gen` 工具的后端路由出现兼容性问题，表现为：

- 报错：`image generation failed: network error: error sending request for url (https://chatgpt.com/backend-api/codex/images/generations)`
- 文字对话完全正常，仅图片生成路由失败
- 请求会挂起数分钟才最终超时，不立即失败

这个问题已被记录在 GitHub Issue #32297（标签：`bug`, `connectivity`, `imagen`），截至 2026-08-20 官方尚未给出修复。

### 当前可行的绕过方案

1. **回退到较早版本**：如果之前版本能正常生成，可以回退到 7 月 9 日更新之前的版本（需要手动安装旧版本安装包）
2. **改用 Codex Cloud 代替 Desktop**：Codex Cloud 走的是不同的后端路径，该端点 bug 不影响 Cloud 端，但需要先解决原因一的网络白名单问题
3. **改用直接 API 调用**：在 Codex 任务中让 Agent 执行 Shell 命令直接调用 Image API，而不依赖内置 `image_gen` 工具：
   
   ```bash
    curl https://api.openai.com/v1/images/generations \
      -H "Authorization: Bearer $OPENAI_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"model": "gpt-image-2", "prompt": "your prompt here", "size": "1024x1024"}' \
      -o generated_image.json
   ```
4. **关注 issue 进展**：github.com/openai/codex/issues/32297，官方修复后第一时间更新

* * *

![](https://news-static.qiniu.com/legacy/images/0b/0bed130d03cf19bbd1ad446d6aa25158fa4ce0e430751d56b3f096a4f1da26b5.jpg)

## 原因四：使用第三方 API 提供商，gpt-image-2 未映射

如果你通过第三方 API 网关（将 `base_url` 指向非 `api.openai.com` 的地址），图片生成失败的原因往往是提供商的模型列表中没有映射 `gpt-image-2`。

### 验证方法

先直接测试官方端点：

```bash
# 测试官方端点
curl https://api.openai.com/v1/images/generations \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{"model": "gpt-image-2", "prompt": "test", "size": "1024x1024"}'

# 测试第三方端点（将 YOUR_BASE_URL 替换为实际地址）
curl YOUR_BASE_URL/v1/images/generations \
  -H "Authorization: Bearer $YOUR_KEY" \
  -d '{"model": "gpt-image-2", "prompt": "test", "size": "1024x1024"}'
```

- 官方端点 200、第三方端点报错 → 提供商未映射该模型
- 两者都 200 → 问题不在提供商层

### 解决选项

1. **切换回官方端点**：确认 `base_url` 为 `https://api.openai.com/v1`
2. **选择已映射 gpt-image-2 的提供商**：向提供商确认其模型列表是否包含图片生成模型
3. **使用统一多模型 API 接入平台**：支持国内直接访问的多模型 API 服务（如七牛云大模型广场 qiniu.com/ai/models）提供统一 Key，可避免多个提供商分散管理的问题；接入时确认图片生成模型的支持范围

* * *

## 完整排查流程

遇到 Codex 图片生成失败，按以下顺序逐步排查，找到第一个"是"即停止：

1. **是否用的 Codex Cloud？** → 先去检查 Internet Access 白名单，添加 `api.openai.com`
2. **是否用的 Codex Desktop，且 2026-07-09 后更新过？** → 大概率是端点 bug，暂时改用 Cloud 或 Shell 直接调用
3. **是否在代码里直接调用？** → 确认 API 类型：Image API 的 model 字段填 `gpt-image-2`，Responses API 的 model 字段填对话模型
4. **是否通过第三方提供商？** → 先用官方端点测试，确认是否提供商侧未映射
5. **以上都排除了？** → 访问 status.openai.com 确认服务是否降级，记录错误文本/request ID 后向官方提交 issue

* * *

## FAQ

**Q：Codex Cloud 把 api.openai.com 加白名单有安全风险吗？**

有一定风险。官方文档明确提到启用外网访问后存在"从不受信任网页内容发起 prompt injection"和"代码或密钥泄露"的可能性。建议只添加具体需要的域名，不要选"All (unrestricted)"，同时限制 HTTP 方法——图片生成只需要 POST，可以不开放 GET 以外的其他方法，根据需要精确配置。

**Q：Responses API 的 image\_generation 工具和 Image API 哪个更适合 Agent 场景？**

在 Agent 场景中优先用 Responses API + `image_generation` 工具：它与对话上下文天然打通，支持 `previous_response_id` 保持多轮状态，可以根据上下文自动判断是生成还是编辑（`action: "auto"`），且支持流式预览。Image API 更适合代码中独立调用、不依赖对话历史的场景。

**Q：Codex Desktop 的端点 bug 什么时候会修复？**

截至 2026-08-20，GitHub Issue #32297 尚未有官方人员回应或修复 PR。建议关注该 issue 或订阅 OpenAI 状态页（status.openai.com）的 Codex 相关通知。如果是生产环境，建议暂时切换到 Shell 直接调用 Image API 的方案，不依赖内置 `image_gen` 工具。

**Q：Codex CLI 在本地运行时也会有沙箱网络限制吗？**

Codex CLI 本地运行时默认使用"workspace-write"沙箱保护文件系统，但网络限制的级别与 Cloud 不同——CLI 本地模式下通常不阻断外网访问，但具体权限取决于运行模式（`--approval-mode` 设置）。如果 CLI 也报网络错误，检查 `--approval-mode` 配置或 `codex.md` 中的权限设置。

* * *

## 结语

Codex 图片生成失败最高频的原因是 Cloud 沙箱的网络白名单缺失，其次是 Responses API 与 Image API 的调用方式混淆，2026-07-09 Desktop 更新引入的端点 bug 也在持续影响部分用户。解决思路很简单：先用官方端点直接测试一次 `curl`，30 秒内就能判断问题出在哪一层，再针对性地修。

**数据来源**（2026-08-20）：

- Codex Cloud 网络配置文档：learn.chatgpt.com/docs/cloud/internet-access
- OpenAI Responses API image\_generation tool：developers.openai.com/api/docs/guides/image-generation
- GitHub Issue #32297（端点 bug 报告）：github.com/openai/codex/issues/32297
- gpt-image-2 错误分析：blog.laozhang.ai/en/posts/gpt-image-2-does-not-exist-codex-error

* * *

## 延伸阅读

- Codex Cloud 网络访问配置：[https://learn.chatgpt.com/docs/cloud/internet-access](https://learn.chatgpt.com/docs/cloud/internet-access)
- OpenAI Image 生成文档：[https://developers.openai.com/api/docs/guides/image-generation](https://developers.openai.com/api/docs/guides/image-generation)
- GitHub Issue #32297（Desktop 端点 bug）：[https://github.com/openai/codex/issues/32297](https://github.com/openai/codex/issues/32297)
- OpenAI 服务状态页：[https://status.openai.com](https://status.openai.com)
- 七牛云大模型广场（多模型统一 API 接入）：[https://www.qiniu.com/ai/models](https://www.qiniu.com/ai/models)
