一、先把 Codex CLI 装好

如果电脑还没有 Node.js，先到官网安装 LTS 版本：

安装完成后重新打开 PowerShell 或终端，执行：

最后一条命令能显示版本号，说明 CLI 已经安装成功。

Codex 当前的基本使用方式很直接：先进入项目目录，再执行 codex 打开交互界面。旧教程里常见的 codex generate、codex fix 和 codex init 等命令，不要直接照搬到新版本中。

二、先理解登录和接口接入

Codex 支持 ChatGPT 账号登录，也支持 API Key 认证。如果你的官方账号、网络和接口都能正常使用，直接走官方链路即可。

国内环境更容易卡住的是后半段：账号登录成功了，但 Key、Base URL、模型名和客户端配置仍然分散，换一个客户端又要重新设置。

我自己常用的一个 AI API 统一接入入口是：

通过 KKFlow 可以统一管理 Key、模型和接口地址，再把 Codex 接到同一套 API 网关里。本文后面的配置都以它为例。

三、准备 API Key 和模型信息

登录 KKFlow 后台，创建一条给 Codex 使用的 API Key，然后确认后台当前提供的模型 ID。

本文使用：

模型上下架或名称变化时，以后台实际显示为准。model 和 review_model 要一起修改，不能只改其中一项。

真实 API Key 不要放进文章、截图、聊天记录或 Git 仓库。下面统一使用脱敏占位符：

四、写入 Codex 配置

Codex 用户级配置目录为：

Windows 用户可以在 PowerShell 中执行：

在 auth.json 中保存 API Key：

接着打开主配置文件：

macOS 和 Linux 用户对应编辑 ~/.codex/auth.json 与 ~/.codex/config.toml。

config.toml 使用下面这份完整配置：

这里最容易写错的是三处：

• Base URL 要带 /v1；
• wire_api 使用 responses；
• API Key 放在 auth.json，不要写进 config.toml。

上下文窗口参数必须与模型实际规格匹配。以后更换模型时，除了模型 ID，也要检查 model_context_window 和 model_auto_compact_token_limit。

五、重新启动并验证

保存两个文件后，完全退出已经运行的 Codex，再重新打开终端。

先检查版本和登录状态：

然后进入一个测试项目，执行：

第一次不要让它直接重构整个项目，可以先发一个只读任务：

如果 Codex 能正常读取目录并返回结果，说明认证、模型和接口协议基本已经接通。

六、常见报错按什么顺序查

1. 401 Unauthorized

先检查 auth.json 中的 Key 是否完整、是否过期。JSON 最后一项不能多写逗号，也不要把中文占位符当成真实 Key 使用。

2. model not found

模型名不是自己猜的，要以 KKFlow 后台实际模型 ID 为准。修改时同步更新：

3. 404 或接口不存在

检查地址是否写成完整的：

模型列表测试接口为：

需要认证的接口要使用自己的 API Key，公开排错时只能展示脱敏内容。

4. 改了配置仍然不生效

关闭所有 Codex 进程和终端窗口，再重新打开。已经运行的进程不一定会自动读取新配置。

5. 仍然不知道卡在哪里

当前 Codex CLI 提供了诊断命令，可以继续执行：

排错时按“认证 → 地址 → 模型 → 协议 → 本地配置”的顺序检查，通常比反复重装更快。

七、跑通之后怎么开始用

Codex 真正有价值的地方，不是让它随便生成一段代码，而是让它进入现有项目，读取文件、修改代码并运行检查。

刚开始可以使用这种任务描述：

这样能减少它一上来改动过多，也方便你判断它是否真正理解了项目。

如果经常在多个客户端或模型之间切换，统一管理 Key、模型和 Base URL 会省掉很多重复配置。先理解 Codex 的官方使用方式，再通过 KKFlow 把 API 接入跑通，后面的工作流就会简单很多。

结语

Codex 安装成功，只代表命令已经可用；真正跑起来，还要让 Key、Base URL、模型和 Responses API 协议全部对应。

把这四项检查清楚，再用一个只读任务做验证，通常就能避开大部分登录和接口问题。配置跑通后，再逐步让 Codex 处理修复、测试和重构任务，会比一开始就把整个项目交给它更稳妥。