OpenAI Codex CLI 配置第三方 API 完全指南（2026 最新）

本文基于 Codex CLI 0.130.0 版本，记录了配置第三方兼容 API 的完整过程，包括踩坑经验和解决方案。

前言

OpenAI Codex CLI 是一个强大的命令行编程助手，但官方 API 价格不菲，且国内访问不稳定。好在 Codex CLI 支持配置第三方 OpenAI 兼容 API，本文将详细介绍配置方法。

环境准备

• Node.js 18+
• 一个支持 Responses API 的第三方 API 服务

安装 Codex CLI

npm install -g @openai/codex

核心概念：Responses API

Codex CLI 使用的是 OpenAI 的 Responses API（/v1/responses），而不是常见的 Chat Completions API（/v1/chat/completions）。这意味着你的第三方 API 必须支持 Responses API 兼容。

目前主流的 API 管理面板（如 NewAPI、One API 等）已经开始支持 ChatCompletions → Responses 的协议转换功能。如果你使用的中转服务支持这个特性，配置起来会非常简单。

配置方法

方法一：直接配置 config.toml（推荐）

编辑 ~/.codex/config.toml：

model_provider = "custom"
model = "gpt-5.5"
model_reasoning_effort = "high"
disable_response_storage = true

[model_providers.custom]
name = "custom"
wire_api = "responses"
requires_openai_auth = false
base_url = "https://your-api-provider.com/v1"
api_key = "sk-your-api-key"

关键参数说明：

参数	说明
wire_api	必须设为 "responses"，Codex 强制使用 Responses API
base_url	你的 API 地址，注意要带 /v1
api_key	你的 API Key

方法二：环境变量

# Windows CMD
set OPENAI_BASE_URL=https://your-api-provider.com/v1
set OPENAI_API_KEY=sk-your-api-key
codex

# Linux/Mac
export OPENAI_BASE_URL=https://your-api-provider.com/v1
export OPENAI_API_KEY=sk-your-api-key
codex

常见问题排查

1. 401 Unauthorized: Invalid token

原因： Codex CLI 可能没有正确读取你的 API Key。

解决方案：

• 确认环境变量中没有残留的旧 OPENAI_API_KEY（用 echo %OPENAI_API_KEY% 检查）
• 确认 config.toml 中 requires_openai_auth = false
• 尝试删除 ~/.codex/auth.json 和 ~/.codex/sqlite/ 目录后重试

2. stream disconnected before completion

原因： API 服务端的 Responses 兼容层没有正确发送 response.completed 事件。

解决方案：

• 确认 base_url 是否正确（是否需要 /v1 后缀）
• 确认 API 服务端的 Responses 兼容功能已正确启用
• 检查 API Key 对应的分组是否有权限访问目标渠道

3. error sending request for url

原因： 网络连接问题，无法访问 API 地址。

解决方案：

• 如果 API 在海外，需要设置代理：`set HTTPS_PROXY=你的代理地址
• 确认 API 地址是否可以正常访问

4. 403 Forbidden: 无权访问某分组

原因： API Key 的分组与渠道的分组不匹配。

解决方案：

• 在 API 管理后台确认 Key 所属分组
• 确认该分组有权限访问配置了 Responses 兼容的渠道

5. OAuth 相关错误（refresh token / auth.openai.com）

原因： 之前登录过 OpenAI 官方账号，残留的 OAuth token 干扰。

解决方案：

codex auth logout
# 如果还不行，直接删除认证文件
rm ~/.codex/auth.json
rm -rf ~/.codex/sqlite/

推荐的模型选择

对于编程任务，推荐以下模型（按性价比排序）：

1. gpt-5.5 — 最新旗舰，代码能力极强
2. gpt-5.4-mini — 性价比之选，速度快
3. gpt-5.3-codex — 专为代码优化

完整配置示例

以下是一个经过验证的完整配置：

model_provider = "custom"
model = "gpt-5.5"
model_reasoning_effort = "high"
disable_response_storage = true

[model_providers.custom]
name = "custom"
wire_api = "responses"
requires_openai_auth = false
base_url = "https://your-api-provider.com/v1"
api_key = "sk-your-api-key"

[windows]
sandbox = "elevated"

本地代理方案（备选）

如果你的 API 服务不支持 Responses API，可以在本地搭建一个协议转换代理，将 Responses API 请求转换为 Chat Completions API 格式。这个方案稍微复杂一些，但兼容性更好。

核心思路：

1. 本地启动一个 HTTP 服务器监听（如 18888 端口）
2. 接收 Codex 的 /v1/responses 请求
3. 转换为 /v1/chat/completions 格式转发到上游
4. 将响应转回 Responses API 格式返回给 Codex

有兴趣的同学可以参考 GitHub 上的开源实现。

总结

配置第三方 API 的关键点：

1. API 服务必须支持 Responses API（或有兼容层）
2. wire_api = "responses" 不能少
3. requires_openai_auth = false 避免走 OpenAI 官方认证
4. 注意环境变量不要有残留值干扰
5. 网络问题记得配代理

---

如果你在寻找稳定的第三方 API 服务，可以在评论区交流。笔者测试了多家服务商，目前在用的方案延迟低、模型全、支持 Responses API 兼容，有需要的可以私信。

---

参考链接：

• OpenAI Codex CLI 官方文档
• Responses API 文档

---

💡 觉得有帮助的话点个赞收藏一下，后续会更新更多 Codex 使用技巧。