OpenAI Codex 是一款强大的 AI 编程助手,支持桌面 App 和 CLI 两种形式。本文介绍如何将 Codex 接入第三方 API,实现灵活的模型切换。

桌面版 vs CLI

Codex 有两种使用形式:

  • 桌面 App:图形界面,左侧有项目列表,支持可视化 diff 审查,适合 Windows 用户日常使用

  • CLI:纯终端运行,适合 Linux/macOS 开发者、SSH 远程操作或脚本自动化场景

两者共用同一套配置文件,本文的配置方法对两者均适用——包括桌面版,同样可以接入第三方 API。

OpenAI Codex 接入第三方 API 与协议适配全栈架构流程图


⚠️ 重要:协议变更(2026 年 2 月)

接入第三方 API 最大的坑是协议不匹配,而且这一情况在 2026 年 2 月发生了重大变化。

当前版本(2026 年 2 月之后)只支持 Responses API。

Codex 最初同时支持两种协议,可通过 wire_api 字段切换:

值

协议

当前状态

"responses"

OpenAI Responses API(/v1/responses)

✅ 当前唯一支持

"chat"

Chat Completions API(/v1/chat/completions)

❌ 已移除

注意:网上大量 2025 年写的教程仍然推荐 wire_api = "chat",这些配置现在全部失效,会导致 404 或连接断开。

第三方中转站怎么办?

大多数中转站(NewAPI、OneAPI 等)实现的是 Chat Completions API,无法直接与当前版本的 Codex 对接。有两条路可走:

方案 1(推荐):选用支持 Responses API 的中转

部分平台(如 OpenRouter 的特定接入方式)已原生支持 Responses API,可以直接配置使用。

方案 2:用 LiteLLM 做协议转换代理

在 Codex 和中转站之间架一层 LiteLLM,将 Responses API 请求翻译成 Chat Completions 格式再转发:

pip install litellm
litellm --model openai/gpt-4o --api_base https://你的中转地址/v1

然后将 Codex 的 base_url 指向 LiteLLM 本地监听地址(默认 http://localhost:4000/v1)。有关 LiteLLM 本地代理容器化部署与模型别名(Model Aliasing)深度实操,可参考实战文章 Claude Code 接入国产大模型实操指南:LiteLLM 适配 Kimi、GLM-4 与 DeepSeek。


安装 Codex CLI

# npm 安装(跨平台推荐)
npm install -g @openai/codex

# macOS Homebrew
brew install codex

# 验证安装
codex --version

Windows 官方支持偏"实验性",建议在 WSL 环境下使用 CLI,或直接使用桌面 App。


配置文件位置

系统

路径

macOS / Linux

~/.codex/config.toml

Windows

C:\Users\你的用户名\.codex\config.toml

如果文件不存在,手动创建 .codex 文件夹和 config.toml 即可。Windows 下看不到 .codex 文件夹需要开启"显示隐藏项目"。


方案 A:最简接入(两个环境变量)

适合只换 API 地址、不需要多 provider 切换的场景:

# 加入 ~/.zshrc 或 ~/.bashrc
export OPENAI_API_KEY=你的中转key
export OPENAI_BASE_URL=https://你的中转地址/v1

注意:使用自定义 provider 时,模型 ID 需要加前缀,例如写 openai/gpt-5.4-mini-codex 而不是 gpt-5.4-mini-codex。


方案 B:config.toml 配置(推荐)

支持多服务商定义,随时切换,配置更清晰。

多 Provider + Profile 完整示例

下面是一份包含 OpenAI 官方、OpenRouter、DeepSeek、Gemini 的完整配置。所有 provider 均需使用 wire_api = "responses",或省略该字段(默认即为 "responses"):

# ~/.codex/config.toml

# 改这一行切换当前使用的服务商
profile = "openrouter"

# ── Provider 定义 ──────────────────────────

[model_providers.openai]
name = "OpenAI Official"
base_url = "https://api.openai.com/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"
disable_response_storage = true

[model_providers.openrouter]
name = "OpenRouter"
base_url = "https://openrouter.ai/api/v1"
env_key = "OPENROUTER_KEY"
wire_api = "responses"

[model_providers.litellm_proxy]
name = "LiteLLM Proxy(中转翻译层)"
base_url = "http://localhost:4000/v1"
env_key = "LITELLM_KEY"
wire_api = "responses"

[model_providers.azure]
name = "Azure OpenAI"
base_url = "https://YOUR_PROJECT_NAME.openai.azure.com/openai"
env_key = "AZURE_OPENAI_API_KEY"
wire_api = "responses"
query_params = { api-version = "2025-04-01-preview" }

# ── Profile 定义 ──────────────────────────

[profiles.official]
model = "gpt-5.5"
model_provider = "openai"

[profiles.openrouter]
model = "openai/gpt-5.5"
model_provider = "openrouter"

[profiles.via_litellm]
model = "gpt-4o"
model_provider = "litellm_proxy"

[profiles.azure]
model = "gpt-5.5"
model_provider = "azure"

切换服务商只需修改第一行 profile = "xxx",重启 App 或终端生效。


API Key 管理

在 ~/.codex/ 目录下创建 .env 文件,将所有 Key 集中存放:

OPENAI_API_KEY=sk-你的key
OPENROUTER_KEY=sk-你的key
LITELLM_KEY=sk-你的key
AZURE_OPENAI_API_KEY=你的key

安全提示:

  • 不要把 Key 直接写进 config.toml,使用 env_key 引用环境变量

  • 不要把 .env 提交到 Git 仓库

  • Key 如果不小心泄露,立即去对应平台重置


验证配置

# 重启终端后测试
codex "用一句话解释递归"

# 指定 profile 临时切换(CLI)
codex --profile openrouter "hello"

常见报错排查

报错

原因

解决方法

401 Unauthorized

Key 未生效或名称不一致

检查 env_key 和 .env 中变量名是否完全一致

404 Not Found

provider 不支持 Responses API

使用支持 Responses API 的中转,或前置 LiteLLM 代理

model not found

模型名写错

以第三方平台实际可用模型名为准,注意加 provider 前缀

stream disconnection

endpoint 兼容性问题

换用支持 Responses API 的 endpoint

command not found

npm 全局路径未加入 PATH

运行 npm config get prefix 查路径后手动添加


总结

Codex 接入第三方 API 的核心是三步:

  1. 在 config.toml 里定义 [model_providers.xxx] 块,指定 base_url,不要设置 wire_api = "chat"(已移除)

  2. 在 [profiles.xxx] 里绑定 model 和 provider

  3. 在 .env 里存放对应的 API Key

切换服务商只需改一行 profile = "xxx",重启生效。

如果你使用的中转站只支持 Chat Completions,需要在前面挂一层 LiteLLM 做协议转换,再将 Codex 指向 LiteLLM 的本地地址。

相关 AI 助手与本地大模型开发阅读:
• Claude Code 接入国产大模型实操指南:LiteLLM 适配 Kimi、GLM-4 与 DeepSeek
• WorkBuddy 自定义模型教程:Claude、OpenAI、DeepSeek 与 Sub2API
• Ollama + Open WebUI 本地大语言模型部署实战:告别云端断连
• 海外数字工具与云服务支付订阅避坑指南:虚拟卡与防封对齐实操
• Claude 中国使用限制全解析:Anthropic 新版支持地区政策三条判定线详解

更多现代 AI 辅助编程与效率工具实战,欢迎持续锁定 AI 与效率专栏!