Codex中API Key与KKFlow配置精简教程

我见过最多的情况，不是 Codex 安装失败，而是明明已经能执行 codex --version，真正开始使用时却一直卡在登录、401、model not found 或网络超时。

卡住的问题，十有八九不在 Codex 本身，而是下面几项没有对齐：

API Key
Base URL
模型 ID
接口协议

这篇不再写成万字说明，只保留一条能实际跑通的路线。第一次接触 Codex，也可以照着从安装做到验证。

一、先把 Codex CLI 装好

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

https://nodejs.org/

装好后，重新打开 PowerShell 或终端，执行：

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、模型名和客户端配置仍然分散，换一个客户端又要重新设置。后面的配置我们就以某个统一接入服务为例，这种方式可以统一管理 Key、模型和接口地址，再把 Codex 接到同一套 API 网关里。

三、准备 API Key 和模型信息

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

本文使用：

Base URL：https://kkflow.org/v1
模型：gpt-5.6-sol
接口协议：Responses API

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

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

sk-这里替换为你的KKFlow密钥

四、写入 Codex 配置

Codex 用户级配置目录为：

Windows：%USERPROFILE%.codex
macOS / Linux：~/.codex/

Windows 用户可以在 PowerShell 中执行：

New-Item -ItemType Directory -Force "$env:USERPROFILE.codex" | Out-Null
notepad "$env:USERPROFILE.codexauth.json"

在 auth.json 中保存 API Key：

{
  "OPENAI_API_KEY": "sk-这里替换为你的KKFlow密钥"
}

接着打开主配置文件：

notepad "$env:USERPROFILE.codexconfig.toml"

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

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

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，再重新打开终端。

先检查版本和登录状态：

codex --version
codex login status

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

codex

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

先不要修改文件。请读取当前目录，告诉我项目使用的技术栈、主要入口和可以运行的测试命令。

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

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

1. 401 Unauthorized

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

2. model not found

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

model = "gpt-5.6-sol"
review_model = "gpt-5.6-sol"

3. 404 或接口不存在

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

https://kkflow.org/v1

模型列表测试接口为：

https://kkflow.org/v1/models

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

4. 改了配置仍然不生效

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

5. 仍然不知道卡在哪里

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

codex doctor

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

七、跑通之后怎么开始用

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

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

请先阅读 README、依赖文件和测试配置，不要立即修改。
先说明问题原因和修改计划，确认后再动手。
完成后运行现有测试，并列出实际修改的文件。

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

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

结语

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

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