OpenAI Codex 是一款强大的 AI 编程助手,支持桌面 App 和 CLI 两种形式。本文介绍如何将 Codex 接入第三方 API,实现灵活的模型切换。
桌面版 vs CLI
Codex 有两种使用形式:
桌面 App:图形界面,左侧有项目列表,支持可视化 diff 审查,适合 Windows 用户日常使用
CLI:纯终端运行,适合 Linux/macOS 开发者、SSH 远程操作或脚本自动化场景
两者共用同一套配置文件,本文的配置方法对两者均适用——包括桌面版,同样可以接入第三方 API。
⚠️ 重要:协议变更(2026 年 2 月)
接入第三方 API 最大的坑是协议不匹配,而且这一情况在 2026 年 2 月发生了重大变化。
当前版本(2026 年 2 月之后)只支持 Responses API。
Codex 最初同时支持两种协议,可通过 wire_api 字段切换:
注意:网上大量 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 --versionWindows 官方支持偏"实验性",建议在 WSL 环境下使用 CLI,或直接使用桌面 App。
配置文件位置
如果文件不存在,手动创建 .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"常见报错排查
总结
Codex 接入第三方 API 的核心是三步:
在
config.toml里定义[model_providers.xxx]块,指定base_url,不要设置wire_api = "chat"(已移除)在
[profiles.xxx]里绑定model和provider在
.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 与效率专栏!
评论