【Bug已解决】codex config.json parse error / Invalid configuration — CodeX CLI 配置文件解析错误解决方案

【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() 解析 ↓ 格式错误 / 配置项名称错误 / 编码问题 ↓ 解析失败 → 使用默认配置或报错

原因分类表

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 codex

4. 各方案对比总结

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 # 或删除配置文件后启动 codex

5.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. 总结

1. 根本原因：配置文件解析错误最常见原因是缺少引号（30%）、尾部逗号（25%）和单引号（20%）
2. 最佳实践：编辑 config.json 后运行python3 -m json.tool ~/.codex/config.json验证格式
3. 配置项名称：使用codex config list确认正确的配置项名称，避免使用错误的 key
4. JSON 规范：不支持注释和单引号，所有 key 和字符串值用双引号，不能有尾部逗号
5. 最佳实践建议：使用 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