2026最新Codex配置第三方API的实战教程

话说现在很多开发者已经不满足于“和AI聊代码”了，大家更希望的是，AI能直接钻进项目目录里，读文件、改代码、跑命令、甚至帮着分析报错。Codex CLI就是干这个的——它运行在终端里，能理解你的项目结构，在你点头确认后，帮你实打实地完成开发任务。

这篇文章主要面向手里已经有第三方API配置的用户。你手头通常会握有三样东西：

。只要把这三样东西正确填进Codex，它就能通过中转站调用对应的OpenAI模型。

本文以某个典型的API接口服务商的接入流程为例来说明：在控制台充值、创建令牌、选择模型分组，然后把这些信息填到Codex配置里。具体模型端点、可用模型以及计费规则，一切以模型广场展示的为准。

开始前先确认一件事

Codex和普通聊天客户端不完全是一回事。像Chatbox、Cherry Studio这些客户端，通常用的是OpenAI Chat Completions接口，也就是/v1/chat/completions；但Codex现在更适合走OpenAI Responses API，也就是/v1/responses这类接口。

所以在动手配置前，先确认好下面几点：

• 你的中转站是否支持Codex所需的OpenAI Responses API
• 你选的模型是否支持Codex/Responses API调用
• 令牌分组是否覆盖了这个模型
• Base URL是不是OpenAI兼容地址，比如https://xxx.com/v1

如果一个网关只支持普通聊天接口/v1/chat/completions，那它未必能直接跑通Codex。模型名和Key全对，也可能因为接口协议不匹配而失败。

安装前准备

在安装Codex CLI之前，先备好这些内容：

• Node.js和npm，建议用当前LTS版本
• 稳定的网络连接
• 第三方API账户余额大于0
• 控制台生成的API Key
• 从模型广场复制的完整模型名
• 平台提供的Base URL，比如https://xxx.com/v1

Windows用户要额外注意：Codex可以在PowerShell里跑；如果遇到路径、权限、脚本或依赖的问题，可以考虑用WSL2。

安装 Codex CLI

Windows

1. 安装Node.js，建议选当前LTS版本。
2. 打开PowerShell。
3. 执行安装命令：

npm i -g @openai/codex

安装完成后验证：

codex --version

能看见版本号，说明命令已经可用了。

macOS

macOS可以用npm安装：

npm i -g @openai/codex
codex --version

如果习惯Homebrew，也可以按Codex官方页面里的Homebrew方式安装。装完直接用下面命令验证：

codex --version

Linux

Linux先装好Node.js和npm，不同发行版的命令会略有差异。准备妥当后执行：

npm i -g @openai/codex
codex --version

如果安装时报权限错误，再考虑用sudo或者调整npm全局安装目录。

配置思路

Codex的配置文件通常就在用户目录下：

~/.codex/config.toml

Windows下通常是：

C:Users你的用户名.codexconfig.toml

登录凭据会缓存在本机。根据配置和系统环境，它可能会存到：

~/.codex/auth.json

也可能存到系统钥匙串或凭据管理器里。新手不需要一下子搞懂所有细节，只要记住：config.toml放模型和Base URL，API Key用登录命令或环境变量提供。

方案一：使用内置 OpenAI Provider

这是最适合普通用户的写法。只要中转站提供了OpenAI兼容入口，就可以继续用Codex内置的openai provider，只把Base URL改成中转站的地址。

第一步：创建配置目录

macOS / Linux：

mkdir -p ~/.codex

Windows可以手动进用户目录，新建.codex文件夹。如果看不到.codex，记得在资源管理器里打开“显示隐藏的项目”。

第二步：写入模型和 Base URL

打开~/.codex/config.toml，写入：

model = "从模型广场复制的模型名"
model_provider = "openai"
openai_base_url = "https://xxx.com/v1"

这里最容易搞错的就是这三项：

• model：不要手打，去模型广场复制完整模型名。
• model_provider：这里保持openai，表示使用Codex内置的OpenAI provider。
• openai_base_url：填中转站提供的Base URL，通常到/v1为止。

注意，不要把完整接口路径写进openai_base_url。也就是说，不要写成：

https://xxx.com/v1/chat/completions
https://xxx.com/v1/responses

Codex要的是Base URL，它会根据自己的协议去拼接具体路径。

第三步：写入 API Key

推荐用Codex登录命令来缓存API Key。macOS / Linux：

export OPENAI_API_KEY="替换成平台生成的完整 API Key"
printenv OPENAI_API_KEY | codex login --with-api-key

Windows PowerShell：

$env:OPENAI_API_KEY="替换成平台生成的完整 API Key"
$env:OPENAI_API_KEY | codex login --with-api-key

这里的Key来自控制台的「密钥管理」。不要改大小写，不要手动补前缀，也不要只复制前几位。

如果你明确想让Codex把凭据存到auth.json，可以在config.toml里加一行：

cli_auth_credentials_store = "file"

然后重新执行登录命令。auth.json里包含密钥或登录凭据，千万别提交到Git仓库，也别发到群聊或工单里。

第四步：验证登录和配置

先看看登录状态：

codex login status

再进入一个项目目录：

cd your-project-folder
codex "请只回复 OK"

如果能正常返回，再做一个只读测试：

codex "先阅读这个项目结构，不要修改文件，只告诉我主要目录分别做什么"

方案二：使用自定义 Provider

如果不想把中转站Key放进Codex的OpenAI登录缓存，或者需要同时配置多个网关，可以使用自定义provider。

先设置环境变量。macOS / Linux：

export CODEX_PROXY_API_KEY="替换成平台生成的完整 API Key"

Windows PowerShell：

$env:CODEX_PROXY_API_KEY="替换成平台生成的完整 API Key"

然后在~/.codex/config.toml里写：

model = "从模型广场复制的模型名"
model_provider = "third_party"

[model_providers.third_party]
name = "Third Party API"
base_url = "https://xxx.com/v1"
env_key = "CODEX_PROXY_API_KEY"
wire_api = "responses"

这几个字段分别表示：

• model_provider = "third_party"：告诉Codex使用下面定义的provider。
• [model_providers.third_party]：provider的具体配置，名字要和上面一致。
• base_url：中转站提供的Base URL，通常到/v1。
• env_key：从哪个环境变量读取API Key。
• wire_api = "responses"：Codex使用Responses协议。

如果你只是配一个中转站，新手优先用方案一。方案二更适合多网关、多Key或团队脚本的场景。

启动与基本使用

进入你的项目目录：

cd your-project-folder
codex

也可以在命令后直接跟一个初始任务：

codex "先阅读这个项目结构，告诉我主要目录分别做什么"

第一次使用，不建议马上让Codex大范围改代码。更稳妥的方式是先让它只读项目、输出计划，你再决定要不要让它动手。

推荐的使用习惯

先读项目，再改代码

可以这样问：

先扫描项目结构，列出你会读取哪些文件、准备修改哪些文件，等我确认后再动手。

这样你能先看到它的判断，避免它一上来就改错方向。

一次只交给它一件事

不要一条指令里同时让它“重构登录、修复支付、顺便优化页面”。更合适的做法是：

• 修一个明确的bug
• 加一个小功能
• 解释一段代码
• 写一组测试

任务越清楚，结果越容易验收。

用 Git 做检查点

Codex会改文件，所以每次开始前最好先确认工作区状态：

git status

重要任务前可以先提交一次，或者至少保证你知道哪些文件已经被修改。这样就算结果不理想，也能轻松回滚。

VS Code 里怎么用 Codex

如果你使用VS Code、Cursor或Windsurf，可以安装Codex IDE扩展。一般流程是：

1. 先在终端里完成Codex CLI配置。
2. 安装Codex IDE扩展。
3. 打开项目目录。
4. 从侧边栏启动Codex。

如果侧边栏里无法正常问答，先回到终端执行：

codex "请只回复 OK"

终端能跑通，说明API、Base URL和模型配置大概率没问题；插件侧再排查登录状态、权限或扩展版本。

常见问题与排查

Q1：codex: command not found

通常是npm全局安装路径没有加到PATH里，或者安装失败。先运行：

codex --version

如果仍旧找不到，重新安装：

npm i -g @openai/codex

Q2：安装时报权限错误

macOS / Linux可以临时用：

sudo npm i -g @openai/codex

更长期的做法是把npm全局目录改到用户目录，但这属于Node.js环境配置，不是Codex专属问题。

Q3：配置了 Key 但仍提示未认证或 401

按顺序检查：

1. API Key是否复制完整。
2. Key是否仍然有效。
3. 账户余额是否大于0。
4. 令牌分组是否支持当前模型。
5. 方案一是否已经执行codex login --with-api-key。
6. 方案二的环境变量名是否和env_key完全一致。

Q4：404、接口不存在或请求路径错误

重点看Base URL和接口协议：

• openai_base_url / base_url通常填到https://xxx.com/v1
• 不要填/v1/chat/completions
• 不要填/v1/responses
• 确认中转站支持Responses API

如果中转站只支持Chat Completions，普通聊天客户端可能能用，但Codex不一定能用。

Q5：报model not found

这通常不是Codex本身坏了，而是模型名不匹配。去模型广场复制完整模型名，别用自己猜的简称。

同时确认你的令牌分组支持这个模型。不同分组对应的资源渠道、稳定性、质量和价格可能都不一样。

Q6：config.toml写了但没有生效

常见原因有四个：

• 文件不在~/.codex/config.toml
• TOML格式写错了
• 修改后没有重新打开终端
• 自定义provider的名字不一致

如果用了自定义provider，要确认：

model_provider = "third_party"

和：

[model_providers.third_party]

这两个名字必须一致。

Q7：一直超时或返回很慢

可能原因包括：

• 当前模型本身比较慢
• 分组资源繁忙
• 网络袋里不稳定
• 上下文太长
• 中转站对流式响应或Responses API支持不完整

先用请只回复 OK这种短请求测试。如果短请求都慢，再考虑换模型、换分组或者检查网络。

Q8：怎么升级 Codex CLI？

执行：

npm i -g @openai/codex@latest

升级后再运行：

codex --version

总结

Codex通过中转站调用OpenAI模型，本质上还是三件事：

和普通聊天客户端相比，Codex更需要注意接口协议。配置时不要只看有没有/v1/chat/completions，还要确认中转站是否支持Codex所需的Responses API。新手优先用内置openai provider加openai_base_url的方案；需要多网关或独立环境变量时，再使用自定义provider。