🇨🇳 中文文档 | 🇬🇧 English |

说明：原版 claude-code-router 仓库已不再活跃维护。本项目是基于原仓库 fork 的社区活跃版本，持续进行 Bug 修复、功能开发和长期维护。

从CLI工具风格看工具渐进式披露

一款强大的工具，可将 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 等）的限额使用情况。
插件系统: 使用自定义转换器扩展功能。

🚀 快速入门

1. 安装

您可以从 npm 官方仓库安装 Claude Code Router，或者直接从本 GitHub 仓库安装以获取最新的开发版本。

选项 A：从 npm 官方仓库安装（稳定版）

首先，请确保您已安装 Claude Code：

npm install -g @anthropic-ai/claude-code

然后，安装 Claude Code Router：

npm install -g @wengine-ai/claude-code-router-next

选项 B：从 GitHub 安装（最新开发版）

如果您想直接使用源码中的最新功能和修复：

先卸载已安装的全局版本（以避免指令冲突）：

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)

如果您当前正在使用官方原版社区版本 @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

📅 升级功能列表 (Changelog)

版本	发布内容
v2.1.36	Codex 最新 RT 导出：Codex 账号管理支持导出当前或指定托管账号的最新 refresh token，CLI 新增 `ccr clients codex export-rt [account-id]`，Web UI 新增复制最新 RT 按钮，并会在当前 auth 文件更新时同步托管快照。
v2.1.35	定时唤醒稳定性修复：提供商定时唤醒在 macOS 睡眠/唤醒或系统时间跳变后会重新计算下一次触发时间，避免错过或重复执行唤醒任务。
v2.1.34	本地客户端配置接管：新增 Client Configuration 管理能力，可通过 UI/API/CLI 启用、禁用或恢复本地 Claude Code、Codex 等客户端配置，并自动写入 CCR 代理地址与模型别名。 Codex 本地账号代管理：新增 Codex 账号管理页与 `ccr clients codex` 命令，支持导入当前登录账号、通过 refresh token 导入、切换激活账号、删除托管账号，并对官方 auth 文件做备份与替换。 Codex 账号列表缓存优化：Codex 账号页优先读取本地固化账号与限额缓存，页面刷新无需等待官方 usage 接口；当前账号后台 1 分钟刷新一次，非当前账号 30 分钟刷新一次。 Codex / OpenAI Responses API 兼容：新增 `openai-responses` Transformer，支持 Codex 使用 Responses API wire format 接入 CCR，并完成 Chat/Anthropic 与 Responses 的流式、非流式转换。状态栏视觉升级：状态栏新增彩色渐变 Context 上下文占用进度条，提升长上下文使用情况的可读性。
v2.1.32	供应商刷新按钮位置优化：单个供应商刷新按钮移动到卡片顶部状态行，位于启用开关左侧；hover 操作区仅保留编辑和删除。
v2.1.31	供应商操作区优化：供应商卡片右侧刷新、编辑、删除按钮改为紧凑横向排列，避免纵向拉伸导致卡片视觉松散。
v2.1.30	Codex 多账号限额展示：Codex 账号管理页新增官方限额信息展示，通过 `chatgpt.com/backend-api/wham/usage` 获取 5 小时速率限制与 7 天周限制的使用百分比和重置时间。 Codex 账号自动切换：Codex 请求前会检查当前账号官方限额，默认任一窗口达到 95% 自动切换到下一个可用账号；仍保留 429/限流错误后的自动切换兜底。
v2.1.27	DeepSeek / GLM 工具调用兼容修复：修复部分 DeepSeek 与 GLM 兼容接口因 `tool_choice` 参数格式不一致导致的请求失败问题。
v2.1.26	修复 Anthropic Transformer URI 覆盖问题：当 `Anthropic` 与 DeepSeek/OpenAI 兼容提供商组合使用时，不再把 `chat/completions` 端点错误改写为 `/v1/messages`，避免 DeepSeek 返回 404。协议转换边界收紧：仅当 provider 的 `api_base_url` 明确指向 `/messages` 端点时，才将请求体转换为 Anthropic messages 结构。
v2.1.25	修复新版 Claude Code (v2.1.154+) 422 报错：完美解决请求 `/v1/messages` 兼容提供商时因 messages 数组中包含 `role: "system"` 造成的 400/422 报错。动态 Passthrough 绕过自愈：强制拦截带有 system 消息的 Anthropic 兼容提供商透传，自动进行双向协议规范化与 system 字段合并。响应无损透传修复：支持目标为 Anthropic 协议响应的原样直出，解决了第三方接口转发时“请求成功但无数据返回”的重大漏洞。
v2.1.22	提供商定时唤醒功能 (定时唤醒)：新增通用及提供商级别的清晨定时自动重置/唤醒机制，通过发送 dummy 消息提前激活额度。对称用量展示面板：将 Web 控制台的用量统计网格从 8 张卡片升级为更美观对称的 10 卡片布局。高级用量指标统计：新增对缓存命中率 (Cache Hit Rate) 及生成速度 (Average Speed) 的多维度计算与动态展示。
v2.1.7	Gemini 思考模式签名支持：完美支持 Gemini 思考模式 (thinking mode) 及思维链签名 (thought_signature)，防止转发时出现 400 校验异常并拦截 API Key 泄露。系统级调试日志面板：引入运行时一键切换的系统调试日志，与 Web 控制台深度集成，提供实时请求响应细节。
v2.1.2	状态栏 Token 缓存计数：支持 CLI 状态栏 (statusline) 中的 Token 计数正确显示缓存命中详情，并在响应速度及文字格式上完成多项优化。
v2.0.87	Web 控制台额度支持：正式打通并适配智谱 GLM 与百炼 Qwen 等主流渠道的额度使用详情实时分析。健康失败记录优化：修复 HTTP 429 速率限制请求在健康监测系统中未被记录为失败并导致熔断延迟的 Bug。

2. 配置

创建并配置您的 ~/.claude-code-router/config.json 文件。有关更多详细信息，您可以参考 config.example.json。

[!IMPORTANT]
重要提示：手动修改 config.json 配置文件（如更新 API Key、百炼 Cookie 等）后，必须重启后台服务才能使新配置生效。请在保存文件后，在终端运行以下命令：
ccr restart

config.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 文件中
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"
  }
}

🔑 阿里云百炼用量 Token (Cookie) 获取引导

如果您想让 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 列表中将会实时展示您的套餐剩余用量额度条与刷新状态：

阿里云用量 Cookie 获取方式

阿里云用量额度条展示

🔑 讯飞 Coding Plan 用量 Token (Cookie) 获取引导

如果您想让 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 不是长期有效的，可能会过期；过期后需要重新手动添加。

3. 使用 Router 运行 Claude Code

使用 router 启动 Claude Code：

ccr code

注意: 修改配置文件后，需要重启服务使配置生效：
ccr restart

4. UI 模式

为了获得更直观的体验，您可以使用 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

5. CLI 模型管理

对于偏好终端工作流的用户，可以使用交互式 CLI 模型选择器：

ccr model

该命令提供交互式界面来：

查看当前配置
查看所有配置的模型（default、background、think、longContext、webSearch、image）
切换模型：快速更改每个路由器类型使用的模型
添加新模型：向现有提供商添加模型
创建新提供商：设置完整的提供商配置，包括：
- 提供商名称和 API 端点
- API 密钥
- 可用模型
- Transformer 配置，支持：
  - 多个转换器（openrouter、deepseek、gemini 等）
  - Transformer 选项（例如，带自定义限制的 maxtoken）
  - 特定于提供商的路由（例如，OpenRouter 提供商偏好）

CLI 工具验证所有输入并提供有用的提示来引导您完成配置过程，使管理复杂的设置变得容易，无需手动编辑 JSON 文件。

6. 预设管理

预设允许您轻松保存、共享和重用配置。您可以将当前配置导出为预设，并从文件或 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    # 包含配置和元数据

7. Activate 命令（环境变量设置）

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

Providers 数组是您定义要使用的不同模型提供商的地方。每个提供商对象都需要：

name: 提供商的唯一名称。
api_base_url: 聊天补全的完整 API 端点。
api_key: 您提供商的 API 密钥。
models: 此提供商可用的模型名称列表。
transformer (可选): 指定用于处理请求和响应的转换器。

Transformers

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

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>
请帮我分析这段代码是否存在潜在的优化空间...

Status Line (Beta)

为了在运行时更好的查看claude-code-router的状态，claude-code-router在v1.0.40内置了一个statusline工具，你可以在UI中启用它，

效果如下（包含全新的彩色渐变 Context 上下文占用进度条）：
statusline

🤖 GitHub Actions

将 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 成本。

🎯 高级功能

模型族映射 (Family Routing)

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`	后台任务	自动提交、简单检查

Fallback 机制

当主模型失败时，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

Provider 健康状态

Fallback 配置层级

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 提供完善的用量统计功能：

Quota 监控

UI 界面实时显示各服务商的额度使用情况：

5h 额度：短窗口限额（5 小时重置）
7d 额度：周度限额（7 天重置）
重置时间：显示下次额度重置时间

Quota 用量条

支持的服务商：

智谱 GLM Coding Plan
阿里云 Qwen Coding Plan
Kimi Coding Plan
MiniMax Coding Plan
DeepSeek
OpenRouter
SiliconFlow

Usage 记录

每次请求都会记录详细统计信息：

字段	说明
`inputTokens`	输入 token 数
`outputTokens`	输出 token 数
`cacheReadInputTokens`	缓存读取 token
`cacheCreationInputTokens`	缓存创建 token
`ttft`	首 token 时间 (ms)
`tokensPerSecond`	输出速度
`durationMs`	请求耗时
`status`	success / error

数据存储位置：~/.claude-code-router/data/usage.jsonl

交流群

✨ 功能

🚀 快速入门

1. 安装

选项 A：从 npm 官方仓库安装（稳定版）

选项 B：从 GitHub 安装（最新开发版）

🔄 从官方原版社区版迁移 (@musistudio/claude-code-router)

升级

📅 升级功能列表 (Changelog)

2. 配置

🔑 阿里云百炼用量 Token (Cookie) 获取引导

🔑 讯飞 Coding Plan 用量 Token (Cookie) 获取引导

3. 使用 Router 运行 Claude Code

4. UI 模式

用量统计

5. CLI 模型管理

6. 预设管理

7. Activate 命令（环境变量设置）

Providers

Transformers

Router

自定义路由器

子代理路由

Status Line (Beta)

🤖 GitHub Actions

🎯 高级功能

模型族映射 (Family Routing)

配置示例

场景说明

Fallback 机制

工作流程

Fallback 配置层级

用量统计

Quota 监控

Usage 记录

交流群

Yorumlar (0)