claude-code-router/docs/i18n/zh-CN/docusaurus-plugin-content-docs/current/server/config/routing.md

title, sidebar_position

title	sidebar_position
路由配置	3

路由配置

配置如何将请求路由到不同的模型。

默认路由

为所有请求设置默认模型：

{
  "Router": {
    "default": "deepseek,deepseek-chat"
  }
}

内置场景

后台任务

将后台任务路由到轻量级模型：

{
  "Router": {
    "background": "groq,llama-3.3-70b-versatile"
  }
}

思考模式（计划模式）

将思考密集型任务路由到更强大的模型：

{
  "Router": {
    "think": "deepseek,deepseek-reasoner"
  }
}

长上下文

路由长上下文请求：

{
  "Router": {
    "longContextThreshold": 100000,
    "longContext": "gemini,gemini-2.5-pro"
  }
}

网络搜索

路由网络搜索任务：

{
  "Router": {
    "webSearch": "gemini,gemini-2.5-flash"
  }
}

图像任务

路由图像相关任务：

{
  "Router": {
    "image": "gemini,gemini-2.5-pro"
  }
}

故障转移（Fallback）

当请求失败时，可以配置备用模型列表。系统会按顺序尝试每个模型，直到请求成功：

基本配置

{
  "Router": {
    "default": "deepseek,deepseek-chat",
    "background": "ollama,qwen2.5-coder:latest",
    "think": "deepseek,deepseek-reasoner",
    "longContext": "openrouter,google/gemini-2.5-pro-preview",
    "longContextThreshold": 60000,
    "webSearch": "gemini,gemini-2.5-flash"
  },
  "fallback": {
    "default": [
      "aihubmix,Z/glm-4.5",
      "openrouter,anthropic/claude-sonnet-4"
    ],
    "background": [
      "ollama,qwen2.5-coder:latest"
    ],
    "think": [
      "openrouter,anthropic/claude-3.7-sonnet:thinking"
    ],
    "longContext": [
      "modelscope,Qwen/Qwen3-Coder-480B-A35B-Instruct"
    ],
    "webSearch": [
      "openrouter,anthropic/claude-sonnet-4"
    ]
  }
}

工作原理

1. 触发条件：当某个路由场景的模型请求失败时（HTTP 错误响应）
2. 自动切换：系统自动检查该场景的 fallback 配置
3. 顺序尝试：按照列表顺序依次尝试每个备用模型
4. 成功返回：一旦某个模型成功响应，立即返回结果
5. 全部失败：如果所有备用模型都失败，返回原始错误

配置说明

• 格式：每个备用模型格式为 provider,model
• 验证：备用模型必须在 Providers 配置中存在
• 灵活性：可以为不同场景配置不同的备用列表
• 可选性：如果某个场景不需要备用，可以不配置或使用空数组

使用场景

场景一：主模型配额不足

{
  "Router": {
    "default": "openrouter,anthropic/claude-sonnet-4"
  },
  "fallback": {
    "default": [
      "deepseek,deepseek-chat",
      "aihubmix,Z/glm-4.5"
    ]
  }
}

当主模型配额用完时，自动切换到备用模型。

场景二：服务稳定性保障

{
  "Router": {
    "background": "volcengine,deepseek-v3-250324"
  },
  "fallback": {
    "background": [
      "modelscope,Qwen/Qwen3-Coder-480B-A35B-Instruct",
      "dashscope,qwen3-coder-plus"
    ]
  }
}

当主服务商出现故障时，自动切换到其他服务商。

日志监控

系统会记录详细的 fallback 过程：

[warn] Request failed for default, trying 2 fallback models
[info] Trying fallback model: aihubmix,Z/glm-4.5
[warn] Fallback model aihubmix,Z/glm-4.5 failed: API rate limit exceeded
[info] Trying fallback model: openrouter,anthropic/claude-sonnet-4
[info] Fallback model openrouter,anthropic/claude-sonnet-4 succeeded

注意事项

1. 成本考虑：备用模型可能产生不同的费用，请合理配置
2. 性能差异：不同模型的响应速度和质量可能有差异
3. 配额管理：确保备用模型有足够的配额
4. 测试验证：定期测试备用模型的可用性

项目级路由

在 ~/.claude/projects/<project-id>/claude-code-router.json 中为每个项目配置路由：

{
  "Router": {
    "default": "groq,llama-3.3-70b-versatile"
  }
}

项目级配置优先于全局配置。

自定义路由器

创建自定义 JavaScript 路由器函数：

1. 创建路由器文件（例如 custom-router.js）：

module.exports = async function(req, config) {
  // 分析请求上下文
  const userMessage = req.body.messages.find(m => m.role === 'user')?.content;

  // 自定义路由逻辑
  if (userMessage && userMessage.includes('解释代码')) {
    return 'openrouter,anthropic/claude-3.5-sonnet';
  }

  // 返回 null 以使用默认路由
  return null;
};

2. 在 config.json 中设置 CUSTOM_ROUTER_PATH：

{
  "CUSTOM_ROUTER_PATH": "/path/to/custom-router.js"
}

Token 计数

路由器使用 tiktoken (cl100k_base) 来估算请求 token 数量。这用于：

• 确定请求是否超过 longContextThreshold
• 基于 token 数量的自定义路由逻辑

子代理路由

使用特殊标签为子代理指定模型：

<CCR-SUBAGENT-MODEL>provider,model</CCR-SUBAGENT-MODEL>
请帮我分析这段代码...

动态模型切换

在 Claude Code 中使用 /model 命令动态切换模型：

/model provider_name,model_name

示例：/model openrouter,anthropic/claude-3.5-sonnet

路由优先级

1. 项目级配置
2. 自定义路由器
3. 内置场景路由
4. 默认路由

下一步

• 转换器 - 对请求应用转换
• 自定义路由器 - 高级自定义路由