Claude Code Router 故障解决指南

故障诊断决策树

flowchart TD
    A[故障发生] --> B{观察现象}
    
    B --> C[服务未启动]
    B --> D[请求无响应]
    B --> E[配置加载失败]
    B --> F[路由异常]
    
    C --> C1[检查进程状态]
    C --> C2[查看启动日志]
    C --> C3[验证依赖环境]
    
    D --> D1[测试网络连通性]
    D --> D2[检查API密钥]
    D --> D3[分析响应超时]
    
    E --> E1[验证JSON格式]
    E --> E2[检查环境变量]
    E --> E3[确认文件权限]
    
    F --> F1[启用路由调试]
    F --> F2[检查模型配置]
    F --> F3[验证转换器逻辑]
    
    C1 & C2 & C3 --> G[服务启动类故障]
    D1 & D2 & D3 --> H[API通信类故障]
    E1 & E2 & E3 --> I[配置解析类故障]
    F1 & F2 & F3 --> J[路由逻辑类故障]

[S001] 服务启动故障

故障现象

• 执行 ccr start 命令后无任何输出或立即退出
• 终端显示 "Address already in use" 错误信息
• 服务进程未在后台持续运行

核心原因

1. 默认端口（3456）被其他应用占用
2. 配置文件权限不足导致无法读取
3. 依赖包未正确安装或版本不兼容
4. 残留进程PID文件导致启动冲突

解决方案

方案1：端口冲突解决

# 查找占用3456端口的进程
sudo lsof -i :3456 -P -n | grep LISTEN

# 终止占用进程（风险等级：中）
kill -TERM $(lsof -t -i:3456)

# 或使用备用端口启动（风险等级：低）
ccr start --port 3458

适用场景：临时解决端口冲突，推荐用于开发环境

方案2：权限问题修复

# 检查配置目录权限
ls -ld ~/.claude-code-router

# 修复权限（风险等级：低）
chmod -R 700 ~/.claude-code-router

# 检查配置文件所有者
ls -la ~/.claude-code-router/config.json

适用场景：服务提示"Permission denied"错误时使用

方案3：依赖与环境修复

# 重新安装依赖（风险等级：中）
cd /data/web/disk1/git_repo/GitHub_Trending/cl/claude-code-router
pnpm install --force

# 检查Node.js版本兼容性
node -v | grep -E "v16|v18" || echo "Node.js版本不兼容"

# 清理缓存并重启（风险等级：低）
ccr stop
rm -rf ~/.claude-code-router/cache
ccr start

适用场景：服务启动时报错"Module not found"或类似依赖错误

预防措施

1. 设置开机自启动脚本，确保服务稳定运行
2. 定期执行 ccr check 命令验证系统环境
3. 使用进程管理工具如PM2监控服务状态：

   # 安装PM2（风险等级：低）
   npm install -g pm2
   
   # 创建启动脚本
   cat > start-ccr.sh << 'EOF'
   #!/bin/bash
   export PATH=$PATH:/usr/local/bin
   ccr start --port 3456
   EOF
   
   # 使用PM2管理服务
   pm2 start start-ccr.sh --name "claude-code-router"
   pm2 save
   pm2 startup
   

[A001] API通信故障

故障现象

• 客户端收到401/403错误响应
• 请求超时无响应
• 模型返回"Invalid API Key"错误信息

核心原因

1. API密钥未正确配置或已过期
2. 网络代理设置错误或防火墙拦截
3. 请求参数超出API提供商限制
4. 服务端API端点变更未同步更新

解决方案

方案1：API密钥验证与更新

# 检查环境变量设置（风险等级：低）
echo $OPENAI_API_KEY | cut -c1-5 # 仅显示前5位验证是否设置

# 验证JSON配置中的密钥引用（风险等级：低）
grep -A 5 "openai" ~/.claude-code-router/config.json

# 临时设置新密钥测试（风险等级：低）
OPENAI_API_KEY="sk-newkey..." ccr start

适用场景：明确收到认证错误时使用

方案2：网络连接诊断

# 测试API端点连通性（风险等级：低）
curl -v -X POST https://api.openai.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{"model":"gpt-3.5-turbo","messages":[{"role":"user","content":"test"}]}'

# 检查代理配置（风险等级：低）
cat ~/.claude-code-router/config.json | grep -i proxy

# 使用代理测试连接（风险等级：低）
export https_proxy=http://127.0.0.1:7890
ccr start

适用场景：网络环境复杂或需要代理访问API时

方案3：API请求参数调整

// ~/.claude-code-router/config.json
{
  "API_TIMEOUT_MS": 180000,  // 增加超时时间至3分钟
  "Providers": [
    {
      "name": "openai",
      "api_base_url": "https://api.openai.com/v1/chat/completions",
      "api_key": "$OPENAI_API_KEY",
      "timeout": 90000,  // 单独设置该提供商超时
      "retry_count": 3,  // 添加重试机制
      "retry_delay": 2000  // 重试间隔2秒
    }
  ]
}

适用场景：API请求频繁超时或偶尔失败时

预防措施

1. 实现API密钥轮换机制，定期更新密钥
2. 添加请求重试与退避策略，增强容错能力
3. 监控API响应时间和错误率，设置告警阈值
4. 维护API提供商状态页面订阅，及时获取服务变更通知

[C001] 配置解析故障

故障现象

• 服务启动时报"JSON parse error"
• 配置变更后服务行为未改变
• 环境变量引用未正确解析

核心原因

1. JSON配置文件存在语法错误
2. 环境变量引用格式不正确
3. 配置文件路径或权限问题
4. 配置项数据类型不匹配

解决方案

方案1：JSON语法验证

# 验证配置文件语法（风险等级：低）
jq empty ~/.claude-code-router/config.json

# 定位语法错误（风险等级：低）
cat -n ~/.claude-code-router/config.json | grep -n "error"

适用场景：服务启动时明确提示JSON解析错误

方案2：环境变量引用修复

// 错误示例
{
  "api_key": "$OPENAI_API_KEY"  // 正确格式应为"{{OPENAI_API_KEY}}"
}

// 正确示例
{
  "api_key": "{{OPENAI_API_KEY}}"  // 使用双大括号包裹环境变量
}

适用场景：配置中的环境变量未被正确替换时

方案3：配置文件恢复

# 查找最近的配置备份（风险等级：低）
ls -lt ~/.claude-code-router/config.json.*.bak | head -n 1

# 恢复最近的备份配置（风险等级：中）
cp ~/.claude-code-router/config.json.20231015_143022.bak ~/.claude-code-router/config.json

# 使用默认配置重建（风险等级：高）
ccr init --force

适用场景：配置文件损坏且无法快速修复时

预防措施

1. 使用配置验证工具定期检查配置完整性
2. 实现配置变更版本控制，保留历史修改记录
3. 配置文件变更前创建自动备份
4. 开发环境中启用配置热加载，避免服务重启

[R001] 路由逻辑故障

故障现象

• 请求未路由到预期的模型
• 自定义路由规则不生效
• 路由决策与配置预期不符

核心原因

1. 路由规则定义存在逻辑错误
2. 模型可用性检查失败
3. 请求参数不符合路由匹配条件
4. 自定义路由函数存在bug

解决方案

方案1：路由规则验证

# 启用路由调试日志（风险等级：低）
export CCR_ROUTER_DEBUG=true
ccr restart

# 查看路由决策过程（风险等级：低）
tail -f ~/.claude-code-router/logs/router-debug.log | grep "Routing decision"

适用场景：需要了解路由决策依据时

方案2：自定义路由调试

// custom-router.js - 添加详细调试日志
module.exports = async function router(req, config) {
  // 记录请求基本信息
  console.log(`[ROUTER_DEBUG] Request model: ${req.body.model}`);
  console.log(`[ROUTER_DEBUG] Message count: ${req.body.messages.length}`);
  
  // 记录关键决策点
  const contentLength = req.body.messages[0]?.content?.length || 0;
  console.log(`[ROUTER_DEBUG] Content length: ${contentLength}`);
  
  // 简单路由逻辑示例
  if (contentLength > 1000) {
    console.log(`[ROUTER_DEBUG] Routing to long-content model`);
    return { provider: "openai", model: "gpt-4" };
  }
  
  // 返回null使用默认路由
  return null;
};

适用场景：自定义路由不按预期工作时

方案3：路由配置重置

# 导出当前路由配置（风险等级：低）
ccr router export > router-backup.json

# 重置为默认路由配置（风险等级：中）
ccr router reset

# 验证路由配置（风险等级：低）
ccr router test --prompt "测试路由" --model "gpt-3.5-turbo"

适用场景：路由配置混乱且难以修复时

预防措施

1. 为路由规则编写单元测试，验证不同场景下的路由决策
2. 实现路由决策模拟工具，在不发送实际请求的情况下测试路由
3. 使用版本控制管理自定义路由脚本变更
4. 定期审查路由统计数据，识别异常路由模式

故障排查效率工具

1. ccr-diag - 专用诊断工具

Claude Code Router自带的诊断工具，可快速检查系统状态：

# 运行完整系统诊断（风险等级：低）
ccr diag --full

# 检查特定模块（风险等级：低）
ccr diag --module router
ccr diag --module providers

功能：自动检查配置完整性、依赖状态、网络连通性和服务健康度

2. jq - JSON处理工具

用于解析和操作配置文件的强大命令行工具：

# 提取所有配置的提供商
jq '.Providers[].name' ~/.claude-code-router/config.json

# 检查特定提供商配置
jq '.Providers[] | select(.name == "openai")' ~/.claude-code-router/config.json

适用场景：快速查询和修改JSON配置文件

3. httpie - HTTP客户端工具

用于测试API端点的用户友好工具：

# 测试本地API服务
http POST http://localhost:3456/v1/chat/completions \
  model="gpt-3.5-turbo" \
  messages:='[{"role":"user","content":"Hello"}]'

适用场景：直接测试API接口，验证服务响应

4. pm2 - 进程管理工具

用于监控和管理服务进程：

# 安装pm2（风险等级：低）
npm install -g pm2

# 使用pm2启动并监控服务
pm2 start "ccr start" --name ccr
pm2 monit  # 实时监控CPU和内存使用

适用场景：需要长期稳定运行服务并监控性能时

常见误区解析

误区1：过度依赖默认配置

许多用户在遇到问题时未检查默认配置是否适合其使用场景。例如，默认超时设置可能不适合网络条件较差的环境，导致频繁请求失败。

正确做法：根据实际使用环境调整关键参数，特别是超时设置、重试机制和资源限制。建议为不同网络环境创建单独的配置文件。

误区2：忽视日志文件分析

当服务出现问题时，很多用户直接尝试各种解决方案而不先查看日志文件，导致无法准确诊断问题根源。

正确做法：养成先检查日志的习惯，重点关注ERROR和WARN级别信息。使用日志分析命令快速定位问题：

# 查找最近的错误日志
grep -i error ~/.claude-code-router/claude-code-router.log | tail -n 20

误区3：修改配置后未验证

修改配置后立即重启服务而不验证配置文件的有效性，可能导致服务无法启动或出现意外行为。

正确做法：修改配置后先使用验证工具检查，再进行服务重启：

# 验证配置有效性
ccr config validate

# 平滑重启服务
ccr restart

故障案例库

启动类案例

• 端口占用冲突：开发环境中与其他应用共享3456端口导致启动失败
• 权限不足：Linux系统下配置目录所有者与运行用户不匹配
• Node.js版本不兼容：使用不受支持的Node.js版本导致依赖加载失败

API通信案例

• 代理配置错误：代理服务器地址格式不正确导致连接失败
• API密钥权限不足：使用的API密钥没有访问特定模型的权限
• 请求频率超限：未配置请求限流导致API提供商临时封禁

配置解析案例

• JSON语法错误：配置文件中存在多余逗号或引号不匹配
• 环境变量引用错误：使用错误的环境变量引用格式
• 配置项类型错误：将数值类型配置项写成字符串形式

路由逻辑案例

• 路由规则冲突：多个路由规则同时匹配导致非预期路由
• 模型可用性检查失败：未正确配置模型状态检查导致路由到不可用模型
• 自定义路由函数异常：路由函数抛出未捕获异常导致路由失败

通过系统化的故障排查方法和预防性维护措施，大多数Claude Code Router的常见问题都可以快速解决。建立有效的故障处理流程，结合工具辅助诊断，可以显著提高系统的稳定性和可靠性。