CC Switch 如何区分 Chat Completions 与 Responses

Chat Completions 与 Responses 的字段和事件模型不同，把一个接口的配置直接复制到另一个接口很容易得到 400 或空响应。本文用 CC Switch 的配置边界说明如何识别协议、映射模型字段并用最小请求验证。文中只讨论可在本地复现的步骤，不把单次结果扩展成产品承诺；每个结论都标注前提、证据和无法覆盖的边界。读者可以先完成最小验证，再根据自己的版本、权限和数据补充实验，避免把配置示例误当成普遍结论。

如果你只看“API Key、Base URL、Model”这三个词，会觉得 GPT、Claude 和 Codex 的接入方式差不多。真正配置时，最容易出错的恰恰是这三个字段背后的协议。

Claude Code 常见的是 Anthropic Messages。很多第三方模型服务提供的是 OpenAI Chat Completions。Codex 的部分工作流则可能依赖 Responses 风格的请求、流式事件、工具调用和模型目录。

它们都可以被口头称为“兼容 API”，但兼容的层次并不一样：

能打开 URL，不等于协议兼容
能返回文本，不等于工具调用兼容
能完成一次问答，不等于 Codex 工作流可用

CC Switch 的本地路由价值，就在于为一部分应用和供应商之间做协议转换、模型映射、日志记录和故障处理。但它不是万能翻译器，转换后仍然要用真实任务验收。

名称	在工作流里的角色
GPT 模型	可被 API 调用的上游模型或模型系列
Codex	面向编码任务的应用或 Agent 工作流
CC Switch	管理 Codex 配置、供应商切换和可选本地路由的一层

Codex
  -> CC Switch 写入或接管配置
  -> 上游 API Base URL
  -> GPT 或其他可用模型

Codex Responses
  -> CC Switch 本地路由
  -> Chat Completions 转换
  -> 上游 API

这就是为什么不能直接把 Claude Code 的地址和认证字段复制到 Codex 页面。

二、三种协议先分清

1. Chat Completions

它通常以 messages 数组描述对话，常见结构类似：

{
  "model": "<model-id>",
  "messages": [
    {"role": "user", "content": "只回复 OK"}
  ]
}

2. Responses

Responses 更强调统一响应对象、输出事件、推理内容、工具调用和跨轮状态。对 Codex 这类编码 Agent 来说，文本返回只是最小能力，真正要验证的是：

模型目录能否被 Codex 读取
流式输出是否正常
工具调用 ID 是否保留
推理内容是否被正确处理
并行工具调用是否能回传
结构化输出和错误事件是否符合应用预期

3. Anthropic Messages

这是 Claude 系列常见的协议。它和 Chat Completions、Responses 的字段、认证习惯、工具定义和响应事件不同。CC Switch 官方当前文档也提供了本地路由攻略，用于在特定应用之间转换协议；是否需要转换，要由目标应用和上游供应商的实际能力决定。

三、先判断 Codex 能不能直连

检查项	能直连的表现	需要路由的信号
模型目录	Codex 能读取可用模型	模型列表为空或字段不全
工具调用	工具 schema 和响应事件匹配	纯文本可以，工具调用失败
流式输出	事件顺序和 ID 正常	卡住、乱序或 400
用量统计	请求能被正确记录	请求成功但用量为空

原则很简单：

你只想做一次纯文本测试，可以先验证最小请求，但不要把它当成生产兼容性结论。

四、在 CC Switch 中添加 Codex 供应商

第一步：确认选中 Codex

打开 CC Switch，切换到 Codex 应用页面。不要在 Claude Code 页面创建一个名为 GPT 的供应商，然后期待 Codex 自动读取。

第二步：选择预设或自定义

自定义时重点确认：

字段	处理方式
API Format	明确选 Responses、Chat Completions 或预设要求的格式
Model Mapping	将 Codex 请求的模型名映射到真实上游 ID
Local Route	只有协议不匹配或需要代理能力时打开

第三步：不要照抄 Claude Code 的 URL

Claude Code 的 URL 可能指向 Messages 兼容路径。Codex 需要的路径和字段可能不同。常见错误是把一个完整接口路径复制到 Base URL，导致 CC Switch 再拼接一次，最后出现类似：

/v1/chat/completions/chat/completions
/v1/responses/responses

第四步：配置模型映射

模型映射解决的是“应用叫法”和“上游真实模型 ID”不一致的问题。例如：

Codex 请求模型：gpt-coding-default
        -> CC Switch 映射
上游 API 上游模型：<当前控制台显示的真实模型 ID>

不要把不存在的模型 ID 写进映射。也不要把一个只能文本输出的模型映射给依赖工具调用的 Codex 任务。

五、什么时候打开本地路由

在 Codex 供应商配置里，如果看到类似“需要本地路由映射”“启用代理接管”或“协议转换”的选项，先读当前版本说明再决定。一般在下面情况打开：

需要 CC Switch 统一记录调用日志和用量。
需要故障转移或备用模型。
需要把多个应用的调用统一收口到本机。

打开后重点检查：

本地路由是否已启动。
监听地址是否仍为 127.0.0.1。
端口是否被其他进程占用。
Codex 供应商是否显示为已启用。
Codex 的 live 配置是否已指向本地代理。
用量页或诊断日志是否出现请求。

官方 CC Switch v3.18.0 的发布说明中提到，本地路由用于协议转换、模型映射和部分应用接入，也修复了 Responses 与 Chat 转换中的推理内容、并行工具调用和工具 schema 问题。版本更新会改变实现细节，生产环境不要只凭旧截图判断。

官方参考：

CC Switch 官方仓库
CC Switch v3.18.0 Release
官方 Claude/Codex 路由说明

六、Codex 的验证顺序

第 1 步：只测文本

只回复 OK，不读取文件，不调用工具，并告诉我当前模型名称。

第 2 步：只读项目

只列出当前项目根目录的文件名，不创建、修改或删除任何文件。

第 3 步：让 Codex 解释一个小文件

读取 README.md，只总结它的安装步骤，不要修改文件。

第 4 步：验证工具调用

在测试项目中让 Codex 执行一个无副作用命令，例如查看当前目录或运行只读测试。不要第一步就让它改生产代码。

第 5 步：检查用量

请求时间对应当前测试
模型名称没有变成默认模型
Token 统计不是空值
没有重复计费
如果开启本地路由，请求确实经过本地入口

七、常见问题

1. 401 Unauthorized

检查 Key 是否有效、是否带空格、是否填到了 Codex 的正确供应商，以及本地路由是否读取到了新的 Key。不要在公开日志中打印完整 Key。

2. 404 或 `/responses` 不存在

3. 模型列表为空

检查模型目录、模型 ID 和本地路由映射。某些版本的 Codex 会严格解析模型目录，字段不完整时可能表现为启动失败或模型不可见。

4. 能回复文字但工具调用失败

这不是“链路完全可用”。重点看工具 schema、工具调用 ID、流式事件和模型是否支持工具。先用一个简单只读工具测试，再决定是否用于真实编码。

5. 请求成功但用量页没有记录

6. 官方 Codex 功能失效

第三方供应商接入通常只解决模型调用，不一定包含官方账户、云端任务、远程执行或官方插件能力。需要这些能力时，保留官方配置作为回退，并按工具官方说明使用。

八、适合怎么分工

如果你同时使用 Claude Code 和 Codex，可以把任务拆开：

工具	更适合
Claude Code	复杂项目理解、多文件重构、长上下文修改
Codex	独立复核、局部修复、测试、PR 或第二意见
CC Switch	在多个应用之间切供应商、启用路由和查看状态

不要让两个 Agent 同时修改同一个工作区。更稳的方式是一个负责方案或主改动，另一个负责只读检查和验收。

九、企业级接入建议

团队使用时，建议把 Codex 的供应商配置拆成环境：

dev：开发测试，允许低成本模型。
staging：验证工具调用、流式输出和日志。
prod：限制 Key、模型和预算，保留人工审批。

通过企业级 API 网关统一接入时，至少追踪应用、项目、成员、模型、Token、请求结果和错误类型。不要只看月底账单，最好在单次调用超预算或重复重试时就告警。

总结

Codex 需要什么协议
上游 API 当前提供什么协议
CC Switch 是否需要本地转换
模型目录和工具调用是否真的通过

结论

本文给出了问题定位、配置或验证的可执行路径。实际结果仍取决于当前版本、权限和运行环境，提交前应按官方文档复核可变字段，并保留失败证据和回滚边界。