最近几次帮人排查 Codex，发现大家卡住的位置都差不多：软件已经装好了，打开后却一直停在登录页；好不容易找到 API Key 登录，进去以后又报 401、model not found，或者一直重试。

这类问题通常不是 Codex 没装成功，而是只处理了“登录”，没有把接口地址、模型名和协议一起配好。

这篇就从官方支持的 API Key 登录讲起，再用 CC Switch 管理配置，最后接到我自己常用的统一 API 入口 https://kkflow.org。不需要反复试错，按顺序做完就能判断问题到底出在哪一步。

本文整理于 2026 年 7 月 27 日。Codex、CC Switch 和模型列表都会更新，界面名称及模型 ID 请以当前版本和 KKFlow 后台实际显示为准。

一、先弄清楚：Codex 为什么会卡在登录页

目前打开 https://developers.openai.com/codex/app，会进入 ChatGPT 桌面应用的官方页面，Codex 是其中面向本地项目和代码任务的工作入口。

按照 OpenAI 当前的认证说明，本地 Codex 支持两种方式：

1. 使用 ChatGPT 账号登录；
2. 使用 API Key 登录，按 API 实际用量计费。

所以看到登录页时，不一定非要继续走 ChatGPT 账号流程。界面里如果有“使用其他方式登录”或 Sign in another way，可以选择 API Key。

但这里有个很容易忽略的区别：

API Key 只负责证明你有调用权限，它不会自动告诉 Codex 应该请求哪个中转地址、使用哪个模型。

如果用的是 OpenAI 兼容接口，还要同时配置：

1. Base URL；
2. API Key；
3. 模型 ID；
4. Responses API 协议。

这也是为什么有人明明已经“登录成功”，真正发消息时仍然报错。

二、这套方案里三个工具分别做什么

整条链路可以简单理解为：

Codex / ChatGPT 桌面应用        ↓ 读取配置     CC Switch        ↓ 写入 Key、Base URL、模型配置     KKFlow API        ↓   gpt-5.6-sol

Codex 负责读取项目、修改代码和运行命令；CC Switch 负责用图形界面保存、启用和切换不同 Provider；KKFlow 则作为统一 API 接入入口，集中管理 Key、模型和接口地址。

如果你只用一套配置，完全可以手动写文件。经常在官方接口、不同环境或多个客户端之间切换时，CC Switch 会更省事。

三、第一步：安装官方桌面应用

官方入口：

https://developers.openai.com/codex/app

Windows 用户也可以在 PowerShell 中执行：

winget install --id 9PLM9XGG6VKS -s msstore

安装后先打开一次。如果停在登录页，不用反复点击 ChatGPT 登录，可以先退出应用，继续完成下面的接口配置。

四、第二步：安装 CC Switch

CC Switch 是开源的跨平台配置管理工具，目前支持 Windows、macOS 和 Linux，也支持 Codex 配置管理。

下载地址：

https://github.com/farion1231/cc-switch/releases

Windows 通常选择 .msi 安装包或 Portable 便携版；macOS 可以选择 .dmg，也可以通过 Homebrew 安装：

brew install --cask cc-switch

安装完成后打开 CC Switch。如果它提示导入现有配置，先看清内容再确认，避免把原来仍在使用的配置覆盖掉。

五、第三步：准备 KKFlow API Key

官方工具和登录方式弄清以后，接下来才是接口接入。

国内使用官方链路时，常见麻烦并不只在网络，还包括 Key、Base URL、模型名、客户端配置和用量管理分散。我自己常用的一个统一 API 接入入口是：

https://kkflow.org

登录后台后创建一个给 Codex 使用的 API Key，并确认当前可用模型。本文示例使用：

模型：gpt-5.6-solBase URL：https://kkflow.org/v1模型列表接口：https://kkflow.org/v1/models

模型上下架或名称发生变化时，以后台实际模型 ID 为准。创建好的 Key 只在自己的设备上使用，不要发到文章、聊天记录或 Git 仓库里。

文中统一使用下面的脱敏占位符：

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

六、第四步：在 CC Switch 中添加 Codex 配置

打开 CC Switch，进入 Codex 标签页，点击添加 Provider，选择自定义配置。

不同版本的字段名称可能略有变化，核心内容保持一致：

如果当前版本没有单独显示“模型”或“接口协议”字段，不要随便填到其他输入框里，保存 Provider 后按下一节直接检查 config.toml。

保存以后选择这套配置，点击“启用”。CC Switch 官方说明也提示，Codex 切换 Provider 后需要重启对应客户端才能读取新配置。

如果后台提供“导入到 CC Switch”一类入口，也可以使用，但导入后仍建议检查一次 Base URL 和模型名，不要看到“导入成功”就默认接口一定已经跑通。

七、第五步：检查完整配置文件

这是整篇最关键的一步。

CC Switch 负责降低切换配置的成本，但最终 Codex 读取的仍是用户目录下的配置。Windows 路径为：

%USERPROFILE%.codex

macOS 和 Linux 路径为：

~/.codex/

注意不要把 Provider 配置写到项目内的 .codex/config.toml。官方文档说明，项目级配置不能覆盖 model_provider 和 model_providers 等认证相关设置。

Windows 用户可以这样打开完整配置：

New-Item -ItemType Directory -Force "$env:USERPROFILE.codex" | Out-Nullnotepad "$env:USERPROFILE.codexconfig.toml"

确认 config.toml 为下面这套配置：

model_provider = "kkflow"model = "gpt-5.6-sol"review_model = "gpt-5.6-sol"model_reasoning_effort = "xhigh"disable_response_storage = truenetwork_access = "enabled"windows_wsl_setup_acknowledged = truemodel_context_window = 400000model_auto_compact_token_limit = 360000[model_providers.kkflow]name = "KKFlow"base_url = "https://kkflow.org/v1"wire_api = "responses"requires_openai_auth = true

接着打开认证文件：

notepad "$env:USERPROFILE.codexauth.json"

写入：

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

这里重点检查五件事：

1. model 和 review_model 必须保持一致；
2. Base URL 要写成 https://kkflow.org/v1；
3. wire_api 要使用 responses；
4. Key 放在 auth.json，不要写进公开文章；
5. 上下文窗口参数要与模型实际规格匹配。

如果 KKFlow 后台显示的模型 ID 或上下文规格已经变化，要同步修改配置，不能只换模型名而保留不匹配的上下文参数。

八、第六步：重新打开应用并用 API Key 进入

配置完成后，把 Codex / ChatGPT 桌面应用完全退出。如果应用还在系统托盘运行，也要一并退出，然后重新打开。

如果仍然出现登录页：

1. 点击“使用其他方式登录”或 Sign in another way；
2. 选择 API Key；
3. 输入同一个 KKFlow API Key；
4. 点击继续。

如果已经通过 CC Switch 或 auth.json 保存了认证信息，部分版本会直接读取本地状态，不再重复要求输入。

需要注意，API Key 登录主要面向本地 Codex 工作流。依赖 ChatGPT 工作区或云端服务的部分功能可能不可用，这不等于本地代码能力配置失败。

九、第七步：用一个最小任务验证

进入应用后，先打开一个测试项目或不重要的目录，选择 Codex，然后发送：

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

这条任务能同时验证：

1. 应用是否已经进入 Codex；
2. API Key 是否有效；
3. Base URL 和模型是否正确；
4. Codex 是否能读取本地项目。

确认只读任务正常后，再做一个小修改：

先给出修改计划，等我确认后再动手。完成后运行现有测试，并列出实际修改的文件。

第一次不要直接让它重构整个项目。先确认读取、修改和测试三条链路都正常，再逐步增加任务规模。

十、常见报错怎么排查

1. 一直停在登录页

先确认选的是 API Key 登录，而不是反复打开 ChatGPT 浏览器登录。然后检查 CC Switch 是否已经启用正确 Provider，并把桌面应用完全退出后重开。

2.401 Unauthorized

优先检查 API Key 是否复制完整、前后是否带空格，以及 auth.json 中是否仍然是旧 Key。不要把真实 Key 发到评论区。

3.403 Forbidden

通常表示当前 Key 没有目标模型权限、账号状态异常或用量不足。回到后台检查 Key 权限和模型可用状态。

4.model not found

到 KKFlow 后台或模型列表接口核对模型 ID，再同时修改：

model = "实际模型ID"review_model = "实际模型ID"

不要只改其中一个。

5.404、连接失败或一直重试

重点检查：

base_url = "https://kkflow.org/v1"wire_api = "responses"

不要根据其他平台的教程随意删除 /v1。不同网关的接口规则不一样，KKFlow 的 OpenAI 兼容地址按本文使用 /v1。

6. CC Switch 显示已启用，但应用还是旧模型

完全退出应用再重开。如果仍然不生效，直接检查用户目录下的 config.toml，确认 CC Switch 当前启用项确实已经写入文件。

7. 配置明明正确，却完全没有被读取

检查文件位置。Provider 必须放在用户级 %USERPROFILE%.codexconfig.toml 或 ~/.codex/config.toml，不能只放在某个项目的 .codex/ 目录里。

十一、最后提醒：保护好 API Key

API Key 和密码一样敏感。对外发布内容前，至少检查下面几个位置：

1. CC Switch 的 Provider 编辑页；
2. auth.json；
3. PowerShell 历史记录；
4. KKFlow 后台 Key 列表；
5. Codex 错误日志和调试输出。

对外示例不要保留真实 Key，文章中统一使用脱敏占位符。

十二、本文查阅的官方资料

1. ChatGPT 桌面应用与 Codex 入口：https://learn.chatgpt.com/docs/app
2. Codex 认证方式：https://learn.chatgpt.com/docs/auth
3. Codex 自定义模型 Provider：https://learn.chatgpt.com/docs/config-file/config-advanced#custom-model-providers
4. CC Switch 开源仓库：https://github.com/farion1231/cc-switch

总结

Codex 卡在登录页时，不要只盯着账号本身。对 OpenAI 兼容接口来说，真正完整的配置是四件套：API Key、Base URL、模型 ID、Responses 协议。

先从官方思路理解 API Key 登录，再用 CC Switch 管理 Provider，最后通过 KKFlow 统一管理 Key、模型和接口地址。这样以后不管是在桌面应用、Codex CLI，还是其他 OpenAI 兼容客户端里切换，排查思路都是一致的。

遇到问题时，按“登录方式 -> 当前 Provider -> API Key -> Base URL -> 模型 ID -> 重启应用”的顺序检查，比反复卸载重装更容易找到真正原因。