很多 Codex 新手第一次配置时，最容易混淆两个文件：auth.json 和 config.toml。一个放认证信息，一个放模型和接口配置。如果这两个文件职责没分清，后面很容易出现“看起来都写了，但就是不能用”的情况。
新手先别急着研究所有字段。第一步只要记住最小可用版本：Key 放哪里，模型写哪里，接口地址写哪里，provider 名字怎么对上。
在此之前，我把配置教程，常见字段，排查顺序和首次测试模板整理成了一个持续更新的资料页，可以点击这里快速开始
https://gitcode.com/u011635002/little_ai/blob/main/docs/%E5%AE%89%E8%A3%85%E5%9F%BA%E7%A1%80%E6%95%99%E7%A8%8B/02-OpenAI%20Codex%20CLI%20%E9%85%8D%E7%BD%AE%E6%95%99%E7%A8%8B.md
先说结论：auth 管认证，config 管模型和接口
可以先这样理解：
- auth.json：告诉 Codex 你用什么 Key
- config.toml：告诉 Codex 用哪个模型、哪个接口、哪个 provider
这两个文件不要混着写。
Key 不应该随便塞进 config.toml。
模型和接口地址也不应该写进 auth.json。
分工清楚，排查才会清楚。
auth.json 最小只放 Key
对新手来说，auth.json 不要写复杂。
最小版本只放认证信息。
示例：
{
"OPENAI_API_KEY": "你的真实 Key"
}
这里最容易错的是：
- Key 少复制了一段
- Key 前后多了空格
- Key 类型不匹配
- JSON 格式写错
- 文件名写错
- 文件放错位置
JSON 格式尤其要注意。
不能用中文引号。
不能多一个逗号。
不能把注释写进去。
如果 auth.json 格式不合法，后面配置再对也可能失败。
config.toml 管 provider、model 和 base_url
config.toml 更像是 Codex 的运行配置。
它告诉 Codex：
- 用哪个 provider
- 用哪个模型
- 请求发到哪里
- 使用哪种认证方式
- 是否启用某些行为设置
新手可以先记住一个最小结构：
model_provider = "example"
model = "your-model-name"
preferred_auth_method = "apikey"
[model_providers.example]
name = "example"
base_url = "https://example.com/api"
wire_api = "responses"
这里有一个非常关键的点：
model_provider = "example"
要和：
[model_providers.example]
对上。
很多新手就是错在这里。
上面写了一个名字，下面 section 写了另一个名字。
看起来都配置了，实际上 Codex 找不到对应 provider。
base_url 不要凭感觉改
base_url 是非常容易错的字段。
它错一个字符，请求都可能失败。
新手不要自己猜路径。
应该以当前服务文档里的示例为准。
尤其要注意：
- 有没有多写 /v1
- 有没有少写路径
- 是否需要特定后缀
- http 和 https 是否写对
- 末尾斜杠是否影响当前服务
如果你遇到请求失败，但 Key 看起来没问题，就应该把 base_url 放到重点排查里。
不要先怀疑 Prompt。
这和 Prompt 没关系。
provider 名字对不上，是最隐蔽的错误
config.toml 里还有一个很隐蔽的问题：provider 名字没有对上。
比如上面写：
model_provider = "myprovider"
下面却写：
[model_providers.example]
这时候你以为自己已经配置了 provider，但 Codex 实际找不到 myprovider 对应的配置。
正确方式是两边一致：
model_provider = "myprovider"
[model_providers.myprovider]
name = "myprovider"
base_url = "https://example.com/api"
wire_api = "responses"
新手排查配置时，一定要把这个放进清单。
因为它不像 JSON 格式错误那样明显。
它看起来很像“都写了”，但就是不生效。
model 名称要和服务支持的名称一致
model 字段也不能随便写。
有些新手会看到别人配置里写某个模型名，就直接复制。
但你的服务未必支持同一个名称。
所以 model 要和你当前可用的模型列表一致。
如果模型名写错，常见表现可能是请求失败、模型不存在、返回异常。
这类问题也不应该从 Prompt 查。
先查配置。
auth 和 config 错了，表现可能很像
还有一点容易让新手混乱：auth.json 错了，和 config.toml 错了，表现有时都像“请求失败”。
所以不要只看表面现象。
可以按这个顺序拆：
第一，先确认 auth.json 是合法 JSON。
第二，确认 Key 完整。
第三，确认 config.toml 里的 provider 名字对上。
第四，确认 model 名称可用。
第五，确认 base_url 正确。
如果你一上来同时改 Key、model、base_url，就会越改越乱。
一次只查一层。
这比凭感觉改配置稳很多。
修改配置后要重启
这一步很小，但非常高频。
很多人改完 auth.json 或 config.toml，立刻在原来的终端里测试。
结果配置没有生效。
更稳的方式是：
如果你改了配置但表现完全没变化，先确认有没有重启终端。
不要马上继续改更多字段。
一个常见的错误配置长什么样
很多新手的配置不是完全没写，而是“每一块都差一点”。
比如：
model_provider = "openai"
model = "some-model"
preferred_auth_method = "apikey"
[model_providers.default]
name = "default"
base_url = "https://example.com/api"
wire_api = "responses"
这份配置看起来有 provider，有 model，也有 base_url。
但问题是：
model_provider = "openai"
下面却只有：
[model_providers.default]
两个名字对不上。
Codex 会按 openai 去找 provider 配置，但下面没有对应的 section。
这类错误最烦，因为它不像 JSON 格式错误那样一眼能看出来。
所以排查 config.toml 时，不要只看字段有没有写。
还要看字段之间有没有对上。
新手不要一上来复制一大份配置
网上能看到很多配置示例。
但新手最容易的问题，是复制了一整份自己看不懂的配置。
一旦报错，就不知道是哪一行出问题。
更稳的方式是先用最小版本。
先只保留：
- model_provider
- model
- preferred_auth_method
- [model_providers.xxx]
- name
- base_url
- wire_api
能跑通以后，再考虑其他字段。
不要第一版就加很多自己暂时用不到的配置。
配置越多，排查越难。
新手第一目标不是把配置写得完整，而是先让它稳定跑起来。
如果还是不通，按这个顺序问 Codex
你也可以让 Codex 帮你检查配置，但要注意方式。
不要直接说：
帮我看看哪里错了。
这句话太宽。
更好的问法是：
请只检查这份 Codex 配置是否存在明显问题。
重点看：
1. auth.json 是否应该只放 Key
2. config.toml 里的 model_provider 是否和 section 对上
3. model 名称是否需要和当前服务支持的名称一致
4. base_url 是否应该以当前服务文档为准
5. 修改后是否需要重启终端
请先只分析，不要修改文件。
这样问，Codex 会按排查清单看，而不是泛泛解释配置文件。
如果你不确定某个字段含义，也可以单独问：
请用新手能听懂的话解释 config.toml 里的 model_provider、model、base_url 分别负责什么。
先理解字段，再改配置。
这个顺序会少很多折腾。
配置文件最怕“半懂半复制”
新手配置 Codex 时，最容易处在一种状态：
知道要有 Key，也知道要有模型名，但不知道每个字段到底负责什么。
于是看到一份配置就复制。
一旦失败，就开始同时改很多地方。
这会让排查越来越乱。
更稳的方式是每次只确认一个问题：
第一，认证有没有问题。
第二，provider 有没有对上。
第三，模型名有没有写对。
第四，接口地址有没有写对。
第五，修改后有没有重启。
每次只动一个点。
如果动完以后表现变化了，说明你找到了相关层。
如果完全没变化，再看下一层。
配置排错不是靠猜，而是靠缩小范围。
什么时候应该回到最小配置
如果你已经改了很多次，仍然不通，建议回到最小配置。
先把不确定的字段删掉，只保留认证、provider、model、base_url 这些必要内容。
等最小版本能回复以后，再逐步加其他设置。
这比在一份很长的配置里反复试要稳很多。
对新手来说，最小配置不是低级配置。
它是排查问题时最可靠的起点。
最小测试方式
配置完成后，不要一上来就让 Codex 写项目。
先做两个测试。
第一个测试：能不能回复。
请用一句话回复：Codex 已经可以正常响应。
第二个测试：能不能读目录。
请先不要修改代码。
请阅读当前目录，并告诉我：
1. 这里有哪些主要文件
2. 你判断入口文件可能在哪里
3. 这个项目大概是做什么的
如果这两个测试都通过，再开始做小任务。
否则先不要进入代码修改。
一份最小排查清单
可以保存下面这份：
Codex 配置排查：
1. auth.json 是否存在
2. auth.json 是否是合法 JSON
3. Key 是否完整、类型是否正确
4. config.toml 是否存在
5. model_provider 名字是否和 section 对上
6. model 名称是否可用
7. base_url 是否和文档一致
8. preferred_auth_method 是否符合当前认证方式
9. 修改后是否重启终端
10. 是否先用简单请求测试
这份清单不复杂，但能解决很多新手问题。
适用边界
这篇只讲新手如何理解 auth.json 和 config.toml 的最小配置。
不同环境、不同服务、不同版本，字段可能会有差异。
所以不要把某一份配置当成永远不变的标准。
更重要的是理解分工：
认证归认证。
模型和接口归配置。
排查时一层一层看。
最后
Codex 配置最怕的不是字段多，而是你不知道每个文件负责什么。
先记住：
auth.json 管 Key。
config.toml 管 provider、model 和 base_url。
provider 名字要对上。
改完配置要重启。
测试先用最小请求。
这几件事搞清楚，新手配置会少很多无效折腾。
