mirror of
https://github.com/musistudio/claude-code-router.git
synced 2026-02-18 22:50:49 +08:00
fix docs
This commit is contained in:
musistudio
@@ -0,0 +1,148 @@
|
||||
---
|
||||
title: 自定义路由器
|
||||
sidebar_position: 1
|
||||
---
|
||||
|
||||
# 自定义路由器
|
||||
|
||||
使用 JavaScript 编写自己的路由逻辑。
|
||||
|
||||
## 创建自定义路由器
|
||||
|
||||
创建一个导出路由函数的 JavaScript 文件：
|
||||
|
||||
```javascript
|
||||
// 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;
|
||||
};
|
||||
```
|
||||
|
||||
## 参数说明
|
||||
|
||||
路由函数接收以下参数：
|
||||
|
||||
| 参数 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `req` | object | 来自 Claude Code 的请求对象，包含请求体 |
|
||||
| `config` | object | 应用程序的配置对象 |
|
||||
|
||||
## 配置
|
||||
|
||||
在 `config.json` 中设置 `CUSTOM_ROUTER_PATH` 以使用您的自定义路由器：
|
||||
|
||||
```json
|
||||
{
|
||||
"CUSTOM_ROUTER_PATH": "/path/to/custom-router.js"
|
||||
}
|
||||
```
|
||||
|
||||
## 返回格式
|
||||
|
||||
路由函数应返回以下格式的字符串：
|
||||
|
||||
```
|
||||
{provider-name},{model-name}
|
||||
```
|
||||
|
||||
示例：
|
||||
|
||||
```
|
||||
deepseek,deepseek-chat
|
||||
```
|
||||
|
||||
如果返回 `null`，则回退到默认路由配置。
|
||||
|
||||
## 错误处理
|
||||
|
||||
如果路由函数抛出错误或返回无效格式，路由器将回退到默认路由配置。
|
||||
|
||||
## 示例：基于时间的路由
|
||||
|
||||
```javascript
|
||||
module.exports = async function(req, config) {
|
||||
const hour = new Date().getHours();
|
||||
|
||||
// 工作时间使用更快的模型
|
||||
if (hour >= 9 && hour <= 18) {
|
||||
return 'groq,llama-3.3-70b-versatile';
|
||||
}
|
||||
|
||||
// 非工作时间使用更强大的模型
|
||||
return 'deepseek,deepseek-chat';
|
||||
};
|
||||
```
|
||||
|
||||
## 示例：成本优化
|
||||
|
||||
```javascript
|
||||
module.exports = async function(req, config) {
|
||||
const userMessage = req.body.messages.find(m => m.role === 'user')?.content;
|
||||
|
||||
// 简单任务使用较便宜的模型
|
||||
if (userMessage && userMessage.length < 100) {
|
||||
return 'groq,llama-3.3-70b-versatile';
|
||||
}
|
||||
|
||||
// 复杂任务使用默认模型
|
||||
return null;
|
||||
};
|
||||
```
|
||||
|
||||
## 示例：任务类型路由
|
||||
|
||||
```javascript
|
||||
module.exports = async function(req, config) {
|
||||
const userMessage = req.body.messages.find(m => m.role === 'user')?.content;
|
||||
|
||||
if (!userMessage) return null;
|
||||
|
||||
// 代码相关任务
|
||||
if (userMessage.includes('代码') || userMessage.includes('code')) {
|
||||
return 'deepseek,deepseek-coder';
|
||||
}
|
||||
|
||||
// 解释任务
|
||||
if (userMessage.includes('解释') || userMessage.includes('explain')) {
|
||||
return 'openrouter,anthropic/claude-3.5-sonnet';
|
||||
}
|
||||
|
||||
// 默认
|
||||
return null;
|
||||
};
|
||||
```
|
||||
|
||||
## 测试您的路由器
|
||||
|
||||
通过检查日志来测试您的自定义路由器：
|
||||
|
||||
```bash
|
||||
tail -f ~/.claude-code-router/claude-code-router.log
|
||||
```
|
||||
|
||||
查找路由决策以查看正在选择哪个模型。
|
||||
|
||||
## 子代理路由
|
||||
|
||||
对于子代理内的路由，您必须在子代理提示词的**开头**包含 `<CCR-SUBAGENT-MODEL>provider,model</CCR-SUBAGENT-MODEL>` 来指定特定的提供商和模型。
|
||||
|
||||
**示例：**
|
||||
|
||||
```
|
||||
<CCR-SUBAGENT-MODEL>openrouter,anthropic/claude-3.5-sonnet</CCR-SUBAGENT-MODEL>
|
||||
请帮我分析这段代码是否存在潜在的优化空间...
|
||||
```
|
||||
|
||||
## 下一步
|
||||
|
||||
- [Agent](/zh/docs/advanced/agents) - 使用 Agent 扩展功能
|
||||
- [预设](/zh/docs/advanced/presets) - 使用预定义配置
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,672 @@
|
||||
---
|
||||
title: 预设配置
|
||||
sidebar_position: 3
|
||||
---
|
||||
|
||||
# 预设配置
|
||||
|
||||
使用预定义配置进行快速设置。
|
||||
|
||||
## 什么是预设？
|
||||
|
||||
预设是预配置的设置，包括针对特定用例优化的提供商配置、路由规则和转换器。
|
||||
|
||||
## 使用预设
|
||||
|
||||
### CLI 方式（命令行）
|
||||
|
||||
CLI 方式适合开发者通过命令行快速操作。
|
||||
|
||||
#### 安装预设
|
||||
|
||||
**从本地目录安装：**
|
||||
|
||||
```bash
|
||||
ccr preset install /path/to/preset-directory
|
||||
```
|
||||
|
||||
**重新配置已安装的预设：**
|
||||
|
||||
```bash
|
||||
ccr preset install my-preset
|
||||
```
|
||||
|
||||
:::note 注意
|
||||
CLI 方式**不支持**从 URL 直接安装预设。如需从 GitHub 安装，请先克隆到本地或使用 Web UI。
|
||||
:::
|
||||
|
||||
#### 使用预设
|
||||
|
||||
安装预设后，可以使用预设名称启动 Claude Code：
|
||||
|
||||
```bash
|
||||
# 使用指定预设启动
|
||||
ccr my-preset "your prompt"
|
||||
|
||||
# 后台任务使用预设
|
||||
ccr my-preset --background "your prompt"
|
||||
```
|
||||
|
||||
预设会：
|
||||
- 自动加载预配置的 Provider
|
||||
- 应用预设的路由规则
|
||||
- 使用预设中配置的 transformer
|
||||
|
||||
#### 列出所有预设
|
||||
|
||||
```bash
|
||||
ccr preset list
|
||||
```
|
||||
|
||||
此命令将显示所有已安装的预设及其名称、版本和描述。
|
||||
|
||||
#### 查看预设信息
|
||||
|
||||
```bash
|
||||
ccr preset info my-preset
|
||||
```
|
||||
|
||||
#### 删除预设
|
||||
|
||||
```bash
|
||||
ccr preset delete my-preset
|
||||
```
|
||||
|
||||
### Web UI 方式
|
||||
|
||||
Web UI 提供更友好的可视化界面，支持更多安装方式。
|
||||
|
||||
#### 访问 Web UI
|
||||
|
||||
```bash
|
||||
ccr ui
|
||||
```
|
||||
|
||||
然后在浏览器中打开 `http://localhost:3000`
|
||||
|
||||
#### 从 GitHub 仓库安装
|
||||
|
||||
1. 点击"预设商城"按钮
|
||||
2. 在预设列表中选择要安装的预设
|
||||
3. 点击"安装"按钮
|
||||
|
||||
或手动输入 GitHub 仓库地址：
|
||||
|
||||
```
|
||||
格式：https://github.com/username/repo
|
||||
示例：https://github.com/example/ccr-presets
|
||||
```
|
||||
|
||||
#### 重新配置预设
|
||||
|
||||
1. 在预设列表中点击"查看详情"按钮
|
||||
2. 在详情页面中修改配置项
|
||||
3. 点击"应用"保存配置
|
||||
|
||||
#### 管理预设
|
||||
|
||||
- **查看**：点击预设右侧的信息图标
|
||||
- **删除**：点击预设右侧的删除图标
|
||||
|
||||
## 创建自定义预设
|
||||
|
||||
### 预设目录结构
|
||||
|
||||
预设以目录形式存储，每个预设包含以下结构：
|
||||
|
||||
```
|
||||
~/.claude-code-router/presets/<preset-name>/
|
||||
├── manifest.json # 必填：预设配置文件
|
||||
├── transformers/ # 可选：自定义转换器
|
||||
│ └── custom-transformer.js
|
||||
├── scripts/ # 可选：自定义脚本
|
||||
│ └── status.js
|
||||
└── README.md # 可选：说明文档
|
||||
```
|
||||
|
||||
### 动态配置系统
|
||||
|
||||
CCR 引入了强大的动态配置系统，支持：
|
||||
|
||||
- **多种输入类型**：选择器、多选、确认框、文本输入、数字输入等
|
||||
- **条件逻辑**：根据用户输入动态显示/隐藏配置项
|
||||
- **变量引用**：配置项之间可以互相引用
|
||||
- **动态选项**：选项列表可以从预设配置或用户输入中动态生成
|
||||
|
||||
#### Schema 字段类型
|
||||
|
||||
| 类型 | 说明 | 示例 |
|
||||
|------|------|------|
|
||||
| `password` | 密码输入（隐藏显示） | API Key |
|
||||
| `input` | 单行文本输入 | Base URL |
|
||||
| `number` | 数字输入 | 最大Token数 |
|
||||
| `select` | 单选下拉框 | 选择Provider |
|
||||
| `multiselect` | 多选框 | 启用功能 |
|
||||
| `confirm` | 确认框 | 是否使用代理 |
|
||||
| `editor` | 多行文本编辑器 | 自定义配置 |
|
||||
|
||||
#### 条件运算符
|
||||
|
||||
| 运算符 | 说明 | 示例 |
|
||||
|--------|------|------|
|
||||
| `eq` | 等于 | `{"field": "provider", "operator": "eq", "value": "openai"}` |
|
||||
| `ne` | 不等于 | `{"field": "advanced", "operator": "ne", "value": true}` |
|
||||
| `in` | 包含于 | `{"field": "feature", "operator": "in", "value": ["a", "b"]}` |
|
||||
| `nin` | 不包含于 | `{"field": "type", "operator": "nin", "value": ["x", "y"]}` |
|
||||
| `exists` | 字段存在 | `{"field": "apiKey", "operator": "exists"}` |
|
||||
| `gt/lt/gte/lte` | 大于/小于/大于等于/小于等于 | 用于数字比较 |
|
||||
|
||||
#### 动态选项类型
|
||||
|
||||
##### static - 静态选项
|
||||
```json
|
||||
"options": {
|
||||
"type": "static",
|
||||
"options": [
|
||||
{"label": "选项1", "value": "value1"},
|
||||
{"label": "选项2", "value": "value2"}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
##### providers - 从 Providers 配置提取
|
||||
```json
|
||||
"options": {
|
||||
"type": "providers"
|
||||
}
|
||||
```
|
||||
自动从 `Providers` 数组中提取 name 作为选项。
|
||||
|
||||
##### models - 从指定 Provider 的 models 提取
|
||||
```json
|
||||
"options": {
|
||||
"type": "models",
|
||||
"providerField": "{{selectedProvider}}"
|
||||
}
|
||||
```
|
||||
根据用户选择的 Provider，动态显示该 Provider 的 models。
|
||||
|
||||
#### 模板变量
|
||||
|
||||
使用 `{{变量名}}` 语法在 template 中引用用户输入：
|
||||
|
||||
```json
|
||||
"template": {
|
||||
"Providers": [
|
||||
{
|
||||
"name": "{{providerName}}",
|
||||
"api_key": "{{apiKey}}"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### 配置映射
|
||||
|
||||
对于复杂的配置需求，使用 `configMappings` 精确控制值的位置：
|
||||
|
||||
```json
|
||||
"configMappings": [
|
||||
{
|
||||
"target": "Providers[0].api_key",
|
||||
"value": "{{apiKey}}"
|
||||
},
|
||||
{
|
||||
"target": "PROXY_URL",
|
||||
"value": "{{proxyUrl}}",
|
||||
"when": {
|
||||
"field": "useProxy",
|
||||
"operator": "eq",
|
||||
"value": true
|
||||
}
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
#### 完整示例
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "multi-provider-example",
|
||||
"version": "1.0.0",
|
||||
"description": "多Provider配置示例 - 支持OpenAI和DeepSeek切换",
|
||||
"author": "CCR Team",
|
||||
"keywords": ["openai", "deepseek", "multi-provider"],
|
||||
"ccrVersion": "2.0.0",
|
||||
"schema": [
|
||||
{
|
||||
"id": "primaryProvider",
|
||||
"type": "select",
|
||||
"label": "主要Provider",
|
||||
"prompt": "选择您主要使用的LLM提供商",
|
||||
"options": {
|
||||
"type": "static",
|
||||
"options": [
|
||||
{
|
||||
"label": "OpenAI",
|
||||
"value": "openai",
|
||||
"description": "使用OpenAI的GPT模型"
|
||||
},
|
||||
{
|
||||
"label": "DeepSeek",
|
||||
"value": "deepseek",
|
||||
"description": "使用DeepSeek的高性价比模型"
|
||||
}
|
||||
]
|
||||
},
|
||||
"required": true,
|
||||
"defaultValue": "openai"
|
||||
},
|
||||
{
|
||||
"id": "apiKey",
|
||||
"type": "password",
|
||||
"label": "API Key",
|
||||
"prompt": "请输入您的API Key",
|
||||
"placeholder": "sk-...",
|
||||
"required": true
|
||||
},
|
||||
{
|
||||
"id": "defaultModel",
|
||||
"type": "select",
|
||||
"label": "默认模型",
|
||||
"prompt": "选择默认使用的模型",
|
||||
"options": {
|
||||
"type": "static",
|
||||
"options": [
|
||||
{"label": "GPT-4o", "value": "gpt-4o"},
|
||||
{"label": "GPT-4o-mini", "value": "gpt-4o-mini"}
|
||||
]
|
||||
},
|
||||
"required": true,
|
||||
"defaultValue": "gpt-4o",
|
||||
"when": {
|
||||
"field": "primaryProvider",
|
||||
"operator": "eq",
|
||||
"value": "openai"
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "enableProxy",
|
||||
"type": "confirm",
|
||||
"label": "启用代理",
|
||||
"prompt": "是否通过代理访问API？",
|
||||
"defaultValue": false
|
||||
},
|
||||
{
|
||||
"id": "proxyUrl",
|
||||
"type": "input",
|
||||
"label": "代理地址",
|
||||
"prompt": "输入代理服务器地址",
|
||||
"placeholder": "http://127.0.0.1:7890",
|
||||
"required": true,
|
||||
"when": {
|
||||
"field": "enableProxy",
|
||||
"operator": "eq",
|
||||
"value": true
|
||||
}
|
||||
}
|
||||
],
|
||||
"template": {
|
||||
"Providers": [
|
||||
{
|
||||
"name": "{{primaryProvider}}",
|
||||
"api_base_url": "https://api.openai.com/v1",
|
||||
"api_key": "{{apiKey}}",
|
||||
"models": ["{{defaultModel}}"]
|
||||
}
|
||||
],
|
||||
"Router": {
|
||||
"default": "{{primaryProvider}}/{{defaultModel}}"
|
||||
},
|
||||
"PROXY_URL": "{{proxyUrl}}"
|
||||
},
|
||||
"configMappings": [
|
||||
{
|
||||
"target": "PROXY_URL",
|
||||
"value": "{{proxyUrl}}",
|
||||
"when": {
|
||||
"field": "enableProxy",
|
||||
"operator": "eq",
|
||||
"value": true
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### manifest.json 完整字段说明
|
||||
|
||||
`manifest.json` 是预设的核心配置文件，使用 JSON5 格式（支持注释）。
|
||||
|
||||
#### 1. 元数据字段（Metadata）
|
||||
|
||||
这些字段用于描述预设的基本信息：
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| `name` | string | ✓ | 预设名称（唯一标识符） |
|
||||
| `version` | string | ✓ | 版本号（遵循 semver 规范） |
|
||||
| `description` | string | - | 预设描述 |
|
||||
| `author` | string | - | 作者信息 |
|
||||
| `homepage` | string | - | 项目主页 URL |
|
||||
| `repository` | string | - | 源代码仓库 URL |
|
||||
| `license` | string | - | 许可证类型 |
|
||||
| `keywords` | string[] | - | 关键词标签 |
|
||||
| `ccrVersion` | string | - | 兼容的 CCR 版本 |
|
||||
| `source` | string | - | 预设来源 URL |
|
||||
| `sourceType` | string | - | 来源类型（`local`/`gist`/`registry`） |
|
||||
| `checksum` | string | - | 内容校验和（SHA256） |
|
||||
|
||||
示例：
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "my-preset",
|
||||
"version": "1.0.0",
|
||||
"description": "我的自定义预设",
|
||||
"author": "Your Name",
|
||||
"homepage": "https://github.com/yourname/ccr-presets",
|
||||
"repository": "https://github.com/yourname/ccr-presets.git",
|
||||
"license": "MIT",
|
||||
"keywords": ["openai", "production"],
|
||||
"ccrVersion": "2.0.0"
|
||||
}
|
||||
```
|
||||
|
||||
#### 2. 配置字段（Configuration）
|
||||
|
||||
这些字段会直接合并到 CCR 的配置中，所有 `config.json` 支持的字段都可以在这里使用：
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `Providers` | array | Provider 配置数组 |
|
||||
| `Router` | object | 路由配置 |
|
||||
| `transformers` | array | 转换器配置 |
|
||||
| `StatusLine` | object | 状态栏配置 |
|
||||
|
||||
示例：
|
||||
|
||||
```json
|
||||
{
|
||||
"Providers": [
|
||||
{
|
||||
"name": "openai",
|
||||
"api_base_url": "https://api.openai.com/v1",
|
||||
"api_key": "${OPENAI_API_KEY}",
|
||||
"models": ["gpt-4o", "gpt-4o-mini"]
|
||||
}
|
||||
],
|
||||
"Router": {
|
||||
"default": "openai/gpt-4o",
|
||||
"background": "openai/gpt-4o-mini"
|
||||
},
|
||||
"PORT": 8080
|
||||
}
|
||||
```
|
||||
|
||||
#### 3. 动态配置系统字段
|
||||
|
||||
这些字段用于创建可交互的配置模板：
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `schema` | array | 配置输入表单定义 |
|
||||
| `template` | object | 配置模板（使用变量引用） |
|
||||
| `configMappings` | array | 配置映射规则 |
|
||||
| `userValues` | object | 用户填写的值（运行时使用） |
|
||||
| `requiredInputs` | array | 必填输入项列表（自动生成） |
|
||||
|
||||
**schema 字段类型：**
|
||||
|
||||
| 类型 | 说明 | 使用场景 |
|
||||
|------|------|----------|
|
||||
| `password` | 密码输入（隐藏） | API Key |
|
||||
| `input` | 单行文本输入 | URL |
|
||||
| `number` | 数字输入 | 端口号 |
|
||||
| `select` | 单选下拉框 | 选择 Provider |
|
||||
| `multiselect` | 多选框 | 启用功能 |
|
||||
| `confirm` | 确认框 | 是否启用 |
|
||||
| `editor` | 多行文本编辑器 | 自定义配置 |
|
||||
|
||||
动态配置示例：
|
||||
|
||||
```json
|
||||
{
|
||||
"schema": [
|
||||
{
|
||||
"id": "apiKey",
|
||||
"type": "password",
|
||||
"label": "API Key",
|
||||
"prompt": "请输入您的 API Key",
|
||||
"required": true
|
||||
},
|
||||
{
|
||||
"id": "provider",
|
||||
"type": "select",
|
||||
"label": "Provider",
|
||||
"options": {
|
||||
"type": "static",
|
||||
"options": [
|
||||
{"label": "OpenAI", "value": "openai"},
|
||||
{"label": "DeepSeek", "value": "deepseek"}
|
||||
]
|
||||
},
|
||||
"defaultValue": "openai"
|
||||
}
|
||||
],
|
||||
"template": {
|
||||
"Providers": [
|
||||
{
|
||||
"name": "#{provider}",
|
||||
"api_key": "#{apiKey}"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 创建预设示例
|
||||
|
||||
#### 示例 1：简单预设（无动态配置）
|
||||
|
||||
```bash
|
||||
# 创建预设目录
|
||||
mkdir -p ~/.claude-code-router/presets/simple-openai
|
||||
|
||||
# 创建 manifest.json
|
||||
cat > ~/.claude-code-router/presets/simple-openai/manifest.json << 'EOF'
|
||||
{
|
||||
"name": "simple-openai",
|
||||
"version": "1.0.0",
|
||||
"description": "简单的 OpenAI 配置",
|
||||
"author": "Your Name",
|
||||
|
||||
"Providers": [
|
||||
{
|
||||
"name": "openai",
|
||||
"api_base_url": "https://api.openai.com/v1",
|
||||
"api_key": "${OPENAI_API_KEY}",
|
||||
"models": ["gpt-4o", "gpt-4o-mini"]
|
||||
}
|
||||
],
|
||||
|
||||
"Router": {
|
||||
"default": "openai/gpt-4o",
|
||||
"background": "openai/gpt-4o-mini"
|
||||
},
|
||||
|
||||
"requiredInputs": [
|
||||
{
|
||||
"id": "Providers[0].api_key",
|
||||
"prompt": "Enter OpenAI API Key",
|
||||
"placeholder": "OPENAI_API_KEY"
|
||||
}
|
||||
]
|
||||
}
|
||||
EOF
|
||||
|
||||
# 配置预设（输入 API Key）
|
||||
ccr preset install simple-openai
|
||||
|
||||
# 使用预设
|
||||
ccr simple-openai "your prompt"
|
||||
```
|
||||
|
||||
#### 示例 2：高级预设（动态配置）
|
||||
|
||||
```bash
|
||||
# 创建预设目录
|
||||
mkdir -p ~/.claude-code-router/presets/advanced-config
|
||||
|
||||
# 创建 manifest.json
|
||||
cat > ~/.claude-code-router/presets/advanced-config/manifest.json << 'EOF'
|
||||
{
|
||||
"name": "advanced-config",
|
||||
"version": "1.0.0",
|
||||
"description": "支持多 Provider 选择的高级配置",
|
||||
"author": "Your Name",
|
||||
"keywords": ["openai", "deepseek", "multi-provider"],
|
||||
|
||||
"schema": [
|
||||
{
|
||||
"id": "provider",
|
||||
"type": "select",
|
||||
"label": "选择 Provider",
|
||||
"prompt": "选择您主要使用的 LLM 提供商",
|
||||
"options": {
|
||||
"type": "static",
|
||||
"options": [
|
||||
{
|
||||
"label": "OpenAI",
|
||||
"value": "openai",
|
||||
"description": "使用 OpenAI 的 GPT 模型"
|
||||
},
|
||||
{
|
||||
"label": "DeepSeek",
|
||||
"value": "deepseek",
|
||||
"description": "使用 DeepSeek 的高性价比模型"
|
||||
}
|
||||
]
|
||||
},
|
||||
"defaultValue": "openai",
|
||||
"required": true
|
||||
},
|
||||
{
|
||||
"id": "apiKey",
|
||||
"type": "password",
|
||||
"label": "API Key",
|
||||
"prompt": "请输入您的 API Key",
|
||||
"placeholder": "sk-...",
|
||||
"required": true
|
||||
},
|
||||
{
|
||||
"id": "enableProxy",
|
||||
"type": "confirm",
|
||||
"label": "启用代理",
|
||||
"prompt": "是否通过代理访问 API？",
|
||||
"defaultValue": false
|
||||
},
|
||||
{
|
||||
"id": "proxyUrl",
|
||||
"type": "input",
|
||||
"label": "代理地址",
|
||||
"prompt": "输入代理服务器地址",
|
||||
"placeholder": "http://127.0.0.1:7890",
|
||||
"required": true,
|
||||
"when": {
|
||||
"field": "enableProxy",
|
||||
"operator": "eq",
|
||||
"value": true
|
||||
}
|
||||
}
|
||||
],
|
||||
|
||||
"template": {
|
||||
"Providers": [
|
||||
{
|
||||
"name": "#{provider}",
|
||||
"api_base_url": "#{provider === 'openai' ? 'https://api.openai.com/v1' : 'https://api.deepseek.com'}",
|
||||
"api_key": "#{apiKey}",
|
||||
"models": ["gpt-4o", "gpt-4o-mini"]
|
||||
}
|
||||
],
|
||||
"Router": {
|
||||
"default": "#{provider}/gpt-4o",
|
||||
"background": "#{provider}/gpt-4o-mini"
|
||||
}
|
||||
},
|
||||
|
||||
"configMappings": [
|
||||
{
|
||||
"target": "PROXY_URL",
|
||||
"value": "#{proxyUrl}",
|
||||
"when": {
|
||||
"field": "enableProxy",
|
||||
"operator": "eq",
|
||||
"value": true
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
EOF
|
||||
|
||||
# 配置预设（会提示输入）
|
||||
ccr preset install advanced-config
|
||||
|
||||
# 使用预设
|
||||
ccr advanced-config "your prompt"
|
||||
```
|
||||
|
||||
### 导出当前配置为预设
|
||||
|
||||
如果您已经配置好了 CCR，可以导出当前配置：
|
||||
|
||||
```bash
|
||||
# 导出当前配置
|
||||
ccr preset export my-exported-preset
|
||||
```
|
||||
|
||||
导出时会自动：
|
||||
- 识别敏感字段（如 `api_key`）并替换为环境变量占位符
|
||||
- 生成 `schema` 用于收集用户输入
|
||||
- 生成 `template` 和 `configMappings`
|
||||
|
||||
可选项：
|
||||
|
||||
```bash
|
||||
ccr preset export my-exported-preset \
|
||||
--description "导出的配置" \
|
||||
--author "Your Name" \
|
||||
--tags "production,openai"
|
||||
```
|
||||
|
||||
:::tip 分享预设
|
||||
导出的预设目录可以直接分享给他人。接收者可以：
|
||||
- **CLI 方式**：将目录放到 `~/.claude-code-router/presets/`，然后运行 `ccr preset install 预设名`
|
||||
- **Web UI 方式**：将目录上传到 GitHub，然后通过仓库 URL 安装
|
||||
:::
|
||||
|
||||
## 预设文件位置
|
||||
|
||||
预设保存在：
|
||||
|
||||
```
|
||||
~/.claude-code-router/presets/
|
||||
```
|
||||
|
||||
每个预设都是一个目录，包含 `manifest.json` 文件。
|
||||
|
||||
## 最佳实践
|
||||
|
||||
1. **使用动态配置**：为需要用户输入的配置项使用schema系统
|
||||
2. **提供默认值**：为非必填项提供合理的默认值
|
||||
3. **条件显示**：使用when条件避免不必要的输入
|
||||
4. **清晰的标签**：为每个字段提供清晰的label和prompt
|
||||
5. **验证输入**：使用validator确保输入的有效性
|
||||
6. **版本控制**：将常用预设保存在版本控制中
|
||||
7. **文档化**：为自定义预设添加描述和版本信息
|
||||
|
||||
## 下一步
|
||||
|
||||
- [CLI 参考](/zh/docs/cli/start) - 完整的 CLI 命令参考
|
||||
- [配置](/zh/docs/config/basic) - 详细配置指南
|
||||
@@ -0,0 +1,220 @@
|
||||
# 配置 API
|
||||
|
||||
## GET /api/config
|
||||
|
||||
获取当前服务器配置。
|
||||
|
||||
### 请求示例
|
||||
|
||||
```bash
|
||||
curl http://localhost:3456/api/config \
|
||||
-H "x-api-key: your-api-key"
|
||||
```
|
||||
|
||||
### 响应示例
|
||||
|
||||
```json
|
||||
{
|
||||
"HOST": "0.0.0.0",
|
||||
"PORT": 3456,
|
||||
"APIKEY": "sk-xxxxx",
|
||||
"Providers": [
|
||||
{
|
||||
"name": "openai",
|
||||
"baseUrl": "https://api.openai.com/v1",
|
||||
"apiKey": "sk-...",
|
||||
"models": ["gpt-4", "gpt-3.5-turbo"]
|
||||
}
|
||||
],
|
||||
"Router": {
|
||||
"default": "openai,gpt-4"
|
||||
},
|
||||
"transformers": [
|
||||
"anthropic"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## POST /api/config
|
||||
|
||||
更新服务器配置。更新后会自动备份旧配置。
|
||||
|
||||
### 请求示例
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:3456/api/config \
|
||||
-H "x-api-key: your-api-key" \
|
||||
-H "content-type: application/json" \
|
||||
-d '{
|
||||
"HOST": "0.0.0.0",
|
||||
"PORT": 3456,
|
||||
"Providers": [
|
||||
{
|
||||
"name": "openai",
|
||||
"baseUrl": "https://api.openai.com/v1",
|
||||
"apiKey": "$OPENAI_API_KEY",
|
||||
"models": ["gpt-4"]
|
||||
}
|
||||
],
|
||||
"Router": {
|
||||
"default": "openai,gpt-4"
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
### 配置对象结构
|
||||
|
||||
#### 基础配置
|
||||
|
||||
| 字段 | 类型 | 必需 | 说明 |
|
||||
|------|------|------|------|
|
||||
| `HOST` | string | 否 | 监听地址（默认 127.0.0.1） |
|
||||
| `PORT` | integer | 否 | 监听端口（默认 3456） |
|
||||
| `APIKEY` | string | 否 | API 密钥 |
|
||||
| `LOG` | boolean | 否 | 是否启用日志（默认 true） |
|
||||
| `LOG_LEVEL` | string | 否 | 日志级别（debug/info/warn/error） |
|
||||
|
||||
#### Providers 配置
|
||||
|
||||
```json
|
||||
{
|
||||
"Providers": [
|
||||
{
|
||||
"name": "provider-name",
|
||||
"baseUrl": "https://api.example.com/v1",
|
||||
"apiKey": "your-api-key",
|
||||
"models": ["model-1", "model-2"]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 类型 | 必需 | 说明 |
|
||||
|------|------|------|------|
|
||||
| `name` | string | 是 | 提供商名称 |
|
||||
| `baseUrl` | string | 是 | API 基础 URL |
|
||||
| `apiKey` | string | 是 | API 密钥 |
|
||||
| `models` | array | 是 | 支持的模型列表 |
|
||||
|
||||
#### Router 配置
|
||||
|
||||
```json
|
||||
{
|
||||
"Router": {
|
||||
"default": "provider,model",
|
||||
"longContextThreshold": 100000,
|
||||
"routes": {
|
||||
"background": "lightweight-model",
|
||||
"think": "powerful-model",
|
||||
"longContext": "long-context-model",
|
||||
"webSearch": "search-model",
|
||||
"image": "vision-model"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Transformers 配置
|
||||
|
||||
```json
|
||||
{
|
||||
"transformers": [
|
||||
{
|
||||
"name": "anthropic",
|
||||
"provider": "provider-name",
|
||||
"models": ["model-1"],
|
||||
"options": {}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 响应示例
|
||||
|
||||
成功：
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "Config saved successfully"
|
||||
}
|
||||
```
|
||||
|
||||
### 配置备份
|
||||
|
||||
每次更新配置时，旧配置会自动备份到：
|
||||
|
||||
```
|
||||
~/.claude-code-router/config.backup.{timestamp}.json
|
||||
```
|
||||
|
||||
保留最近 3 个备份。
|
||||
|
||||
## GET /api/transformers
|
||||
|
||||
获取服务器加载的所有转换器列表。
|
||||
|
||||
### 请求示例
|
||||
|
||||
```bash
|
||||
curl http://localhost:3456/api/transformers \
|
||||
-H "x-api-key: your-api-key"
|
||||
```
|
||||
|
||||
### 响应示例
|
||||
|
||||
```json
|
||||
{
|
||||
"transformers": [
|
||||
{
|
||||
"name": "anthropic",
|
||||
"endpoint": null
|
||||
},
|
||||
{
|
||||
"name": "openai",
|
||||
"endpoint": null
|
||||
},
|
||||
{
|
||||
"name": "gemini",
|
||||
"endpoint": "https://generativelanguage.googleapis.com"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 转换器列表
|
||||
|
||||
内置转换器：
|
||||
|
||||
- `anthropic` - Anthropic Claude 格式
|
||||
- `openai` - OpenAI 格式
|
||||
- `deepseek` - DeepSeek 格式
|
||||
- `gemini` - Google Gemini 格式
|
||||
- `openrouter` - OpenRouter 格式
|
||||
- `groq` - Groq 格式
|
||||
- `maxtoken` - 调整 max_tokens 参数
|
||||
- `tooluse` - 工具使用转换
|
||||
- `reasoning` - 推理模式转换
|
||||
- `enhancetool` - 增强工具功能
|
||||
|
||||
## 环境变量插值
|
||||
|
||||
配置支持环境变量插值：
|
||||
|
||||
```json
|
||||
{
|
||||
"Providers": [
|
||||
{
|
||||
"apiKey": "$OPENAI_API_KEY"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
或使用 `${VAR_NAME}` 格式：
|
||||
|
||||
```json
|
||||
{
|
||||
"baseUrl": "${API_BASE_URL}"
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,166 @@
|
||||
# 日志 API
|
||||
|
||||
## GET /api/logs/files
|
||||
|
||||
获取所有可用的日志文件列表。
|
||||
|
||||
### 请求示例
|
||||
|
||||
```bash
|
||||
curl http://localhost:3456/api/logs/files \
|
||||
-H "x-api-key: your-api-key"
|
||||
```
|
||||
|
||||
### 响应示例
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"name": "ccr-20241226143022.log",
|
||||
"path": "/home/user/.claude-code-router/logs/ccr-20241226143022.log",
|
||||
"size": 1024000,
|
||||
"lastModified": "2024-12-26T14:30:22.000Z"
|
||||
},
|
||||
{
|
||||
"name": "ccr-20241226143021.log",
|
||||
"path": "/home/user/.claude-code-router/logs/ccr-20241226143021.log",
|
||||
"size": 980000,
|
||||
"lastModified": "2024-12-26T14:30:21.000Z"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
### 字段说明
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `name` | string | 文件名 |
|
||||
| `path` | string | 完整文件路径 |
|
||||
| `size` | integer | 文件大小（字节） |
|
||||
| `lastModified` | string | 最后修改时间（ISO 8601） |
|
||||
|
||||
文件按修改时间倒序排列。
|
||||
|
||||
## GET /api/logs
|
||||
|
||||
获取指定日志文件的内容。
|
||||
|
||||
### 查询参数
|
||||
|
||||
| 参数 | 类型 | 必需 | 说明 |
|
||||
|------|------|------|------|
|
||||
| `file` | string | 否 | 日志文件路径（默认使用 app.log） |
|
||||
|
||||
### 请求示例（获取默认日志）
|
||||
|
||||
```bash
|
||||
curl "http://localhost:3456/api/logs" \
|
||||
-H "x-api-key: your-api-key"
|
||||
```
|
||||
|
||||
### 请求示例（获取指定文件）
|
||||
|
||||
```bash
|
||||
curl "http://localhost:3456/api/logs?file=/home/user/.claude-code-router/logs/ccr-20241226143022.log" \
|
||||
-H "x-api-key: your-api-key"
|
||||
```
|
||||
|
||||
### 响应示例
|
||||
|
||||
```json
|
||||
[
|
||||
"{\"level\":30,\"time\":1703550622000,\"pid\":12345,\"hostname\":\"server\",\"msg\":\"Incoming request\",\"req\":{\"id\":1,\"method\":\"POST\",\"url\":\"/v1/messages\",\"remoteAddress\":\"127.0.0.1\"}}",
|
||||
"{\"level\":30,\"time\":1703550622500,\"pid\":12345,\"hostname\":\"server\",\"msg\":\"Request completed\",\"res\":{\"statusCode\":200,\"responseTime\":500}}",
|
||||
"..."
|
||||
]
|
||||
```
|
||||
|
||||
返回的是日志行数组，每行是一个 JSON 字符串。
|
||||
|
||||
### 日志格式
|
||||
|
||||
日志使用 Pino 格式：
|
||||
|
||||
```json
|
||||
{
|
||||
"level": 30,
|
||||
"time": 1703550622000,
|
||||
"pid": 12345,
|
||||
"hostname": "server",
|
||||
"msg": "Incoming request",
|
||||
"req": {
|
||||
"id": 1,
|
||||
"method": "POST",
|
||||
"url": "/v1/messages",
|
||||
"remoteAddress": "127.0.0.1"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 日志级别
|
||||
|
||||
| 级别 | 值 | 说明 |
|
||||
|------|------|------|
|
||||
| `trace` | 10 | 最详细的日志 |
|
||||
| `debug` | 20 | 调试信息 |
|
||||
| `info` | 30 | 一般信息 |
|
||||
| `warn` | 40 | 警告信息 |
|
||||
| `error` | 50 | 错误信息 |
|
||||
| `fatal` | 60 | 致命错误 |
|
||||
|
||||
## DELETE /api/logs
|
||||
|
||||
清除指定日志文件的内容。
|
||||
|
||||
### 查询参数
|
||||
|
||||
| 参数 | 类型 | 必需 | 说明 |
|
||||
|------|------|------|------|
|
||||
| `file` | string | 否 | 日志文件路径（默认使用 app.log） |
|
||||
|
||||
### 请求示例（清除默认日志）
|
||||
|
||||
```bash
|
||||
curl -X DELETE "http://localhost:3456/api/logs" \
|
||||
-H "x-api-key: your-api-key"
|
||||
```
|
||||
|
||||
### 请求示例（清除指定文件）
|
||||
|
||||
```bash
|
||||
curl -X DELETE "http://localhost:3456/api/logs?file=/home/user/.claude-code-router/logs/ccr-20241226143022.log" \
|
||||
-H "x-api-key: your-api-key"
|
||||
```
|
||||
|
||||
### 响应示例
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "Logs cleared successfully"
|
||||
}
|
||||
```
|
||||
|
||||
## 日志位置
|
||||
|
||||
### 服务器日志
|
||||
|
||||
位置：`~/.claude-code-router/logs/`
|
||||
|
||||
文件命名：`ccr-{YYYYMMDD}{HH}{MM}{SS}.log`
|
||||
|
||||
内容：HTTP 请求、API 调用、服务器事件
|
||||
|
||||
### 应用日志
|
||||
|
||||
位置：`~/.claude-code-router/claude-code-router.log`
|
||||
|
||||
内容：路由决策、业务逻辑事件
|
||||
|
||||
## 日志轮转
|
||||
|
||||
服务器日志使用 rotating-file-stream 自动轮转：
|
||||
|
||||
- **maxFiles**: 3 - 保留最近 3 个日志文件
|
||||
- **interval**: 1d - 每天轮转
|
||||
- **maxSize**: 50M - 单个文件最大 50MB
|
||||
@@ -0,0 +1,220 @@
|
||||
# 消息 API
|
||||
|
||||
## POST /v1/messages
|
||||
|
||||
发送消息到 LLM，兼容 Anthropic Claude API 格式。
|
||||
|
||||
### 请求格式
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:3456/v1/messages \
|
||||
-H "x-api-key: your-api-key" \
|
||||
-H "content-type: application/json" \
|
||||
-d '{
|
||||
"model": "claude-3-5-sonnet-20241022",
|
||||
"max_tokens": 1024,
|
||||
"messages": [
|
||||
{
|
||||
"role": "user",
|
||||
"content": "Hello, Claude!"
|
||||
}
|
||||
]
|
||||
}'
|
||||
```
|
||||
|
||||
### 请求参数
|
||||
|
||||
| 参数 | 类型 | 必需 | 说明 |
|
||||
|------|------|------|------|
|
||||
| `model` | string | 是 | 模型名称（会被路由到实际提供商） |
|
||||
| `messages` | array | 是 | 消息数组 |
|
||||
| `max_tokens` | integer | 是 | 最大生成 Token 数 |
|
||||
| `system` | string | 否 | 系统提示词 |
|
||||
| `tools` | array | 否 | 可用工具列表 |
|
||||
| `stream` | boolean | 否 | 是否使用流式响应（默认 false） |
|
||||
| `temperature` | number | 否 | 温度参数（0-1） |
|
||||
|
||||
### 消息对象格式
|
||||
|
||||
```json
|
||||
{
|
||||
"role": "user|assistant",
|
||||
"content": "string | array"
|
||||
}
|
||||
```
|
||||
|
||||
### 响应格式（非流式）
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "msg_xxx",
|
||||
"type": "message",
|
||||
"role": "assistant",
|
||||
"content": [
|
||||
{
|
||||
"type": "text",
|
||||
"text": "Hello! How can I help you today?"
|
||||
}
|
||||
],
|
||||
"model": "claude-3-5-sonnet-20241022",
|
||||
"stop_reason": "end_turn",
|
||||
"usage": {
|
||||
"input_tokens": 10,
|
||||
"output_tokens": 20
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 流式响应
|
||||
|
||||
设置 `stream: true` 启用流式响应：
|
||||
|
||||
```json
|
||||
{
|
||||
"model": "claude-3-5-sonnet-20241022",
|
||||
"max_tokens": 1024,
|
||||
"messages": [...],
|
||||
"stream": true
|
||||
}
|
||||
```
|
||||
|
||||
流式响应事件类型：
|
||||
|
||||
- `message_start` - 消息开始
|
||||
- `content_block_start` - 内容块开始
|
||||
- `content_block_delta` - 内容增量
|
||||
- `content_block_stop` - 内容块结束
|
||||
- `message_delta` - 消息元数据（usage）
|
||||
- `message_stop` - 消息结束
|
||||
|
||||
### 工具使用
|
||||
|
||||
支持函数调用（Tool Use）：
|
||||
|
||||
```json
|
||||
{
|
||||
"model": "claude-3-5-sonnet-20241022",
|
||||
"max_tokens": 1024,
|
||||
"messages": [
|
||||
{
|
||||
"role": "user",
|
||||
"content": "What's the weather like?"
|
||||
}
|
||||
],
|
||||
"tools": [
|
||||
{
|
||||
"name": "get_weather",
|
||||
"description": "Get the current weather",
|
||||
"input_schema": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"location": {
|
||||
"type": "string",
|
||||
"description": "City name"
|
||||
}
|
||||
},
|
||||
"required": ["location"]
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 多模态支持
|
||||
|
||||
支持图片输入：
|
||||
|
||||
```json
|
||||
{
|
||||
"role": "user",
|
||||
"content": [
|
||||
{
|
||||
"type": "image",
|
||||
"source": {
|
||||
"type": "base64",
|
||||
"media_type": "image/png",
|
||||
"data": "iVBORw0KGgo..."
|
||||
}
|
||||
},
|
||||
{
|
||||
"type": "text",
|
||||
"text": "Describe this image"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## POST /v1/messages/count_tokens
|
||||
|
||||
计算消息的 Token 数量。
|
||||
|
||||
### 请求格式
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:3456/v1/messages/count_tokens \
|
||||
-H "x-api-key: your-api-key" \
|
||||
-H "content-type: application/json" \
|
||||
-d '{
|
||||
"model": "claude-3-5-sonnet-20241022",
|
||||
"messages": [
|
||||
{
|
||||
"role": "user",
|
||||
"content": "Hello!"
|
||||
}
|
||||
],
|
||||
"tools": [],
|
||||
"system": "You are a helpful assistant."
|
||||
}'
|
||||
```
|
||||
|
||||
### 请求参数
|
||||
|
||||
| 参数 | 类型 | 必需 | 说明 |
|
||||
|------|------|------|------|
|
||||
| `model` | string | 是 | 模型名称 |
|
||||
| `messages` | array | 是 | 消息数组 |
|
||||
| `tools` | array | 否 | 工具列表 |
|
||||
| `system` | string | 否 | 系统提示词 |
|
||||
|
||||
### 响应格式
|
||||
|
||||
```json
|
||||
{
|
||||
"input_tokens": 42
|
||||
}
|
||||
```
|
||||
|
||||
## 错误响应
|
||||
|
||||
### 400 Bad Request
|
||||
|
||||
```json
|
||||
{
|
||||
"error": {
|
||||
"type": "invalid_request_error",
|
||||
"message": "messages is required"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 401 Unauthorized
|
||||
|
||||
```json
|
||||
{
|
||||
"error": {
|
||||
"type": "authentication_error",
|
||||
"message": "Invalid API key"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 500 Internal Server Error
|
||||
|
||||
```json
|
||||
{
|
||||
"error": {
|
||||
"type": "api_error",
|
||||
"message": "Failed to connect to provider"
|
||||
}
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,88 @@
|
||||
# API 概览
|
||||
|
||||
Claude Code Router Server 提供了完整的 HTTP API，支持：
|
||||
|
||||
- **消息 API**：兼容 Anthropic Claude API 的消息接口
|
||||
- **配置 API**：读取和更新服务器配置
|
||||
- **日志 API**：查看和管理服务日志
|
||||
- **工具 API**：计算 Token 数量
|
||||
|
||||
## 基础信息
|
||||
|
||||
**Base URL**: `http://localhost:3456`
|
||||
|
||||
**认证方式**: API Key（通过 `x-api-key` 请求头）
|
||||
|
||||
```bash
|
||||
curl -H "x-api-key: your-api-key" http://localhost:3456/api/config
|
||||
```
|
||||
|
||||
## API 端点列表
|
||||
|
||||
### 消息相关
|
||||
|
||||
| 端点 | 方法 | 描述 |
|
||||
|------|------|------|
|
||||
| `/v1/messages` | POST | 发送消息（兼容 Anthropic API） |
|
||||
| `/v1/messages/count_tokens` | POST | 计算消息的 Token 数量 |
|
||||
|
||||
### 配置管理
|
||||
|
||||
| 端点 | 方法 | 描述 |
|
||||
|------|------|------|
|
||||
| `/api/config` | GET | 获取当前配置 |
|
||||
| `/api/config` | POST | 更新配置 |
|
||||
| `/api/transformers` | GET | 获取可用的转换器列表 |
|
||||
|
||||
### 日志管理
|
||||
|
||||
| 端点 | 方法 | 描述 |
|
||||
|------|------|------|
|
||||
| `/api/logs/files` | GET | 获取日志文件列表 |
|
||||
| `/api/logs` | GET | 获取日志内容 |
|
||||
| `/api/logs` | DELETE | 清除日志 |
|
||||
|
||||
### 服务管理
|
||||
|
||||
| 端点 | 方法 | 描述 |
|
||||
|------|------|------|
|
||||
| `/api/restart` | POST | 重启服务 |
|
||||
| `/ui` | GET | Web 管理界面 |
|
||||
| `/ui/` | GET | Web 管理界面（重定向） |
|
||||
|
||||
## 认证
|
||||
|
||||
### API Key 认证
|
||||
|
||||
在请求头中添加 API Key：
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:3456/v1/messages \
|
||||
-H "x-api-key: your-api-key" \
|
||||
-H "content-type: application/json" \
|
||||
-d '...'
|
||||
```
|
||||
|
||||
## 流式响应
|
||||
|
||||
消息 API 支持流式响应（Server-Sent Events）：
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:3456/v1/messages \
|
||||
-H "x-api-key: your-api-key" \
|
||||
-H "content-type: application/json" \
|
||||
-d '{"stream": true, ...}'
|
||||
```
|
||||
|
||||
流式响应格式：
|
||||
|
||||
```
|
||||
event: message_start
|
||||
data: {"type":"message_start","message":{...}}
|
||||
|
||||
event: content_block_delta
|
||||
data: {"type":"content_block_delta","delta":{"type":"text_delta","text":"Hello"}}
|
||||
|
||||
event: message_stop
|
||||
data: {"type":"message_stop"}
|
||||
```
|
||||
@@ -0,0 +1,160 @@
|
||||
---
|
||||
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) - 应用转换
|
||||
@@ -0,0 +1,212 @@
|
||||
---
|
||||
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) - 对请求应用转换
|
||||
@@ -0,0 +1,164 @@
|
||||
---
|
||||
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) - 高级自定义路由
|
||||
@@ -0,0 +1,282 @@
|
||||
---
|
||||
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 扩展功能
|
||||
@@ -0,0 +1,182 @@
|
||||
# Server 部署
|
||||
|
||||
Claude Code Router Server 支持多种部署方式，从本地开发到生产环境。
|
||||
|
||||
## Docker 部署（推荐）
|
||||
|
||||
### 使用 Docker Hub 镜像
|
||||
|
||||
```bash
|
||||
docker run -d \
|
||||
--name claude-code-router \
|
||||
-p 3456:3456 \
|
||||
-v ~/.claude-code-router:/app/.claude-code-router \
|
||||
musistudio/claude-code-router:latest
|
||||
```
|
||||
|
||||
### 使用 Docker Compose
|
||||
|
||||
创建 `docker-compose.yml`：
|
||||
|
||||
```yaml
|
||||
version: '3.8'
|
||||
services:
|
||||
claude-code-router:
|
||||
image: musistudio/claude-code-router:latest
|
||||
container_name: claude-code-router
|
||||
ports:
|
||||
- "3456:3456"
|
||||
volumes:
|
||||
- ./config:/app/.claude-code-router
|
||||
environment:
|
||||
- LOG_LEVEL=info
|
||||
- HOST=0.0.0.0
|
||||
- PORT=3456
|
||||
restart: unless-stopped
|
||||
```
|
||||
|
||||
启动服务：
|
||||
|
||||
```bash
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
### 自定义构建
|
||||
|
||||
从源码构建 Docker 镜像：
|
||||
|
||||
```bash
|
||||
git clone https://github.com/musistudio/claude-code-router.git
|
||||
cd claude-code-router
|
||||
docker build -t claude-code-router:latest .
|
||||
```
|
||||
|
||||
## 配置文件挂载
|
||||
|
||||
将配置文件挂载到容器中：
|
||||
|
||||
```bash
|
||||
docker run -d \
|
||||
--name claude-code-router \
|
||||
-p 3456:3456 \
|
||||
-v $(pwd)/config.json:/app/.claude-code-router/config.json \
|
||||
musistudio/claude-code-router:latest
|
||||
```
|
||||
|
||||
配置文件示例：
|
||||
|
||||
```json5
|
||||
{
|
||||
// 服务器配置
|
||||
"HOST": "0.0.0.0",
|
||||
"PORT": 3456,
|
||||
"APIKEY": "your-api-key-here",
|
||||
|
||||
// 日志配置
|
||||
"LOG": true,
|
||||
"LOG_LEVEL": "info",
|
||||
|
||||
// LLM 提供商配置
|
||||
"Providers": [
|
||||
{
|
||||
"name": "openai",
|
||||
"baseUrl": "https://api.openai.com/v1",
|
||||
"apiKey": "$OPENAI_API_KEY",
|
||||
"models": ["gpt-4", "gpt-3.5-turbo"]
|
||||
}
|
||||
],
|
||||
|
||||
// 路由配置
|
||||
"Router": {
|
||||
"default": "openai,gpt-4"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 环境变量
|
||||
|
||||
支持通过环境变量覆盖配置：
|
||||
|
||||
| 变量名 | 说明 | 默认值 |
|
||||
|--------|------|--------|
|
||||
| `HOST` | 监听地址 | `127.0.0.1` |
|
||||
| `PORT` | 监听端口 | `3456` |
|
||||
| `APIKEY` | API 密钥 | - |
|
||||
| `LOG_LEVEL` | 日志级别 | `debug` |
|
||||
| `LOG` | 是否启用日志 | `true` |
|
||||
|
||||
## 生产环境建议
|
||||
|
||||
### 1. 使用反向代理
|
||||
|
||||
使用 Nginx 作为反向代理：
|
||||
|
||||
```nginx
|
||||
server {
|
||||
listen 80;
|
||||
server_name your-domain.com;
|
||||
|
||||
location / {
|
||||
proxy_pass http://localhost:3456;
|
||||
proxy_http_version 1.1;
|
||||
proxy_set_header Upgrade $http_upgrade;
|
||||
proxy_set_header Connection 'upgrade';
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_cache_bypass $http_upgrade;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. 配置 HTTPS
|
||||
|
||||
使用 Let's Encrypt 获取免费证书：
|
||||
|
||||
```bash
|
||||
sudo certbot --nginx -d your-domain.com
|
||||
```
|
||||
|
||||
### 3. 日志管理
|
||||
|
||||
配置日志轮转和持久化：
|
||||
|
||||
```yaml
|
||||
version: '3.8'
|
||||
services:
|
||||
claude-code-router:
|
||||
image: musistudio/claude-code-router:latest
|
||||
volumes:
|
||||
- ./logs:/app/.claude-code-router/logs
|
||||
environment:
|
||||
- LOG_LEVEL=warn
|
||||
```
|
||||
|
||||
### 4. 健康检查
|
||||
|
||||
配置 Docker 健康检查：
|
||||
|
||||
```yaml
|
||||
healthcheck:
|
||||
test: ["CMD", "curl", "-f", "http://localhost:3456/api/config"]
|
||||
interval: 30s
|
||||
timeout: 10s
|
||||
retries: 3
|
||||
```
|
||||
|
||||
## 访问 Web UI
|
||||
|
||||
部署完成后，访问 Web UI：
|
||||
|
||||
```
|
||||
http://localhost:3456/ui/
|
||||
```
|
||||
|
||||
通过 Web UI 可以：
|
||||
- 查看和管理配置
|
||||
- 监控日志
|
||||
- 查看服务状态
|
||||
|
||||
## 二次开发
|
||||
|
||||
如果需要基于 CCR Server 进行二次开发，请查看 [API 参考](/docs/category/api)。
|
||||
@@ -0,0 +1,77 @@
|
||||
# Server 简介
|
||||
|
||||
Claude Code Router Server 是一个核心服务组件，负责将 Claude Code 的 API 请求路由到不同的 LLM 提供商。它提供了完整的 HTTP API，支持：
|
||||
|
||||
- **API 请求路由**：将 Anthropic 格式的请求转换为各种提供商的 API 格式
|
||||
- **认证与授权**：支持 API Key 认证
|
||||
- **配置管理**：动态配置提供商、路由规则和转换器
|
||||
- **Web UI**：内置管理界面
|
||||
- **日志系统**：完整的请求日志记录
|
||||
|
||||
## 架构概述
|
||||
|
||||
```
|
||||
┌─────────────┐ ┌──────────────────┐ ┌──────────────┐
|
||||
│ Claude Code │────▶│ CCR Server │────▶│ LLM Provider │
|
||||
│ Client │ │ (Router + │ │ (OpenAI/ │
|
||||
└─────────────┘ │ Transformer) │ │ Gemini/etc)│
|
||||
└──────────────────┘ └──────────────┘
|
||||
│
|
||||
├─ Web UI
|
||||
├─ Config API
|
||||
└─ Logs API
|
||||
```
|
||||
|
||||
## 核心功能
|
||||
|
||||
### 1. 请求路由
|
||||
- 基于 Token 数量的智能路由
|
||||
- 项目级路由配置
|
||||
- 自定义路由函数
|
||||
- 场景化路由（background、think、longContext 等）
|
||||
|
||||
### 2. 请求转换
|
||||
- 支持多种 LLM 提供商的 API 格式转换
|
||||
- 内置转换器：Anthropic、DeepSeek、Gemini、OpenRouter、Groq 等
|
||||
- 可扩展的转换器系统
|
||||
|
||||
### 3. Agent 系统
|
||||
- 插件式的 Agent 架构
|
||||
- 内置图片处理 Agent
|
||||
- 自定义 Agent 支持
|
||||
|
||||
### 4. 配置管理
|
||||
- JSON5 格式配置文件
|
||||
- 环境变量插值
|
||||
- 配置热更新（需重启服务）
|
||||
|
||||
## 使用场景
|
||||
|
||||
### 场景一：个人本地服务
|
||||
在本地运行服务，供个人 Claude Code 使用：
|
||||
|
||||
```bash
|
||||
ccr start
|
||||
```
|
||||
|
||||
### 场景二：团队共享服务
|
||||
使用 Docker 部署，为团队成员提供共享服务：
|
||||
|
||||
```bash
|
||||
docker run -d -p 3456:3456 musistudio/claude-code-router
|
||||
```
|
||||
|
||||
### 场景三：二次开发
|
||||
基于暴露的 API 构建自定义应用：
|
||||
|
||||
```bash
|
||||
GET /api/config
|
||||
POST /v1/messages
|
||||
GET /api/logs
|
||||
```
|
||||
|
||||
## 下一步
|
||||
|
||||
- [Docker 部署指南](/docs/server/deployment) - 学习如何部署服务
|
||||
- [API 参考](/docs/category/api) - 查看完整的 API 文档
|
||||
- [配置说明](/docs/category/server-config) - 了解服务器配置选项
|
||||
Reference in New Issue
Block a user