最近不少人开始用 Codex 做代码分析、项目重构、Bug 修复和日常开发辅助。真正容易卡住的地方，往往不是安装客户端，而是后面的 API 配置：API Key、base_url、模型名、配置文件路径、provider 名称这些字段只要有一项没对上，就可能出现连接失败、401、模型不存在或配置不生效。

这篇文章整理一份偏实操的 Codex CLI / App 配置排查流程，适合已经安装好 Codex，但还没有成功跑通自定义 API 或 OpenAI 兼容接口的朋友参考。

如果你想看更完整的图文版步骤、代码块配置模板和截图位置说明，我也整理了一份飞书教程页，后续会持续更新：

https://my.feishu.cn/wiki/QAuNw1tL7iWMhRkUWTecywRHnyh?from=from_copylink

说明：本文是个人学习记录和配置经验，不代表 OpenAI 官方说明。不同版本客户端、不同接口平台的配置项可能会变化，具体以官方文档和对应平台后台实际展示为准。第三方 OpenAI 兼容接口仅作为可选测试方案，使用前建议先小额测试。

一、Codex CLI 和 Codex App 有什么区别

简单理解：

工具	适合场景
Codex CLI	在终端里处理本地项目、分析代码、执行命令、查看报错
Codex App	用桌面图形界面管理项目、任务和会话
IDE 扩展	在 VS Code、Cursor 等编辑器里辅助修改代码

如果你是第一次排查配置，建议先从 Codex CLI 开始。CLI 的报错更直接，也更容易判断是 Key、模型名、base_url 还是 provider 配置问题。

二、安装和检查 Codex CLI

先确认本机是否已经安装 Node.js：

node -v
npm -v

如果没有安装，建议先安装 Node.js LTS 版本。然后执行：

npm i -g @openai/codex

安装完成后检查版本：

codex --version

首次运行：

codex

按提示完成登录或初始化。后面修改配置后，建议完全退出 Codex 再重新打开，避免旧配置缓存导致误判。

三、找到 Codex 配置目录

Windows 可以按 Win + R，输入：

%userprofile%\.codex

macOS / Linux 可以在终端执行：

cd ~/.codex
ls

常见配置文件包括：

auth.json
config.toml

如果还没有这些文件，可以先运行一次 codex，让客户端自动初始化。

四、auth.json 负责什么

auth.json 通常用于保存认证信息。使用 API Key 方式时，可以参考：

{
  "OPENAI_API_KEY": "替换成你的 API Key"
}

注意几点：

• 不要把 API Key 发到公开平台。
• 截图排查时一定要打码。
• JSON 最后一项后面不要多写逗号。
• 不建议把模型名、base_url 写进 auth.json。

错误示例：

{
  "OPENAI_API_KEY": "sk-xxxx",
  "MODEL": "gpt-5.5"
}

认证信息和模型配置最好分开，后续排查会清晰很多。

五、config.toml 负责什么

config.toml 通常用于配置模型、provider、API 地址和调用方式。可以参考下面的结构：

model_provider = "custom"
model = "后台真实模型名"
model_reasoning_effort = "high"
preferred_auth_method = "apikey"

[model_providers.custom]
name = "custom"
base_url = "后台显示的 API Base URL"
wire_api = "responses"

这里最容易写错的是几项：

• model_provider = "custom" 要和 [model_providers.custom] 对上。
• model 要写后台真实模型名，不要凭感觉填写。
• base_url 要写平台提供的 API Base URL，不要直接写到具体接口路径。
• 如果后台要求带 /v1，就填写带 /v1 的地址。
• 修改后建议完全退出 Codex 再重启。

六、base_url 不要写成接口路径

很多连接失败都和 base_url 层级有关。

通常应该填写类似：

https://example.com/v1

不要写成：

https://example.com/v1/chat/completions

base_url 是基础地址，不是某一个具体接口地址。不同平台要求可能不同，最终以后台说明为准。

七、模型名一定要从后台复制

Codex 里的 model 不是随便填一个昵称，而是要填接口后台实际支持的模型名。例如你以为模型叫：

gpt-5.5

但后台真实模型名可能带后缀，例如：

gpt-5.5-high
gpt-5.5-1m
gpt-5.5-code

所以不要手打，建议直接从后台模型列表复制。复制后再粘贴到 config.toml 里。

八、可选：OpenAI 兼容 API 测试入口

如果你需要测试 OpenAI 兼容接口，可以先注册、创建 API Key，再复制后台展示的 API Base URL 和真实模型名。

可选测试入口：

https://code4ai.top/register?aff=myQZ

使用前建议先小额测试，不要一开始就大额充值。模型名称、上下文长度、倍率、速度和可用性都应以后台实时显示为准。

如果你想看完整配置模板，可以查看我整理的飞书教程页：

https://my.feishu.cn/wiki/QAuNw1tL7iWMhRkUWTecywRHnyh?from=from_copylink

九、先用简单任务测试

不要一上来就让 Codex 分析超大项目。建议先用小项目测试，例如：

请读取当前项目结构，不要修改文件，只说明主要目录和核心模块分别做什么。

如果能正常回复，再测试稍长一点的任务：

请分析当前项目中可能存在的 Bug，并给出可以直接修改的文件和原因。不要泛泛而谈，要结合具体文件说明。

这样更容易判断问题到底是配置问题、模型问题，还是项目本身太复杂。

十、常见报错排查

报错或现象	可能原因	排查方法
401 Unauthorized	API Key 错误或没有生效	重新复制 Key，检查 auth.json
model not found	模型名不是后台真实名称	到后台复制准确模型名
connection failed	base_url 写错	检查 API Base URL 是否正确
配置不生效	provider 名称前后不一致	检查 model_provider 和配置块
改完仍然没变化	Codex 没有完全重启	完全退出后重新打开
输出中断	网络、分组或任务过大	先用小任务测试
App 里不生效	App 版本或设置读取方式不同	优先用 CLI 验证配置

排查时不要同时改很多地方。一次只改一项，保存、重启、测试，这样最容易定位问题。

十一、关于模型和价格的选择

如果你主要用 Codex 做代码分析、项目重构、长日志排查，建议重点关注这些指标：

模型是否真实可用
上下文长度是否够用
输出速度是否稳定
计费倍率是否适合长期使用
后台用量记录是否清楚

有些平台会提供适合代码任务的模型分组，例如长上下文、高速输出或低倍率分组。不要只看宣传文案，最稳妥的方式是：

先小额测试
再跑小项目
确认稳定后再用于大项目

十二、我的排查顺序

如果配置失败，可以按这个顺序检查：

1. API Key 是否复制完整
2. auth.json 是否是合法 JSON
3. model 是否是后台真实模型名
4. base_url 是否写到了正确层级
5. model_provider 和配置块名称是否一致
6. wire_api 是否符合当前接口要求
7. Codex 是否完全退出并重启
8. 是否先用小项目测试

十三、总结

Codex CLI 和 Codex App 都适合做代码辅助，但新手排查配置时，建议先从 CLI 开始。

关键字段主要是：

API Key
base_url
model
model_provider
wire_api

只要这些字段对应正确，大多数 401、模型不存在、连接失败、配置不生效的问题都能定位出来。

完整图文教程和配置模板我放在这里：

https://my.feishu.cn/wiki/QAuNw1tL7iWMhRkUWTecywRHnyh?from=from_copylink

如果你也遇到类似的 401、模型不存在、连接失败、配置不生效等问题，可以按上面的顺序逐项排查。截图时记得把 API Key 打码。