本篇文章将详细解读 Codex CLI 的配置文件默认路径、字段含义，以及如何在 JSON 与 YAML 之间进行选择和迁移。通过这些说明，你可以快速搭建稳定、安全的开发环境，避免常见配置误区。
目录
配置文件位置与格式
JSON 配置示例解读
YAML 配配置的等效写法
逐字段深入解析
model、provider、providers
history
兼容性与迁移要点
使用技巧与最佳实践
常见问题与排错
快速上手要点
配置文件位置与格式
OpenAI Codex CLI 支持两种配置文件格式，并将它们放在用户主目录的 ~/.codex 目录下：
JSON 版本：~/.codex/config.json
YAML 版本：~/.codex/config.yaml
提供的 JSON 示例（已给出），同等信息也可以用 YAML 表达。为了清晰对比，下面以 JSON 为主进行讲解，随后给出等效的 YAML 写法。
如果你偏好结构化、可读性更强的配置，推荐使用 YAML；如果你习惯简洁的 JSON，也完全支持。
给定的 JSON 配置示例
请参考以下示例，作为你自己配置的起点：
{
"model": "o4-mini",
"provider": "openai",
"providers": {
"openai": {
"name": "OpenAI",
"baseURL": "https://api.openai.com/v1",
"envKey": "OPENAI_API_KEY"
},
"azure": {
"name": "AzureOpenAI",
"baseURL": "https://YOUR_PROJECT_NAME.openai.azure.com/openai",
"envKey": "AZURE_OPENAI_API_KEY"
},
"openrouter": { "...": "..." },
"gemini": { "...": "..." },
"xai": { "...": "..." }
},
"history": {
"maxSize": 1000,
"saveHistory": true,
"sensitivePatterns": []
}
}
等效的 YAML 写法
如果你更习惯 YAML，可以将上面的 JSON 等效转换为 YAML，如下所示：
model: o4-mini
provider: openai
providers:
openai:
name: OpenAI
baseURL: https://api.openai.com/v1
envKey: OPENAI_API_KEY
azure:
name: AzureOpenAI
baseURL: https://YOUR_PROJECT_NAME.openai.azure.com/openai
envKey: AZURE_OPENAI_API_KEY
openrouter: { "...": "..." }
gemini: { "...": "..." }
xai: { "...": "..." }
history:
maxSize: 1000
saveHistory: true
sensitivePatterns: []
逐字段深入解析
下面逐字段解释每个配置项的含义、取值以及常见注意事项。
1) model
含义：要使用的模型标识符。
取值示例："o4-mini"、"gpt-4"等，具体可用模型以 Codex CLI 支持的为准。
设计要点：
不同模型可能有不同的能力、价格与延迟，选择时要结合实际工作负载与预算。
如果某些提供者不支持你选的模型，CLI 可能返回错误，请确认该模型在所选 provider 下可用。
2) provider
含义：全局默认提供者名称，用来决定调用哪个后端 API。
取值示例："openai"、"azure" 等。
设计要点：
该字段通常与 providers 中的同名条目配合使用。只有当你在 providers 中配置相应密钥/端点时，才建议设置正确的 provider。
如果你希望动态切换提供者，确保你的实现逻辑能在运行时安全地选择不同的 envKey 和 baseURL。
3) providers
含义：各个提供者的具体配置信息，是一个映射对象（字典）。
典型子字段：
openai：
name: 显示名称，例如 OpenAI
baseURL: API 基础地址，例如 https://api.openai.com/v1
envKey: 用来读取 API Key 的环境变量名，例如 OPENAI_API_KEY
azure：
name: 显示名称，例如 AzureOpenAI
baseURL: Azure 上的 OpenAI API 基础地址，例如 https://YOUR_PROJECT_NAME.openai.azure.com/openai
envKey: 对应的环境变量名，例如 AZURE_OPENAI_API_KEY
openrouter、gemini、xai：
目前示例中为占位或待填充的提供者，具体字段和要求请参考对应提供者的集成文档。
设计要点：
environment-driven：通过 envKey 指定环境变量来读取密钥，更安全，避免把密钥写死在配置文件中。
多提供者并存：你可以在同一个配置中声明多个提供者，按需切换使用；默认的 provider 字段决定当前使用哪个提供者。
4) history
含义：历史对话/请求的保存策略，便于追溯与上下文复用。
字段解释：
maxSize（整数）：历史记录的最大条目数或条目容量，确保不无限增长。示例中给出 1000。
saveHistory（布尔）：是否将历史记录持久化保存。开启后，下次启动可能会读取历史继续对话。
sensitivePatterns（数组）：用于定义需要屏蔽或处理的敏感信息的模式集合，具体格式取决于实现。空数组表示不启用额外的敏感信息处理。
设计要点：
如果历史包含敏感信息，请在 sensitivePatterns 中添加相应的正则或关键词，以提升隐私保护。
根据应用场景权衡 history 的大小，避免占用过多磁盘或内存。
兼容性与迁移要点
JSON <-> YAML 互相转换
两种格式表达的是同一配置的语义。若你在维护一个跨平台的工具链，确保字段名称、数据类型和层级结构保持一致即可。
启用时机
以实际使用的配置文件为准。CLI 通常会优先读取 ~/.codex/config.json 或 ~/.codex/config.yaml，具体优先级请参考你所使用的 Codex CLI 版本文档。
密钥管理
强烈推荐使用 envKey 指定的环境变量来加载 API Key，而不要把密钥直接硬编码到配置文件中。
保护配置文件的权限，例如在 Unix 系统上使用 600 权限，避免普通用户读到密钥。
使用技巧与最佳实践
安全优先
将密钥放在环境变量中，避免提交到版本控制系统。
对配置文件目录设置严格权限，例如 chmod 700 ~/.codex；配置文件本身设为 600。
最小化暴露
只在需要时启用历史记录（history.saveHistory），并且配置合适的 maxSize。
清晰的 provider 切换
如果你需要在同一工作流中对接不同的后端，确保在代码中显式地处理 provider 切换逻辑，避免混用造成的密钥错配。
保持同步
当某个提供者的 baseURL、认证方式或 API 版本变更时，及时更新配置，并在测试用例中覆盖相关路径。
备份与版本控制
将示例配置模板（不包含真实密钥）放在版本控制中，方便团队按照模板填充实际值。
快速上手要点
步骤 1：选择格式并创建配置文件
JSON：~/.codex/config.json
YAML：~/.codex/config.yaml
步骤 2：填充关键字段（以 JSON 示例为起点）
设置你常用的模型（如 model: "o4-mini"）和默认 provider（如 provider: "openai"）。
在 providers 中为你要使用的后端填入 baseURL 与 envKey。
步骤 3：配置 API Key 的环境变量
将实际的 API Key 通过环境变量暴露，例如：
export OPENAI_API_KEY=sk-...
若使用 Azure OpenAI，export AZURE_OPENAI_API_KEY=...
步骤 4：运行并测试
启动 Codex CLI，观察是否能正常读取配置和 API Key，并进行一次简单的请求以确保连通性。
步骤 5：增强与保护
根据需要开启 history、并设置 sensible patterns，确保日志中不过多暴露敏感信息。
常见问题与排错
问题：CLI 无法读取配置中的某个字段
检查字段名是否拼写正确，JSON 和 YAML 的数据结构是否保持一致。
查看 CLI 日志，确认是否有路径或解析错误。
问题：API Key 未通过验证
确认 envKey 指定的环境变量确实已导出且拼写正确。
确认 baseURL 与模型在所选 provider 下是可用的。
问题：在打开历史记录时内存/磁盘耗高
降低 maxSize，或禁用 saveHistory，检查历史记录的写入路径和权限。
小结
你的配置文件可以是 JSON 也可以是 YAML，核心信息包括模型、默认 provider、各提供者的连接信息以及历史记录策略。
通过 envKey 将 API Key 安全地从环境变量载入，避免将密钥写死在配置文件中。
History 设置提供了便捷的对话上下文管理，同时要注意对敏感信息的屏蔽与权限控制。
如果你愿意，我可以把以上内容整理成一个完整的博客草稿，包含更丰富的示例、截图和 SEO 优化标题/摘要。也可以根据你的目标受众（如开发者初学者、团队运维、还是企业用户）定制风格与深度。需要的话告诉我你偏好的口吻（如技术干货、教程式、还是故事化表达）。