🇨🇳 中文文档 | 🇬🇧 English |
说明：原版 claude-code-router 仓库已不再活跃维护。本项目是基于原仓库 fork 的社区活跃版本，持续进行 Bug 修复、功能开发和长期维护。
一款强大的工具，可将 Claude Code 和 Codex 请求路由到不同的模型，并自定义任何请求。
- 模型路由: 根据您的需求将请求路由到不同的模型（例如，后台任务、思考、长上下文）。
- 多提供商支持: 支持 OpenRouter、DeepSeek、Ollama、Gemini、Volcengine 和 SiliconFlow 等各种模型提供商。
- Codex CLI 支持: 通过 Responses API 协议转换，支持 Codex CLI 接入任意 LLM 提供商（Anthropic、DeepSeek、GLM 等），实现工具调用、文件修改等完整功能。
- 请求/响应转换: 使用转换器为不同的提供商自定义请求和响应。
- 动态模型切换: 在 Claude Code 中使用
/model命令动态切换模型。 - GitHub Actions 集成: 在您的 GitHub 工作流程中触发 Claude Code 任务。
- 用量统计与限额监控: 追踪请求的 Token 数、缓存命中率、首 Token 延迟 (TTFT) 和生成速度，并实时展示主流服务商（如智谱、Qwen 等）的限额使用情况。
- 插件系统: 使用自定义转换器扩展功能。
您可以从 npm 官方仓库安装 Claude Code Router，或者直接从本 GitHub 仓库安装以获取最新的开发版本。
首先，请确保您已安装 Claude Code：
npm install -g @anthropic-ai/claude-code然后，安装 Claude Code Router：
npm install -g @wengine-ai/claude-code-router-next如果您想直接使用源码中的最新功能和修复：
-
先卸载已安装的全局版本（以避免指令冲突）：
npm uninstall -g @wengine-ai/claude-code-router-next @musistudio/claude-code-router @wengine-ai/claude-code-router
-
克隆本仓库并在本地进行 Link（推荐开发者使用）：
git clone https://github.com/xiaoliu10/claude-code-router-next.git cd claude-code-router-next pnpm install pnpm build npm link或者直接从 GitHub 进行全局安装：
npm install -g github:xiaoliu10/claude-code-router-next
如果您当前正在使用官方原版社区版本 @musistudio/claude-code-router 或之前的版本 @wengine-ai/claude-code-router，希望切换到 @wengine-ai/claude-code-router-next：
-
先卸载旧版本：
npm uninstall -g @musistudio/claude-code-router @wengine-ai/claude-code-router
-
安装本仓库增强版本：
npm install -g @wengine-ai/claude-code-router-next
说明：卸载旧包不会影响您已有的配置文件
~/.claude-code-router/config.json，新版本会自动读取原有配置。
npm install -g @wengine-ai/claude-code-router-next@latest && ccr restart| 版本 | 发布内容 |
|---|---|
| v2.3.17 |
|
| v2.3.16 |
|
| v2.3.15 |
|
| v2.3.14 |
|
| v2.3.13 |
|
| v2.3.12 |
|
| v2.3.11 |
|
| v2.3.10 |
|
| v2.3.9 |
|
| v2.3.8 |
|
仅保留最近 10 个版本，更早版本的发布摘要见 CHANGELOG-archive.md，完整详细变更记录见 CHANGELOG.md。
创建并配置您的 ~/.claude-code-router/config.json 文件。有关更多详细信息，您可以参考 config.example.json。
Important
重要提示：手动修改 config.json 配置文件（如更新 API Key、百炼 Cookie 等）后，必须重启后台服务才能使新配置生效。请在保存文件后，在终端运行以下命令：
ccr restartconfig.json 文件有几个关键部分：
PROXY_URL(可选): 您可以为 API 请求设置代理，例如："PROXY_URL": "http://127.0.0.1:7890"。LOG(可选): 您可以通过将其设置为true来启用日志记录。当设置为false时，将不会创建日志文件。默认值为true。LOG_LEVEL(可选): 设置日志级别。可用选项包括："fatal"、"error"、"warn"、"info"、"debug"、"trace"。默认值为"debug"。- 日志系统: Claude Code Router 使用两个独立的日志系统：
- 服务器级别日志: HTTP 请求、API 调用和服务器事件使用 pino 记录在
~/.claude-code-router/logs/目录中，文件名类似于ccr-*.log - 应用程序级别日志: 路由决策和业务逻辑事件记录在
~/.claude-code-router/claude-code-router.log文件中
- 服务器级别日志: HTTP 请求、API 调用和服务器事件使用 pino 记录在
APIKEY(可选): 您可以设置一个密钥来进行身份验证。设置后，客户端请求必须在Authorization请求头 (例如,Bearer your-secret-key) 或x-api-key请求头中提供此密钥。例如："APIKEY": "your-secret-key"。HOST(可选): 您可以设置服务的主机地址。如果未设置APIKEY，出于安全考虑，主机地址将强制设置为127.0.0.1，以防止未经授权的访问。例如："HOST": "0.0.0.0"。NON_INTERACTIVE_MODE(可选): 当设置为true时，启用与非交互式环境（如 GitHub Actions、Docker 容器或其他 CI/CD 系统）的兼容性。这会设置适当的环境变量（CI=true、FORCE_COLOR=0等）并配置 stdin 处理，以防止进程在自动化环境中挂起。例如："NON_INTERACTIVE_MODE": true。Providers: 用于配置不同的模型提供商。Router: 用于设置路由规则。default指定默认模型，如果未配置其他路由，则该模型将用于所有请求。API_TIMEOUT_MS: API 请求超时时间，单位为毫秒。
这是一个综合示例：
{
"APIKEY": "your-secret-key",
"PROXY_URL": "http://127.0.0.1:7890",
"LOG": true,
"API_TIMEOUT_MS": 600000,
"NON_INTERACTIVE_MODE": false,
"Providers": [
{
"name": "openrouter",
"api_base_url": "https://openrouter.ai/api/v1/chat/completions",
"api_key": "sk-xxx",
"models": [
"google/gemini-2.5-pro-preview",
"anthropic/claude-sonnet-4",
"anthropic/claude-3.5-sonnet",
"anthropic/claude-3.7-sonnet:thinking"
],
"transformer": {
"use": ["openrouter"]
}
},
{
"name": "deepseek",
"api_base_url": "https://api.deepseek.com/chat/completions",
"api_key": "sk-xxx",
"models": ["deepseek-chat", "deepseek-reasoner"],
"transformer": {
"use": ["deepseek"],
"deepseek-chat": {
"use": ["tooluse"]
}
}
},
{
"name": "ollama",
"api_base_url": "http://localhost:11434/v1/chat/completions",
"api_key": "ollama",
"models": ["qwen2.5-coder:latest"]
},
{
"name": "gemini",
"api_base_url": "https://generativelanguage.googleapis.com/v1beta/models/",
"api_key": "sk-xxx",
"models": ["gemini-2.5-flash", "gemini-2.5-pro"],
"transformer": {
"use": ["gemini"]
}
},
{
"name": "volcengine",
"api_base_url": "https://ark.cn-beijing.volces.com/api/v3/chat/completions",
"api_key": "sk-xxx",
"models": ["deepseek-v3-250324", "deepseek-r1-250528"],
"transformer": {
"use": ["deepseek"]
}
},
{
"name": "modelscope",
"api_base_url": "https://api-inference.modelscope.cn/v1/chat/completions",
"api_key": "",
"models": ["Qwen/Qwen3-Coder-480B-A35B-Instruct", "Qwen/Qwen3-235B-A22B-Thinking-2507"],
"transformer": {
"use": [
[
"maxtoken",
{
"max_tokens": 65536
}
],
"enhancetool"
],
"Qwen/Qwen3-235B-A22B-Thinking-2507": {
"use": ["reasoning"]
}
}
},
{
"name": "dashscope",
"api_base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions",
"api_key": "",
"models": ["qwen3-coder-plus"],
"transformer": {
"use": [
[
"maxtoken",
{
"max_tokens": 65536
}
],
"enhancetool"
]
}
},
{
"name": "aihubmix",
"api_base_url": "https://aihubmix.com/v1/chat/completions",
"api_key": "sk-",
"models": [
"Z/glm-4.5",
"claude-opus-4-20250514",
"gemini-2.5-pro"
]
}
],
"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"
}
}如果您想让 Claude Code Router 的后台 Web UI 实时拉取并可视化展示您的 Qwen Coding Plan（Qwen 编程时限套餐） 剩余用量额度条，您需要获取控制台的浏览器 Cookie 作为 quotaToken 填入配置：
- 登录 阿里云百炼控制台。
- 按键盘
F12打开浏览器开发者工具，并切换到 Network (网络) 标签页。 - 点击页面用量模块右上角的 用量刷新（旋转循环箭头）按钮。
- 在左侧网络请求列表中，找到一个以
api.json?action=BroadScope...开头的接口调用请求并点击。 - 在右侧 Headers (标头) 的 Request Headers (请求头) 中找到
Cookie这一项，将其右侧的完整超长内容复制下来。 - 在您的
config.json中，将这个 cookie 填入阿里云 provider 下的quotaToken属性中即可！
配置成功后，Web UI 的 Provider 列表中将会实时展示您的套餐剩余用量额度条与刷新状态：
如果您想让 Claude Code Router 的后台 Web UI 实时拉取并可视化展示您的 讯飞 Coding Plan 剩余用量额度条，您需要进入讯飞 Coding Plan 订阅查询页面，打开浏览器开发者工具的 Network 面板，刷新页面后复制请求中的 Cookie 作为 quotaToken 填入配置：
- 登录讯飞 Coding Plan 订阅查询页面。
- 按键盘
F12打开浏览器开发者工具，并切换到 Network (网络) 标签页。 - 刷新页面。
- 在左侧网络请求列表中，找到订阅查询页面对应的用量查询请求并点击。
- 在右侧 Headers (标头) 的 Request Headers (请求头) 中找到
Cookie这一项，将其右侧的完整内容复制下来。 - 在您的
config.json中，将这个 cookie 填入讯飞 provider 下的quotaToken属性中，或者粘贴到 UI 的 限额查询 Token 输入框中即可。
注意: 这个 token 不是长期有效的，可能会过期；过期后需要重新手动添加。
使用 router 启动 Claude Code：
ccr code注意: 修改配置文件后，需要重启服务使配置生效：
ccr restart
为了获得更直观的体验，您可以使用 UI 模式来管理您的配置：
ccr ui这将打开一个基于 Web 的界面，您可以在其中轻松查看和编辑您的 config.json 文件。
仪表盘在主页面底部内置了用量统计面板。当您的请求通过 Claude Code Router 进行路由时，系统会自动收集用量记录并在 UI 界面中展示。
您可以使用它来查看：
- 总请求数
- 输入和输出 Token 数
- 平均首 Token 延迟 (TTFT)
- 平均生成速度 (Tokens/秒)
- 请求成功率
- 每日用量图表
- 支持筛选和分页的详细请求历史记录
如何使用：
- 使用
ccr start启动路由器服务 - 使用
ccr ui打开 Web 界面 - 通过 Claude Code Router 发送请求（例如使用
ccr code） - 返回主仪表盘，查看用量统计面板
用量数据保存在：
~/.claude-code-router/data/usage.jsonl对于偏好终端工作流的用户，可以使用交互式 CLI 模型选择器：
ccr model该命令提供交互式界面来：
- 查看当前配置
- 查看所有配置的模型（default、background、think、longContext、webSearch、image）
- 切换模型：快速更改每个路由器类型使用的模型
- 添加新模型：向现有提供商添加模型
- 创建新提供商：设置完整的提供商配置，包括：
- 提供商名称和 API 端点
- API 密钥
- 可用模型
- Transformer 配置，支持：
- 多个转换器（openrouter、deepseek、gemini 等）
- Transformer 选项（例如，带自定义限制的 maxtoken）
- 特定于提供商的路由（例如，OpenRouter 提供商偏好）
CLI 工具验证所有输入并提供有用的提示来引导您完成配置过程，使管理复杂的设置变得容易，无需手动编辑 JSON 文件。
预设允许您轻松保存、共享和重用配置。您可以将当前配置导出为预设，并从文件或 URL 安装预设。
# 将当前配置导出为预设
ccr preset export my-preset
# 使用元数据导出
ccr preset export my-preset --description "我的 OpenAI 配置" --author "您的名字" --tags "openai,生产环境"
# 从本地目录安装预设
ccr preset install /path/to/preset
# 列出所有已安装的预设
ccr preset list
# 显示预设信息
ccr preset info my-preset
# 删除预设
ccr preset delete my-preset预设功能：
- 导出：将当前配置保存为预设目录（包含 manifest.json）
- 安装：从本地目录安装预设
- 敏感数据处理：导出期间自动清理 API 密钥和其他敏感数据（标记为
{{field}}占位符） - 动态配置：预设可以包含输入架构，用于在安装期间收集所需信息
- 版本控制：每个预设包含版本元数据，用于跟踪更新
预设文件结构：
~/.claude-code-router/presets/
├── my-preset/
│ └── manifest.json # 包含配置和元数据
activate 命令允许您在 shell 中全局设置环境变量，使您能够直接使用 claude 命令或将 Claude Code Router 与使用 Agent SDK 构建的应用程序集成。
要激活环境变量，请运行：
eval "$(ccr activate)"此命令会以 shell 友好的格式输出必要的环境变量，这些变量将在当前的 shell 会话中设置。激活后，您可以：
- 直接使用
claude命令：无需使用ccr code即可运行claude命令。claude命令将自动通过 Claude Code Router 路由请求。 - 与 Agent SDK 应用程序集成：使用 Anthropic Agent SDK 构建的应用程序将自动使用配置的路由器和模型。
activate 命令设置以下环境变量：
ANTHROPIC_AUTH_TOKEN: 来自配置的 API 密钥ANTHROPIC_BASE_URL: 本地路由器端点（默认：http://127.0.0.1:3456）NO_PROXY: 设置为127.0.0.1以防止代理干扰DISABLE_TELEMETRY: 禁用遥测DISABLE_COST_WARNINGS: 禁用成本警告API_TIMEOUT_MS: 来自配置的 API 超时时间
注意：在使用激活的环境变量之前，请确保 Claude Code Router 服务正在运行（
ccr start）。环境变量仅在当前 shell 会话中有效。要使其持久化，您可以将eval "$(ccr activate)"添加到您的 shell 配置文件（例如~/.zshrc或~/.bashrc）中。
Providers 数组是您定义要使用的不同模型提供商的地方。每个提供商对象都需要：
name: 提供商的唯一名称。api_base_url: 聊天补全的完整 API 端点。api_key: 您提供商的 API 密钥。models: 此提供商可用的模型名称列表。transformer(可选): 指定用于处理请求和响应的转换器。
Transformers 允许您修改请求和响应负载，以确保与不同提供商 API 的兼容性。
-
全局 Transformer: 将转换器应用于提供商的所有模型。在此示例中，
openrouter转换器将应用于openrouter提供商下的所有模型。{ "name": "openrouter", "api_base_url": "https://openrouter.ai/api/v1/chat/completions", "api_key": "sk-xxx", "models": [ "google/gemini-2.5-pro-preview", "anthropic/claude-sonnet-4", "anthropic/claude-3.5-sonnet" ], "transformer": { "use": ["openrouter"] } } -
特定于模型的 Transformer: 将转换器应用于特定模型。在此示例中，
deepseek转换器应用于所有模型，而额外的tooluse转换器仅应用于deepseek-chat模型。{ "name": "deepseek", "api_base_url": "https://api.deepseek.com/chat/completions", "api_key": "sk-xxx", "models": ["deepseek-chat", "deepseek-reasoner"], "transformer": { "use": ["deepseek"], "deepseek-chat": { "use": ["tooluse"] } } } -
向 Transformer 传递选项: 某些转换器（如
maxtoken）接受选项。要传递选项，请使用嵌套数组，其中第一个元素是转换器名称，第二个元素是选项对象。{ "name": "siliconflow", "api_base_url": "https://api.siliconflow.cn/v1/chat/completions", "api_key": "sk-xxx", "models": ["moonshotai/Kimi-K2-Instruct"], "transformer": { "use": [ [ "maxtoken", { "max_tokens": 16384 } ] ] } }
可用的内置 Transformer：
Anthropic: 如果你只使用这一个转换器，则会直接透传请求和响应(你可以用它来接入其他支持Anthropic端点的服务商)。deepseek: 适配 DeepSeek API 的请求/响应。gemini: 适配 Gemini API 的请求/响应。openrouter: 适配 OpenRouter API 的请求/响应。它还可以接受一个provider路由参数，以指定 OpenRouter 应使用哪些底层提供商。有关更多详细信息，请参阅 OpenRouter 文档。请参阅下面的示例："transformer": { "use": ["openrouter"], "moonshotai/kimi-k2": { "use": [ [ "openrouter", { "provider": { "only": ["moonshotai/fp8"] } } ] ] } }
groq: 适配 groq API 的请求/响应maxtoken: 设置特定的max_tokens值。tooluse: 优化某些模型的工具使用(通过tool_choice参数)。gemini-cli(实验性): 通过 Gemini CLI gemini-cli.js 对 Gemini 的非官方支持。reasoning: 用于处理reasoning_content字段。sampling: 用于处理采样信息字段，如temperature、top_p、top_k和repetition_penalty。enhancetool: 对 LLM 返回的工具调用参数增加一层容错处理（这会导致不再流式返回工具调用信息）。cleancache: 清除请求中的cache_control字段。vertex-gemini: 处理使用 vertex 鉴权的 gemini api。qwen-cli(实验性): 通过 Qwen CLI qwen-cli.js 对 qwen3-coder-plus 的非官方支持。rovo-cli(experimental): 通过 Atlassian Rovo Dev CLI rovo-cli.js 对 GPT-5 的非官方支持。
自定义 Transformer:
您还可以创建自己的转换器，并通过 config.json 中的 transformers 字段加载它们。
{
"transformers": [
{
"path": "/User/xxx/.claude-code-router/plugins/gemini-cli.js",
"options": {
"project": "xxx"
}
}
]
}Router 对象定义了在不同场景下使用哪个模型：
default: 用于常规任务的默认模型。background: 用于后台任务的模型。这可以是一个较小的本地模型以节省成本。think: 用于推理密集型任务（如计划模式）的模型。longContext: 用于处理长上下文（例如，> 60K 令牌）的模型。longContextThreshold(可选): 触发长上下文模型的令牌数阈值。如果未指定，默认为 60000。webSearch: 用于处理网络搜索任务，需要模型本身支持。如果使用openrouter需要在模型后面加上:online后缀。image(测试版): 用于处理图片类任务（采用CCR内置的agent支持），如果该模型不支持工具调用，需要将config.forceUseImageAgent属性设置为true。
您还可以使用 /model 命令在 Claude Code 中动态切换模型：
/model provider_name,model_name
示例: /model openrouter,anthropic/claude-3.5-sonnet
对于更高级的路由逻辑，您可以在 config.json 中通过 CUSTOM_ROUTER_PATH 字段指定一个自定义路由器脚本。这允许您实现超出默认场景的复杂路由规则。
在您的 config.json 中配置:
{
"CUSTOM_ROUTER_PATH": "/User/xxx/.claude-code-router/custom-router.js"
}自定义路由器文件必须是一个导出 async 函数的 JavaScript 模块。该函数接收请求对象和配置对象作为参数，并应返回提供商和模型名称的字符串（例如 "provider_name,model_name"），如果返回 null 则回退到默认路由。
这是一个基于 custom-router.example.js 的 custom-router.js 示例：
// /User/xxx/.claude-code-router/custom-router.js
/**
* 一个自定义路由函数，用于根据请求确定使用哪个模型。
*
* @param {object} req - 来自 Claude Code 的请求对象，包含请求体。
* @param {object} config - 应用程序的配置对象。
* @returns {Promise<string|null>} - 一个解析为 "provider,model_name" 字符串的 Promise，如果返回 null，则使用默认路由。
*/
module.exports = async function router(req, config) {
const userMessage = req.body.messages.find(m => m.role === 'user')?.content;
if (userMessage && userMessage.includes('解释这段代码')) {
// 为代码解释任务使用更强大的模型
return 'openrouter,anthropic/claude-3.5-sonnet';
}
// 回退到默认的路由配置
return null;
};对于子代理内的路由，您必须在子代理提示词的开头包含 <CCR-SUBAGENT-MODEL>provider,model</CCR-SUBAGENT-MODEL> 来指定特定的提供商和模型。这样可以将特定的子代理任务定向到指定的模型。
示例：
<CCR-SUBAGENT-MODEL>openrouter,anthropic/claude-3.5-sonnet</CCR-SUBAGENT-MODEL>
请帮我分析这段代码是否存在潜在的优化空间...
为了在运行时更好的查看claude-code-router的状态，claude-code-router在v1.0.40内置了一个statusline工具，你可以在UI中启用它，
效果如下（包含全新的彩色渐变 Context 上下文占用进度条）：
将 Claude Code Router 集成到您的 CI/CD 管道中。在设置 Claude Code Actions 后，修改您的 .github/workflows/claude.yaml 以使用路由器：
name: Claude Code
on:
issue_comment:
types: [created]
# ... other triggers
jobs:
claude:
if: |
(github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
# ... other conditions
runs-on: ubuntu-latest
permissions:
contents: read
pull-requests: read
issues: read
id-token: write
steps:
- name: Checkout repository
uses: actions/checkout@v4
with:
fetch-depth: 1
- name: Prepare Environment
run: |
curl -fsSL https://bun.sh/install | bash
mkdir -p $HOME/.claude-code-router
cat << 'EOF' > $HOME/.claude-code-router/config.json
{
"log": true,
"NON_INTERACTIVE_MODE": true,
"OPENAI_API_KEY": "${{ secrets.OPENAI_API_KEY }}",
"OPENAI_BASE_URL": "https://api.deepseek.com",
"OPENAI_MODEL": "deepseek-chat"
}
EOF
shell: bash
- name: Start Claude Code Router
run: |
nohup ~/.bun/bin/bunx @wengine-ai/claude-code-router-next@latest start &
shell: bash
- name: Run Claude Code
id: claude
uses: anthropics/claude-code-action@beta
env:
ANTHROPIC_BASE_URL: http://localhost:3456
with:
anthropic_api_key: "any-string-is-ok"这种设置可以实现有趣的自动化，例如在非高峰时段运行任务以降低 API 成本。
Claude Code Router 支持模型族映射，将 Claude Code 的模型分级（opus/sonnet/haiku）映射到不同服务商的模型。这实现了智能成本控制：主进程保持相同模型以最大化缓存命中，子代理可自动降级。
{
"Router": {
"enableFamilyRouting": true,
"families": {
"opus": {
"default": "智谱 Coding Plan,glm-5",
"think": "DeepSeek,deepseek-reasoner",
"longContext": "阿里云,qwen3-plus",
"webSearch": "Gemini,gemini-2.5-flash",
"fallback": {
"default": ["阿里云,glm-4", "DeepSeek,deepseek-chat"],
"think": ["阿里云,qwen-plus", "DeepSeek,deepseek-reasoner"]
}
},
"sonnet": {
"default": "OpenRouter,deepseek/deepseek-v3",
"think": "DeepSeek,deepseek-reasoner",
"fallback": {
"default": ["阿里云,qwen-turbo", "Gemini,gemini-2.0-flash"]
}
},
"haiku": {
"default": "阿里云,qwen-turbo",
"fallback": {
"default": ["Gemini,gemini-2.0-flash-lite"]
}
}
}
}
}| 场景 | 触发条件 | 说明 |
|---|---|---|
default |
默认 | 日常对话和代码生成 |
think |
Plan Mode | 复杂推理、架构设计 |
longContext |
token > 60000 | 大文件分析 |
webSearch |
web_search tool | 网络搜索任务 |
background |
后台任务 | 自动提交、简单检查 |
当主模型失败时，Router 会自动尝试 fallback 链中的备用模型，确保请求不中断。
-
健康检查：每个 provider/model 维护健康状态
closed（健康）→ 绿色指示器open（失败池）→ 红色指示器，自动跳过half-open（恢复中）→ 黄色指示器
-
供应商主开关 (Master Toggle)：在管理面板中，每个供应商都拥有独立的开启/关闭开关：
- 最高优先级：当供应商关闭时，旗下所有模型将强制失效且不可选中，健康指示器置灰。
- 智能 Fallback：若主模型路由被关闭，系统立刻发起重试并直接进入 fallback 链；若 fallback 列表中的某备用模型所对应的供应商处于关闭状态，则系统自动跳过该模型。
- 防冗余探测：关闭的供应商会完全免除主动探测和健康恢复检查，避免无谓的网络调用和资源占用，直至开关重新开启。
- 智能预警提示：如果当前设置的某项主模型路由（如
default等）所属的供应商已被关闭，控制台界面会实时显示醒目的警示红字，提醒及时更换模型配置。
-
失败判定：连续 3 次失败后进入
open状态 -
拖动排序：UI 支持拖动 fallback 模型调整优先级，排序越靠前越先尝试
-
Fallback Promotion：当主模型失败且 fallback 成功时，临时"晋升" fallback 模型（TTL 10 分钟），后续请求直接使用晋升模型，避免重复尝试失败的主模型
-
自动恢复：每 5 分钟探测失败模型，成功后恢复为
half-open，再成功 2 次后恢复为closed
family fallback → global fallback
优先使用模型族专属的 fallback 配置，其次使用全局 fallback。
{
"Router": {
"enableFallback": true,
"families": {
"opus": {
"fallback": {
"default": ["阿里云,glm-4", "DeepSeek,deepseek-chat"]
}
}
}
},
"fallback": {
"default": ["OpenRouter,deepseek/deepseek-v3", "Gemini,gemini-2.5-flash"],
"think": ["DeepSeek,deepseek-reasoner"]
}
}Router 提供完善的用量统计功能：
UI 界面实时显示各服务商的额度使用情况：
- 5h 额度：短窗口限额（5 小时重置）
- 7d 额度：周度限额（7 天重置）
- 重置时间：显示下次额度重置时间
支持的服务商：
- 智谱 GLM Coding Plan
- 阿里云 Qwen Coding Plan
- Kimi Coding Plan
- MiniMax Coding Plan
- DeepSeek
- OpenRouter
- SiliconFlow
每次请求都会记录详细统计信息：
| 字段 | 说明 |
|---|---|
inputTokens |
输入 token 数 |
outputTokens |
输出 token 数 |
cacheReadInputTokens |
缓存读取 token |
cacheCreationInputTokens |
缓存创建 token |
ttft |
首 token 时间 (ms) |
tokensPerSecond |
输出速度 |
durationMs |
请求耗时 |
status |
success / error |
数据存储位置：~/.claude-code-router/data/usage.jsonl
