This commit is contained in:
musistudio
2025-12-27 07:58:01 +08:00
parent 085ee97cdc
commit 160594a8d6
64 changed files with 17205 additions and 15 deletions

View File

@@ -0,0 +1,161 @@
---
id: config/basic
title: 基础配置
sidebar_position: 1
---
# 基础配置
学习如何配置 Claude Code Router 以满足您的需求。
## 配置文件位置
配置文件位于:
```
~/.claude-code-router/config.json
```
## 配置结构
### Providers提供商
配置 LLM 提供商以将请求路由到:
```json
{
"Providers": [
{
"name": "deepseek",
"api_base_url": "https://api.deepseek.com/chat/completions",
"api_key": "your-api-key",
"models": ["deepseek-chat", "deepseek-coder"]
},
{
"name": "groq",
"api_base_url": "https://api.groq.com/openai/v1/chat/completions",
"api_key": "your-groq-api-key",
"models": ["llama-3.3-70b-versatile"]
}
]
}
```
### Router路由器
配置默认使用的模型:
```json
{
"Router": {
"default": "deepseek,deepseek-chat"
}
}
```
格式:`{provider-name},{model-name}`
### Transformers转换器
对请求/响应应用转换:
```json
{
"transformers": [
{
"path": "/path/to/custom-transformer.js",
"options": {
"key": "value"
}
}
]
}
```
### 环境变量
在配置中使用环境变量:
```json
{
"Providers": [
{
"name": "deepseek",
"api_base_url": "https://api.deepseek.com/chat/completions",
"api_key": "$DEEPSEEK_API_KEY"
}
]
}
```
同时支持 `$VAR_NAME``${VAR_NAME}` 语法。
## 完整示例
```json
{
"PORT": 8080,
"APIKEY": "your-secret-key",
"PROXY_URL": "http://127.0.0.1:7890",
"LOG": true,
"LOG_LEVEL": "debug",
"API_TIMEOUT_MS": 600000,
"Providers": [
{
"name": "deepseek",
"api_base_url": "https://api.deepseek.com/chat/completions",
"api_key": "$DEEPSEEK_API_KEY",
"models": ["deepseek-chat", "deepseek-coder"],
"transformer": {
"use": ["deepseek"]
}
},
{
"name": "groq",
"api_base_url": "https://api.groq.com/openai/v1/chat/completions",
"api_key": "$GROQ_API_KEY",
"models": ["llama-3.3-70b-versatile"]
}
],
"Router": {
"default": "deepseek,deepseek-chat",
"longContextThreshold": 100000,
"background": "groq,llama-3.3-70b-versatile"
}
}
```
## 编辑配置
使用 CLI 编辑配置:
```bash
ccr config edit
```
这将在您的默认编辑器中打开配置文件。
## 重新加载配置
编辑配置后,重启路由器:
```bash
ccr restart
```
## 配置选项说明
- **PORT**: 服务器端口号默认3456
- **APIKEY**: API 密钥,用于身份验证
- **HOST**: 服务器监听地址默认127.0.0.1,如果配置了 Providers 且没有设置 APIKEY则强制为 127.0.0.1
- **PROXY_URL**: 代理服务器地址
- **LOG**: 是否启用日志默认true
- **LOG_LEVEL**: 日志级别fatal/error/warn/info/debug/trace
- **API_TIMEOUT_MS**: API 请求超时时间(毫秒)
- **NON_INTERACTIVE_MODE**: 非交互模式(用于 CI/CD 环境)
## 下一步
- [提供商配置](/zh/docs/config/providers) - 详细的提供商配置
- [路由配置](/zh/docs/config/routing) - 配置路由规则
- [转换器](/zh/docs/config/transformers) - 应用转换

View File

@@ -0,0 +1,213 @@
---
id: config/providers
title: 提供商配置
sidebar_position: 2
---
# 提供商配置
配置 LLM 提供商的详细指南。
## 支持的提供商
### DeepSeek
```json
{
"name": "deepseek",
"api_base_url": "https://api.deepseek.com/chat/completions",
"api_key": "your-api-key",
"models": ["deepseek-chat", "deepseek-coder", "deepseek-reasoner"],
"transformer": {
"use": ["deepseek"]
}
}
```
### Groq
```json
{
"name": "groq",
"api_base_url": "https://api.groq.com/openai/v1/chat/completions",
"api_key": "your-api-key",
"models": ["llama-3.3-70b-versatile"]
}
```
### Gemini
```json
{
"name": "gemini",
"api_base_url": "https://generativelanguage.googleapis.com/v1beta/models/",
"api_key": "your-api-key",
"models": ["gemini-2.5-flash", "gemini-2.5-pro"],
"transformer": {
"use": ["gemini"]
}
}
```
### OpenRouter
```json
{
"name": "openrouter",
"api_base_url": "https://openrouter.ai/api/v1/chat/completions",
"api_key": "your-api-key",
"models": [
"anthropic/claude-3.5-sonnet",
"google/gemini-2.5-pro-preview"
],
"transformer": {
"use": ["openrouter"]
}
}
```
### Ollama本地模型
```json
{
"name": "ollama",
"api_base_url": "http://localhost:11434/v1/chat/completions",
"api_key": "ollama",
"models": ["qwen2.5-coder:latest"]
}
```
### 火山引擎
```json
{
"name": "volcengine",
"api_base_url": "https://ark.cn-beijing.volces.com/api/v3/chat/completions",
"api_key": "your-api-key",
"models": ["deepseek-v3-250324", "deepseek-r1-250528"],
"transformer": {
"use": ["deepseek"]
}
}
```
### ModelScope
```json
{
"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"]
}
}
}
```
### DashScope阿里云
```json
{
"name": "dashscope",
"api_base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions",
"api_key": "your-api-key",
"models": ["qwen3-coder-plus"],
"transformer": {
"use": [
["maxtoken", { "max_tokens": 65536 }],
"enhancetool"
]
}
}
```
## 提供商配置选项
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `name` | string | 是 | 提供商的唯一标识符 |
| `api_base_url` | string | 是 | API 基础 URL |
| `api_key` | string | 是 | API 认证密钥 |
| `models` | string[] | 否 | 可用模型列表 |
| `transformer` | object | 否 | 应用的转换器配置 |
## 模型选择
在路由中选择模型时,使用以下格式:
```
{provider-name},{model-name}
```
例如:
```
deepseek,deepseek-chat
```
## 使用环境变量
您可以在配置中使用环境变量来保护 API 密钥:
```json
{
"Providers": [
{
"name": "deepseek",
"api_base_url": "https://api.deepseek.com/chat/completions",
"api_key": "$DEEPSEEK_API_KEY",
"models": ["deepseek-chat"]
}
]
}
```
支持 `$VAR_NAME``${VAR_NAME}` 两种语法。
## 转换器配置
转换器用于适配不同提供商的 API 差异。您可以在提供商级别或模型级别配置转换器:
### 提供商级别转换器
应用于提供商的所有模型:
```json
{
"name": "openrouter",
"transformer": {
"use": ["openrouter"]
}
}
```
### 模型级别转换器
应用于特定模型:
```json
{
"name": "deepseek",
"transformer": {
"use": ["deepseek"],
"deepseek-chat": {
"use": ["tooluse"]
}
}
}
```
## 下一步
- [路由配置](/zh/docs/config/routing) - 配置请求如何路由
- [转换器](/zh/docs/config/transformers) - 对请求应用转换

View File

@@ -0,0 +1,165 @@
---
id: config/routing
title: 路由配置
sidebar_position: 3
---
# 路由配置
配置如何将请求路由到不同的模型。
## 默认路由
为所有请求设置默认模型:
```json
{
"Router": {
"default": "deepseek,deepseek-chat"
}
}
```
## 内置场景
### 后台任务
将后台任务路由到轻量级模型:
```json
{
"Router": {
"background": "groq,llama-3.3-70b-versatile"
}
}
```
### 思考模式(计划模式)
将思考密集型任务路由到更强大的模型:
```json
{
"Router": {
"think": "deepseek,deepseek-reasoner"
}
}
```
### 长上下文
路由长上下文请求:
```json
{
"Router": {
"longContextThreshold": 100000,
"longContext": "gemini,gemini-2.5-pro"
}
}
```
### 网络搜索
路由网络搜索任务:
```json
{
"Router": {
"webSearch": "gemini,gemini-2.5-flash"
}
}
```
### 图像任务
路由图像相关任务:
```json
{
"Router": {
"image": "gemini,gemini-2.5-pro"
}
}
```
## 项目级路由
`~/.claude/projects/<project-id>/claude-code-router.json` 中为每个项目配置路由:
```json
{
"Router": {
"default": "groq,llama-3.3-70b-versatile"
}
}
```
项目级配置优先于全局配置。
## 自定义路由器
创建自定义 JavaScript 路由器函数:
1. 创建路由器文件(例如 `custom-router.js`
```javascript
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`
```json
{
"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. 默认路由
## 下一步
- [转换器](/zh/docs/config/transformers) - 对请求应用转换
- [自定义路由器](/zh/docs/advanced/custom-router) - 高级自定义路由

View File

@@ -0,0 +1,283 @@
---
id: config/transformers
title: 转换器
sidebar_position: 4
---
# 转换器
转换器用于适配不同提供商之间的 API 差异。
## 内置转换器
### anthropic
将请求转换为兼容 Anthropic 风格的 API
```json
{
"transformer": {
"use": ["anthropic"]
}
}
```
如果只使用这一个转换器,它将直接透传请求和响应(您可以用来接入其他支持 Anthropic 端点的服务商)。
### deepseek
专门用于 DeepSeek API 的转换器:
```json
{
"transformer": {
"use": ["deepseek"]
}
}
```
### gemini
用于 Google Gemini API 的转换器:
```json
{
"transformer": {
"use": ["gemini"]
}
}
```
### groq
用于 Groq API 的转换器:
```json
{
"transformer": {
"use": ["groq"]
}
}
```
### openrouter
用于 OpenRouter API 的转换器:
```json
{
"transformer": {
"use": ["openrouter"]
}
}
```
OpenRouter 转换器还支持 `provider` 路由参数,以指定 OpenRouter 应使用哪些底层提供商:
```json
{
"transformer": {
"use": ["openrouter"],
"moonshotai/kimi-k2": {
"use": [
["openrouter", {
"provider": {
"only": ["moonshotai/fp8"]
}
}]
]
}
}
}
```
### maxtoken
设置特定的 `max_tokens` 值:
```json
{
"transformer": {
"use": [
["maxtoken", { "max_tokens": 65536 }]
]
}
}
```
### tooluse
通过 `tool_choice` 参数优化某些模型的工具使用:
```json
{
"transformer": {
"use": ["tooluse"]
}
}
```
### reasoning
用于处理 `reasoning_content` 字段:
```json
{
"transformer": {
"use": ["reasoning"]
}
}
```
### sampling
用于处理采样信息字段,如 `temperature``top_p``top_k``repetition_penalty`
```json
{
"transformer": {
"use": ["sampling"]
}
}
```
### enhancetool
对 LLM 返回的工具调用参数增加一层容错处理(注意:这会导致不再流式返回工具调用信息):
```json
{
"transformer": {
"use": ["enhancetool"]
}
}
```
### cleancache
清除请求中的 `cache_control` 字段:
```json
{
"transformer": {
"use": ["cleancache"]
}
}
```
### vertex-gemini
处理使用 Vertex 鉴权的 Gemini API
```json
{
"transformer": {
"use": ["vertex-gemini"]
}
}
```
## 应用转换器
### 全局应用
应用于提供商的所有请求:
```json
{
"Providers": [
{
"name": "deepseek",
"api_base_url": "https://api.deepseek.com/chat/completions",
"api_key": "your-api-key",
"transformer": {
"use": ["deepseek"]
}
}
]
}
```
### 模型特定应用
应用于特定模型:
```json
{
"name": "deepseek",
"transformer": {
"use": ["deepseek"],
"deepseek-chat": {
"use": ["tooluse"]
}
}
}
```
### 传递选项
某些转换器接受选项:
```json
{
"transformer": {
"use": [
["maxtoken", { "max_tokens": 8192 }]
]
}
}
```
## 自定义转换器
创建自定义转换器插件:
1. 创建转换器文件:
```javascript
module.exports = {
name: 'my-transformer',
transformRequest: async (req, config) => {
// 修改请求
return req;
},
transformResponse: async (res, config) => {
// 修改响应
return res;
}
};
```
2. 在配置中加载:
```json
{
"transformers": [
{
"path": "/path/to/transformer.js",
"options": {
"key": "value"
}
}
]
}
```
## 实验性转换器
### gemini-cli实验性
通过 Gemini CLI 对 Gemini 的非官方支持。
### qwen-cli实验性
通过 Qwen CLI 对 qwen3-coder-plus 的非官方支持。
### rovo-cli实验性
通过 Atlassian Rovo Dev CLI 对 GPT-5 的非官方支持。
## 下一步
- [高级主题](/zh/docs/advanced/custom-router) - 高级路由自定义
- [Agent](/zh/docs/advanced/agents) - 使用 Agent 扩展功能