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

API网关LLM 网关后端【免费下载链接】ccxClaude / Codex / Gemini API Proxy - CCX项目地址https://gitcode.com/gh_mirrors/cc/ccx点击查看免费下载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 专用的上游渠道打开 CCX 管理界面进入Responses入口点击「添加渠道」根据上游能力选择服务类型上游能力服务类型说明原生 OpenAI ResponsesResponses直接转发 Responses 协议OpenAI Chat 兼容OpenAI ChatCCX 将 Responses 转换为 Chat CompletionsClaudeClaudeCCX 将 Responses 转换为 Claude Messages如果上游是 Chat 兼容端点且不支持developer等非标准 Chat role建议编辑渠道并启用规范化非标准 Chat role。该开关的底层实现位于 backend-go/internal/converters/chat_roles.goNormalizeNonstandardChatRolesInRequest会把请求中的非标准 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 都使用下面这组值两者无需区分两套配置配置项值API Keyyour-ccx-proxy-keyBase URLhttp://localhost:3000/v1Model客户端请求模型名例如gpt-5::: 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 通过常量时间比较校验客户端携带的 KeyIsValidProxyAccessKey见 env.go并支持EXTRA_PROXY_ACCESS_KEYS配置多个附加代理密钥。生产环境务必把PROXY_ACCESS_KEY改为自定义强密钥而不是沿用默认占位值。三、Codex CLI 配置在终端中设置环境变量后直接运行export OPENAI_API_KEYyour-ccx-proxy-key export OPENAI_BASE_URLhttp://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 配置并填写设置项值API Keyyour-ccx-proxy-keyBase URLhttp://localhost:3000/v1Modelgpt-5或你的映射模型名CLI 与 App 的差别仅是填写位置不同CLI 在终端环境变量或配置文件中填App 在图形界面的模型/Provider 设置里填。五、模型映射建议Codex 默认可能请求 GPT 模型名。如果上游使用不同模型名建议在 Responses 渠道里配置模型映射请求模型匹配映射到上游模型示例gpt上游主力模型mini上游轻量模型::: 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检查优先查看当前环境变量是否设置了OPENAI_API_KEY它可能覆盖你在 Codex 配置里填写的 Keyprintenv OPENAI_API_KEYOPENAI_API_KEY或 App 中的 API Key 是否等于 CCX 的PROXY_ACCESS_KEY是否误填了上游厂商 API KeyCCX 服务是否使用了同一个PROXY_ACCESS_KEY启动补充说明如果 CCX 启动了EXTRA_PROXY_ACCESS_KEYS多密钥模式则必须同时配置独立的ADMIN_ACCESS_KEY且附加密钥不能等于主PROXY_ACCESS_KEY或管理密钥校验逻辑见 env.go。排查 401 时先确认你填写的 Key 属于主密钥或附加密钥之一。返回 404 或接口不存在检查 Base URL。正确export OPENAI_BASE_URLhttp://localhost:3000/v1不要填写export OPENAI_BASE_URLhttp://localhost:3000 export OPENAI_BASE_URLhttp://localhost:3000/v1/responsesBase URL 只填到/v1前缀即可Codex 客户端会自动在其后拼接/responses路径如果误填了完整入口路径或裸根地址请求会命中不存在的路由而返回 404。返回 model_not_found检查 Responses 渠道模型白名单是否包含请求模型或映射后的上游模型模型映射是否覆盖 Codex 实际请求的模型名上游模型名是否填写为该厂商真实支持的名称Codex 实际请求的模型名可能随版本变化例如带-mini后缀的轻量型号因此既要在白名单中放行映射后的上游模型也要让模型映射键覆盖客户端真实请求的模型名。上游报 role 不支持如果错误中出现developer、tool、system等 role 相关提示编辑 Responses 渠道并启用规范化非标准 Chat role。这对 DeepSeek 等 Chat 兼容上游尤其常见。如第一节所述该开关由 chat_roles.go 的NormalizeNonstandardChatRolesInRequest实现标准 role 原样保留非标准 role 降级为user携带tool_call_id的响应链消息降级为tool。流式输出中断检查上游是否稳定支持流式响应代理或反向代理是否设置了过短超时当前渠道是否已被熔断或频繁 failover客户端是否请求了上游不支持的工具调用或响应格式第 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 网关后端【免费下载链接】ccxClaude / Codex / Gemini API Proxy - CCX项目地址https://gitcode.com/gh_mirrors/cc/ccx点击查看免费下载相关推荐将 Codex CLI / Codex App 接入 CCXResponses 端点配置与故障排查完整指南将 Codex CLI / Codex App 接入 CCXResponses 端点配置与故障排查完整指南 本指南以 docs/en/guide/clientAPI网关LLM 网关后端openai-agents-python Codex 扩展 ThreadOptions 完全指南线程级配置模型与 Codex CLI 映射详解openai agents python Codex 扩展 ThreadOptions 完全指南线程级配置模型与 Codex CLI 映射详解 导读 Thre人工智能AI AgentAgent 框架多智能体工具调用MCP Clients如何把Claude Code和Codex接入CCX多模型API代理配置完全指南如何把Claude Code和Codex接入CCX多模型API代理配置完全指南 CCX 是一款多模型 API 代理网关Claude / Codex / GeAPI网关LLM 网关后端上一篇RxDB 本地优先Local-First / Offline First架构实战指南下一篇Sails 蓝图 Replace 操作如何用 PUT /:model/:id/:association 整体替换集合关联记录创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考