当 Codex 遇上 AI 中转站：写一个协议转换代理解决 Responses API 的兼容性困境

让 OpenAI Codex CLI 与任何 Chat Completions API 无缝协作

背景：Codex 的新架构带来的兼容性难题

2025 年 4 月，OpenAI 正式开源了 Codex CLI------一个基于终端的 AI 编程助手。作为一个重度终端用户，我第一时间就尝试将其集成到我的工作流中。

然而，在配置过程中我发现了一个关键变化：Codex v0.130+ 默认使用 wire_api = "responses" ，也就是 OpenAI 的 Responses API（/v1/responses），而非传统的 Chat Completions API（/v1/chat/completions）。

这个设计决策的背后是 OpenAI 对新一代 API 的押注：Responses API 原生支持函数调用跟踪、多轮工具对话、自动_truncation 管理等更复杂的功能。但问题在于------绝大多数第三方 API 提供商目前只支持 Chat Completions API。

我的实际困境

我手头有多个 AI 模型渠道的访问权限：

小米赠送的 Token------在 AI 社区很火的活动，赠送了大量额度，但只支持标准 Chat Completions 接口
自建的中转服务 ------基于 Calcium-Ion/new-api 搭建，方便统一管理多个上游渠道
第三方的聚合 API------支持多家模型，但同样是 Chat Completions 协议

当我兴冲冲地配置好 Codex，准备连接这些渠道时，得到的却是一串错误：

bash 复制代码

POST https://xxx/v1/responses
404 Not Found

{"error": {"code": "not_implemented", "message": "Responses API not supported"}}

经过深入排查，我发现 new-api------这个在中转站圈子里使用最广泛的开源项目------截至 v1.0.0-rc.4 仍不支持 Responses API。同样，小米赠送 Token 的官方渠道也仅实现了 Chat Completions 端点。

为了使用新版本的 Codex，我必须直接连接 OpenAI 官方------这意味着放弃已经积累的所有第三方渠道资源。

解决方案：协议转换代理

与其等待所有上游提供商适配 Responses API（这可能需要数月甚至更长时间），不如在本地搭建一个协议转换层。

这就是 api2codex 诞生的原因------一个轻量级的 FastAPI 代理，实时将 Responses API 请求转换为 Chat Completions 请求，并将响应转换回来。

架构设计

整个转换流程包含三个关键环节：

环节	转换内容
请求转换	`input` → `messages`, `instructions` → `system`, `developer` → `system`, 工具格式扁平化 → 嵌套化
流式响应	Chat Completions SSE → Responses API SSE 事件流
工具调用	`tool_calls` 索引追踪 → `function_call` 事件序列

核心实现难点

1. 工具调用协议的差异

Responses API 和 Chat Completions API 在工具调用格式上有微妙但关键的差异：

Responses API（Codex 发送的）:

json 复制代码

{
  "type": "function",
  "name": "exec_command",
  "description": "...",
  "parameters": {...}
}

Chat Completions API（上游需要的）:

json 复制代码

{
  "type": "function",
  "function": {
    "name": "exec_command",
    "description": "...",
    "parameters": {...}
  }
}

如果不做这个转换，工具名称和描述都是空的，模型根本不知道该如何调用工具。

2. 多轮工具对话的消息重组

更复杂的是多轮对话。当 Codex 执行一个任务时，流程是：

用户请求 → 2. 模型决定调用工具 → 3. 工具执行 → 4. 结果返回模型 → 5. 模型生成最终回复

在 Responses API 中，工具调用和结果被表示为 function_call 和 function_call_output 类型的 item。但在 Chat Completions API 中，这需要被重组为：

助手消息：{role: "assistant", content: null, tool_calls: [...]}
工具消息：{role: "tool", tool_call_id: "...", content: "..."}

我的实现使用了一个 pending_tool_calls 列表来收集连续的 function_call 项，在碰到其他类型的 item 时统一 flush，这样就确保了消息顺序的正确性。

3. 流式响应的实时转换

Codex 的终端界面是流式显示的，这意味着代理必须实时转换 SSE（Server-Sent Events）流。这包括：

response.created / response.in_progress ------ 会话开始事件
response.output_text.delta ------ 文本流
response.reasoning_text.delta ------ 推理内容流
response.output_item.added / response.output_item.done ------ 消息/工具调用开始结束
response.function_call_arguments.delta / response.function_call_arguments.done ------ 工具参数流

每个工具调用需要被追踪索引，因为它们在 Chat Completions 的 delta.tool_calls 中是通过 index 字段分批到达的。

快速开始

安装运行

bash 复制代码

# 克隆仓库
git clone https://github.com/talkcozy/api2codex.git
cd api2codex

# 安装依赖
pip install -r requirements.txt

# 配置环境变量
export UPSTREAM_BASE_URL="https://your-api-provider.com/v1"
export UPSTREAM_API_KEY="sk-your-key"
export DEFAULT_MODEL="gpt-4o"

# 启动
python api2codex.py

代理默认监听 0.0.0.0:8000。

配置 Codex

编辑 ~/.codex/config.toml：

toml 复制代码

model = "gpt-5.5"
model_provider = "api2codex"

[model_providers.api2codex]
base_url = "http://127.0.0.1:8000/v1"
env_key = "CODEX_API_KEY"
wire_api = "responses"

设置占位符 API Key（实际认证由代理处理）：

bash 复制代码

export CODEX_API_KEY="placeholder"

模型元数据配置

如果 Codex 提示 "Model metadata not found"，需要创建 ~/.codex/model_catalog.json 来描述模型能力。一个简化示例：

json 复制代码

{
  "models": {
    "gpt-4o": {
      "context_window": 128000,
      "max_output_tokens": 16384,
      "supports_functions": true,
      "supports_vision": true,
      "supports_streaming": true
    }
  }
}

局限与未来

当前版本实现了 Responses API 的核心功能：文本生成、流式传输、函数调用、多轮对话。但以下 Responses API 特性尚未实现：

自动 truncation ------ 当上下文超过限制时的智能截断
推理 effort 控制 ------ reasoning.effort 参数映射
Web search 工具 ------ 内置的网络搜索能力
文件 attachment ------ 上传文件到 Code Interpreter

这些功能大多需要上游 Chat Completions 提供商本身支持，或通过额外的代理层来实现。

为什么不等待官方支持？

你可能会问：既然 new-api 等项目迟早会支持 Responses API，为什么不直接等待？

我的看法是：

时间成本------从 OpenAI 推出 Responses API 到现在已经数月，主流中转项目仍未完整支持，等待可能意味着几个月无法使用新版 Codex
灵活性 ------协议转换代理让 Codex 可以对接任何 Chat Completions 兼容的端点，包括自托管模型、内部 API、甚至本地 LLM
理解价值------实现这个代理的过程让我深入理解了两种 API 的设计哲学差异，这种认知本身就有价值

结语

api2codex 是一个务实的解决方案。它不是要替代 Eventually 会出现的原生支持，而是作为一个桥梁，让我们现在就能用上手头的资源。

如果你也遇到了类似的困境------手上有小米 Token、自建了 new-api、或者有其他只支持 Chat Completions 的渠道------希望这个项目能帮到你。

项目地址 : github.com/talkcozy/ap...

技术栈: Python, FastAPI, httpx, SSE streaming

许可: MIT