mirror of
https://github.com/musistudio/claude-code-router.git
synced 2026-02-03 07:10:51 +08:00
change doc
This commit is contained in:
musistudio
@@ -12,6 +12,216 @@ sidebar_position: 3
|
||||
|
||||
预设是预配置的设置，包括针对特定用例优化的提供商配置、路由规则和转换器。
|
||||
|
||||
## 动态配置系统 (v2.0+)
|
||||
|
||||
CCR 2.0 引入了强大的动态配置系统，支持：
|
||||
|
||||
- **多种输入类型**：选择器、多选、确认框、文本输入、数字输入等
|
||||
- **条件逻辑**：根据用户输入动态显示/隐藏配置项
|
||||
- **变量引用**：配置项之间可以互相引用
|
||||
- **动态选项**：选项列表可以从预设配置或用户输入中动态生成
|
||||
|
||||
### 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
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## 可用预设
|
||||
|
||||
### Development（开发）
|
||||
@@ -66,7 +276,42 @@ ccr preset list
|
||||
|
||||
## 创建自定义预设
|
||||
|
||||
您可以通过保存配置并稍后重新加载来创建自定义预设：
|
||||
创建包含 `schema` 和 `template` 的预设文件：
|
||||
|
||||
```bash
|
||||
# 创建预设目录
|
||||
mkdir -p ~/.claude-code-router/presets/my-preset
|
||||
|
||||
# 创建 manifest.json
|
||||
cat > ~/.claude-code-router/presets/my-preset/manifest.json << 'EOF'
|
||||
{
|
||||
"name": "my-preset",
|
||||
"version": "1.0.0",
|
||||
"description": "我的自定义预设",
|
||||
"schema": [
|
||||
{
|
||||
"id": "apiKey",
|
||||
"type": "password",
|
||||
"label": "API Key",
|
||||
"required": true
|
||||
}
|
||||
],
|
||||
"template": {
|
||||
"Providers": [
|
||||
{
|
||||
"name": "my-provider",
|
||||
"api_key": "{{apiKey}}"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
EOF
|
||||
|
||||
# 应用预设（会提示输入API Key）
|
||||
ccr my-preset
|
||||
```
|
||||
|
||||
您也可以通过保存配置并稍后重新加载来创建自定义预设：
|
||||
|
||||
```bash
|
||||
# 将当前配置保存为预设
|
||||
@@ -116,35 +361,7 @@ ccr preset delete <预设名称>
|
||||
~/.claude-code-router/presets/
|
||||
```
|
||||
|
||||
每个预设都是一个 JSON 文件，包含完整的配置。
|
||||
|
||||
## 预设文件示例
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "development",
|
||||
"description": "针对软件开发优化的配置",
|
||||
"Providers": [
|
||||
{
|
||||
"name": "deepseek",
|
||||
"api_base_url": "https://api.deepseek.com/chat/completions",
|
||||
"api_key": "$DEEPSEEK_API_KEY",
|
||||
"models": ["deepseek-chat", "deepseek-coder"]
|
||||
},
|
||||
{
|
||||
"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",
|
||||
"background": "groq,llama-3.3-70b-versatile",
|
||||
"think": "deepseek,deepseek-chat"
|
||||
}
|
||||
}
|
||||
```
|
||||
每个预设都是一个目录，包含 `manifest.json` 文件。
|
||||
|
||||
## 导出和导入预设
|
||||
|
||||
@@ -163,10 +380,13 @@ ccr config edit
|
||||
|
||||
## 最佳实践
|
||||
|
||||
1. **为不同项目创建预设**：为不同的工作流程创建专门的预设
|
||||
2. **版本控制**：将常用预设保存在版本控制中
|
||||
3. **文档化**：为自定义预设添加描述
|
||||
4. **测试**：在应用预设后验证配置
|
||||
1. **使用动态配置**：为需要用户输入的配置项使用schema系统
|
||||
2. **提供默认值**：为非必填项提供合理的默认值
|
||||
3. **条件显示**：使用when条件避免不必要的输入
|
||||
4. **清晰的标签**：为每个字段提供清晰的label和prompt
|
||||
5. **验证输入**：使用validator确保输入的有效性
|
||||
6. **版本控制**：将常用预设保存在版本控制中
|
||||
7. **文档化**：为自定义预设添加描述和版本信息
|
||||
|
||||
## 下一步
|
||||
|
||||
|
||||
@@ -0,0 +1,208 @@
|
||||
# CLI 基础配置
|
||||
|
||||
CLI 使用与 Server 相同的配置文件：`~/.claude-code-router/config.json`
|
||||
|
||||
## 配置文件位置
|
||||
|
||||
```bash
|
||||
~/.claude-code-router/config.json
|
||||
```
|
||||
|
||||
## 快速配置
|
||||
|
||||
使用交互式命令配置：
|
||||
|
||||
```bash
|
||||
ccr model
|
||||
```
|
||||
|
||||
这将引导你完成：
|
||||
1. 选择 LLM 提供商
|
||||
2. 配置 API Key
|
||||
3. 选择模型
|
||||
4. 设置路由规则
|
||||
|
||||
## 手动配置
|
||||
|
||||
### 编辑配置文件
|
||||
|
||||
```bash
|
||||
# 打开配置文件
|
||||
nano ~/.claude-code-router/config.json
|
||||
```
|
||||
|
||||
### 最小配置示例
|
||||
|
||||
```json5
|
||||
{
|
||||
// API 密钥（可选，用于保护服务）
|
||||
"APIKEY": "your-api-key-here",
|
||||
|
||||
// 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"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 环境变量
|
||||
|
||||
配置支持环境变量插值：
|
||||
|
||||
```json5
|
||||
{
|
||||
"Providers": [
|
||||
{
|
||||
"apiKey": "$OPENAI_API_KEY" // 从环境变量读取
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
在 `.bashrc` 或 `.zshrc` 中设置：
|
||||
|
||||
```bash
|
||||
export OPENAI_API_KEY="sk-..."
|
||||
export ANTHROPIC_API_KEY="sk-ant-..."
|
||||
```
|
||||
|
||||
## 常用配置项
|
||||
|
||||
### HOST 和 PORT
|
||||
|
||||
```json5
|
||||
{
|
||||
"HOST": "127.0.0.1", // 监听地址
|
||||
"PORT": 3456 // 监听端口
|
||||
}
|
||||
```
|
||||
|
||||
### 日志配置
|
||||
|
||||
```json5
|
||||
{
|
||||
"LOG": true, // 启用日志
|
||||
"LOG_LEVEL": "info" // 日志级别
|
||||
}
|
||||
```
|
||||
|
||||
### 路由配置
|
||||
|
||||
```json5
|
||||
{
|
||||
"Router": {
|
||||
"default": "openai,gpt-4",
|
||||
"background": "openai,gpt-3.5-turbo",
|
||||
"think": "openai,gpt-4",
|
||||
"longContext": "anthropic,claude-3-opus"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 配置验证
|
||||
|
||||
配置文件会自动验证。常见错误：
|
||||
|
||||
- **缺少 Providers**：必须至少配置一个提供商
|
||||
- **API Key 缺失**：如果配置了 Providers，必须提供 API Key
|
||||
- **模型不存在**：确保模型在提供商的 models 列表中
|
||||
|
||||
## 配置备份
|
||||
|
||||
每次更新配置时会自动备份：
|
||||
|
||||
```
|
||||
~/.claude-code-router/config.backup.{timestamp}.json
|
||||
```
|
||||
|
||||
## 重新加载配置
|
||||
|
||||
修改配置后需要重启服务：
|
||||
|
||||
```bash
|
||||
ccr restart
|
||||
```
|
||||
|
||||
## 查看当前配置
|
||||
|
||||
```bash
|
||||
# 通过 API 查看
|
||||
curl http://localhost:3456/api/config
|
||||
|
||||
# 或查看配置文件
|
||||
cat ~/.claude-code-router/config.json
|
||||
```
|
||||
|
||||
## 示例配置
|
||||
|
||||
### OpenAI
|
||||
|
||||
```json5
|
||||
{
|
||||
"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"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Anthropic
|
||||
|
||||
```json5
|
||||
{
|
||||
"Providers": [
|
||||
{
|
||||
"name": "anthropic",
|
||||
"baseUrl": "https://api.anthropic.com/v1",
|
||||
"apiKey": "$ANTHROPIC_API_KEY",
|
||||
"models": ["claude-3-5-sonnet-20241022", "claude-3-opus-20240229"]
|
||||
}
|
||||
],
|
||||
"Router": {
|
||||
"default": "anthropic,claude-3-5-sonnet-20241022"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 多提供商
|
||||
|
||||
```json5
|
||||
{
|
||||
"Providers": [
|
||||
{
|
||||
"name": "openai",
|
||||
"baseUrl": "https://api.openai.com/v1",
|
||||
"apiKey": "$OPENAI_API_KEY",
|
||||
"models": ["gpt-4", "gpt-3.5-turbo"]
|
||||
},
|
||||
{
|
||||
"name": "anthropic",
|
||||
"baseUrl": "https://api.anthropic.com/v1",
|
||||
"apiKey": "$ANTHROPIC_API_KEY",
|
||||
"models": ["claude-3-5-sonnet-20241022", "claude-3-opus-20240229"]
|
||||
}
|
||||
],
|
||||
"Router": {
|
||||
"default": "openai,gpt-4",
|
||||
"think": "anthropic,claude-3-5-sonnet-20241022",
|
||||
"background": "openai,gpt-3.5-turbo"
|
||||
}
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,213 @@
|
||||
# 项目级配置
|
||||
|
||||
除了全局配置，`ccr` 还支持为特定项目设置不同的路由规则。
|
||||
|
||||
## 项目配置文件
|
||||
|
||||
项目配置文件位于：
|
||||
|
||||
```
|
||||
~/.claude/projects/<project-id>/claude-code-router.json
|
||||
```
|
||||
|
||||
其中 `<project-id>` 是 Claude Code 项目的唯一标识符。
|
||||
|
||||
## 项目配置结构
|
||||
|
||||
```json5
|
||||
{
|
||||
"Router": {
|
||||
"default": "openai,gpt-4",
|
||||
"background": "openai,gpt-3.5-turbo"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 查找项目 ID
|
||||
|
||||
### 方法一：使用 CLI
|
||||
|
||||
```bash
|
||||
# 在项目目录中运行
|
||||
ccr status
|
||||
```
|
||||
|
||||
输出会显示当前项目 ID：
|
||||
|
||||
```
|
||||
Project: my-project (abc123def456)
|
||||
```
|
||||
|
||||
### 方法二：查看 Claude Code 配置
|
||||
|
||||
```bash
|
||||
cat ~/.claude.json
|
||||
```
|
||||
|
||||
找到你的项目 ID：
|
||||
|
||||
```json
|
||||
{
|
||||
"projects": {
|
||||
"abc123def456": {
|
||||
"path": "/path/to/your/project",
|
||||
"name": "my-project"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 创建项目配置
|
||||
|
||||
### 手动创建
|
||||
|
||||
```bash
|
||||
# 创建项目配置目录
|
||||
mkdir -p ~/.claude/projects/abc123def456
|
||||
|
||||
# 创建配置文件
|
||||
cat > ~/.claude/projects/abc123def456/claude-code-router.json << 'EOF'
|
||||
{
|
||||
"Router": {
|
||||
"default": "anthropic,claude-3-5-sonnet-20241022",
|
||||
"background": "openai,gpt-3.5-turbo"
|
||||
}
|
||||
}
|
||||
EOF
|
||||
```
|
||||
|
||||
### 使用 ccr model 命令
|
||||
|
||||
```bash
|
||||
# 在项目目录中运行
|
||||
cd /path/to/your/project
|
||||
ccr model --project
|
||||
```
|
||||
|
||||
## 配置优先级
|
||||
|
||||
路由配置的优先级（从高到低）：
|
||||
|
||||
1. **自定义路由函数** (`CUSTOM_ROUTER_PATH`)
|
||||
2. **项目级配置** (`~/.claude/projects/<id>/claude-code-router.json`)
|
||||
3. **全局配置** (`~/.claude-code-router/config.json`)
|
||||
4. **内置路由规则**
|
||||
|
||||
## 使用场景
|
||||
|
||||
### 场景一：不同项目使用不同模型
|
||||
|
||||
```json5
|
||||
// Web 项目使用 GPT-4
|
||||
~/.claude/projects/web-project-id/claude-code-router.json:
|
||||
{
|
||||
"Router": {
|
||||
"default": "openai,gpt-4"
|
||||
}
|
||||
}
|
||||
|
||||
// AI 项目使用 Claude
|
||||
~/.claude/projects/ai-project-id/claude-code-router.json:
|
||||
{
|
||||
"Router": {
|
||||
"default": "anthropic,claude-3-5-sonnet-20241022"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 场景二：测试项目使用低成本模型
|
||||
|
||||
```json5
|
||||
~/.claude/projects/test-project-id/claude-code-router.json:
|
||||
{
|
||||
"Router": {
|
||||
"default": "openai,gpt-3.5-turbo",
|
||||
"background": "openai,gpt-3.5-turbo"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 场景三：长上下文项目
|
||||
|
||||
```json5
|
||||
~/.claude/projects/long-context-project-id/claude-code-router.json:
|
||||
{
|
||||
"Router": {
|
||||
"default": "anthropic,claude-3-opus-20240229",
|
||||
"longContext": "anthropic,claude-3-opus-20240229"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 验证项目配置
|
||||
|
||||
```bash
|
||||
# 查看当前项目使用的路由
|
||||
ccr status
|
||||
|
||||
# 查看日志确认路由决策
|
||||
tail -f ~/.claude-code-router/claude-code-router.log
|
||||
```
|
||||
|
||||
## 删除项目配置
|
||||
|
||||
```bash
|
||||
rm ~/.claude/projects/<project-id>/claude-code-router.json
|
||||
```
|
||||
|
||||
删除后会回退到全局配置。
|
||||
|
||||
## 完整示例
|
||||
|
||||
假设你有两个项目：
|
||||
|
||||
### 全局配置（`~/.claude-code-router/config.json`）
|
||||
|
||||
```json5
|
||||
{
|
||||
"Providers": [
|
||||
{
|
||||
"name": "openai",
|
||||
"baseUrl": "https://api.openai.com/v1",
|
||||
"apiKey": "$OPENAI_API_KEY",
|
||||
"models": ["gpt-4", "gpt-3.5-turbo"]
|
||||
},
|
||||
{
|
||||
"name": "anthropic",
|
||||
"baseUrl": "https://api.anthropic.com/v1",
|
||||
"apiKey": "$ANTHROPIC_API_KEY",
|
||||
"models": ["claude-3-5-sonnet-20241022"]
|
||||
}
|
||||
],
|
||||
"Router": {
|
||||
"default": "openai,gpt-4",
|
||||
"background": "openai,gpt-3.5-turbo"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Web 项目配置
|
||||
|
||||
```json5
|
||||
{
|
||||
"Router": {
|
||||
"default": "openai,gpt-4"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### AI 项目配置
|
||||
|
||||
```json5
|
||||
{
|
||||
"Router": {
|
||||
"default": "anthropic,claude-3-5-sonnet-20241022",
|
||||
"think": "anthropic,claude-3-5-sonnet-20241022"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
这样：
|
||||
- Web 项目使用 GPT-4
|
||||
- AI 项目使用 Claude
|
||||
- 所有项目的后台任务使用 GPT-3.5-turbo（继承全局配置）
|
||||
83
docs/i18n/zh-CN/docusaurus-plugin-content-docs/cli/intro.md
Normal file
83
docs/i18n/zh-CN/docusaurus-plugin-content-docs/cli/intro.md
Normal file
@@ -0,0 +1,83 @@
|
||||
# CLI 简介
|
||||
|
||||
Claude Code Router CLI (`ccr`) 是一个命令行工具，用于管理和控制 Claude Code Router 服务。
|
||||
|
||||
## 功能概述
|
||||
|
||||
`ccr` 提供以下功能：
|
||||
|
||||
- **服务管理**：启动、停止、重启服务
|
||||
- **配置管理**：交互式配置模型选择
|
||||
- **状态查看**：查看服务运行状态
|
||||
- **代码执行**：直接执行 `claude` 命令
|
||||
- **环境集成**：输出环境变量用于 shell 集成
|
||||
- **Web UI**：打开 Web 管理界面
|
||||
- **状态栏**：集成到编辑器状态栏
|
||||
|
||||
## 安装
|
||||
|
||||
```bash
|
||||
npm install -g @musistudio/claude-code-router-cli
|
||||
```
|
||||
|
||||
或使用项目别名：
|
||||
|
||||
```bash
|
||||
npm install -g claude-code-router
|
||||
```
|
||||
|
||||
## 基本使用
|
||||
|
||||
### 启动服务
|
||||
|
||||
```bash
|
||||
ccr start
|
||||
```
|
||||
|
||||
### 查看状态
|
||||
|
||||
```bash
|
||||
ccr status
|
||||
```
|
||||
|
||||
### 停止服务
|
||||
|
||||
```bash
|
||||
ccr stop
|
||||
```
|
||||
|
||||
### 查看模型
|
||||
|
||||
```bash
|
||||
ccr model
|
||||
```
|
||||
|
||||
## 与 Claude Code 集成
|
||||
|
||||
`ccr` 可以与 Claude Code 无缝集成，将请求路由到你选择的 LLM 提供商。
|
||||
|
||||
### 方式一：设置 API 地址
|
||||
|
||||
```bash
|
||||
export ANTHROPIC_BASE_URL="http://localhost:3456/v1"
|
||||
export ANTHROPIC_API_KEY="your-api-key"
|
||||
```
|
||||
|
||||
### 方式二：使用 activate 命令
|
||||
|
||||
```bash
|
||||
eval "$(ccr activate)"
|
||||
```
|
||||
|
||||
## 配置文件
|
||||
|
||||
`ccr` 使用与 Server 相同的配置文件：`~/.claude-code-router/config.json`
|
||||
|
||||
配置一次，CLI 和 Server 都会使用。
|
||||
|
||||
## 下一步
|
||||
|
||||
- [安装指南](/docs/cli/installation) - 详细安装说明
|
||||
- [快速开始](/docs/cli/quick-start) - 5 分钟上手
|
||||
- [命令参考](/docs/category/cli-commands) - 完整命令列表
|
||||
- [配置说明](/docs/category/cli-config) - 配置文件详解
|
||||
@@ -3,52 +3,76 @@
|
||||
"message": "Next",
|
||||
"description": "The label for version current"
|
||||
},
|
||||
"sidebar.tutorialSidebar.category.Getting Started": {
|
||||
"message": "Getting Started",
|
||||
"description": "The label for category 'Getting Started' in sidebar 'tutorialSidebar'"
|
||||
"sidebar.tutorialSidebar.category.Server": {
|
||||
"message": "服务器",
|
||||
"description": "The label for category 'Server' in sidebar 'tutorialSidebar'"
|
||||
},
|
||||
"sidebar.tutorialSidebar.category.Getting Started.link.generated-index.title": {
|
||||
"message": "Getting Started",
|
||||
"description": "The generated-index page title for category 'Getting Started' in sidebar 'tutorialSidebar'"
|
||||
"sidebar.tutorialSidebar.category.Server.link.generated-index.title": {
|
||||
"message": "Claude Code Router 服务器",
|
||||
"description": "The generated-index page title for category 'Server' in sidebar 'tutorialSidebar'"
|
||||
},
|
||||
"sidebar.tutorialSidebar.category.Getting Started.link.generated-index.description": {
|
||||
"message": "Learn the basics of Claude Code Router",
|
||||
"description": "The generated-index page description for category 'Getting Started' in sidebar 'tutorialSidebar'"
|
||||
"sidebar.tutorialSidebar.category.Server.link.generated-index.description": {
|
||||
"message": "部署和管理 Claude Code Router 服务器",
|
||||
"description": "The generated-index page description for category 'Server' in sidebar 'tutorialSidebar'"
|
||||
},
|
||||
"sidebar.tutorialSidebar.category.API Reference": {
|
||||
"message": "API 参考",
|
||||
"description": "The label for category 'API Reference' in sidebar 'tutorialSidebar'"
|
||||
},
|
||||
"sidebar.tutorialSidebar.category.API Reference.link.generated-index.title": {
|
||||
"message": "API 参考",
|
||||
"description": "The generated-index page title for category 'API Reference' in sidebar 'tutorialSidebar'"
|
||||
},
|
||||
"sidebar.tutorialSidebar.category.API Reference.link.generated-index.description": {
|
||||
"message": "服务器 API 接口文档",
|
||||
"description": "The generated-index page description for category 'API Reference' in sidebar 'tutorialSidebar'"
|
||||
},
|
||||
"sidebar.tutorialSidebar.category.Configuration": {
|
||||
"message": "Configuration",
|
||||
"message": "配置",
|
||||
"description": "The label for category 'Configuration' in sidebar 'tutorialSidebar'"
|
||||
},
|
||||
"sidebar.tutorialSidebar.category.Configuration.link.generated-index.title": {
|
||||
"message": "Configuration",
|
||||
"message": "服务器配置",
|
||||
"description": "The generated-index page title for category 'Configuration' in sidebar 'tutorialSidebar'"
|
||||
},
|
||||
"sidebar.tutorialSidebar.category.Configuration.link.generated-index.description": {
|
||||
"message": "Configure Claude Code Router to suit your needs",
|
||||
"message": "服务器配置说明",
|
||||
"description": "The generated-index page description for category 'Configuration' in sidebar 'tutorialSidebar'"
|
||||
},
|
||||
"sidebar.tutorialSidebar.category.Advanced": {
|
||||
"message": "Advanced",
|
||||
"message": "高级",
|
||||
"description": "The label for category 'Advanced' in sidebar 'tutorialSidebar'"
|
||||
},
|
||||
"sidebar.tutorialSidebar.category.Advanced.link.generated-index.title": {
|
||||
"message": "Advanced Topics",
|
||||
"message": "高级主题",
|
||||
"description": "The generated-index page title for category 'Advanced' in sidebar 'tutorialSidebar'"
|
||||
},
|
||||
"sidebar.tutorialSidebar.category.Advanced.link.generated-index.description": {
|
||||
"message": "Advanced features and customization",
|
||||
"message": "高级功能和自定义",
|
||||
"description": "The generated-index page description for category 'Advanced' in sidebar 'tutorialSidebar'"
|
||||
},
|
||||
"sidebar.tutorialSidebar.category.CLI Reference": {
|
||||
"message": "CLI Reference",
|
||||
"description": "The label for category 'CLI Reference' in sidebar 'tutorialSidebar'"
|
||||
"sidebar.tutorialSidebar.category.CLI": {
|
||||
"message": "CLI",
|
||||
"description": "The label for category 'CLI' in sidebar 'tutorialSidebar'"
|
||||
},
|
||||
"sidebar.tutorialSidebar.category.CLI Reference.link.generated-index.title": {
|
||||
"message": "CLI Commands",
|
||||
"description": "The generated-index page title for category 'CLI Reference' in sidebar 'tutorialSidebar'"
|
||||
"sidebar.tutorialSidebar.category.CLI.link.generated-index.title": {
|
||||
"message": "Claude Code Router CLI",
|
||||
"description": "The generated-index page title for category 'CLI' in sidebar 'tutorialSidebar'"
|
||||
},
|
||||
"sidebar.tutorialSidebar.category.CLI Reference.link.generated-index.description": {
|
||||
"message": "Complete reference for all CLI commands",
|
||||
"description": "The generated-index page description for category 'CLI Reference' in sidebar 'tutorialSidebar'"
|
||||
"sidebar.tutorialSidebar.category.CLI.link.generated-index.description": {
|
||||
"message": "命令行工具使用指南",
|
||||
"description": "The generated-index page description for category 'CLI' in sidebar 'tutorialSidebar'"
|
||||
},
|
||||
"sidebar.tutorialSidebar.category.Commands": {
|
||||
"message": "命令",
|
||||
"description": "The label for category 'Commands' in sidebar 'tutorialSidebar'"
|
||||
},
|
||||
"sidebar.tutorialSidebar.category.Commands.link.generated-index.title": {
|
||||
"message": "CLI 命令",
|
||||
"description": "The generated-index page title for category 'Commands' in sidebar 'tutorialSidebar'"
|
||||
},
|
||||
"sidebar.tutorialSidebar.category.Commands.link.generated-index.description": {
|
||||
"message": "完整的命令参考",
|
||||
"description": "The generated-index page description for category 'Commands' in sidebar 'tutorialSidebar'"
|
||||
}
|
||||
}
|
||||
|
||||
@@ -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,190 @@
|
||||
# 日志 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
|
||||
|
||||
## 日志分析
|
||||
|
||||
### 使用 jq 分析日志
|
||||
|
||||
```bash
|
||||
# 查看所有错误日志
|
||||
curl "http://localhost:3456/api/logs" \
|
||||
-H "x-api-key: your-api-key" | \
|
||||
jq -r '.[] | fromjson | select(.level >= 40)'
|
||||
|
||||
# 统计请求次数
|
||||
curl "http://localhost:3456/api/logs" \
|
||||
-H "x-api-key: your-api-key" | \
|
||||
jq -r '.[] | fromjson | .req.method' | \
|
||||
sort | uniq -c
|
||||
```
|
||||
|
||||
### 实时监控日志
|
||||
|
||||
```bash
|
||||
# 通过 API 实时获取最新日志
|
||||
watch -n 5 'curl -s "http://localhost:3456/api/logs" -H "x-api-key: your-api-key" | jq -r ".[-10:]"'
|
||||
```
|
||||
@@ -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,129 @@
|
||||
# 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 在发生错误时返回统一的错误格式：
|
||||
|
||||
```json
|
||||
{
|
||||
"error": {
|
||||
"type": "invalid_request_error",
|
||||
"message": "错误描述"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
常见 HTTP 状态码：
|
||||
|
||||
- `200` - 成功
|
||||
- `400` - 请求参数错误
|
||||
- `401` - 未授权（API Key 无效）
|
||||
- `404` - 资源不存在
|
||||
- `500` - 服务器内部错误
|
||||
|
||||
## 认证
|
||||
|
||||
### 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 '...'
|
||||
```
|
||||
|
||||
### 无认证模式
|
||||
|
||||
当没有配置 Providers 时，服务器会监听在 `0.0.0.0` 且无需认证：
|
||||
|
||||
```json5
|
||||
{
|
||||
"Providers": []
|
||||
}
|
||||
```
|
||||
|
||||
## 流式响应
|
||||
|
||||
消息 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"}
|
||||
```
|
||||
|
||||
## 速率限制
|
||||
|
||||
服务器本身不实现速率限制，建议通过反向代理（如 Nginx）配置。
|
||||
|
||||
## 版本管理
|
||||
|
||||
当前 API 版本：`v1`
|
||||
|
||||
所有 `/v1/*` 端点保持向后兼容。
|
||||
@@ -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