Codex CLI 接到自定义模型网关踩了哪些坑？

最近在把 Codex CLI 接入自建的模型网关时，发现看似“改个 Base URL + Key”就能搞定的事，实际操作起来却处处是坑。统一管理 API Key、合并调用日志、实现多模型切换……这些需求都指向同一个解决方案：自建 OpenAI-compatible 网关。但真正落地之后，协议差异、鉴权逻辑、流式响应等细节问题接踵而至。

本文结合真实踩坑经历，梳理 Codex CLI 对接自建网关时最容易翻车的 5 个环节，并给出可落地的避坑方案。

1. 协议格式不兼容：Responses API 与 Chat Completions 的鸿沟

Codex CLI 默认走 OpenAI 的 Responses API，而大多数国产模型或自建网关只实现了 Chat Completions。两者在消息结构、工具调用格式、流式事件字段上都有差异，直接转发请求大概率失败。

避坑要点：
– 网关必须做协议转换，把 Codex 的 /v1/responses 请求重写为上游的 /v1/chat/completions。
– 流式响应要重建 SSE 事件，把 delta.content 映射回 Codex 期望的 response.output_text.delta 格式。
– 工具调用（function call）需要双向转换 JSON Schema，否则 Codex 会认为模型不支持工具。

2. 鉴权与 Key 管理混乱

Codex CLI 只认 OPENAI_API_KEY 环境变量，而自建网关通常需要独立的 Gateway Key + 后端 Provider Key 两层鉴权。直接把 Provider Key 写进 Codex 配置，既不安全，也无法实现团队级统一管理。

避坑要点：
– 在网关层做 Key 映射：Codex 用 Gateway Key，网关内部再路由到不同 Provider 的真实 Key。
– 开启 Key 轮换与用量配额，避免单 Key 超额导致整个团队服务中断。

3. 会话状态与上下文丢失

Responses API 支持 previous_response_id 实现多轮对话，而 Chat Completions 依赖完整 messages 数组。网关如果不持久化历史消息，Codex 的连续追问就会断层。

避坑要点：
– 网关用 SQLite 或 Redis 缓存会话 ID 与历史消息，默认保留 7 天。
– 重启服务后会话不丢失，确保 Codex 的长时段任务（如大型重构）不中断。

4. 模型名映射与能力声明不一致

Codex CLI 在启动时会校验模型是否存在并拉取能力列表。自建网关若直接透传模型名，Codex 可能报“model not found”或无法识别工具/结构化输出能力。

避坑要点：
– 网关提供模型别名映射表，例如把 deepseek-chat 映射为 Codex 可见的 gpt-4o-mini。
– 能力声明接口（/v1/models）需返回 Codex 关心的参数，如 supports_tools、supports_vision 等字段。

5. 流式输出与错误恢复机制缺失

Codex CLI 依赖稳定的 SSE 流来实时展示推理过程。自建网关若简单转发，一旦上游中断或网络抖动，Codex 会直接抛出“stream interrupted”错误，且无法自动重试。

避坑要点：
– 网关实现断点续传：记录最后收到的 sequence_id，中断后自动重连并补发缺失事件。
– 对上游错误做友好包装，把 429/500 错误转化为 Codex 可理解的“请稍后重试”提示，避免 CLI 直接退出。

5 步快速验证配置是否可用

安装 Node.js（macOS 用 Homebrew，Windows 推荐 WSL2）。
全局安装 Codex CLI：npm install -g @openai/codex。
部署或选用已支持 Responses API 的网关（如 LLMEX、GodeX）。
配置环境变量：
bash export OPENAI_BASE_URL=http://localhost:3000 export OPENAI_API_KEY=gateway-key
进入项目目录执行 codex，观察是否能正常发起请求并返回流式结果。

踩过上述坑之后，你会发现：Codex CLI 接入自建网关的核心难点不在“能不能通”，而在“通了之后是否稳定、是否可观测、是否能平滑切换多模型”。把协议转换、会话持久化、模型映射、流式重建这几层边界处理干净，才能真正实现“零侵入”地统一管理所有 AI 编码工具。