Claude Code Router 故障排查指南：10 分钟定位并修复 4 类常见故障

Claude Code Router 故障排查指南10 分钟定位并修复 4 类常见故障【免费下载链接】claude-code-routerOne local control plane for every AI agent: route across models, fuse new capabilities, orchestrate tools, and stay fully in control.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-code-routerClaude Code RouterCLI 命令 ccr负责把 AI 编码工具的请求路由到不同模型和供应商。这篇 Claude Code Router 故障排查指南带你按「先定位、再逐层深挖、最后预防」的动线走一遍目标是你 10 分钟内独立修好常见故障。先看报错30 秒定位到该查哪一层报错别慌它其实已经告诉你该查哪一层。网关把请求转发到上游模型的中间服务默认监听 3456 端口管理服务默认 3458 端口先对照这张表缩小范围报错现象先查哪层一条验证命令ccr start启动失败提示端口占用或秒退端口与进程第二层lsof -i :3456401/403 认证失败、API 调用超时网络与超时第三层curl -sv --max-time 10 -o /dev/null https://api.openai.com/v1/models路由命中错误模型、model not found路由逻辑第四层请求日志页对比resolved model判断口诀启动期出错查配置和端口运行期出错查网络和路由。⚙️ 第一层配置报错先查这里如果启动时报 JSON 语法错或找不到凭据问题多半出在配置这一层。当前版本的运行配置存在~/.claude-code-router目录的 SQLite关系型数据库文件config.sqlite里旧版 config.json 只作迁移来源读取一次位置与备份方式见 配置数据库位置。如果你手工维护过 JSON 文件或配置目录权限不对就按下面这条自查链走先验 JSON 语法再看目录是否可读。这一步检查遗留 JSON 配置是否合法并确认配置目录权限正常jq empty ~/.claude-code-router/config.json ls -la ~/.claude-code-router如果 jq 报错就回到编辑器修掉语法再重启否则检查报错里提到的环境变量名是否真的设置。密钥一般从环境变量读取缺失时表现就是 401 而不是配置错。怎么确认修好了重新执行ccr start不再出现配置类报错服务正常进入运行状态。 第二层端口 3456 与进程状态如果配置没问题但ccr start秒退多半是端口 3456 被占或者上次退出时留下的服务状态没清理干净状态文件 service.json 记录着后台服务的进程 ID 和地址。lsof 是列出端口占用进程的命令先看清楚谁占着这一步查看 3456 端口占用情况并用 ccr 自带的停止命令清理旧状态lsof -i :3456 ccr stop ccr start如果占用进程是 ccr 自己残留的ccr stop就能清掉否则说明是别的程序占了端口就 kill 掉它的 PID或者换端口启动并记下打印出的实际地址。另外记住前台运行ccr serve不受ccr stop管理要看日志排查时优先用它错误会直接打在当前终端。怎么确认修好了启动输出里打印出网关地址访问该地址能正常响应说明端口和服务都已就绪。 第三层网络连通与 API 超时服务起来了但模型调用失败接下来看网络这一段。这类问题分三种代理没配、密钥不对、超时太短顺序排查就行。先确认代理环境变量再直接 curl 上游curl 模拟一次真实 HTTP 请求这一步检查代理设置并测试到上游 API 的连通性printenv | grep -i proxy curl -sv --max-time 10 -o /dev/null https://api.openai.com/v1/models如果 curl 卡在连接阶段就检查代理或换网络否则如果连通但返回 401就核对密钥再否则如果网络正常、只是慢请求被掐断就调大超时。默认 API 超时是 60000ms长上下文或慢速供应商可以适当放大怎么确认修好了curl 返回 200或至少返回供应商的 JSON 认证提示而非超时再发一次真实请求能拿到模型回复。 第四层路由逻辑命中检查前三层都正常但请求总走到错误模型那就是路由规则决定请求交给哪个供应商和模型的配置的问题。规则按顺序匹配顺序或条件不对就会命中错误目标官方 常见问题 里也建议以请求日志为准。开调试日志然后打一条最小请求看它落到哪里这一步打开 debug 日志并向本地网关发一条最小请求验证路由命中export LOG_LEVELdebug curl -s http://127.0.0.1:3456/v1/chat/completions \ -H Authorization: Bearer $CCR_API_KEY -H Content-Type: application/json \ -d {model:gpt-4,messages:[{role:user,content:hi}]}如果响应里的模型不是你期望的就到请求日志对比request model请求声明的模型和resolved model路由解析后实际使用的模型再回路由页调整规则顺序或回退fallback主模型失败后改用的备选规则。怎么确认修好了连续两条请求的 resolved model 都等于你配置的目标模型日志里不再出现意外的供应商。一个真实排障过程ccr start 启动失败下面是完整走一遍的典型流程跟着做即可。执行ccr start命令秒退终端提示端口 3456 已被占用。这个报错很常见先别动配置。运行lsof -i :3456发现一个上次没停干净的旧 node 进程还占着端口记下它的 PID。先ccr stop清理失效的服务状态再kill掉那个残留 PID然后重新ccr start。服务这次正常启动并打印出网关地址发一条测试请求日志显示它命中了默认模型故障恢复。坏掉之前做的 5 件事修完别忘加固以下 5 件事把故障挡在发生之前备份配置定期从设置页导出数据不要在 CCR 运行时直接改 SQLite 文件。健康检查用脚本定期探测 /health健康检查用一个轻量请求确认服务还活着curl -s -o /dev/null -w %{http_code} http://127.0.0.1:3456/health监控内存进程 RSS 长期超过 1GB 就安排重启防内存缓慢增长。日志常开请求日志和观测开关保持打开出问题先查 resolved model 不靠猜。告警到位/health 非 200 或管理端口失联时让你能及时收到通知。排障的本质不是背命令而是先定位层、再逐层缩小范围本文的顺序就是这条路径。把上表当成你的第一反应把请求日志当成最终裁判。实操提示每次改完配置先发一条测试请求并核对日志里的 resolved model再投入日常使用——这是成本最低的验证方式。【免费下载链接】claude-code-routerOne local control plane for every AI agent: route across models, fuse new capabilities, orchestrate tools, and stay fully in control.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-code-router创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考