【Bug已解决】codex: 配置文件解析错误 — CodeX CLI 配置格式无效解决方案

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

1. 问题描述

CodeX CLI 无法解析配置文件 config.json，导致启动失败：

# JSON 解析错误
$ codex "task"
Error: Failed to parse config.json
Unexpected token } at position 42.

# 或配置值类型错误
$ codex "task"
Error: Invalid configuration
'maxTurns' must be a number, got string.

# 或配置字段不存在
$ codex "task"
Error: Unknown configuration key: 'auto_mode'
Did you mean 'autoApprove'?

# 或配置文件不存在
$ codex "task"
Error: config.json not found
No configuration file in ~/.codex/ or .codex/.

这个问题在以下场景中特别常见：

• JSON 语法错误（尾逗号、引号）
• 配置值类型错误
• 配置字段名错误
• 配置文件路径不对
• 编码问题（BOM）
• 注释不支持

2. 原因分析

原因分类表

原因分类	具体表现	占比
JSON 语法	尾逗号/引号	约 40%
值类型错误	string vs number	约 25%
字段名错误	auto_mode	约 15%
路径不对	不在 .codex/	约 10%
编码问题	BOM	约 5%
注释	// 不支持	约 5%

3. 解决方案

方案一：验证 JSON 格式（最推荐）

# 步骤 1：验证 JSON
python3 -m json.tool .codex/config.json

# 步骤 2：如果报错，查看错误位置
python3 -c "
import json
try:
    json.load(open('.codex/config.json'))
    print('Valid JSON')
except json.JSONDecodeError as e:
    print(f'Error at line {e.lineno}, col {e.colno}: {e.msg}')
"

# 步骤 3：修复后验证
python3 -m json.tool .codex/config.json

# 步骤 4：测试
codex "task"

方案二：重新创建配置

# 步骤 1：备份旧配置
cp .codex/config.json .codex/config.json.bak

# 步骤 2：重新创建
cat > .codex/config.json << 'EOF'
{
  "model": "o1",
  "maxTurns": 30,
  "sandbox": {
    "enabled": true,
    "autoApprove": true,
    "allowedDirectories": ["./src", "./tests"]
  }
}
EOF

# 步骤 3：验证
python3 -m json.tool .codex/config.json

# 步骤 4：测试
codex --print "hello" --max-turns 1

方案三：修复常见 JSON 错误

# 步骤 1：检查尾逗号
# 错误: {"model": "o1",}
# 正确: {"model": "o1"}

# 步骤 2：检查引号
# 错误: {'model': 'o1'}  (单引号)
# 正确: {"model": "o1"}  (双引号)

# 步骤 3：检查注释
# 错误: {"model": "o1"} // 注释
# 正确: {"model": "o1"}  (JSON 不支持注释)

# 步骤 4：重新创建
cat > .codex/config.json << 'EOF'
{
  "model": "o1",
  "maxTurns": 30
}
EOF
codex "task"

方案四：检查配置值类型

# 步骤 1：检查类型
# maxTurns: number (不是 string)
# sandbox.enabled: boolean (不是 string)
# allowedDirectories: array (不是 string)

# 步骤 2：正确类型
cat > .codex/config.json << 'EOF'
{
  "model": "o1",
  "maxTurns": 30,
  "sandbox": {
    "enabled": true,
    "autoApprove": true,
    "allowedDirectories": ["./src", "./tests"]
  }
}
EOF

# 步骤 3：验证
python3 -m json.tool .codex/config.json

# 步骤 4：测试
codex --print "hello" --max-turns 1

方案五：检查文件位置

# 步骤 1：检查位置
ls -la .codex/config.json
ls -la ~/.codex/config.json

# 步骤 2：如果没有 .codex 目录
mkdir -p .codex

# 步骤 3：创建配置
cat > .codex/config.json << 'EOF'
{
  "model": "o1",
  "maxTurns": 30
}
EOF

# 步骤 4：验证
codex --debug 2>&1 | grep -i "config\|settings"

方案六：检查编码

# 步骤 1：检查编码
file -I .codex/config.json
# 应该是: application/json; charset=utf-8

# 步骤 2：如果有 BOM
# 使用 sed 移除 BOM
sed -i '1s/^\xEF\xBB\xBF//' .codex/config.json

# 步骤 3：或重新创建（无 BOM）
cat > .codex/config.json << 'EOF'
{
  "model": "o1",
  "maxTurns": 30
}
EOF

# 步骤 4：验证
file -I .codex/config.json
python3 -m json.tool .codex/config.json

4. 各方案对比总结

方案	适用场景	推荐指数	难度
方案一：验证 JSON	排查	⭐⭐⭐⭐⭐	低
方案二：重新创建	严重	⭐⭐⭐⭐⭐	低
方案三：修复错误	语法	⭐⭐⭐⭐⭐	低
方案四：检查类型	类型	⭐⭐⭐⭐⭐	低
方案五：检查位置	路径	⭐⭐⭐⭐⭐	低
方案六：检查编码	BOM	⭐⭐⭐⭐	低

5. 常见问题 FAQ

5.1 如何验证 JSON

python3 -m json.tool .codex/config.json

5.2 JSON 支持注释吗

不支持。JSON 标准不允许 // 或 /* */ 注释。

5.3 JSON 用什么引号

双引号 "，不是单引号 '。

5.4 尾逗号允许吗

不允许。{"model": "o1",} 是错误的。

5.5 config.json 在哪里

• 项目级: .codex/config.json
• 用户级: ~/.codex/config.json

5.6 常见的配置字段

model, maxTurns, sandbox, maxTokens, allowedDirectories。

5.7 maxTurns 是什么类型

数字（number），不是字符串。30 不是 "30"。

5.8 BOM 是什么

Byte Order Mark。某些编辑器在文件开头添加，导致 JSON 解析失败。

5.9 如何查看错误位置

python3 -c "import json; json.load(open('file.json'))"
# 显示错误行和列

5.10 排查清单速查表

□ 1. python3 -m json.tool 验证 JSON
□ 2. 检查尾逗号
□ 3. 使用双引号 "
□ 4. 不使用注释
□ 5. maxTurns: 30 (number)
□ 6. sandbox.enabled: true (boolean)
□ 7. allowedDirectories: ["./src"] (array)
□ 8. mkdir -p .codex 创建目录
□ 9. file -I 检查编码
□ 10. sed 移除 BOM

6. 总结

1. 根本原因：配置解析错误最常见原因是 JSON 语法错误（40%）和值类型错误（25%）
2. 最佳实践 ：使用 python3 -m json.tool 验证 JSON 格式
3. JSON 规则：双引号、无尾逗号、无注释、正确类型
4. 重新创建：如果无法修复，重新创建 config.json
5. 最佳实践建议 ：检查编码（BOM），确保配置在 .codex/config.json 位置

故障排查流程图

flowchart TD A[config.json 解析错误] --> B[python3 -m json.tool 验证] B --> C{JSON 有效?} C -->|是| D[检查值类型] C -->|否| E[修复 JSON 语法] D --> F{类型正确?} F -->|否| G[修复类型] F -->|是| H[检查文件位置] E --> I[修复尾逗号/引号/注释] G --> j[maxTurns: number, enabled: boolean] I --> K[重新创建 config.json] j --> K K --> L[python3 -m json.tool 验证] L --> M[codex --print hello 验证] H --> N{在 .codex/?} N -->|否| O[mkdir -p .codex] N -->|是| P[检查编码] O --> K P --> Q[file -I 检查] Q --> R{有 BOM?} R -->|是| S[sed 移除 BOM] R -->|否| M S --> M M --> T{成功?} T -->|是| U[✅ 问题解决] T -->|否| V[重新创建配置] V --> K U --> W[长期: json.tool + 正确类型 + 无 BOM] W --> X[✅ 长期方案]