【Bug已解决】codex: project-level config overrides user settings / Config conflicts — CodeX CLI 配置冲突解决方案1. 问题描述CodeX CLI 的项目级配置覆盖了用户级设置导致行为不符合预期# 项目级覆盖用户级 $ cat ~/.codex/config.json {model: o1, sandbox: {enabled: true}} $ cat .codex/config.json {model: gpt-4o-mini, sandbox: {enabled: false}} $ codex --debug 21 | grep model # 使用 gpt-4o-mini 而非 o1沙箱被禁用 # 或 .codexignore 覆盖 $ cat ~/.codex/.codexignore *.log $ cat .codex/.codexignore # 空文件 $ codex 分析 logs/app.log # 文件被读取因为项目级 .codexignore 为空 # 或 API Key 冲突 $ cat ~/.codex/config.json {apiKey: sk-proj-USER} $ cat .codex/config.json {apiKey: sk-proj-PROJECT} $ codex # 使用项目级 Key可能没有权限这个问题在以下场景中特别常见项目级 .codex/ 目录存在配置文件优先级不明确多人协作时配置不一致旧配置未清理.codexignore 未同步环境变量与配置文件冲突2. 原因分析核心原理拆解用户级配置 ← 项目级配置 ← 环境变量 ← 命令行参数 ↓ 项目级覆盖用户级设置 ↓ 行为不符合预期原因分类表原因分类具体表现占比项目级覆盖.codex/config.json约 40%.codexignore忽略规则不同步约 25%API Key 冲突不同 Key约 15%优先级不明不知道谁覆盖谁约 10%旧配置未清理约 5%环境变量env 覆盖配置约 5%3. 解决方案方案一了解配置优先级最推荐# 步骤 1配置优先级从高到低 # 1. 命令行参数 (--model, --no-sandbox) # 2. 环境变量 (OPENAI_MODEL, OPENAI_API_KEY) # 3. 项目级 .codex/config.json # 4. 用户级 ~/.codex/config.json # 步骤 2检查所有来源 echo 环境变量 env | grep OPENAI echo 项目级 cat .codex/config.json 2/dev/null echo 用户级 cat ~/.codex/config.json # 步骤 3使用 --debug 确认 codex --debug 21 | grep -i config\|model\|sandbox方案二清理项目级配置# 步骤 1删除项目级配置 rm -rf .codex/ # 步骤 2或只移除冲突项 # 保留项目级配置但删除冲突的键 python3 -c import json with open(.codex/config.json) as f: config json.load(f) # 删除冲突的键 config.pop(model, None) config.pop(sandbox, None) with open(.codex/config.json, w) as f: json.dump(config, f, indent2) # 步骤 3验证 codex --debug 21 | grep model方案三统一配置# 步骤 1将所有配置放在用户级 cat ~/.codex/config.json EOF { model: o1, sandbox: { enabled: true, allowedDirectories: [./src, ./tests] }, maxTokens: 4096 } EOF # 步骤 2删除项目级配置 rm .codex/config.json # 步骤 3或项目级只放项目特定配置 cat .codex/config.json EOF { allowedDirectories: [./src, ./tests, ./docs] } EOF # 不放 model、sandbox 等方案四使用环境变量覆盖# 步骤 1环境变量优先级高于配置文件 export OPENAI_MODELo1 export OPENAI_API_KEYsk-proj-USER_KEY # 步骤 2无论项目级配置如何环境变量生效 codex # 步骤 3永久设置 echo export OPENAI_MODELo1 ~/.zshrc echo export OPENAI_API_KEYsk-proj-USER_KEY ~/.zshrc source ~/.zshrc方案五使用 .gitignore 管理配置# 步骤 1将 .codex/ 加入 .gitignore echo .codex/ .gitignore # 步骤 2或只忽略 config.json echo .codex/config.json .gitignore # 步骤 3创建模板 cat .codex/config.example.json EOF { allowedDirectories: [./src, ./tests] } EOF # 步骤 4每人复制使用 cp .codex/config.example.json .codex/config.json方案六使用 --debug 诊断# 步骤 1使用 debug 模式 codex --debug 21 | tee /tmp/codex-debug.log # 步骤 2查看加载的配置 grep -i config\|model\|sandbox\|key /tmp/codex-debug.log # 步骤 3逐步排查 # 根据日志确定哪个配置在生效 # 步骤 4修复后验证 codex --debug 21 | grep model4. 各方案对比总结方案适用场景推荐指数难度方案一了解优先级排查⭐⭐⭐⭐⭐低方案二清理项目级冲突⭐⭐⭐⭐⭐低方案三统一配置长期⭐⭐⭐⭐⭐低方案四环境变量覆盖⭐⭐⭐⭐低方案五.gitignore团队⭐⭐⭐⭐⭐低方案六--debug诊断⭐⭐⭐⭐⭐低5. 常见问题 FAQ5.1 配置优先级是什么命令行 环境变量 项目级 config.json 用户级 config.json5.2 项目级配置在哪里在项目根目录的.codex/config.json。5.3 如何查看生效的配置codex --debug 21 | grep -i config5.4 .codexignore 也有优先级吗是的。项目级 .codexignore 覆盖用户级。5.5 如何避免团队配置冲突将.codex/config.json加入.gitignore使用config.example.json模板。5.6 环境变量能覆盖配置文件吗可以。环境变量优先级高于配置文件。5.7 如何删除项目级配置rm .codex/config.json # 或 rm -rf .codex/5.8 项目级应该放什么配置只放项目特定的配置如allowedDirectories。不放 model、API Key 等全局设置。5.9 多个项目使用不同模型使用环境变量或命令行参数cd project1 OPENAI_MODELo1 codex cd project2 OPENAI_MODELgpt-4o codex5.10 排查清单速查表□ 1. 了解优先级: CLI env 项目 用户 □ 2. cat .codex/config.json 检查项目级 □ 3. cat ~/.codex/config.json 检查用户级 □ 4. env | grep OPENAI 检查环境变量 □ 5. codex --debug 确认生效配置 □ 6. rm .codex/config.json 清理冲突 □ 7. 统一配置到用户级 □ 8. .gitignore 忽略 .codex/config.json □ 9. 使用 config.example.json 模板 □ 10. 环境变量覆盖配置文件6. 总结根本原因配置冲突最常见原因是项目级覆盖用户级40%和 .codexignore 不同步25%最佳实践了解优先级CLI env 项目 用户使用codex --debug确认生效配置统一配置全局设置model、API Key放在用户级项目特定设置放在项目级团队管理将.codex/config.json加入.gitignore使用config.example.json模板最佳实践建议使用环境变量OPENAI_MODEL、OPENAI_API_KEY覆盖配置文件确保跨项目一致性故障排查流程图flowchart TD A[配置冲突] -- B[检查所有配置来源] B -- C[cat .codex/config.json 项目级] B -- D[cat ~/.codex/config.json 用户级] B -- E[env | grep OPENAI 环境变量] C -- F{项目级有冲突?} D -- F E -- F F --|是| G[清理项目级配置] F --|否| H[codex --debug 确认] G -- I[rm .codex/config.json 或移除冲突键] I -- j[统一配置到用户级] j -- H H -- K{配置正确?} K --|是| L[✅ 问题解决] K --|否| M[使用环境变量覆盖] M -- N[export OPENAI_MODEL/API_KEY] N -- H L -- O[.gitignore 忽略 .codex/config.json] O -- P[使用 config.example.json 模板] P -- Q[✅ 长期方案]
)
