JSON / API 配置错误导致服务启动失败

你会遇到什么

你改了 provider 或 profile 配置，然后 ccr start 直接报错、甚至崩溃；或者服务起来了，但管理界面 API 一路 500。改配置改出问题，服务起不来，又不知道错在哪一行。

本文路径：快速修复（30 秒一段命令）→ 一步步排查（可跳读）→ 原理与变体（症状/原因/证据）。赶时间直接跳到「快速修复」。

为什么会这样

配置文件对语法和字段名都极其敏感：

• JSON 语法错误：多一个逗号、少一个引号 → 解析直接失败 → 服务起不来。
• 字段名/结构错误：api_base_url、type 这类字段拼写错或层级不对，解析能过但运行时报错 → 管理界面 API 500。

配置真实写入面是 ~/.claude-code-router/config.sqlite（本市场实测），改错后恢复备份即可回滚。

配置驱动型服务启动时有两道独立的“闸门”：语法解析和语义校验。语法闸门在启动最前面——JSON 多一个逗号/少一个引号，解析器直接抛错，服务根本没机会起来，表现是“启动即失败/崩溃”；语义闸门在解析之后——字段拼写错或层级不对，JSON 解析能过，但服务按错误字段取值，运行到路由/API 层才炸，表现是“能启动但 500”。这就是“同样改错，表现完全不同”的原因。

两个闸门对应两种定位工具：语法闸门用 jq empty/python3 -m json.tool 一次定位到行；语义闸门只能对照项目配置文档逐个核对字段。还有个确定性保障：改配置前先备份——配置文件是状态，备份让“改错”从不可逆变成可逆，恢复 = 删除 + 移回 + 重启三步固定。

一步步来

1. 先备份 — 必做

cp -r ~/.claude-code-router ~/.claude-code-router.bak

改配置前永远先备份，改坏了有后悔药。

2. 校验 JSON 语法 — 必做

jq empty <你的配置文件>

没输出 = 语法 OK；有报错会指出第几行。没有 jq 可用 python3 -m json.tool 文件。

3. 对照文档核对字段 — 必做

打开项目配置文档，逐个核对 api_base_url、type 等字段名与层级，别只凭记忆写。

4. 改错就恢复备份并重启 — 必做

rm -rf ~/.claude-code-router && mv ~/.claude-code-router.bak ~/.claude-code-router && ccr restart

怎么确认修好了

配置修复后，服务能正常启动（预期输出形态）：

ccr start
→ 服务正常启动日志，无 JSON 解析错误 / 崩溃

管理界面 API 不再返回 500；改一条测试配置能正常保存并生效。

其它环境的表现

症状

修改配置后 ccr start 报错或崩溃；管理界面 API 返回 500。

原因

provider/profile 配置 JSON 语法错误或字段名不符（如 api_base_url、type 拼写/结构错误）。

解法

1. 改前备份配置文件（~/.claude-code-router/）。
2. 改后用 JSON 校验工具检查语法。
3. 对照项目配置文档核对字段；改错恢复备份后重启。