# Codex CLI 挂在中转上？根因是 Responses API

> https://router.one/zh/codex-responses-api 的 Markdown 镜像，供 AI 助手与爬虫使用。Router One 是 OpenAI 兼容的统一 LLM API 网关。
> 最后更新：2026-08-25

OpenAI 的 Codex CLI 调用的不是经典的 Chat Completions API，而是更新的 Responses API 协议。多数 OpenAI 兼容中转只实现了 Chat Completions，于是同一个 key 在 curl 里正常、放进 Codex 就 404 或报格式错误。Router One 原生实现了 Responses 协议（wire_api = "responses"），改两分钟配置即可跑通。

## 一句话根因

Codex 把请求发往 /responses 风格的路径，请求 schema 也是 Chat Completions 服务端不认识的。只会说 Chat Completions 的中转只能回 404（路径不存在）或 400（字段不识别）。换 key、换模型都救不了协议不匹配——必须网关本身支持。

## 可用的配置

在 ~/.codex/config.toml 里把 Codex 指向 Router One，并在运行 codex 的同一个 shell 里导出密钥：

`config.toml`

```bash
# ~/.codex/config.toml
model_provider = "router"

[model_providers.router]
name = "router"
base_url = "https://api.router.one/v1"
env_key = "ROUTER_ONE_API_KEY"
wire_api = "responses"

# 在 shell 里：
# export ROUTER_ONE_API_KEY=sk-your-router-one-key
```

## 报错排查表

改完配置仍然失败时：

| 症状 | 原因 | 修复 |
| --- | --- | --- |
| 所有请求都 404 | base_url 指向了不支持 Responses API 的中转，或有拼写错误 | base_url 精确设为 https://api.router.one/v1，并保留 wire_api = "responses"。 |
| 401 未授权 | 运行 codex 的 shell 里看不到 ROUTER_ONE_API_KEY | 在同一会话（或 shell profile）里导出密钥，重启终端后再运行 codex。 |
| 模型不存在 | 模型 ID 与目录不一致 | 从 /models 页复制精确 ID——区分大小写。 |
| 402 余额不足 | 钱包或 Key 消费上限用尽 | 充值，或在 Dashboard → API Keys 调高 maxSpend。 |
| 配置像是没生效 | Codex 读的配置文件不是你改的那个 | 确认文件位于 ~/.codex/config.toml（Windows：%USERPROFILE%\.codex\config.toml）。 |
| 400 里提到 background 或 image_generation | Codex 请求了后台执行或 image_generation 工具——这是网关不提供的两项 Responses 特性 | 关掉 background 模式；图片生成改走 POST /v1/images/generations。hosted 工具与 previous_response_id 在原生走 Responses 的模型上照常可用。 |
| 400 提示模型必须走 /v1/messages | 你在 Codex 里填了 Claude 家族的模型 ID；Claude 在 Anthropic 兼容端点和 /v1/chat/completions 上服务，不在 /v1/responses 上 | 换成详情页列出 POST /v1/responses 的模型（GPT 系列或 DeepSeek V4）。要用 Claude 请改用 Claude Code。 |
| codex-auto-review 报模型不存在 | Codex CLI 的 review 线（/review 与自动审查）会以模型 ID codex-auto-review 发请求，除非 config.toml 里的 review_model 改了它；只认自家模型清单、或只实现 Chat Completions 的中转会拒绝这个 ID | Router One 侧无需改动——codex-auto-review 就在目录里，走 /v1/responses 与 /v1/chat/completions，价格见 /models/codex-auto-review。想用别的模型审查，在 ~/.codex/config.toml 里设置 review_model。 |

## Responses 端点接受什么、拒绝哪两样

Router One 自己实现了 Responses 协议，服务对象是模型详情页列出 POST /v1/responses 的模型（GPT 系列与 DeepSeek V4）。下表按请求特性列出当前行为；凡是接受的，都按原样转发、按该模型标准费率计费。

| 请求特性 | 状态 | 说明 |
| --- | --- | --- |
| function 工具（Codex 默认的工具形态） | 接受 | 结构化工具调用作为一等 Responses 输出项返回。 |
| custom 工具（Codex 的 freeform apply_patch 等） | 原生走 Responses 的模型上接受 | 请用详情页列出 POST /v1/responses 的模型；其他模型返回 400 invalid_request。 |
| previous_response_id / conversation / prompt（服务端上下文引用） | 原生走 Responses 的模型上接受 | 模型限制与 custom 工具相同；引用在原生路径上解析。 |
| hosted 工具：file_search、code_interpreter、computer_use、mcp、web_search | 原生走 Responses 的模型上接受 | 按原样转发、按该模型标准费率计费——Router One 自身不执行其中任何一项。 |
| 带 file_id 或 file_url 的 input_file 块 | 原生走 Responses 的模型上接受 | 模型限制相同；文件引用随请求一起转发。 |
| service_tier（任意取值） | 接受 | 按原样转发；无论哪个档位都按该模型标准费率计费。 |
| stream / instructions / temperature / max_output_tokens | 接受 | 按原样转发；见 Responses 接口参考。 |
| image_generation 工具与 image_generation_call 输入项 | 拒绝——400 invalid_request | 图片生成不经 Responses 端点开放；请改走 POST /v1/images/generations（见 /image-generation-api）。 |
| background: true | 拒绝——400 invalid_request | 不提供后台执行，也没有 GET /v1/responses/{id} 可事后取回结果；每个请求必须在自己的 HTTP 连接内完成。 |

## 用 trace 验证

请求一旦到达网关，每次 Codex 调用都会出现在 Dashboard → Logs 里，带模型、tokens、花费和状态。如果 Codex 在报错而日志是空的，问题仍在本地——配置路径或环境变量；如果日志里有 4xx 记录，trace 会直接指出撞上的限制。

## 常见问题

### 为什么我的 key 在 curl 里能用，在 Codex 里不行？

curl 测的是 Chat Completions 面；Codex 用的是 Responses API 协议。一个中转完全可以通过 curl 测试、却对 Codex 返回 404。网关必须原生实现 Responses 协议——Router One 支持。

### wire_api = "responses" 到底是干什么的？

它告诉 Codex 用哪种协议形态与该 provider 块通信。设为 "responses" 时，Codex 发送 Responses API 格式的请求；对面的端点必须原生理解它。

### base URL 要不要带 /v1？

要——Codex 用的 OpenAI 兼容 base URL 是 https://api.router.one/v1，包含 /v1。这和 Claude Code 正好相反：Anthropic 兼容 base URL 不带 /v1。

### 通过网关 Codex 能用哪些模型？

原生走 Responses 协议的模型：GPT 系列与 DeepSeek V4（deepseek-v4-pro、deepseek-v4-flash）。用 /models 页的精确模型 ID——每个模型页都会列出是否提供 POST /v1/responses。Claude 模型不在这个端点上：发过来会在调用任何模型之前就拿到 400。

### Codex 里指定 Claude 模型报 400，怎么办？

网关在调用任何模型之前就拒绝了这个请求，消息里直接写明该模型在哪条路径上：model 'anthropic/claude-opus-5' must be called via /v1/messages or /v1/chat/completions。Claude 在 Anthropic 兼容端点（Claude Code 走的那条）和 /v1/chat/completions 上服务，不在 /v1/responses 上。把 Codex 换成 GPT 系列模型或 DeepSeek V4；要用 Claude 就改用 Claude Code——见 /claude-code-china。

### Codex 一直在请求的 codex-auto-review 是什么模型？

这是 Codex CLI 的 review 线（/review 与自动审查）发出的模型 ID，除非 ~/.codex/config.toml 里的 review_model 指向了别的模型。只按自家清单校验模型名、或只实现 Chat Completions 的中转会回 model not found。Router One 的目录里就有 codex-auto-review，请求会像其他模型一样被路由和计费——在 /v1/responses 与 /v1/chat/completions 上可用，当前价格见 /models/codex-auto-review。

### previous_response_id、hosted 工具和 service_tier 经网关能用吗？

能，在原生走 Responses 协议的模型上可用——模型页的端点列表会标明。请求按原样转发、按该模型标准费率计费；只有 background: true 和 image_generation 工具会被 400 拒绝。

### Codex 里调图片生成为什么 400？

图片生成不经 Responses 端点开放，所以 image_generation 工具或 image_generation_call 输入项会在调用任何模型之前被 400 invalid_request 拒掉。图片生成请改走 POST /v1/images/generations——见 /image-generation-api。

### 能后台跑 response 吗？

不能。background 必须省略或为 false；background: true 会返回 400 invalid_request。网关不提供后台执行，也没有 GET /v1/responses/{id}，连接断开后结果无法再取回。

### 中国大陆能用吗？

能。网关在大陆可直连、无需 VPN；上面的 config.toml 在任何地区都完全一致。

## 相关页面

- 错误码速查：https://router.one/zh/llm-api-error-codes#codex-cli-里的报错
- Claude Code 403 排查清单：https://router.one/zh/claude-code-403
- Claude Code 中国大陆接入：https://router.one/zh/claude-code-china
- 中转 API 真伪检测：https://router.one/zh/llm-api-authenticity
- Codex CLI 中国大陆接入：https://router.one/zh/codex-china
- insufficient_quota 修复：https://router.one/zh/openai-insufficient-quota
- Responses 接口参考（POST /v1/responses）：https://router.one/zh/docs/chat/createResponse
- CLI 配置指南：https://router.one/zh/docs/guides/cli-setup
- 图片生成 API：https://router.one/zh/image-generation-api
- 本页规范地址：https://router.one/zh/codex-responses-api
- 模型与每模型 token 价格：https://router.one/zh/models（markdown：https://router.one/zh/models.md）
- 定价：https://router.one/zh/pricing
- API 文档（markdown）：https://router.one/zh/docs.md
- 公司事实（markdown）：https://router.one/zh/facts/company.md