Codex CLI / Codex App 接入 CCX 指南：Responses 入口配置、模型映射与故障排查

• API网关
• LLM 网关
• 后端

CCX 通过 OpenAI Responses 协议为 Codex CLI 与 Codex App 提供统一接入通道：客户端请求先到达CCX /v1/responses，再按渠道配置转发到上游 Responses 或 Chat 端点。本文完整覆盖渠道创建、通用配置值、CLI 与 App 的差异化配置、模型映射策略，并针对 401、404、model_not_found、role 不支持、流式中断等高频问题进行逐项排查。

如果你正在使用CCX Desktop，可先在 Agent Config 中写入 Codex 配置，再回到本页确认 Responses 入口和 Base URL 规则。

工作方式

Codex 客户端（CLI 或 App）与 CCX 之间走 OpenAI 兼容的 Responses 协议，CCX 负责协议转换与上游路由：

Codex CLI / App -> CCX /v1/responses -> Responses 渠道 -> 上游 Responses 或 Chat 端点

从源码看，这条链路在 backend-go/internal/handlers/responses/ 中实现：POST /v1/responses由 Responses 处理器接管（见 handler_response_matrix_test.go），之后根据渠道ServiceType决定是否做协议转换。若上游是原生 Responses 端点则直接转发；若上游是 OpenAI Chat 兼容端点，则由 responses_to_chat.go 中的ConvertResponsesToOpenAIChatRequest将 Responses 输入转换为 Chat Completions 请求体。

一、配置 CCX 渠道

在 CCX 管理界面按以下步骤创建 Codex 专用的上游渠道：

1. 打开 CCX 管理界面，进入Responses入口
2. 点击「添加渠道」
3. 根据上游能力选择服务类型

如果上游是 Chat 兼容端点，且不支持developer等非标准 Chat role，建议编辑渠道并启用规范化非标准 Chat role。

该开关的底层实现位于 backend-go/internal/converters/chat_roles.go：NormalizeNonstandardChatRolesInRequest会把请求中的非标准 role 统一改写为user，而system/user/assistant/tool四个标准 role 保持不变；若非标准 role 的消息携带tool_call_id，则改写为tool以保留 OpenAI tool_calls 响应链的完整性。这一机制对 DeepSeek 等只接受标准 Chat role 的上游尤其关键——Codex 默认请求中常携带developerrole，若上游不支持，要么开启本开关做全量降级，要么依赖自动学习路径中的窄改写DowngradeDeveloperRoleToSystem（仅将developer降为system，语义损失更小）。

二、通用配置值

Codex CLI 和 Codex App 都使用下面这组值，两者无需区分两套配置：

::: tip 这里的 API Key 是 CCX 的PROXY_ACCESS_KEY，不是上游提供商的 API Key。上游 API Key 只配置在 CCX 渠道里。 :::

PROXY_ACCESS_KEY由环境变量注入 CCX 后端，默认值即your-proxy-access-key（见 backend-go/internal/config/env.go）；服务默认监听 3000 端口（PORT默认值 3000，见 env.go），因此本地默认 Base URL 为http://localhost:3000/v1。认证时 CCX 通过常量时间比较校验客户端携带的 Key（IsValidProxyAccessKey，见 env.go），并支持EXTRA_PROXY_ACCESS_KEYS配置多个附加代理密钥。生产环境务必把PROXY_ACCESS_KEY改为自定义强密钥，而不是沿用默认占位值。

三、Codex CLI 配置

在终端中设置环境变量后直接运行：

export OPENAI_API_KEY="your-ccx-proxy-key" export OPENAI_BASE_URL="http://localhost:3000/v1"

然后运行：

codex "你好"

如果你的 Codex CLI 版本使用配置文件而不是环境变量，仍然填写同一组值：

API Key: your-ccx-proxy-key Base URL: http://localhost:3000/v1 Model: gpt-5

四、Codex App 配置

在 Codex App 的模型或 Provider 设置中，选择 OpenAI 兼容 / 自定义 API 配置，并填写：

CLI 与 App 的差别仅是填写位置不同：CLI 在终端环境变量或配置文件中填，App 在图形界面的模型/Provider 设置里填。

五、模型映射建议

Codex 默认可能请求 GPT 模型名。如果上游使用不同模型名，建议在 Responses 渠道里配置模型映射：

::: tip 不要只给gpt-5配高能力模型而忽略gpt-5-mini。CCX 按更长匹配键优先匹配，通常可以用gpt和mini覆盖常见 Codex 模型名。 :::

从路由实现看，模型匹配遵循"更长匹配键优先"的规则：精确的gpt-5-mini会优先于宽泛的mini，而宽泛的gpt又能兜底覆盖gpt-5、gpt-5-mini等一系列前缀模型名。配置时建议同时提供gpt（主力模型）与mini（轻量模型）两个映射键，即可覆盖 Codex 常见请求模型，无需逐个枚举具体版本号。

常见问题

Codex CLI 和 Codex App 是否要分开配置？

不需要。两者使用同一套 CCX OpenAI 兼容配置：

API Key = PROXY_ACCESS_KEY Base URL = http://localhost:3000/v1 Model = 客户端请求模型名

区别只是 CLI 在终端或配置文件里填，App 在图形界面里填。

返回 401 Unauthorized

检查：

1. 优先查看当前环境变量是否设置了OPENAI_API_KEY，它可能覆盖你在 Codex 配置里填写的 Key

   printenv OPENAI_API_KEY

2. OPENAI_API_KEY或 App 中的 API Key 是否等于 CCX 的PROXY_ACCESS_KEY

3. 是否误填了上游厂商 API Key

4. CCX 服务是否使用了同一个PROXY_ACCESS_KEY启动

补充说明：如果 CCX 启动了EXTRA_PROXY_ACCESS_KEYS多密钥模式，则必须同时配置独立的ADMIN_ACCESS_KEY，且附加密钥不能等于主PROXY_ACCESS_KEY或管理密钥（校验逻辑见 env.go）。排查 401 时，先确认你填写的 Key 属于主密钥或附加密钥之一。

返回 404 或接口不存在

检查 Base URL。

正确：

export OPENAI_BASE_URL="http://localhost:3000/v1"

不要填写：

export OPENAI_BASE_URL="http://localhost:3000" export OPENAI_BASE_URL="http://localhost:3000/v1/responses"

Base URL 只填到/v1前缀即可，Codex 客户端会自动在其后拼接/responses路径；如果误填了完整入口路径或裸根地址，请求会命中不存在的路由而返回 404。

返回 model_not_found

检查 Responses 渠道：

1. 模型白名单是否包含请求模型或映射后的上游模型
2. 模型映射是否覆盖 Codex 实际请求的模型名
3. 上游模型名是否填写为该厂商真实支持的名称

Codex 实际请求的模型名可能随版本变化（例如带-mini后缀的轻量型号），因此既要在白名单中放行映射后的上游模型，也要让模型映射键覆盖客户端真实请求的模型名。

上游报 role 不支持

如果错误中出现developer、tool、system等 role 相关提示，编辑 Responses 渠道并启用规范化非标准 Chat role。这对 DeepSeek 等 Chat 兼容上游尤其常见。

如第一节所述，该开关由 chat_roles.go 的NormalizeNonstandardChatRolesInRequest实现，标准 role 原样保留，非标准 role 降级为user，携带tool_call_id的响应链消息降级为tool。

流式输出中断

检查：

1. 上游是否稳定支持流式响应
2. 代理或反向代理是否设置了过短超时
3. 当前渠道是否已被熔断或频繁 failover
4. 客户端是否请求了上游不支持的工具调用或响应格式

第 4 点值得特别留意：Codex 会携带大量工具调用（tool_calls）与自定义工具参数。CCX 在 Responses 转换层提供了codexToolCompat兼容模式（见 responses_to_chat.go 的convertToolsToOpenAIFormat），用于把 Codex 风格工具定义规整为上游可接受的格式。若上游对工具参数 schema 校验严格，可确认渠道/转换配置是否正确应用了该兼容路径。

想确认请求是否走 Responses 入口

查看 CCX 后端日志或渠道日志，请求路径应为：

/v1/responses

如果你看到/v1/chat/completions，说明客户端当前没有走 Codex Responses 配置，而是走了 OpenAI Chat 配置。此时应回到 Codex CLI/App 的 Base URL 配置，确认其指向 CCX 的/v1前缀且客户端选择了 OpenAI 兼容/Responses 模式。

• API网关
• LLM 网关
• 后端