先从一个具体场景说起。你装好了 Codex，想让它跑在国产模型上，于是把配置里的 Base URL 改成国内服务商的地址，API Key 填好，回车，终端里弹出一个干脆利落的 

。Key 没错，地址没错，网络也通。问题出在哪？

答案有点反直觉：出在"语言"上。Codex 发出的请求打在 

 这个路径上，走的是 OpenAI 2025 年推出的 Responses API；而国产模型的服务端几乎只认识 

，也就是 Chat Completions API。这两套接口路径不同、请求体不同、流式事件的格式也不同，属于两种协议。服务商的服务器上压根没有 

要理解这件事为什么会发生，得先看一遍今天的大模型 API 版图。

一、先看版图：三家自研协议，外加一门"普通话"

市面上的模型服务商有几十家，但按接口协议划分，格局其实很清晰：OpenAI 自家现在跑着两条线（新的 Responses API 和老的 Chat Completions），Anthropic 用自家的 Messages API，Google Gemini 用自家的 generateContent，剩下最大的一股势力，是 

这个格局不是谁规划出来的，是市场自己长出来的。2023 年 OpenAI 的 Chat Completions 接口因为足够简单，被一波接一波的开源模型、推理框架照搬，最后变成了无人宣布、但人人都遵守的事实标准。国产模型入场时，直接提供同形状的接口，是获客成本最低的选择——开发者拿现成的 SDK 改个 Base URL 就能跑。

问题在于，标准停在了 2023 年，模型没停。2025 年 OpenAI 自己换了一套新协议（Responses API），Anthropic 的编程客户端 Claude Code 也让 Messages API 变成了"智能体客户端协议"。于是出现了开头那一幕：客户端往前走了，兼容阵营还留在原地，中间的裂缝只能靠代理填。

二、Chat Completions：一个接口怎么成了"普通话"

2023 年 3 月，OpenAI 随 gpt-3.5-turbo 推出 Chat Completions 接口。它的设计简单到近乎吝啬：请求是一个 

 数组，每个元素带角色（system / user / assistant）和内容；响应是 

POST /v1/chat/completions
Authorization: Bearer sk-xxxx

{
  "model": "deepseek-chat",
  "messages": [
    { "role": "system", "content": "你是一个简洁的助手。" },
    { "role": "user",   "content": "北京今天天气怎么样？" }
  ],
  "tools": [{
    "type": "function",
    "function": { "name": "get_weather", "parameters": { "city": "string" } }
  }],
  "stream": true
}

它赢在门槛低。一条 curl 就能调通，任何语言十行代码就能封装 SDK。更重要的是时机：2023 到 2024 年，Llama、ChatGLM、通义、Mistral 等开源模型密集发布，配套的推理框架 vLLM、Ollama 默认暴露的就是这个接口。模型要进生态，就得说这门"普通话"，于是它越传越广。

但它的天花板也写在设计里。Chat Completions 本质是个

。服务端不记任何东西，多轮对话全靠客户端把完整历史拼进 

 只是告诉模型"你可以建议调用这些函数"，模型返回 

 后，真正执行函数、把结果塞回对话，全是客户端的活。第三，

。2024 年推理模型（o1 一类）出现后，模型的"思考"内容没有标准字段可放，各家只能塞自定义字段——DeepSeek 用 

，别家又是别的名字，SDK 层根本没法统一。

简单说，Chat Completions 是一台"复读机+建议器"，而 Agent 需要的是一台"执行器"。

三、Responses API：OpenAI 拆掉地基重建

2025 年 3 月，OpenAI 发布 Responses API，同时宣布老一代的 Assistants API 将于 2026 年 8 月退役。官方给它的定位很直白：Chat Completions 的简单性，加上 Assistants 的托管能力。Codex（无论是 CLI 还是云端版本）说的就是这套协议。

它相对 Chat Completions 的变化是结构性的：

POST /v1/responses
Authorization: Bearer sk-xxxx

{
  "model": "gpt-5",
  "instructions": "你是一个简洁的助手。",
  "input": [
    { "role": "user",
      "content": [ { "type": "input_text", "text": "北京今天天气怎么样？" } ] }
  ],
  "tools": [ { "type": "web_search" } ],
  "previous_response_id": "resp_abc123"
}

不再是"消息进、消息出"：请求侧是 

 数组，里面可能是文本、函数调用、推理条目，各有各的类型。

，上下文就由 OpenAI 那边接着，客户端不必每轮搬运全量历史。

分两类：你自己定义的 function，和 OpenAI 托管的内置工具——web_search、file_search、code interpreter、computer use，模型在服务端直接执行，不需要你的代码插手。

有专门的条目类型，多轮之间可以保留，这对 o 系列这类模型的连续推理质量是实打实的影响。

流式格式也换了。Chat Completions 的流式是一堆没有名字的 JSON chunk，靠 

 收尾；Responses 的流式是带语义的事件：

# Chat Completions 的 SSE：只有裸 chunk
data: {"choices":[{"delta":{"content":"北京今天"}}]}
data: {"choices":[{"delta":{"content":"晴"}}]}
data: [DONE]

# Responses 的 SSE：每种事件有名字，客户端按事件类型分发
event: response.created
event: response.output_item.added
event: response.output_text.delta
data: {"delta": "北京今天", ...}
event: response.output_text.delta
data: {"delta": "晴", ...}
event: response.output_text.done
event: response.completed

这套设计明显是冲着 Agent 去的：状态托管、工具托管、推理保留，全是"让客户端变薄"的东西。Codex 这类编程智能体深度依赖这些特性——它把会话状态和工具编排都押在协议层，这也是它不肯降级回 Chat Completions 的原因。

代价是向后不兼容。路径、字段、流式事件全变了。Chat Completions 时代积累的兼容生态，一夜之间对不上新客户端了。

四、Anthropic Messages API：另一种设计洁癖

Anthropic 从未兼容 OpenAI，它的 Messages API 从第一天起就是自己的一套。接口不长，但处处是不同的选择：

POST /v1/messages
x-api-key: sk-ant-xxxx
anthropic-version: 2023-06-01

{
  "model": "claude-sonnet-4-5",
  "max_tokens": 1024,
  "system": "你是一个简洁的助手。",
  "messages": [
    { "role": "user",
      "content": [ { "type": "text", "text": "北京今天天气怎么样？" } ] }
  ],
  "tools": [ { "name": "get_weather", "input_schema": { ... } } ]
}

 是必填的；system 提示词是顶层独立参数，不混进消息列表；消息内容一律用"内容块"（content blocks）表达——文本是 

 块，一条消息里可以混排多种块。流式事件同样是语义化的：

这套协议本来只在 Anthropic 生态内流通，转折点是 Claude Code。这个编程智能体客户端火了之后，Messages API 事实上变成了第二个"智能体客户端协议"。国产厂商的反应很快：通义、智谱、Kimi 等在自家 OpenAI 兼容端点之外，又开了 Anthropic 兼容端点，让 Claude Code 改个配置就能跑国产模型。这是和"OpenAI 兼容"并行的第二条兼容路线。

五、Gemini：自研协议加一层兼容壳

Google 的路数又不一样。Gemini API 的核心端点是 

 组织（一条消息由若干 part 组成，part 可以是文本、图片、函数调用），认证走 API Key 或 Google OAuth，底层还原生支持 gRPC。结构上和 OpenAI、Anthropic 都不同源。

但 Google 清楚生态的分量，所以官方同时提供了一个 OpenAI 兼容端点：把请求发到指定地址，用法和 Chat Completions 一致，Google 内部做转换。换句话说，Gemini 的立场是"我有自己的语言，但也给你配了翻译"。多数用官方 SDK（Google GenAI）的开发者，平时根本接触不到底层协议长什么样。

六、只改 Base URL，到底会错在哪

把四套协议摆在一起看，开头那个 404 就完全清楚了。假设 Codex 直连一个只提供 Chat Completions 的国产端点，会在这些层面依次碰壁：

顺带说一句，Codex 其实留了后门：它的配置文件里有 

 就能降级走 Chat Completions，直连兼容端点。但这属于"能用就行"的妥协——推理模型的中间状态、新版本的特性都得丢掉，部分客户端和版本降级后还有别的问题。所以社区的主流做法仍然是起一个本地代理，让 Codex 继续说 Responses，代理在后面做翻译。

七、协议转换代理：中间那层翻译

翻译层的原理不复杂。本地起一个服务，对 Codex 假装自己是 OpenAI——挂着 

 路由，收 Responses 格式的请求；转过身，把请求改写成 Chat Completions 格式，发给国产模型；回包再逐层翻译回 Responses 的形状。整条链路长这样：

：one-api、它的活跃继任者 new-api，以及 Python 系的 LiteLLM。它们的主业是统一密钥分发、计费、负载均衡，协议转换是附带能力——对外统一 OpenAI 格式，对内适配各家渠道。LiteLLM 的覆盖面最广，也较早支持了 Responses API 的翻译。这类网关适合团队统一管理几十家模型，但对 Codex 这种吃协议细节的客户端，偶尔会有边角料对不齐的情况。

：社区里有一批小项目专门干这一件事，比如 codex-cn-bridge（面向国产主流模型）、codex-bailian-proxy（对接百炼上的国产模型），也有走另一条路线的——把 Responses 翻译成 Anthropic Messages，再借道接模型。它们通常是单文件小服务，几分钟起一个，配置里把 Codex 的 base_url 指过去就行：

# ~/.codex/config.toml（示意）
[model_providers.bridge]
name = "bridge"
base_url = "http://127.0.0.1:8080/v1"   # 指向本地翻译代理
wire_api = "responses"                   # Codex 对代理仍说 Responses

。DeepSeek 已经让 V4-Flash 原生支持 Responses API 格式，还附带一键配置脚本，Codex 直连即可。当然目前是子集实现——不支持 

 这类有状态特性，不支持视觉输入，部分参数会被忽略，但服务端 web_search 是有的。可以预期其他厂商会跟上：与其让社区做翻译，不如自己把协议说了。

短期看，推理层的协议还会继续分裂。原因不难理解：协议是跟着产品能力走的。OpenAI 要做状态托管和多智能体编排，协议里就得有那些字段；Anthropic 的内容块设计服务于它的多模态和工具哲学；各家能力不同构，协议就没法同构。这也是为什么"事实标准"只出现在大家能力趋同的时代——Chat Completions 统一的是"纯聊天"，而今天卖的是 Agent 运行时。

真正在收敛的是工具层。MCP（Model Context Protocol）由 Anthropic 在 2024 年底开源，2025 年被 OpenAI、Google 相继采纳，如今已经是模型接外部工具和数据的事实标准。推理协议各说各话，但接工具的口正在变成同一个——这个分层很健康：上层应用协议竞争，下层连接协议收敛。

做产品调用多家模型的，在代码里包一层适配（Vercel AI SDK、LiteLLM，或者自己写个 provider 抽象），别让任何一家的协议形状渗进业务逻辑。

（Codex、Claude Code 这类）的，优先选原生支持对应协议的厂商或网关，翻译层永远是二等公民。

的，选型时盯紧协议支持矩阵——它支持 Responses 吗？支持到什么程度？这比价格更早决定你能不能接住下一个客户端。

至于开头那个 404，现在的答案很清楚了：要么等厂商把 Responses API 说了，要么在本地养一个翻译。协议分裂的账，总得有人付。

先从一个具体场景说起。你装好了 Codex，想让它跑在国产模型上，于是把配置里的 Base URL 改成国内服务商的地址，API Key 填好，回车，终端里弹出一个干脆利落的 404 Not Found。Key 没错，地址没错，网络也通。问题出在哪？

大模型 API 协议全景： 为什么 Codex 接国产模型，总要绕路

文章摘要： 大模型API协议存在显著差异，导致直接修改Base URL可能引发404错误。当前主流协议分为三类： OpenAI兼容阵营（Chat Completions API）因简单易用成为事实标准，但缺乏状态管理和工具执行能力。 OpenAI Responses API（2025年推出）强化了Agent支持，但路径与格式不兼容旧协议。 Anthropic Messages API和Google

人工智能

编程语言

开发工具

大模型API协议分裂导致Codex改BaseURL直连国产模型报404，核心是Responses与ChatCompletions两套接口不兼容。文章详解四家主流协议差异、流式格式与工具调用区别，并给出三种解决方案：协议转换代理（one-api/LiteLLM）、专用桥接器、厂商原生支持，帮助开发者避开协议翻译陷阱。

负载均衡

服务器

智能体

DeepSeek

路由

Python

Agent

2026上云采购 | AI焕新·智启新局

tione

cngw

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

大模型 API 协议全景：为什么 Codex 接国产模型，总要绕路

大模型 API 协议全景：为什么 Codex 接国产模型，总要绕路

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐

大模型 API 协议全景： 为什么 Codex 接国产模型，总要绕路

大模型 API 协议全景： 为什么 Codex 接国产模型，总要绕路

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐

大模型 API 协议全景：为什么 Codex 接国产模型，总要绕路

大模型 API 协议全景：为什么 Codex 接国产模型，总要绕路