预设配置

使用预定义配置进行快速设置。

什么是预设？

预设是预配置的设置，包括针对特定用例优化的提供商配置、路由规则和转换器。

使用预设

CLI 方式（命令行）

CLI 方式适合开发者通过命令行快速操作。

安装预设

从本地目录安装：

ccr preset install /path/to/preset-directory

重新配置已安装的预设：

ccr preset install my-preset

使用预设

安装预设后，可以使用预设名称启动 Claude Code：

# 使用指定预设启动
ccr my-preset "your prompt"

预设会：

自动加载预配置的 Provider
应用预设的路由规则
使用预设中配置的 transformer

列出所有预设

ccr preset list

此命令将显示所有已安装的预设及其名称、版本和描述。

查看预设信息

ccr preset info my-preset

删除预设

ccr preset delete my-preset

Web UI 方式

Web UI 提供更友好的可视化界面，支持更多安装方式。

访问 Web UI

ccr ui

然后在浏览器中打开 http://localhost:3000

从 GitHub 仓库安装

点击"预设商城"按钮
在预设列表中选择要安装的预设
点击"安装"按钮

重新配置预设

在预设列表中点击"查看详情"按钮
在详情页面中修改配置项
点击"应用"保存配置

管理预设

查看：点击预设右侧的信息图标
删除：点击预设右侧的删除图标

创建自定义预设

预设目录结构

预设以目录形式存储，每个预设包含以下结构：

~/.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 - 静态选项

"options": {
  "type": "static",
  "options": [
    {"label": "选项1", "value": "value1"},
    {"label": "选项2", "value": "value2"}
  ]
}

providers - 从 Providers 配置提取

"options": {
  "type": "providers"
}

自动从 Providers 数组中提取 name 作为选项。

models - 从指定 Provider 的 models 提取

"options": {
  "type": "models",
  "providerField": "{{selectedProvider}}"
}

根据用户选择的 Provider，动态显示该 Provider 的 models。

模板变量

使用 {{变量名}} 语法在 template 中引用用户输入：

"template": {
  "Providers": [
    {
      "name": "{{providerName}}",
      "api_key": "{{apiKey}}"
    }
  ]
}

配置映射

对于复杂的配置需求，使用 configMappings 精确控制值的位置：

"configMappings": [
  {
    "target": "Providers[0].api_key",
    "value": "{{apiKey}}"
  },
  {
    "target": "PROXY_URL",
    "value": "{{proxyUrl}}",
    "when": {
      "field": "useProxy",
      "operator": "eq",
      "value": true
    }
  }
]

完整示例

{
  "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/chat/completions",
        "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 版本

示例：

{
  "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	状态栏配置
`NON_INTERACTIVE_MODE`	boolean	启用非交互模式（用于 CI/CD）

CLI 专用字段（这些字段仅在 CLI 模式下有效，服务器不使用）：

字段	类型	说明
`noServer`	boolean	跳过本地服务器启动，直接使用 Provider 的 API
`claudeCodeSettings`	object	Claude Code 特定设置（环境变量、状态栏等）

示例：

{
  "Providers": [
    {
      "name": "openai",
      "api_base_url": "https://api.openai.com/v1/chat/completions",
      "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	用户填写的值（运行时使用）

schema 字段类型：

类型	说明	使用场景
`password`	密码输入（隐藏）	API Key
`input`	单行文本输入	URL
`number`	数字输入	端口号
`select`	单选下拉框	选择 Provider
`multiselect`	多选框	启用功能
`confirm`	确认框	是否启用
`editor`	多行文本编辑器	自定义配置

动态配置示例：

{
  "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：简单预设（无动态配置）

# 创建预设目录
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/chat/completions",
      "api_key": "${OPENAI_API_KEY}",
      "models": ["gpt-4o", "gpt-4o-mini"]
    }
  ],

  "Router": {
    "default": "openai,gpt-4o",
    "background": "openai,gpt-4o-mini"
  }
}
EOF

# 配置预设（输入 API Key）
ccr preset install simple-openai

# 使用预设
ccr simple-openai "your prompt"

示例 2：高级预设（动态配置）

# 创建预设目录
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/chat/completions' : 'https://api.deepseek.com/v1/chat/completions'}",
        "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，可以导出当前配置：

# 导出当前配置
ccr preset export my-exported-preset

导出时会自动：

识别敏感字段（如 api_key）并替换为环境变量占位符
生成 schema 用于收集用户输入
生成 template 和 configMappings

可选项：

ccr preset export my-exported-preset \
  --description "导出的配置" \
  --author "Your Name" \
  --tags "production,openai"

预设文件位置

预设保存在：

~/.claude-code-router/presets/

每个预设都是一个目录，包含 manifest.json 文件。

最佳实践

使用动态配置：为需要用户输入的配置项使用schema系统
提供默认值：为非必填项提供合理的默认值
条件显示：使用when条件避免不必要的输入
清晰的标签：为每个字段提供清晰的label和prompt
验证输入：使用validator确保输入的有效性
版本控制：将常用预设保存在版本控制中
文档化：为自定义预设添加描述和版本信息

下一步

CLI 参考 - 完整的 CLI 命令参考
配置 - 详细配置指南

什么是预设？​

使用预设​

CLI 方式（命令行）​

安装预设​

使用预设​

列出所有预设​

查看预设信息​

删除预设​

Web UI 方式​

访问 Web UI​

从 GitHub 仓库安装​

重新配置预设​

管理预设​

创建自定义预设​

预设目录结构​

动态配置系统​

Schema 字段类型​

条件运算符​

动态选项类型​

static - 静态选项​

providers - 从 Providers 配置提取​

models - 从指定 Provider 的 models 提取​

模板变量​

配置映射​

完整示例​

manifest.json 完整字段说明​

1. 元数据字段（Metadata）​

2. 配置字段（Configuration）​

3. 动态配置系统字段​

创建预设示例​

示例 1：简单预设（无动态配置）​

示例 2：高级预设（动态配置）​

导出当前配置为预设​

预设文件位置​

最佳实践​

下一步​

什么是预设？

使用预设

CLI 方式（命令行）

安装预设

使用预设

列出所有预设

查看预设信息

删除预设

Web UI 方式

访问 Web UI

从 GitHub 仓库安装

重新配置预设

管理预设

创建自定义预设

预设目录结构

动态配置系统

Schema 字段类型

条件运算符

动态选项类型

static - 静态选项

providers - 从 Providers 配置提取

models - 从指定 Provider 的 models 提取

模板变量

配置映射

完整示例

manifest.json 完整字段说明

1. 元数据字段（Metadata）

2. 配置字段（Configuration）

3. 动态配置系统字段

创建预设示例

示例 1：简单预设（无动态配置）

示例 2：高级预设（动态配置）

导出当前配置为预设

预设文件位置

最佳实践

下一步