Claude Code Router 故障排查从四个症状定位八成问题【免费下载链接】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终端抛出ECONNREFUSED、Claude Code 迟迟没有响应的时候别急着重启。每次 Claude Code Router 故障排查其实都从同一个问题开始本地服务到底还活着没有还是请求卡在了中间某一段。下面按看到什么现象 → 先查哪里 → 怎么修 → 怎么防再犯的完整动线走一遍。看到 connection refused先确认进程和端口你会看到什么客户端侧报错、请求石沉大海本地像没有任何东西在听。执行什么用两条命令确认服务进程存在、且3456端口真的在被监听ps aux | grep -v grep | grep claude-code-router ss -tulpn | grep 3456 # macOS 也可用 lsof -i :3456预期结果两条命令都有输出说明服务活着问题在下游直接跳到 API 报错一节。进程不存在、或3456没有监听项说明服务没起来往下继续查端口占用。3456 端口被占用三种处理方式你会看到什么ccr start执行后立即退出日志里出现EADDRINUSE——3456 已被别的进程占住。执行什么lsof -i :3456 # 找出占用进程 kill -9 $(lsof -t -i:3456) # 确认是 CCR 残留进程才杀 ccr start --port 3457 # 或换端口避开按占用者身份选择上次 CCR 留下的僵尸进程直接杀是别的合法服务就换端口启动不要误杀。预期结果终端打印服务地址和 pid再跑一次ss -tulpn | grep 3457能看到监听。现象多半是第一动作启动即退出3456 被占用释放端口或--port换端口启动成功但请求打不进来绑定到了非本机 host检查--host参数客户端 ECONNREFUSED服务根本没在跑ccr start后复查端口401、502 与超时三种报错指向三个方向服务活着但请求失败时响应代码已经把方向指出来了401 / 403是密钥缺失或过期502 / 504是上游模型服务不可达请求挂住直到超时则是网络绕路或超时设置偏小。执行什么一条 curl 测上游连通性与密钥一行 env 确认代理没有拦路curl -sS -o /dev/null -w %{http_code}\n \ https://api.openai.com/v1/models -H Authorization: Bearer $OPENAI_API_KEY env | grep -i proxy预期结果返回200说明网络与密钥都没问题去查路由配置返回401说明密钥错了连接直接超时、且第二条命令打印出 proxy 变量说明代理在拦截流量——去掉代理或在配置里显式声明就能解决大部分 API 调用超时。配置文件JSON 语法与环境变量一行校验你会看到什么服务起来了但配置像没生效或者启动日志报字段缺失。配置默认在~/.claude-code-router/目录下config.json 为遗留格式新版本主配置已迁入同目录的config.sqlite排查时两者都要留意。执行什么jq empty ~/.claude-code-router/config.json echo JSON OK node -e console.log(process.env.OPENAI_API_KEY ? KEY SET : KEY NOT SET) ls -la ~/.claude-code-router/预期结果jq empty无输出且退出码为 0语法没问题打印出行号和期望符号就照那一行修。KEY NOT SET意味着配置里引用的变量根本不存在要么补变量要么改成字面量。ls确认目录与文件归属正常、当前用户可读可写。自定义路由不生效发一个探针请求看它进了哪个分支你会看到什么改了路由逻辑行为却和原来一模一样甚至直接 500。执行什么开 debug 日志后发一个最小化探针请求确认它实际走进了哪条分支LOG_LEVELdebug ccr restart curl -sS -X POST http://localhost:3456/v1/chat/completions \ -H Content-Type: application/json \ -d {model:deepseek-chat,messages:[{role:user,content:ping}]}debug 日志显示请求进了自定义 router 却返回错误 provider问题就在脚本本身。临时加几行输出只留关键字段module.exports async function router(req, config) { const last req.body.messages[req.body.messages.length - 1]; console.log(route:, req.body.model, | msgs:, req.body.messages.length, | head:, String(last?.content ?? ).slice(0, 80)); return { provider: deepseek, model: deepseek-chat }; };预期结果日志里出现模型名与最后一条消息的前80 个字符对着你预期的分支核对一遍错了改回来修完删掉临时输出。修完之后做三件事防止复发先让服务自证健康把对本地3456端口的 GET 探活挂进定时任务返回非200就自动ccr stop再ccr start不用等人发现。再给关键指标设阈值超过就介入指标告警阈值检查频率内存 RSS超过1GB30sAPI 响应耗时超过10s60s请求错误率超过5%5 分钟最后把配置纳入版本管理每次改动后复制一份带时间戳的快照或直接在配置目录里用 git 提交回滚时不用猜改了什么。长期运行前的检查清单逐条过一遍再放手3456有监听且监听者是 CCR 进程配置引用的每个环境变量都能echo出值curl 上游端点返回200探针请求端到端走通路由落在预期 provider 上。【免费下载链接】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），仅供参考