musistudio/claude-code-router

 [](README_zh.md) [](https://discord.gg/rdftVMaUcS) [](https://github.com/musistudio/claude-code-router/blob/main/LICENSE)

---

 ## ✨ 功能 - **模型路由**：根据您的需求（例如：后台任务、思考、长上下文）将请求路由到不同的模型。 - **多 Provider 支持**：支持多种模型 Provider，如 OpenRouter、DeepSeek、Ollama、Gemini、Volcengine 和 SiliconFlow。 - **请求/响应转换**：使用 transformer 为不同的 Provider 自定义请求和响应。 - **动态模型切换**：在 Claude Code 中使用 `/model` 命令即时切换模型。 - **CLI 模型管理**：通过终端使用 `ccr model` 直接管理模型和 Provider。 - **GitHub Actions 集成**：在您的 GitHub workflows 中触发 Claude Code 任务。 - **插件系统**：使用自定义 transformer 扩展功能。 ## 🚀 快速开始 ### 1. 安装 首先，请确保您已安装 [Claude Code](https://docs.anthropic.com/en/docs/claude-code/quickstart)： ``` npm install -g @anthropic-ai/claude-code ``` 然后，安装 Claude Code Router： ``` npm install -g @musistudio/claude-code-router ``` ### 2. 配置 创建并配置您的 `~/.claude-code-router/config.json` 文件。有关更多详细信息，您可以参考 `config.example.json`。 `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` header（例如 `Bearer your-secret-key`）或 `x-api-key` header 中提供此密钥。示例：`"APIKEY": "your-secret-key"`。 - **`HOST`**（可选）：您可以设置服务器的主机地址。如果未设置 `APIKEY`，出于安全原因以防止未经授权的访问，主机将被强制设置为 `127.0.0.1`。示例：`"HOST": "0.0.0.0"`。 - **`NON_INTERACTIVE_MODE`**（可选）：设置为 `true` 时，启用与 GitHub Actions、Docker container 或其他 CI/CD 系统等非交互式环境的兼容性。这会设置适当的环境变量（`CI=true`、`FORCE_COLOR=0` 等）并配置 stdin 处理，以防止进程在自动化环境中挂起。示例：`"NON_INTERACTIVE_MODE": true`。 - **`Providers`**：用于配置不同的模型 Provider。 - **`Router`**：用于设置路由规则。`default` 指定默认模型，如果没有配置其他路由，该模型将用于所有请求。 - **`API_TIMEOUT_MS`**：以毫秒为单位指定 API 调用的超时时间。 #### 环境变量插值 Claude Code Router 支持环境变量插值，以便安全管理 API key。您可以在 `config.json` 中使用 `$VAR_NAME` 或 `${VAR_NAME}` 语法来引用环境变量： ``` { "OPENAI_API_KEY": "$OPENAI_API_KEY", "GEMINI_API_KEY": "${GEMINI_API_KEY}", "Providers": [ { "name": "openai", "api_base_url": "https://api.openai.com/v1/chat/completions", "api_key": "$OPENAI_API_KEY", "models": ["gpt-5", "gpt-5-mini"] } ] } ``` 这允许您将敏感的 API key 保留在环境变量中，而不是将其硬编码在配置文件中。插值机制将递归地应用于嵌套对象和数组。 这是一个完整的示例： ``` { "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" } } ``` ### 3. 通过 Router 运行 Claude Code 使用 router 启动 Claude Code： ``` ccr code ``` ### 4. UI 模式 为了获得更直观的体验，您可以使用 UI 模式来管理您的配置： ``` ccr ui ``` 这将打开一个基于 Web 的界面，您可以在其中轻松查看和编辑您的 `config.json` 文件。  ### 5. CLI 模型管理 对于喜欢基于终端工作流的用户，您可以使用交互式 CLI 模型选择器： ``` ccr model ```  此命令提供了一个交互式界面来： - 查看当前配置： - 查看所有已配置的模型（default、background、think、longContext、webSearch、image） - 切换模型：快速更改每种 router 类型使用的模型 - 添加新模型：向现有的 Provider 添加模型 - 创建新 Provider：设置完整的 Provider 配置，包括： - Provider 名称和 API endpoint - API key - 可用模型 - Transformer 配置，支持： - 多个 transformer（openrouter、deepseek、gemini 等） - Transformer 选项（例如：带有自定义限制的 maxtoken） - 特定于 Provider 的路由（例如：OpenRouter provider 偏好设置） CLI 工具会验证所有输入并提供有用的提示，指导您完成配置过程，从而无需手动编辑 JSON 文件即可轻松管理复杂的设置。 ### 6. 预设管理 预设允许您轻松地保存、分享和重用配置。您可以将当前配置导出为预设，也可以从文件或 URL 安装预设。 ``` # 将当前配置导出为 preset ccr preset export my-preset # 导出并包含 metadata ccr preset export my-preset --description "My OpenAI config" --author "Your Name" --tags "openai,production" # 从本地目录安装 preset ccr preset install /path/to/preset # 列出所有已安装的 preset ccr preset list # 显示 preset 信息 ccr preset info my-preset # 删除 preset ccr preset delete my-preset ``` **预设功能：** - **导出**：将您当前的配置保存为预设目录（包含 manifest.json） - **安装**：从本地目录安装预设 - **敏感数据处理**：API key 和其他敏感数据在导出期间会自动进行脱敏处理（标记为 `{{field}}` 占位符） - **动态配置**：预设可以包含输入 schema，用于在安装过程中收集所需的信息 - **版本控制**：每个预设都包含用于跟踪更新的版本元数据 **预设文件结构：** ``` ~/.claude-code-router/presets/ ├── my-preset/ │ └── manifest.json # Contains configuration and metadata ``` ### 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 构建的应用程序将自动使用配置好的 router 和模型。 `activate` 命令会设置以下环境变量： - `ANTHROPIC_AUTH_TOKEN`：您配置中的 API key - `ANTHROPIC_BASE_URL`：本地 router endpoint（默认：`http://127.0.0.1:3456`） - `NO_PROXY`：设置为 `127.0.0.1` 以防止代理干扰 - `DISABLE_TELEMETRY`：禁用遥测 - `DISABLE_COST_WARNINGS`：禁用成本警告 - `API_TIMEOUT_MS`：您配置中的 API 超时时间 #### Providers `Providers` 数组用于定义您要使用的不同模型 Provider。每个 provider 对象需要： - `name`：Provider 的唯一名称。 - `api_base_url`：用于对话补全的完整 API endpoint。 - `api_key`：该 Provider 的 API key。 - `models`：该 Provider 可用的模型名称列表。 - `transformer`（可选）：指定用于处理请求和响应的 transformer。 #### Transformers Transformer 允许您修改请求和响应 payload，以确保与不同 Provider API 的兼容性。 - **全局 Transformer**：将 transformer 应用于某个 Provider 的所有模型。在此示例中，`openrouter` transformer 被应用于 `openrouter` provider 下的所有模型。 { "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**：将 transformer 应用于特定模型。在此示例中，`deepseek` transformer 被应用于所有模型，而额外的 `tooluse` transformer 仅应用于 `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 传递选项**：某些 transformer（如 `maxtoken`）接受选项。要传递选项，请使用嵌套数组，其中第一个元素是 transformer 名称，第二个是选项对象。 { "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` transformer，它将保留原始的请求和响应参数（您可以使用它直接连接到 Anthropic endpoint）。 - `deepseek`：适配 DeepSeek API 的请求/响应。 - `gemini`：适配 Gemini API 的请求/响应。 - `openrouter`：适配 OpenRouter API 的请求/响应。它还可以接受 `provider` 路由参数，以指定 OpenRouter 应使用哪些底层 Provider。有关更多详细信息，请参阅 [OpenRouter 文档](https://openrouter.ai/docs/features/provider-routing)。请参阅以下示例： "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 的非官方支持 [gemini-cli.js](https://gist.github.com/musistudio/1c13a65f35916a7ab690649d3df8d1cd)。 - `reasoning`：用于处理 `reasoning_content` 字段。 - `sampling`：用于处理采样信息字段，例如 `temperature`、`top_p`、`top_k` 和 `repetition_penalty`。 - `enhancetool`：为 LLM 返回的工具调用参数增加一层容错处理（这将导致工具调用信息不再以流式传输）。 - `cleancache`：清除请求中的 `cache_control` 字段。 - `vertex-gemini`：使用 Vertex 认证处理 Gemini API。 - `chutes-glm` 通过 Chutes 提供对 GLM 4.5 模型的非官方支持 [chutes-glm-transformer.js](https://gist.github.com/vitobotta/2be3f33722e05e8d4f9d2b0138b8c863)。 - `qwen-cli`（实验性）：通过 Qwen CLI 提供对 qwen3-coder-plus 模型的非官方支持 [qwen-cli.js](https://gist.github.com/musistudio/f5a67841ced39912fd99e42200d5ca8b)。 - `rovo-cli`（实验性）：通过 Atlassian Rovo Dev CLI 提供对 gpt-5 的非官方支持 [rovo-cli.js](https://gist.github.com/SaseQ/c2a20a38b11276537ec5332d1f7a5e53)。 **自定义 Transformer：** 您还可以创建自己的 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 token）的模型。 - `longContextThreshold`（可选）：触发长上下文模型的 token 数量阈值。如果未指定，默认为 60000。 - `webSearch`：用于处理网络搜索任务，这要求模型本身支持该功能。如果您使用的是 openrouter，则需要在模型名称后添加 `:online` 后缀。 - `image`（测试版）：用于处理图像相关任务（由 CCR 的内置 agent 支持）。如果模型不支持工具调用，您需要将 `config.forceUseImageAgent` 属性设置为 `true`。 - 您还可以在 Claude Code 中使用 `/model` 命令动态切换模型： `/model provider_name,model_name` 示例：`/model openrouter,anthropic/claude-3.5-sonnet` #### 自定义 Router 对于更高级的路由逻辑，您可以通过 `config.json` 中的 `CUSTOM_ROUTER_PATH` 指定自定义 router 脚本。这允许您实现超越默认场景的复杂路由规则。 在您的 `config.json` 中： ``` { "CUSTOM_ROUTER_PATH": "/User/xxx/.claude-code-router/custom-router.js" } ``` 自定义 router 文件必须是一个导出 `async` 函数的 JavaScript 模块。此函数接收请求对象和配置对象作为参数，并应返回包含 provider 和模型名称的字符串（例如 `"provider_name,model_name"`），或返回 `null` 以回退到默认 router。 以下是基于 `custom-router.example.js` 的 `custom-router.js` 示例： ``` // /User/xxx/.claude-code-router/custom-router.js /** * A custom router function to determine which model to use based on the request. * * @param {object} req - The request object from Claude Code, containing the request body. * @param {object} config - The application's config object. * @returns {Promise} - A promise that resolves to the "provider,model_name" string, or null to use the default router. */ module.exports = async function router(req, config) { const userMessage = req.body.messages.find((m) => m.role === "user")?.content; if (userMessage && userMessage.includes("explain this code")) { // Use a powerful model for code explanation return "openrouter,anthropic/claude-3.5-sonnet"; } // Fallback to the default router configuration return null; }; ``` ##### 子 Agent 路由 对于子 agent 内部的路由，您必须通过在子 agent prompt 的**开头**包含 `provider,model` 来指定特定的 provider 和模型。这允许您将特定的子 agent 任务定向到指定的模型。 **示例：** ``` openrouter,anthropic/claude-3.5-sonnet Please help me analyze this code snippet for potential optimizations... ``` ## 状态栏（Beta） 为了更好地在运行时监控 claude-code-router 的状态，版本 v1.0.40 包含了一个内置的 statusline 工具，您可以在 UI 中启用它。  效果如下：  ## 🤖 GitHub Actions 将 Claude Code Router 集成到您的 CI/CD pipeline 中。在设置好 [Claude Code Actions](https://docs.anthropic.com/en/docs/claude-code/github-actions) 后，修改您的 `.github/workflows/claude.yaml` 以使用 router： ``` 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 @musistudio/claude-code-router@1.0.8 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 成本。 ## 📝 延伸阅读 - [项目动机及其工作原理](blog/en/project-motivation-and-how-it-works.md) - [也许我们可以用 Router 做更多事情](blog/en/maybe-we-can-do-more-with-the-route.md) - [GLM-4.6 支持推理与交错式思考](blog/en/glm-4.6-supports-reasoning.md) ### 我们的赞助者 非常感谢我们所有赞助者的慷慨支持！ - [AIHubmix](https://aihubmix.com/) - [BurnCloud](https://ai.burncloud.com) - [302.AI](https://share.302.ai/ZGVF9w) - [Z智谱](https://www.bigmodel.cn/claude-code?ic=FPF9IVAGFJ) - @Simon Leischnig - [@duanshuaimin](https://github.com/duanshuaimin) - [@vrgitadmin](https://github.com/vrgitadmin) - @\*o - [@ceilwoo](https://github.com/ceilwoo) - @\*说 - @\*更 - @K\*g - @R\*R - [@bobleer](https://github.com/bobleer) - @\*苗 - @\*划 - [@Clarence-pan](https://github.com/Clarence-pan) - [@carter003](https://github.com/carter003) - @S\*r - @\*晖 - @\*敏 - @Z\*z - @\*然 - [@cluic](https://github.com/cluic) - @\*苗 - [@PromptExpert](https://github.com/PromptExpert) - @\*应 - [@yusnake](https://github.com/yusnake) - @\*飞 - @董\* - @\*汀 - @\*涯 - @\*:-） - @\*\*磊 - @\*琢 - @\*成 - @Z\*o - @\*琨 - [@congzhangzh](https://github.com/congzhangzh) - @\*\_ - @Z\*m - @*鑫 - @c\*y - @\*昕 - [@witsice](https://github.com/witsice) - @b\*g - @\*亿 - @\*辉 - @JACK - @\*光 - @W\*l - [@kesku](https://github.com/kesku) - [@biguncle](https://github.com/biguncle) - @二吉吉 - @a\*g - @\*林 - @\*咸 - @\*明 - @S\*y - @f\*o - @\*智 - @F\*t - @r\*c - [@qierkang](http://github.com/qierkang) - @\*军 - [@snrise-z](http://github.com/snrise-z) - @\*王 - [@greatheart1000](http://github.com/greatheart1000) - @\*王 - @zcutlip - [@Peng-YM](http://github.com/Peng-YM) - @\*更 - @\*. - @F\*t - @\*政 - @\*铭 - @\*叶 - @七\*o - @\*青 - @\*\*晨 - @\*远 - @\*霄 - @\*\*吉 - @\*\*飞 - @\*\*驰 - @x\*g - @\*\*东 - @\*落 - @哆\*k - @\*涛 - [@苗大](https://github.com/WitMiao) - @\*呢 - @\d*u - @crizcraig - s\*s - \*火 - \*勤 - \*\*锟 - \*涛 - \*\*明 - \*知 - \*语 - \*瓜 （如果您的名字被掩码，请通过我的主页邮箱联系我，以便用您的 GitHub 用户名进行更新。）

标签：API代理, Claude, CVE检测, MITM代理, SOC Prime, 人工智能, 开发工具, 暗色界面, 模型路由, 用户模式Hook绕过, 自动化攻击