自动CC路由

快速开始

```bash git clone git@github.com:LostAbaddon/cc2llm.git cd cc2llm

npm 全局安装

npm install -g @openai/codex

运行诊断（部分版本支持）

codex doctor ```

启动 Codex 桌面应用

```

model_catalog_json 必须写在 config.toml 根级别，不能放在 provider 配置段内。Provider ID（如 cc2llm）不能使用系统保留名（openai、ollama、lmstudio 等）。

多客户端同时使用

cc2llm 支持多个不同协议的客户端同时连接到同一代理端口：

```bash

终端 1: 启动代理

npm start

终端 2: 启动 Claude Code

npm start claude

终端 3: 启动 Codex CLI

npm start codex

终端 4: 启动 Gemini CLI

npm start gemini ```

所有客户端共享同一套 Provider 配置、Model Mapping 和 Auto Mode 设置，管理面板统一管理。

复制并填写配置

cp config.template.json config.json

编辑 config.json，填入各厂商 API Key

npm start # 启动代理 + 管理面板 npm start claude # 启动代理后自动拉起 Claude Code TUI npm start codex # 启动代理后自动拉起 Codex CLI npm start gemini # 启动代理后自动拉起 Gemini CLI npm start wui # 在浏览器打开管理面板 ```

• 代理服务：http://127.0.0.1:8764（各客户端配置此地址）
• 管理面板：http://127.0.0.1:8765

~/.codex/config.toml

model = "gpt-5.4" model_provider = "cc2llm" openai_base_url = "http://127.0.0.1:8764/codex"

[model_providers.cc2llm] name = "CC2LLM Bridge" base_url = "http://127.0.0.1:8764/codex" wire_api = "chat" env_key = "OPENAI_API_KEY"

配合环境变量：

> **关于 `wire_api`**：Codex CLI 0.81.0+ 默认使用 `"responses"`（Responses API），但大多数中转服务只支持 Chat Completions API。如果你的后端 Provider 只支持 Chat，请设置 `wire_api = "chat"`。

#### Model Mapping 配置

Codex CLI 发送的模型名是 OpenAI 风格（如 `gpt-5.4`、`gpt-5`、`codex-4`、`o4-mini`、`o3`），需要在 cc2llm 的 `modelMapping` 中添加对应映射：

> 映射规则：按 `prefix` 长度降序匹配，`gpt-5.4` 会优先命中 `gpt-5.4` 前缀而非 `gpt-5`。
>
> 以上示例中的模型名（`gpt-5.4`、`deepseek-v4-pro` 等）为演示前缀，实际使用时请参考 `config.template.json` 中的最新配置或将你所用客户端实际发送的模型名填入映射。

#### 验证配置

确认环境变量

echo $OPENAI_BASE_URL echo $OPENAI_API_KEY

配置

config.json 结构：

{
  "server": { "port": 8764, "host": "127.0.0.1", "adminPort": 8765 },
  "defaultMaxTokens": 131072,
  "providers": { ... },
  "agents": { ... },
  "modelMapping": [ ... ],
  "modeCacheTtl": 60,
  "conversationGroups": 5,
  "logLevel": "info"
}

Codex CLI 接入

Codex CLI 使用 OpenAI Chat Completions API 协议，cc2llm 在代理端口自动识别并处理。

安装 Codex CLI

```bash

Gemini CLI 接入

Gemini CLI 使用 Google Gemini 原生 API 协议，cc2llm 在代理端口自动识别并处理。

安装 Gemini CLI

npm install -g @google/gemini-cli

配置方式

方式一：一键启动（最简单）

npm start gemini

该命令自动设置环境变量并启动 Gemini CLI。

方式二：环境变量

export GOOGLE_GEMINI_BASE_URL=http://127.0.0.1:8764
export GEMINI_API_KEY=cc2llm

gemini

GOOGLE_GEMINI_BASE_URL 末尾无需带路径前缀，Gemini CLI 会自动追加 /v1beta/models/...。

方式三：配置文件

创建 ~/.gemini/settings.json：

{
  "security": {
    "auth": {
      "selectedType": "gemini-api-key"
    }
  }
}

配合环境变量启动。

Model Mapping 配置

Gemini CLI 发送的模型名是 Google 风格（如 gemini-2.5-pro、gemini-2.5-flash、gemini-3-pro-preview），需要在 cc2llm 的 modelMapping 中添加对应映射：

{
  "prefix": "gemini-2.5",
  "provider": "google",
  "target": "gemini-3.1-flash-lite-preview"
},
{
  "prefix": "gemini-3",
  "provider": "google",
  "target": "gemini-3.1-pro-preview"
}

也可以将 Gemini CLI 的请求路由到非 Gemini 的后端（如 DeepSeek），cc2llm 会自动做 Gemini ↔ Anthropic 协议转换：

{
  "prefix": "gemini-2.5",
  "provider": "deepseek",
  "target": "deepseek-v4-pro"
}

常见注意事项

1. OAuth 缓存冲突：如果之前用 Google 账号登录过 Gemini CLI，OAuth 缓存可能导致 GOOGLE_GEMINI_BASE_URL 被忽略。建议清除缓存后重新配置，或者使用 API Key 认证模式。
2. Docker 沙箱：Gemini CLI 启用 sandbox: true 后，GOOGLE_*_BASE_URL 环境变量不会传递到沙箱内部，仅有 GEMINI_API_KEY 被保留。使用 cc2llm 时建议关闭沙箱或使用其他隔离方式。
3. API Key 作为 Query 参数：Gemini CLI 默认将 API Key 放在 URL Query String（?key=...）中传递，cc2llm 会自动处理。

API

模型目录文件（必须写在根级别）

model_catalog_json = "~/.codex/model-catalogs/all-models.json"

model = "deepseek-v4-pro" model_provider = "cc2llm" openai_base_url = "http://127.0.0.1:8764/codex"

[model_providers.cc2llm] name = "CC2LLM Bridge" base_url = "http://127.0.0.1:8764/codex" wire_api = "chat" env_key = "OPENAI_API_KEY"

#### 第三步：设置环境变量并启动

模型名映射总结

cc2llm 使用统一的 modelMapping 前缀匹配机制处理所有客户端的模型名。以下是一个覆盖三种客户端的完整示例：

"modelMapping": [
  { "prefix": "claude-opus",  "target": "deepseek-v4-pro",             "provider": "deepseek" },
  { "prefix": "claude-sonnet", "target": "deepseek-v4-pro",             "provider": "auto" },
  { "prefix": "claude-haiku",  "target": "deepseek-v4-flash",           "provider": "deepseek" },
  { "prefix": "gpt-5.4",      "target": "deepseek-v4-pro",             "provider": "deepseek" },
  { "prefix": "gpt-5",        "target": "deepseek-v4-pro",             "provider": "deepseek" },
  { "prefix": "codex",        "target": "deepseek-v4-pro",             "provider": "deepseek" },
  { "prefix": "o4",           "target": "deepseek-v4-pro",             "provider": "deepseek" },
  { "prefix": "o3",           "target": "deepseek-v4-pro",             "provider": "deepseek" },
  { "prefix": "gemini-2.5",   "target": "gemini-3.1-flash-lite-preview", "provider": "google" },
  { "prefix": "gemini-3",     "target": "gemini-3.1-pro-preview",       "provider": "google" }
]

前缀匹配规则： - 按 prefix 长度降序排列，优先命中更具体的前缀 - gpt-5.4 → 优先命中 gpt-5.4（长度 6），而非 gpt-5（长度 5） - gemini-2.5-flash → 命中 gemini-2.5 前缀 - 空字符串 prefix 作为兜底匹配，通常无需设置

以上示例中的模型名均为演示前缀。实际使用时请根据 config.template.json 中的最新配置和你所用客户端实际发送的模型名来编写映射规则。

Providers（模型厂商）

每个 Provider 代表一个模型服务商。支持三种协议类型：

"deepseek": {
  "type": "anthropic",
  "apiKey": "sk-xxx",
  "baseUrl": "https://api.deepseek.com/anthropic",
  "proxy": "",
  "models": [
    { "name": "deepseek-v4-pro", "maxTokens": 393216 },
    { "name": "deepseek-v4-flash", "maxTokens": 393216 }
  ],
  "defaultMaxTokens": 393216
}

maxTokens 查找优先级（三层）：模型级 models[].maxTokens → Provider 级 defaultMaxTokens → 全局 defaultMaxTokens → 131072。

多 API Key 负载均衡

apiKey 字段支持数组格式来配置同 Provider 的多个 Key。服务会基于内存级加权随机算法自动分配请求到不同 Key，实现故障自愈与负载均衡：

"deepseek": {
  "type": "anthropic",
  "apiKey": ["sk-key1-xxx", "sk-key2-xxx", "sk-key3-xxx"],
  "baseUrl": "..."
}

算法特性： - 动态权重：每次选择 Key 时，根据各 Key 的可用状态、当前并发数、历史完成数计算权重，均衡流量 - 故障感知：4XX 鉴权错误 / 2XX 中嵌入的业务错误 → 标记 Key 为不可用（权重降为 30），但不完全禁用 - Provider 级异常：连接失败 / 5XX → 记录 Provider 级状态，不影响各 Key 的可用性标记 - 自愈机制：标记为不可用的 Key 若后续成功返回，立即恢复为可用（权重回到 100） - 绝不卡死：所有 Key 均不可用时，以 30:30:... 等权重继续分发，一旦任一 Key 成功即回升

状态查看：管理面板 API > Key States 可查看每个 Provider 的所有 Key 实时状态（可用性、并发数、完成数）。

Model Mapping（模型名映射）

将客户端传入的模型名按前缀匹配路由到目标厂商：

"modelMapping": [
  { "prefix": "claude-opus",  "target": "deepseek-v4-pro",  "provider": "deepseek" },
  { "prefix": "gpt-5.4",      "target": "deepseek-v4-pro",  "provider": "deepseek" },
  { "prefix": "gemini-2.5",   "target": "gemini-2.5-pro",   "provider": "google" },
  { "prefix": "auto",         "target": "auto",             "provider": "auto" }
]

匹配规则： - 按 prefix 长度降序排列，优先命中更具体的前缀 - claude-opus-4-7-20250805 → deepseek-v4-pro（前缀 claude-opus 命中第一条） - 空字符串 prefix 作为兜底匹配 - 未匹配任何前缀 → 返回 400 错误 - 通配符前缀：prefix 中可包含 *，如 "gpt-*-mini"，等价于正则 /^gpt-.*-mini/。通配规则排在所有精确规则之后匹配；同组内按 prefix 字符串长度降序

provider 为 auto 时，target 可以是数组：每次命中按权重选取一个 spec（详见下文「多模型加权路由」）。例如：

{
  "prefix": "auto",
  "target": ["deepseek/deepseek-v4-pro", "google/gemini-3.1-pro-preview"],
  "provider": "auto"
}

多模型加权路由（Model Router）

当某个 mode 的 models 字段、或 modelMapping 中 provider: "auto" 的 target 数组、或 quick 模式的 models 数组存在多个候选项时，cc2llm 使用加权随机算法来选择本次请求实际使用的 provider/model。

权重计算公式

对候选项 c，实际权重为：

weight = link_weight(c.provider) / (max_done + 1) * (c.num_done + 1) * (max_doing + 1) / (c.num_doing + 1)

其中： - link_weight(provider) — 该 provider 的连接权重（初始 100，每次"不可用"事件 ×0.9，每次"从不可用恢复"事件 ×1.1） - num_done — 该 provider/model 成功完成的任务数（失败不计入） - num_doing — 该 provider/model 当前正在执行的任务数 - max_done / max_doing — 候选项数组中 num_done / num_doing 的最大值 - 公式中所有 +1 用于避免除零

直觉：成功完成任务越多，被选中概率越大；正在执行的任务越多，被选中概率越小。这避免了对热门 provider/model 的过载。

Provider 健康度感知

link_weight 会随 provider 实际运行情况自动调整（数据从 key-state-manager 现有机制获取，不重复维护）：

"持续压低"是预期行为——provider 持续故障时，权重会逐次降至 0.9 → 0.81 → 0.729 → …，直到几乎不被选中。当 provider 恢复后一次任务成功即开始回升（× 1.1）。

失败重试

每次任务完成（无论成功或失败）都会立即更新所有统计。

任务失败时： - 重新加权选模型，从相同 models[] 数组中重新抽取 - 允许抽到同一个 provider/model 作为重试（不强制过滤） - 最多 MAX_RETRY_ATTEMPTS 次（默认 3，含首次） - 全部失败才返回最后一次错误给 Copilot；只要中间有任意一次成功，调用方看不到任何错误

业务请求和 Classifier Quick 请求都遵循此重试规则——两者各自有独立的重试循环。

数组不去重

候选项数组不会自动去重。如果用户在 models 中输入两个完全相同的 provider/model 字符串，相当于把该候选项的概率人为放大 2 倍。这是规则允许的干预手段，例如：

"code": ["deepseek/deepseek-v4-pro", "deepseek/deepseek-v4-pro", "google/gemini-3.1-pro"]

效果：deepseek 整体被选中的概率约 2/3，gemini 约 1/3。

热加载重置

config.json 热重载时，所有 link_weight、num_done、num_doing 全量清空，回到初始状态。

可调参数

所有可调参数均定义为 lib/model-router.js 文件顶部常量，修改后重启即可生效，无需写死在调用处：

const LINK_WEIGHT_DOWN_FACTOR = 0.9;   // provider 不可用时 link_weight 下调系数
const LINK_WEIGHT_UP_FACTOR = 1.1;     // provider 恢复时 link_weight 上调系数
const MAX_RETRY_ATTEMPTS = 3;          // 单个任务最大尝试次数(含首次)
const INITIAL_LINK_WEIGHT = 100;       // provider 初始 link_weight

与现有 API Key 负载均衡的关系

model-router 是新的、横跨 Provider/Model 级别的路由层，与已有的 key-state-manager（同 Provider 多 Key 负载均衡）是两个完全独立、不冲突的模块：

二者可在同一次请求中先后使用：先由 model-router 选定 provider/model，再由 key-state-manager 在该 provider 内部选择具体 API Key。

状态查看

管理面板可通过 GET /api/model-router 端点获取当前 Model Router 状态快照（providerWeights + taskStats），用于调试权重收敛。

模型列表与过滤

管理面板的 Providers 标签页支持从 Provider API 动态拉取可用模型列表（GET /api/models），按 Provider 分组返回经过滤后的 LLM 模型。为过滤掉 embedding、TTS、图像生成等非 LLM 模型，model-filter.json 按 Provider 配置正则排除规则：

{
  "google": ["embedding", "\\bimagen\\b", "\\bveo\\b", "\\btts\\b", ...],
  "openrouter": ["embedding", "-image\\b", "dall-e", "moderation", ...],
  "openai": ["embedding", "\\btts\\b", "\\bwhisper\\b", "dall-e", "moderation", ...],
  "xai": ["imagine", "\\btts\\b", "\\bstt\\b", "\\bvoice\\b"],
  "deepseek": ["\\bjanus\\b"],
  "moonshot": ["kimi-audio", "\\baudio\\b"],
  "minimax": ["\\bspeech\\b", "image-01", "hailuo"]
}

过滤规则按 Provider 名称匹配，正则大小写不敏感。不在此文件中的 Provider 不做过滤。