跳到主要内容

Server 简介

Claude Code Router Server 将 Anthropic Messages、OpenAI Chat Completions、 OpenAI Responses 与 FIM Completions 请求路由到不同的 LLM 提供商。它提供完整的 HTTP API，支持：

  • API 请求路由：归一化支持的客户端协议，选择提供商/模型，并转换为提供商线格式
  • 认证与授权：支持 API Key 认证
  • 配置管理：动态配置提供商、路由规则和转换器
  • Web UI：内置管理界面
  • 日志系统：完整的请求日志记录

架构概述​

┌──────────────────┐     ┌─────────────────────────────┐     ┌──────────────┐
│ 客户端协议       │────▶│ CCR Server                  │────▶│ LLM Provider │
│ Messages / Chat  │     │  ┌─────────────────────┐    │     │  (OpenAI/    │
│ Responses / FIM  │     │  │ @caeliq/llms        │    │     │   Gemini/etc)│
└──────────────────┘     │  │ (核心包)             │    │     └──────────────┘
                         │  │ - 请求转换           │    │
                         │  │ - 响应转换           │    │
                         │  │ - 认证处理           │    │
                         │  └─────────────────────┘    │
                         │                             │
                         │  - 路由逻辑                 │
                         │  - Agent 系统               │
                         │  - 配置管理                 │
                         └─────────────────────────────┘
                                │
                                ├─ Web UI
                                ├─ Config API
                                └─ Logs API

核心包：@caeliq/llms​

服务器构建于 @caeliq/llms 之上，这是一个通用的 LLM API 转换库，提供了核心的请求/响应转换能力。

什么是 @caeliq/llms？​

@caeliq/llms 是一个独立的 npm 包，负责处理：

  • API 格式转换：在不同的 LLM 提供商 API 之间转换（Anthropic、OpenAI、Gemini 等）
  • 请求/响应转换：将请求和响应转换为统一格式
  • 认证处理：管理不同提供商的认证方法
  • 流式响应支持：处理来自不同提供商的流式响应
  • 转换器系统：提供可扩展的架构来添加新的提供商

核心概念​

1. 统一请求/响应格式​

核心包定义了统一格式（UnifiedChatRequest、UnifiedChatResponse），抽象了提供商特定的差异：

interface UnifiedChatRequest {
  messages: UnifiedMessage[];
  model: string;
  max_tokens?: number;
  temperature?: number;
  stream?: boolean;
  tools?: UnifiedTool[];
  tool_choice?: any;
  reasoning?: {
    effort?: ThinkLevel;  // "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max" | "ultra"
    max_tokens?: number;
    enabled?: boolean;
  };
}

2. 转换器接口​

所有转换器都实现一个通用接口：

interface Transformer {
  transformRequestIn?: (request: UnifiedChatRequest, provider: LLMProvider, context: TransformerContext) => Promise<any>;
  transformRequestOut?: (request: any, context: TransformerContext) => Promise<UnifiedChatRequest>;
  transformResponseIn?: (response: Response, context?: TransformerContext) => Promise<Response>;
  transformResponseOut?: (response: Response, context: TransformerContext) => Promise<Response>;
  endPoint?: string;
  name?: string;
  auth?: (request: any, provider: LLMProvider, context: TransformerContext) => Promise<any>;
}

3. 内置转换器​

核心包包含以下转换器：

  • Anthropic（协议所有者）：Anthropic Messages（/v1/messages）
  • OpenAI（协议所有者）：Chat Completions（/v1/chat/completions）
  • openai-responses（协议所有者）：Responses API（/v1/responses）
  • Fim（协议所有者）+ fim.mistral / fim.deepseek / fim.qwen：FIM Completions（/v1/fim/completions）
  • gemini：Google Gemini API 格式
  • vertex-gemini / vertex-claude：Google Vertex AI 格式
  • deepseek：DeepSeek API 格式
  • mistral：Mistral AI API 格式
  • groq：Groq API 格式
  • cerebras：Cerebras API 格式
  • openrouter：OpenRouter API 格式
  • codex：Codex（ChatGPT）后端 API
  • claude-auth：Claude Pro/Max 订阅 OAuth
  • antigravity-auth：Google Antigravity（cloudcode-pa）OAuth + 封包
  • cursor-sdk：通过 @cursor/sdk 进程内运行 Cursor Agent
  • qwen-auth：Qwen Chat 认证（基于 JWT）
  • chrome-on-device：Chrome 内置 Gemini Nano（本地运行，无需 API 费用）
  • vercel：Vercel AI SDK 格式
  • opencode-headers：OpenCode 请求头注入
  • 以及其他工具转换器：cleancache、customparams、enhancetool、forcereasoning、maxcompletiontokens、maxtoken、reasoning、sampling、streamoptions、tooluse

与 CCR Server 的集成​

CCR server 通过以下方式集成 @caeliq/llms：

  1. 转换器服务（packages/core/src/services/transformer.ts）：管理转换器的注册和实例化
  2. 提供商配置：将提供商配置映射到核心包的 LLMProvider 接口
  3. 请求管道：在请求处理过程中按顺序应用转换器
  4. 自定义转换器：支持加载外部转换器插件

版本和更新​

@caeliq/llms 的当前版本是 1.0.68。它作为独立的 npm 包发布，可以独立使用或作为 CCR Server 的一部分使用。

核心功能​

1. 请求路由​

  • 基于 Token 数量的智能路由
  • 项目级路由配置
  • 自定义路由函数
  • 场景化路由（background、think、longContext、webSearch、fim、image 等）

2. 请求转换​

  • 支持多种 LLM 提供商的 API 格式转换
  • 内置转换器：Anthropic、DeepSeek、Gemini、OpenRouter、Groq 等
  • 可扩展的转换器系统

3. Agent 系统​

  • 插件式的 Agent 架构
  • 内置图片处理 Agent
  • 自定义 Agent 支持

4. 配置管理​

  • JSON5 格式配置文件
  • 环境变量插值
  • 配置热更新（需重启服务）

使用场景​

场景一：个人本地服务​

在本地运行服务，供个人 Claude Code 使用：

cd packages/server
docker compose up --build -d

场景二：团队共享服务​

使用 Docker Compose 部署，为团队成员提供共享服务：

services:
  ccr:
    build:
      context: ../..
      dockerfile: packages/server/Dockerfile
    ports:
      - "3456:3456"
    volumes:
      - ~/.claude-code-router:/root/.claude-code-router
    environment:
      - HOST=0.0.0.0
      - PORT=3456

场景三：二次开发​

基于暴露的 API 构建自定义应用：

GET /api/config
POST /v1/messages
GET /api/logs

下一步​