【Bug已解决】codex: config.json parse error / Invalid configuration — CodeX CLI 配置文件解析错误解决方案
1. 问题描述
CodeX CLI 启动时报配置文件解析错误：
$ codex Error: Failed to parse config.json SyntaxError: Unexpected token ' in JSON at position 30 # 或配置不生效 $ cat ~/.codex/config.json {model: "gpt-4o", maxTokens: 4096,} # 缺少引号 + 尾部逗号 $ codex Warning: Invalid config.json, using defaults # 或配置项不识别 $ cat ~/.codex/config.json {"modelName": "gpt-4o"} # 错误的 key 名 $ codex Warning: Unknown config option 'modelName'这个问题在以下场景中特别常见：
- 手动编辑 JSON 时格式错误
- 配置项名称拼写错误
- JSON 尾部逗号或单引号
- 文件编码不是 UTF-8
- 配置工具写入非标准 JSON
- 多配置文件冲突
2. 原因分析
核心原理拆解
config.json → JSON.parse() 解析 ↓ 格式错误 / 配置项名称错误 / 编码问题 ↓ 解析失败 → 使用默认配置或报错原因分类表
| 原因分类 | 具体表现 | 占比 |
|---|---|---|
| 缺少引号 | key 未用双引号 | 约 30% |
| 尾部逗号 | 最后属性后有逗号 | 约 25% |
| 单引号 | 使用 ' 代替 " | 约 20% |
| 配置项错误 | key 名称不对 | 约 15% |
| 编码问题 | 非 UTF-8 | 约 5% |
| 多文件冲突 | 项目级覆盖 | 约 5% |
3. 解决方案
方案一：使用 JSON 验证工具（最推荐）
# 步骤 1：验证 JSON 格式 python3 -m json.tool ~/.codex/config.json # 会指出具体错误位置和类型 # 步骤 2：或使用 node 验证 node -e "JSON.parse(require('fs').readFileSync(require('os').homedir()+'/.codex/config.json','utf8'))" # 步骤 3：或使用 jq 验证 cat ~/.codex/config.json | jq . # 步骤 4：根据错误信息修复方案二：重写正确的配置文件
# 步骤 1：备份 cp ~/.codex/config.json ~/.codex/config.json.bak # 步骤 2：重写正确格式 cat > ~/.codex/config.json << 'EOF' { "model": "gpt-4o", "maxTokens": 4096, "temperature": 0.7, "sandbox": { "enabled": true, "allowedDirectories": ["./src", "./tests"] } } EOF # 步骤 3：验证 python3 -m json.tool ~/.codex/config.json # 不报错说明格式正确 # 步骤 4：启动 codex方案三：修复常见 JSON 错误
# 错误 1: 缺少引号 # 错误: {model: "gpt-4o"} # 正确: {"model": "gpt-4o"} # 错误 2: 尾部逗号 # 错误: {"model": "gpt-4o",} # 正确: {"model": "gpt-4o"} # 错误 3: 单引号 # 错误: {'model': 'gpt-4o'} # 正确: {"model": "gpt-4o"} # 步骤 1：使用 sed 批量修复 sed -i "s/'/\"/g" ~/.codex/config.json sed -i 's/,\s*}/}/g' ~/.codex/config.json sed -i 's/,\s*]/]/g' ~/.codex/config.json # 步骤 2：验证 python3 -m json.tool ~/.codex/config.json方案四：使用正确的配置项名称
# 步骤 1：查看正确的配置项 codex --help 2>&1 | grep -A 20 "config" # 或 codex config list # 步骤 2：常见配置项 # model（不是 modelName） # maxTokens（不是 max_tokens） # temperature（不是 temp） # sandbox.enabled（不是 sandboxEnabled） # 步骤 3：使用正确名称重写 cat > ~/.codex/config.json << 'EOF' { "model": "gpt-4o", "maxTokens": 4096, "temperature": 0.7 } EOF方案五：检查文件编码
# 步骤 1：检查编码 file ~/.codex/config.json # 应该是 UTF-8 或 ASCII # 步骤 2：如果不是 UTF-8 iconv -f GBK -t UTF-8 ~/.codex/config.json > ~/.codex/config.json.utf8 mv ~/.codex/config.json.utf8 ~/.codex/config.json # 步骤 3：验证 file ~/.codex/config.json python3 -m json.tool ~/.codex/config.json方案六：删除配置使用默认值
# 步骤 1：如果配置一直报错 mv ~/.codex/config.json ~/.codex/config.json.bak # 步骤 2：不使用配置文件启动 codex # 使用默认配置 # 步骤 3：逐步添加配置项 # 每次添加一个配置项并验证 echo '{"model": "gpt-4o"}' > ~/.codex/config.json python3 -m json.tool ~/.codex/config.json codex4. 各方案对比总结
| 方案 | 适用场景 | 推荐指数 | 难度 |
|---|---|---|---|
| 方案一：验证工具 | 排查 | ⭐⭐⭐⭐⭐ | 低 |
| 方案二：重写 | 格式损坏 | ⭐⭐⭐⭐⭐ | 低 |
| 方案三：sed 修复 | 批量修复 | ⭐⭐⭐⭐ | 中 |
| 方案四：正确名称 | 配置项错误 | ⭐⭐⭐⭐⭐ | 低 |
| 方案五：编码修复 | 非 UTF-8 | ⭐⭐⭐ | 低 |
| 方案六：默认值 | 临时方案 | ⭐⭐⭐ | 低 |
5. 常见问题 FAQ
5.1 CodeX 的配置文件在哪里
- 用户级:
~/.codex/config.json - 项目级:
.codex/config.json（项目根目录）
5.2 常见的配置项有哪些
{ "model": "gpt-4o", "maxTokens": 4096, "temperature": 0.7, "sandbox": {"enabled": true}, "requestTimeout": 60000 }5.3 如何验证 JSON 格式
python3 -m json.tool ~/.codex/config.json # 或 cat ~/.codex/config.json | jq .5.4 JSON 支持注释吗
不支持。标准 JSON 不允许//或/* */注释。使用_comment字段代替。
5.5 项目级和用户级配置冲突
项目级配置覆盖用户级的相同配置项。如果项目级格式错误会影响加载。
5.6 如何查看默认配置
codex config list --defaults # 或删除配置文件后启动 codex5.7 配置不生效但不报错
可能是配置项名称错误。使用codex config list确认正确的配置项名称。
5.8 使用 VS Code 编辑配置
VS Code 有 JSON 语法检查功能，编辑时会实时标出格式错误。
5.9 多个配置文件如何管理
用户级~/.codex/config.json是全局配置，项目级.codex/config.json是项目特定配置。两者合并。
5.10 排查清单速查表
□ 1. python3 -m json.tool 验证 JSON □ 2. key 和 value 用双引号 □ 3. 删除尾部逗号 □ 4. 单引号改为双引号 □ 5. 使用正确的配置项名称 □ 6. file 命令检查编码为 UTF-8 □ 7. codex config list 查看正确名称 □ 8. 删除配置文件使用默认值测试 □ 9. 检查项目级和用户级冲突 □ 10. VS Code 编辑器实时验证6. 总结
- 根本原因：配置文件解析错误最常见原因是缺少引号（30%）、尾部逗号（25%）和单引号（20%）
- 最佳实践：编辑 config.json 后运行
python3 -m json.tool ~/.codex/config.json验证格式 - 配置项名称：使用
codex config list确认正确的配置项名称，避免使用错误的 key - JSON 规范：不支持注释和单引号，所有 key 和字符串值用双引号，不能有尾部逗号
- 最佳实践建议：使用 VS Code 等 JSON 语法检查编辑器编辑配置文件，编辑器实时标出格式错误
故障排查流程图
flowchart TD A[config.json 解析错误] --> B[python3 -m json.tool 验证] B --> C{格式正确?} C -->|是| D[检查配置项名称] C -->|否| E[查看错误位置] E --> F{错误类型?} F -->|缺少引号| G[添加双引号] F -->|尾部逗号| H[删除逗号] F -->|单引号| I[改为双引号] F -->|编码| J[iconv 转 UTF-8] G --> K[重新验证] H --> K I --> K J --> K K --> L{验证通过?} L -->|是| M[codex config list 确认名称] L -->|否| N[重写 config.json] N --> M D --> O{名称正确?} M --> O O -->|是| P[重启 codex] O -->|否| Q[使用正确名称] Q --> P P --> R{配置生效?} R -->|是| S[✅ 问题解决] R -->|否| T[删除配置用默认值] T --> S
