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

作者：袖梨 2026-07-01

现在很多开发者已经不满足于“和 AI 聊代码”了，而是希望 AI 能直接进入项目目录，读文件、改代码、跑命令、解释报错。Codex CLI 就是这类工具：它运行在终端里，可以理解你的项目结构，并在你的确认下完成真实开发任务。

这篇文章面向已经拿到第三方 API 配置的用户。你手里通常会有三样东西：Base URL、API Key、模型名。把这三项正确填进 Codex 后，Codex 就可以通过中转站调用对应的 OpenAI 模型。

本文以 147AI的API 接口文档 的接入流程为例说明：先在控制台充值、创建令牌、选择模型分组，再把 API 地址、密钥和模型名填入 Codex 配置。具体模型端点、可用模型和计费规则，请以模型广场展示为准。

img_6a44768039f8a30.webp

开始前先确认一件事

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://147ai.com/v1

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

安装前准备

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

  • Node.js 和 npm，建议使用当前 LTS 版本
  • 稳定网络连接
  • 第三方 API 账户余额大于 0
  • 控制台生成的 API Key
  • 模型广场复制的完整模型名
  • 平台提供的 Base URL，例如 https://147ai.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 用登录命令或环境变量提供。

img_6a44768039f9031.webp

方案一：使用内置 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://147ai.com/v1"

这里最容易错的是三项：

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

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

https://147ai.com/v1/chat/completions
https://147ai.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://147ai.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 和模型配置大概率没问题；插件侧再排查登录状态、权限或扩展版本。

img_6a44768039f9432.webp

常见问题与排查

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://147ai.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 模型，本质上还是三件事：Base URL 指向中转站，API Key 用来鉴权，模型名决定实际调用哪个模型。

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

相关文章

精彩推荐