我见过最多的情况，不是 Codex 安装失败，而是明明已经能执行 codex --version，真正开始使用时却一直卡在登录、401、model not found 或网络超时。
问题通常不在 Codex 本身，而是下面几项没有对应好：
|
1 2 3 4 |
API Key Base URL 模型 ID 接口协议 |
这篇不再写成万字说明，只保留一条能实际跑通的路线。第一次接触 Codex，也可以照着从安装做到验证。
一、先把 Codex CLI 装好
如果电脑还没有 Node.js，先到官网安装 LTS 版本：
|
1 |
https://nodejs.org/ |
安装完成后重新打开 PowerShell 或终端，执行：
|
1 2 3 4 |
node -v npm -v npm install -g @openai/codex@latest codex --version |
最后一条命令能显示版本号，说明 CLI 已经安装成功。
Codex 当前的基本使用方式很直接：先进入项目目录，再执行 codex 打开交互界面。旧教程里常见的 codex generate、codex fix 和 codex init 等命令，不要直接照搬到新版本中。
二、先理解登录和接口接入
Codex 支持 ChatGPT 账号登录，也支持 API Key 认证。如果你的官方账号、网络和接口都能正常使用，直接走官方链路即可。
国内环境更容易卡住的是后半段：账号登录成功了，但 Key、Base URL、模型名和客户端配置仍然分散，换一个客户端又要重新设置。
我自己常用的一个 AI API 统一接入入口是：
|
1 |
https://kkflow.org |
通过 KKFlow 可以统一管理 Key、模型和接口地址，再把 Codex 接到同一套 API 网关里。本文后面的配置都以它为例。
三、准备 API Key 和模型信息
登录 KKFlow 后台，创建一条给 Codex 使用的 API Key，然后确认后台当前提供的模型 ID。
本文使用：
|
1 2 3 |
Base URL：https://kkflow.org/v1 模型：gpt-5.6-sol 接口协议：Responses API |
模型上下架或名称变化时，以后台实际显示为准。model 和 review_model 要一起修改，不能只改其中一项。
真实 API Key 不要放进文章、截图、聊天记录或 Git 仓库。下面统一使用脱敏占位符：
|
1 |
sk-这里替换为你的KKFlow密钥 |
四、写入 Codex 配置
Codex 用户级配置目录为：
|
1 2 |
Windows：%USERPROFILE%\.codex\ macOS / Linux：~/.codex/ |
Windows 用户可以在 PowerShell 中执行：
|
1 2 |
New-Item -ItemType Directory -Force "$env:USERPROFILE\.codex" | Out-Null notepad "$env:USERPROFILE\.codex\auth.json" |
在 auth.json 中保存 API Key：
|
1 2 3 |
{ "OPENAI_API_KEY": "sk-这里替换为你的KKFlow密钥" } |
接着打开主配置文件：
|
1 |
notepad "$env:USERPROFILE\.codex\config.toml" |
macOS 和 Linux 用户对应编辑 ~/.codex/auth.json 与 ~/.codex/config.toml。
config.toml 使用下面这份完整配置：
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
model_provider = "kkflow" model = "gpt-5.6-sol" review_model = "gpt-5.6-sol" model_reasoning_effort = "xhigh" disable_response_storage = true network_access = "enabled" windows_wsl_setup_acknowledged = true model_context_window = 400000 model_auto_compact_token_limit = 360000 [model_providers.kkflow] name = "KKFlow" base_url = "https://kkflow.org/v1" wire_api = "responses" requires_openai_auth = true |
这里最容易写错的是三处：
- Base URL 要带 /v1；
- wire_api 使用 responses；
- API Key 放在 auth.json，不要写进 config.toml。
上下文窗口参数必须与模型实际规格匹配。以后更换模型时，除了模型 ID，也要检查 model_context_window 和 model_auto_compact_token_limit。
五、重新启动并验证
保存两个文件后，完全退出已经运行的 Codex，再重新打开终端。
先检查版本和登录状态：
|
1 2 |
codex --version codex login status |
然后进入一个测试项目，执行：
|
1 |
codex |
第一次不要让它直接重构整个项目，可以先发一个只读任务：
|
1 |
先不要修改文件。请读取当前目录，告诉我项目使用的技术栈、主要入口和可以运行的测试命令。 |
如果 Codex 能正常读取目录并返回结果，说明认证、模型和接口协议基本已经接通。
六、常见报错按什么顺序查
1. 401 Unauthorized
先检查 auth.json 中的 Key 是否完整、是否过期。JSON 最后一项不能多写逗号，也不要把中文占位符当成真实 Key 使用。
2. model not found
模型名不是自己猜的，要以 KKFlow 后台实际模型 ID 为准。修改时同步更新：
|
1 2 |
model = "gpt-5.6-sol" review_model = "gpt-5.6-sol" |
3. 404 或接口不存在
检查地址是否写成完整的：
|
1 |
https://kkflow.org/v1 |
模型列表测试接口为：
|
1 |
https://kkflow.org/v1/models |
需要认证的接口要使用自己的 API Key，公开排错时只能展示脱敏内容。
4. 改了配置仍然不生效
关闭所有 Codex 进程和终端窗口，再重新打开。已经运行的进程不一定会自动读取新配置。
5. 仍然不知道卡在哪里
当前 Codex CLI 提供了诊断命令，可以继续执行：
|
1 |
codex doctor |
排错时按“认证 → 地址 → 模型 → 协议 → 本地配置”的顺序检查，通常比反复重装更快。
七、跑通之后怎么开始用
Codex 真正有价值的地方，不是让它随便生成一段代码，而是让它进入现有项目，读取文件、修改代码并运行检查。
刚开始可以使用这种任务描述：
|
1 2 3 |
请先阅读 README、依赖文件和测试配置，不要立即修改。 先说明问题原因和修改计划，确认后再动手。 完成后运行现有测试，并列出实际修改的文件。 |
这样能减少它一上来改动过多，也方便你判断它是否真正理解了项目。
如果经常在多个客户端或模型之间切换，统一管理 Key、模型和 Base URL 会省掉很多重复配置。先理解 Codex 的官方使用方式，再通过 KKFlow 把 API 接入跑通，后面的工作流就会简单很多。
结语
Codex 安装成功，只代表命令已经可用；真正跑起来，还要让 Key、Base URL、模型和 Responses API 协议全部对应。
把这四项检查清楚，再用一个只读任务做验证，通常就能避开大部分登录和接口问题。配置跑通后，再逐步让 Codex 处理修复、测试和重构任务，会比一开始就把整个项目交给它更稳妥。
