开始前先确认一件事

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. 执行安装命令：

安装完成后验证：

如果能看到版本号，说明命令已经可用。

macOS

macOS 可以用 npm 安装：

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

Linux

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

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

配置思路

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

Windows 下通常是：

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

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

方案一：使用内置 OpenAI Provider

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

第一步：创建配置目录

macOS / Linux：

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

第二步：写入模型和 Base URL

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

这里最容易错的是三项：

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

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

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

第三步：写入 API Key

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

Windows PowerShell：

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

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

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

第四步：验证登录和配置

先看登录状态：

再进入一个项目目录：

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

方案二：使用自定义 Provider

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

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

Windows PowerShell：

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

这几个字段分别表示：

• 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 或团队脚本场景。

启动与基本使用

进入你的项目目录：

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

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

推荐的使用习惯

先读项目，再改代码

可以这样问：

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

一次只交给它一件事

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

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

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

用 Git 做检查点

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

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

VS Code 里怎么用 Codex

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

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

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

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

常见问题与排查

Q1：codex: command not found

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

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

Q2：安装时报权限错误

macOS / Linux 可以临时使用：

更长期的做法是把 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，要确认：

和：

这两个名字必须一致。

Q7：一直超时或返回很慢

可能原因包括：

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

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

Q8：怎么升级 Codex CLI？

执行：

升级后再运行：

总结

Codex 通过中转站调用 OpenAI 模型，本质上还是三件事：Base URL 指向中转站，API Key 用来鉴权，模型名决定实际调用哪个模型。

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