当Claude Code横空出世，开发者们欢呼雀跃。但很快，地域限制、高昂费用、单一模型的枷锁让许多人望而却步。一个大胆的想法诞生了：能不能用自己的模型，享受Claude Code的体验？这就是Claude Code Router的故事——一个用技术打破壁垒的开源项目。

一、从"用不上"到"随便用"：一个逆向工程师的突围之路

1.1 困境：当AI助手遇上地域封锁

2025年2月25日，Anthropic发布了Claude Code，一款能理解代码库、编辑文件、执行命令的AI编程助手。但对于中国大陆的开发者来说，这更像是一场"看得见摸不着"的盛宴：

  • 注册门槛：需要Anthropic账号，还要申请waitlist等待审批

  • 地域封锁：Anthropic直接屏蔽中国大陆用户

  • 成本高昂：即便能用，Claude 3.5 Sonnet的API费用也让人肉疼

就在发布第二天，一位开发者开始了他的"破局"之旅。他的目标很明确：不需要Anthropic账号，用自己的模型，享受Claude Code的完整体验。

1.2 逆向之路：从混淆代码到环境变量的发现

这场技术冒险从一个简单的npm安装开始：

npm install -g @anthropic-ai/claude-code

打开package.json，入口文件是cli.js。但这个文件被混淆和压缩过，代码密密麻麻像天书。不过，WebStorm的"Format File"功能能让代码重新变得可读。

真正的突破来自Chrome DevTools。通过以下命令启动调试模式：

NODE_OPTIONS="--inspect-brk=9229" claude

在Chrome浏览器访问chrome://inspect/，点击inspect进入调试界面。搜索关键词api.anthropic.com，很快就定位到了API调用的核心代码。

关键发现：Claude Code支持通过环境变量覆盖配置！

  • ANTHROPIC_BASE_URL：可以重定向API请求

  • ANTHROPIC_AUTH_TOKEN：可以自定义认证令牌

  • Claude Code严格遵循Anthropic API规范

这意味着，只要搭建一个中间服务，把请求转换成Anthropic格式，再转发给其他模型提供商（如DeepSeek、Gemini、Ollama），就能"偷梁换柱"，用自己的模型驱动Claude Code！

1.3 Claude Code Router诞生：一个优雅的"中间人"

基于这个思路，Claude Code Router应运而生。它的核心架构非常简洁：

Claude Code → 环境变量重定向 → Claude Code Router → 格式转换 → 第三方模型API

项目使用Node.js + TypeScript构建，核心依赖包括：

  • Fastify：高性能HTTP服务器

  • @musistudio/llms：统一的LLM接口转换层

  • tiktoken：实时计算Token数量

  • rotating-file-stream：日志管理

二、技术架构深度剖析：如何优雅地"偷梁换柱"

2.1 核心设计理念：Transformer模式的妙用

Claude Code Router最精妙的设计在于Transformer模式。不同的模型提供商虽然都声称兼容OpenAI格式，但实际上差异巨大：

  • Gemini：工具参数的format字段只支持date和date-time，且没有tool call ID

  • OpenRouter：需要cache_control字段才能启用缓存

  • DeepSeek：官方API的max_output是8192，但火山引擎的限制更高

  • Ollama：本地模型，完全不同的调用方式

为了解决这些差异，项目引入了统一转换层的概念：

// 请求转换流程
AnthropicRequest → AnthropicTransformer → OpenAIRequest 
  → GeminiTransformer → GeminiRequest → GeminiServer

// 响应转换流程
GeminiResponse → GeminiTransformer → OpenAIResponse 
  → AnthropicTransformer → AnthropicResponse

每个Transformer负责处理特定提供商的格式转换，包括：

  • 请求改写：调整参数格式、添加必需字段、处理特殊限制

  • 响应转换：统一返回格式、处理流式响应、错误处理

2.2 智能路由系统：让合适的模型做合适的事

Claude Code Router的路由系统是其灵魂所在。它不是简单地把所有请求转发给同一个模型，而是根据任务特性动态选择最合适的模型：

2.2.1 四种路由模式
{
  "Router": {
    "default": "deepseek,deepseek-chat",
    "background": "ollama,qwen2.5-coder:latest",
    "think": "deepseek,deepseek-reasoner",
    "longContext": "openrouter,google/gemini-2.5-pro-preview",
    "longContextThreshold": 60000,
    "webSearch": "gemini,gemini-2.5-flash"
  }
}

  • default（默认模型）：处理常规任务，作为兜底方案

  • background（后台模型）：处理轻量级后台任务，可以用本地Ollama模型节省成本

  • think（思考模型）：负责推理和规划模式，使用DeepSeek-R1这类推理模型

  • longContext（长上下文模型）：当上下文超过阈值时自动切换，弥补某些模型的长文本处理能力不足

  • webSearch（网络搜索模型）：处理需要联网搜索的任务

2.2.2 路由决策的智能逻辑

路由器的决策过程非常精妙，来看核心代码：

const getUseModel = async (req, tokenCount, config, lastUsage) => {
  // 1. 检查是否手动指定模型（通过/model命令）
  if (req.body.model.includes(",")) {
    const [provider, model] = req.body.model.split(",");
    // 验证并返回指定模型
  }

  // 2. 长上下文检测：实时计算Token数量
  const longContextThreshold = Router.longContextThreshold || 60000;
  if (tokenCount > longContextThreshold && Router.longContext) {
    return Router.longContext;
  }

  // 3. 子代理模型指定：支持在prompt中嵌入模型选择
  if (req.body?.system[1]?.text?.startsWith("<CCR-SUBAGENT-MODEL>")) {
    const model = extractModelFromTag(req.body.system[1].text);
    return model;
  }

  // 4. 后台任务检测：识别Claude Haiku模型
  if (req.body.model?.includes("haiku") && config.Router.background) {
    return config.Router.background;
  }

  // 5. 网络搜索检测：检查工具列表
  if (req.body.tools?.some(tool => tool.type?.startsWith("web_search"))) {
    return Router.webSearch;
  }

  // 6. 思考模式检测
  if (req.body.thinking && Router.think) {
    return Router.think;
  }

  // 7. 默认模型兜底
  return Router.default;
};

这个路由逻辑的精妙之处在于：

  • 实时Token计算：使用tiktoken库精确计算，避免超出模型限制

  • 优先级设计：网络搜索优先级高于思考模式，确保功能正确性

  • 灵活扩展：支持自定义路由脚本，满足复杂场景

2.3 自定义路由器：终极灵活性

对于有特殊需求的用户，Claude Code Router支持自定义路由脚本。你可以编写JavaScript函数，实现任意复杂的路由逻辑：

// custom-router.js
module.exports = async function router(req, config) {
  const userMessage = req.body.messages.find(m => m.role === "user")?.content;

  // 场景1：代码审查任务用强大模型
  if (userMessage?.includes("review this code")) {
    return "openrouter,anthropic/claude-3.5-sonnet";
  }

  // 场景2：简单问答用便宜模型
  if (userMessage?.length < 100) {
    return "deepseek,deepseek-chat";
  }

  // 场景3：根据时间段选择模型（省钱大法）
  const hour = new Date().getHours();
  if (hour >= 2 && hour <= 6) {
    // 凌晨用便宜模型
    return "ollama,qwen2.5-coder:latest";
  }

  // 场景4：根据项目类型选择模型
  if (req.sessionId) {
    const project = await getProjectInfo(req.sessionId);
    if (project.type === "frontend") {
      return "gemini,gemini-2.5-pro"; // 前端项目用Gemini
    }
  }

  return null; // 回退到默认路由
};

这种设计让Claude Code Router不仅是一个简单的代理，更是一个可编程的AI调度中心。

2.4 流式响应处理：实时交互的关键

Claude Code的一大特色是流式响应，用户能实时看到AI的思考过程。Claude Code Router完整保留了这一特性，核心实现在于SSE（Server-Sent Events）流处理：

// SSE解析和序列化
const eventStream = payload
  .pipeThrough(new SSEParserTransform())  // 解析SSE流
  .pipeThrough(new TransformStream({      // 处理每个事件
    async transform(data, controller) {
      // 处理工具调用、消息增量等
      if (data.event === 'content_block_start') {
        // 检测工具调用开始
      }
      if (data.event === 'message_delta') {
        // 处理消息增量
      }
      controller.enqueue(data);
    }
  }))
  .pipeThrough(new SSESerializerTransform()); // 重新序列化

这个流处理管道的巧妙之处：

  • 零延迟转发：边接收边转发，不等待完整响应

  • 中间处理：可以在流中插入自定义逻辑（如工具调用拦截）

  • 错误恢复：优雅处理流中断和异常

三、内置Agent系统：让"笨"模型也能聪明起来

3.1 DeepSeek的工具调用困境

在实际使用中，开发者发现DeepSeek模型有个致命问题：在长对话中会"忘记"使用工具。

最初几轮对话，模型还会主动调用工具（如文件编辑、命令执行）。但随着对话轮次增加，模型开始用纯文本回复，完全忽略可用的工具。这让Claude Code的体验大打折扣。

3.2 Tool Mode：强制工具调用的创新方案

受Claude Code的Plan Mode启发，项目实现了一个Tool Mode Transformer，强制模型使用工具：

export class TooluseTransformer implements Transformer {
  transformRequestIn(request) {
    if (request.tools?.length) {
      // 1. 注入系统提示，强调工具使用
      request.messages.push({
        role: "system",
        content: `<system-reminder>工具模式已激活。用户期望你主动执行最合适的工具来完成任务。
在调用工具前，必须仔细评估是否匹配当前任务。如果没有合适的工具，必须调用ExitTool退出工具模式。
始终优先通过工具高效完成用户任务。</system-reminder>`
      });

      // 2. 强制要求至少调用一个工具
      request.tool_choice = "required";

      // 3. 添加退出工具
      request.tools.unshift({
        type: "function",
        function: {
          name: "ExitTool",
          description: "当你在工具模式中完成任务时使用此工具。这是退出工具模式的唯一有效方式。",
          parameters: {
            type: "object",
            properties: {
              response: {
                type: "string",
                description: "你的回复将原样转发给用户"
              }
            }
          }
        }
      });
    }
    return request;
  }

  async transformResponseOut(response) {
    // 检测ExitTool调用，转换为普通文本响应
    if (toolCall.function.name === "ExitTool") {
      const args = JSON.parse(toolCall.function.arguments);
      jsonResponse.choices[0].message.content = args.response;
      delete jsonResponse.choices[0].message.tool_calls;
    }
    return response;
  }
}

这个设计的精妙之处：

  • 强制约束：通过tool_choice: "required"确保模型必须调用工具

  • 优雅退出：提供ExitTool作为"逃生通道"，避免死循环

  • 透明转换：ExitTool的响应会被转换成普通文本，用户无感知

实测效果显著提升，DeepSeek在长对话中也能持续使用工具。代价是偶尔会调用不必要的工具，增加一些延迟和Token消耗。

3.3 Image Agent：扩展视觉能力

项目还内置了Image Agent，用于处理图片相关任务。对于不支持工具调用的模型，可以通过配置强制启用：

{
  "Router": {
    "image": "gemini,gemini-2.5-flash"
  },
  "forceUseImageAgent": true
}

Image Agent的工作流程：

  1. 检测请求中是否包含图片内容

  2. 自动注入图片处理工具到工具列表

  3. 拦截工具调用，执行图片处理逻辑

  4. 将结果返回给模型继续对话

这种Agent模式的可扩展性很强，未来可以添加更多专用Agent（如代码分析Agent、文档生成Agent等）。

四、实战应用场景：从个人开发到CI/CD

4.1 场景一：本地开发的成本优化

对于个人开发者，Claude Code Router最大的价值是成本控制。一个典型的配置：

{
  "Providers": [
    {
      "name": "deepseek",
      "api_base_url": "https://api.deepseek.com/chat/completions",
      "api_key": "sk-xxx",
      "models": ["deepseek-chat", "deepseek-reasoner"]
    },
    {
      "name": "ollama",
      "api_base_url": "http://localhost:11434/v1/chat/completions",
      "api_key": "ollama",
      "models": ["qwen2.5-coder:latest"]
    }
  ],
  "Router": {
    "default": "deepseek,deepseek-chat",
    "background": "ollama,qwen2.5-coder:latest",
    "think": "deepseek,deepseek-reasoner"
  }
}

成本对比（以10万Token为例）：

  • Claude 3.5 Sonnet：约$3（输入）+ $15（输出）= $18

  • DeepSeek-V3：约$0.27（输入）+ $1.1（输出）= $1.37

  • Ollama本地模型：完全免费

通过智能路由，后台任务用本地模型，复杂任务用DeepSeek，成本可降低90%以上。

4.2 场景二：团队协作的统一接入

在团队环境中，Claude Code Router可以作为统一的AI网关：

{
  "HOST": "0.0.0.0",
  "APIKEY": "team-secret-key-2024",
  "Providers": [
    {
      "name": "openrouter",
      "api_base_url": "https://openrouter.ai/api/v1/chat/completions",
      "api_key": "sk-xxx",
      "models": ["anthropic/claude-sonnet-4", "google/gemini-2.5-pro"]
    }
  ]
}

团队成员只需配置环境变量：

export ANTHROPIC_BASE_URL=http://team-gateway:3456
export ANTHROPIC_AUTH_TOKEN=team-secret-key-2024

优势：

  • 统一计费：所有API调用走团队账号，方便成本管理

  • 权限控制：通过APIKEY控制访问权限

  • 灵活切换：管理员可以随时调整路由策略，无需团队成员修改配置

4.3 场景三：GitHub Actions中的自动化

Claude Code Router支持在CI/CD环境中运行，实现AI驱动的自动化工作流：

name: Claude Code Auto Review

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  ai-review:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Claude Code Router
        run: |
          curl -fsSL https://bun.sh/install | bash
          mkdir -p $HOME/.claude-code-router
          cat << 'EOF' > $HOME/.claude-code-router/config.json
          {
            "NON_INTERACTIVE_MODE": true,
            "OPENAI_API_KEY": "${{ secrets.DEEPSEEK_API_KEY }}",
            "OPENAI_BASE_URL": "https://api.deepseek.com",
            "OPENAI_MODEL": "deepseek-chat"
          }
          EOF

      - name: Start Router
        run: nohup ~/.bun/bin/bunx @musistudio/claude-code-router start &

      - name: Run Code Review
        uses: anthropics/claude-code-action@beta
        env:
          ANTHROPIC_BASE_URL: http://localhost:3456
        with:
          anthropic_api_key: "any-string-is-ok"
          prompt: "Review this PR and provide suggestions"

应用场景：

  • 代码审查：自动分析PR，提供改进建议

  • 文档生成：根据代码变更自动更新文档

  • 测试生成：为新增代码自动生成单元测试

  • 定时任务：凌晨用便宜模型执行批量任务

关键配置NON_INTERACTIVE_MODE: true确保在非交互环境中正常运行。

4.4 场景四：多模型混合策略

对于追求极致性价比的用户，可以设计复杂的混合策略：

// custom-router.js - 高级混合策略
module.exports = async function router(req, config) {
  const hour = new Date().getHours();
  const tokenCount = req.tokenCount;
  const userMessage = req.body.messages.find(m => m.role === "user")?.content;

  // 策略1：凌晨2-6点用本地模型（电费便宜）
  if (hour >= 2 && hour <= 6) {
    return "ollama,qwen2.5-coder:latest";
  }

  // 策略2：简单任务用便宜模型
  if (tokenCount < 1000 && !req.body.thinking) {
    return "deepseek,deepseek-chat";
  }

  // 策略3：代码生成任务用专用模型
  if (userMessage?.match(/write|create|implement|generate/i)) {
    return "openrouter,anthropic/claude-3.5-sonnet";
  }

  // 策略4：数学推理用思考模型
  if (userMessage?.match(/calculate|solve|prove|analyze/i)) {
    return "deepseek,deepseek-reasoner";
  }

  // 策略5：超长上下文用Gemini
  if (tokenCount > 100000) {
    return "gemini,gemini-2.5-pro";
  }

  // 策略6：工作日白天用快速模型（提高响应速度）
  const isWorkday = new Date().getDay() >= 1 && new Date().getDay() <= 5;
  if (isWorkday && hour >= 9 && hour <= 18) {
    return "openrouter,anthropic/claude-3.5-sonnet";
  }

  return null; // 其他情况用默认路由
};

这种策略可以实现：

  • 时间优化：根据时段选择模型

  • 任务优化：根据任务类型选择模型

  • 成本优化：简单任务用便宜模型

  • 性能优化：关键时段用快速模型

五、技术细节与最佳实践

5.1 环境变量插值：安全管理API密钥

Claude Code Router支持在配置文件中使用环境变量，避免硬编码敏感信息：

{
  "OPENAI_API_KEY": "$OPENAI_API_KEY",
  "GEMINI_API_KEY": "${GEMINI_API_KEY}",
  "Providers": [
    {
      "name": "openai",
      "api_key": "$OPENAI_API_KEY",
      "models": ["gpt-4"]
    }
  ]
}

实现原理：

const interpolateEnvVars = (obj: any): any => {
  if (typeof obj === "string") {
    // 替换 $VAR_NAME 或 ${VAR_NAME}
    return obj.replace(/\$\{([^}]+)\}|\$([A-Z_][A-Z0-9_]*)/g, 
      (match, braced, unbraced) => {
        const varName = braced || unbraced;
        return process.env[varName] || match;
      }
    );
  }
  // 递归处理对象和数组
  // ...
};

最佳实践：

  • API密钥存储在.env文件或系统环境变量

  • 配置文件可以安全地提交到Git

  • 支持不同环境（开发/测试/生产）使用不同密钥

5.2 日志系统：双层日志架构

项目采用双层日志系统，分别记录不同层面的信息：

// 1. 服务器级别日志（HTTP请求、API调用）
const loggerConfig = {
  level: config.LOG_LEVEL || "debug",
  stream: createStream(generator, {
    path: HOME_DIR,
    maxFiles: 3,
    interval: "1d",
    compress: false,
    maxSize: "50M"
  })
};

// 2. 应用级别日志（路由决策、业务逻辑）
const appLogPath = join(HOME_DIR, "claude-code-router.log");

日志文件命名规则：

  • 服务器日志：ccr-202501031430.log（按时间滚动）

  • 应用日志：claude-code-router.log（单文件）

日志清理策略：

  • 自动保留最近10个日志文件

  • 单个文件最大50MB

  • 每天自动轮转

查看日志的方式：

# 通过UI查看
ccr ui

# 通过API查看
curl http://localhost:3456/api/logs

# 直接查看文件
tail -f ~/.claude-code-router/claude-code-router.log

5.3 会话缓存：优化长对话性能

项目使用LRU缓存优化会话管理：

// 会话使用情况缓存
const sessionUsageCache = new LRUCache<string, Usage>({
  max: 1000,  // 最多缓存1000个会话
  ttl: 1000 * 60 * 60 * 24  // 24小时过期
});

// 会话到项目的映射缓存
const sessionProjectCache = new LRUCache<string, string | null>({
  max: 1000
});

缓存的作用：

  • Token统计：记录每个会话的Token使用情况

  • 路由优化：根据历史使用情况优化模型选择

  • 项目关联：快速查找会话所属项目

  • 性能提升：避免重复的文件系统查询

5.4 进程管理：后台服务的优雅启停

Claude Code Router作为后台服务运行，进程管理非常关键：

// 保存PID
savePid(process.pid);

// 优雅退出
process.on("SIGINT", () => {
  console.log("Received SIGINT, cleaning up...");
  cleanupPidFile();
  process.exit(0);
});

process.on("SIGTERM", () => {
  cleanupPidFile();
  process.exit(0);
});

// 全局错误处理
process.on("uncaughtException", (err) => {
  server.logger.error("Uncaught exception:", err);
});

process.on("unhandledRejection", (reason, promise) => {
  server.logger.error("Unhandled rejection:", reason);
});

命令行工具：

ccr start    # 启动服务
ccr stop     # 停止服务
ccr restart  # 重启服务
ccr status   # 查看状态

服务状态检测：

  • 检查PID文件是否存在

  • 验证进程是否真实运行

  • 检测端口是否被占用

5.5 UI模式：可视化配置管理

对于不喜欢编辑JSON的用户，项目提供了Web UI：

ccr ui

UI功能包括：

  • 配置编辑：可视化编辑config.json

  • 模型管理：添加/删除提供商和模型

  • 日志查看：实时查看服务日志

  • 状态监控：查看服务运行状态

  • 版本更新：检查并执行更新

UI的技术栈：

  • 前端：React + TypeScript + Vite

  • UI组件：shadcn/ui

  • 状态管理：React Hooks

  • API通信：Fetch API

UI的安全性：

  • 默认只监听127.0.0.1，防止外部访问

  • 支持APIKEY认证

  • 配置文件自动备份，防止误操作

5.6 CLI模型选择器：终端友好的交互

对于终端爱好者，项目提供了交互式CLI工具：

ccr model

功能特性：

  • 当前配置查看：显示所有路由配置

  • 快速切换模型：交互式选择模型

  • 添加新模型：向现有提供商添加模型

  • 创建新提供商：完整的提供商配置向导

  • Transformer配置：支持配置转换器选项

使用体验：

? 选择操作:
  ❯ 查看当前配置
    切换默认模型
    切换思考模型
    切换长上下文模型
    添加新模型
    创建新提供商
    退出

? 选择提供商:
  ❯ deepseek
    openrouter
    gemini
    ollama

? 选择模型:
  ❯ deepseek-chat
    deepseek-reasoner

这种交互式体验大大降低了配置门槛。

六、性能优化与监控

6.1 Token计算优化

实时Token计算是路由决策的基础，但也是性能瓶颈。项目使用tiktoken库，并做了优化：

const enc = get_encoding("cl100k_base");

export const calculateTokenCount = (messages, system, tools) => {
  let tokenCount = 0;
  
  // 优化1：只计算文本内容，跳过图片等
  messages.forEach((message) => {
    if (typeof message.content === "string") {
      tokenCount += enc.encode(message.content).length;
    } else if (Array.isArray(message.content)) {
      message.content.forEach((part) => {
        if (part.type === "text") {
          tokenCount += enc.encode(part.text).length;
        }
      });
    }
  });
  
  // 优化2：缓存工具定义的Token数
  // 工具定义通常不变，可以缓存计算结果
  
  return tokenCount;
};

性能数据：

  • 单次计算耗时：< 10ms（10K tokens）

  • 内存占用：< 50MB（tiktoken编码器）

  • 准确度：与官方API误差 < 5%

6.2 流式响应的零拷贝优化

流式响应处理中，项目使用了零拷贝技术：

// 使用tee()分流，避免重复读取
const [originalStream, clonedStream] = payload.tee();

// 原始流直接返回给客户端（零拷贝）
return done(null, originalStream);

// 克隆流用于后台统计（不阻塞主流）
read(clonedStream);

优势：

  • 零延迟：客户端立即收到数据

  • 低内存：不需要缓存完整响应

  • 并行处理：统计和转发同时进行

6.3 Status Line：实时状态监控

项目内置了状态行工具，可以集成到终端提示符：

ccr statusline

输入JSON格式的状态数据，输出格式化的状态行：

{
  "sessionId": "abc123",
  "model": "deepseek,deepseek-chat",
  "tokenCount": 15234,
  "cost": 0.05
}

输出：

[CCR] 🤖 deepseek-chat | 📊 15.2K tokens | 💰 $0.05

可以集成到各种终端（zsh、bash、fish）的提示符中，实时显示当前会话状态。

6.4 并发控制与限流

对于团队部署，项目支持并发控制：

{
  "API_TIMEOUT_MS": 600000,
  "MAX_CONCURRENT_REQUESTS": 10,
  "RATE_LIMIT": {
    "max": 100,
    "timeWindow": "1 minute"
  }
}

实现机制：

  • 超时控制：防止请求挂起

  • 并发限制：保护后端API

  • 速率限制：防止滥用

七、生态扩展与插件系统

7.1 Transformer插件机制

Claude Code Router的Transformer是可插拔的，支持自定义插件：

{
  "transformers": [
    {
      "path": "/path/to/custom-transformer.js",
      "options": {
        "customOption": "value"
      }
    }
  ]
}

自定义Transformer示例：

// custom-transformer.js
module.exports = class CustomTransformer {
  constructor(options) {
    this.options = options;
  }

  name = "custom";

  transformRequestIn(request) {
    // 请求预处理
    if (this.options.addTimestamp) {
      request.metadata = {
        ...request.metadata,
        timestamp: Date.now()
      };
    }
    return request;
  }

  async transformResponseOut(response) {
    // 响应后处理
    const json = await response.json();
    json.custom_field = this.options.customOption;
    return new Response(JSON.stringify(json), {
      headers: response.headers
    });
  }
};

社区已有的Transformer插件：

  • gemini-cli：通过Gemini CLI非官方支持Gemini

  • qwen-cli：通过Qwen CLI支持qwen3-coder-plus

  • rovo-cli：通过Atlassian Rovo支持GPT-5

  • chutes-glm：通过Chutes支持GLM 4.5

7.2 与Agent SDK的集成

Claude Code Router完美支持Anthropic Agent SDK，通过activate命令设置环境变量：

eval "$(ccr activate)"

这会设置以下环境变量：

export ANTHROPIC_AUTH_TOKEN="your-api-key"
export ANTHROPIC_BASE_URL="http://127.0.0.1:3456"
export NO_PROXY="127.0.0.1"
export DISABLE_TELEMETRY="true"
export DISABLE_COST_WARNINGS="true"

之后，所有使用Agent SDK的应用都会自动通过Router：

# Python Agent SDK示例
from anthropic import Anthropic

client = Anthropic()  # 自动使用环境变量配置

response = client.messages.create(
    model="claude-3-5-sonnet-20241022",  # 会被Router重定向
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}]
)

这意味着你可以：

  • 用DeepSeek运行官方的Agent示例

  • 用本地Ollama测试Agent应用

  • 在不修改代码的情况下切换模型

7.3 项目级配置：精细化管理

Claude Code支持项目（Project）概念，Router也支持项目级配置：

~/.claude-code-router/
  ├── config.json              # 全局配置
  └── my-project/
      ├── config.json          # 项目配置
      └── session-123.json     # 会话配置

配置优先级：

会话配置 > 项目配置 > 全局配置

应用场景：

  • 前端项目：使用擅长前端的模型

  • 后端项目：使用擅长后端的模型

  • 数据分析项目：使用擅长数学的模型

  • 文档项目：使用便宜的模型

实现原理：

const getProjectSpecificRouter = async (req) => {
  if (req.sessionId) {
    const project = await searchProjectBySession(req.sessionId);
    if (project) {
      // 优先读取会话配置
      const sessionConfig = await readConfigFile(
        `${HOME_DIR}/${project}/${req.sessionId}.json`
      );
      if (sessionConfig?.Router) return sessionConfig.Router;
      
      // 其次读取项目配置
      const projectConfig = await readConfigFile(
        `${HOME_DIR}/${project}/config.json`
      );
      if (projectConfig?.Router) return projectConfig.Router;
    }
  }
  return undefined; // 使用全局配置
};

八、实战经验与踩坑指南

8.1 常见问题与解决方案

问题1：DeepSeek长对话中不调用工具

症状：前几轮对话正常，后面开始用纯文本回复

原因：模型在长上下文中"忘记"了工具使用指令

解决方案：

{
  "transformer": {
    "use": ["deepseek"],
    "deepseek-chat": {
      "use": ["tooluse"]  // 启用强制工具模式
    }
  }
}
问题2：Gemini工具调用格式不兼容

症状：工具调用失败，返回格式错误

原因：Gemini对工具参数的format字段有严格限制

解决方案：

{
  "transformer": {
    "use": ["gemini"]  // 使用Gemini专用转换器
  }
}
问题3：长上下文任务Token超限

症状：请求失败，提示Token超出限制

原因：模型的上下文窗口不足

解决方案：

{
  "Router": {
    "longContext": "gemini,gemini-2.5-pro",
    "longContextThreshold": 60000  // 超过6万Token自动切换
  }
}
问题4：GitHub Actions中服务启动失败

症状：进程挂起，无法正常运行

原因：stdin处理导致的阻塞

解决方案：

{
  "NON_INTERACTIVE_MODE": true  // 启用非交互模式
}

8.2 性能调优建议

建议1：合理设置Token阈值
{
  "Router": {
    "longContextThreshold": 60000  // 根据实际情况调整
  }
}

  • 阈值太低：频繁切换模型，增加延迟

  • 阈值太高：可能超出模型限制

  • 推荐值：默认模型上下文窗口的70-80%

建议2：使用本地模型处理后台任务
{
  "Router": {
    "background": "ollama,qwen2.5-coder:latest"
  }
}

后台任务特点：

  • 频繁执行（文件监控、语法检查）

  • 简单快速（不需要复杂推理）

  • 成本敏感（累计调用次数多）

使用本地模型可以：

  • 零API成本

  • 低延迟（无网络请求）

  • 隐私保护（数据不出本地）

建议3：启用日志但控制级别
{
  "LOG": true,
  "LOG_LEVEL": "info"  // 生产环境用info，调试用debug
}

日志级别选择：

  • debug：开发调试，记录所有细节

  • info：生产环境，记录关键信息

  • warn：只记录警告和错误

  • error：只记录错误

建议4：配置合理的超时时间
{
  "API_TIMEOUT_MS": 600000  // 10分钟
}

超时时间考虑因素：

  • 模型响应速度（推理模型需要更长时间）

  • 任务复杂度（Plan模式可能需要多轮调用）

  • 网络状况（国际API可能较慢）

8.3 安全性最佳实践

实践1：使用环境变量管理密钥
# .env文件
DEEPSEEK_API_KEY=sk-xxx
OPENROUTER_API_KEY=sk-yyy
GEMINI_API_KEY=sk-zzz

{
  "Providers": [
    {
      "api_key": "$DEEPSEEK_API_KEY"
    }
  ]
}

优势：

  • 密钥不进入版本控制

  • 不同环境使用不同密钥

  • 便于密钥轮换

实践2：限制网络访问
{
  "HOST": "127.0.0.1",  // 只监听本地
  "APIKEY": "strong-random-key"  // 设置认证密钥
}

如果需要远程访问：

{
  "HOST": "0.0.0.0",
  "APIKEY": "strong-random-key"  // 必须设置
}
实践3：定期备份配置

Router会自动备份配置文件：

~/.claude-code-router/
  ├── config.json
  ├── config.json.2025-01-03T10-30-00.bak
  ├── config.json.2025-01-02T15-20-00.bak
  └── config.json.2025-01-01T09-10-00.bak

保留最近3个备份，防止误操作。

实践4：监控API使用情况

通过日志监控API调用：

# 统计今天的API调用次数
grep "API call" ~/.claude-code-router/claude-code-router.log | wc -l

# 统计各模型使用次数
grep "Using model" ~/.claude-code-router/claude-code-router.log | \
  awk '{print $NF}' | sort | uniq -c

九、未来展望与社区生态

9.1 项目演进方向

根据GitHub上的讨论和用户反馈，项目未来可能的发展方向：

方向1：更智能的路由算法

当前路由基于规则，未来可能引入：

  • 机器学习路由：根据历史数据学习最优模型选择

  • 成本优化算法：在性能和成本间自动平衡

  • A/B测试支持：对比不同模型的效果

方向2：更丰富的Agent生态

当前只有Image Agent和Tool Mode，未来可能添加：

  • Code Review Agent：专门的代码审查代理

  • Documentation Agent：自动生成和维护文档

  • Test Generation Agent：智能生成测试用例

  • Refactoring Agent：代码重构建议

方向3：企业级特性

  • 多租户支持：为不同团队/项目隔离配置

  • 审计日志：详细记录所有API调用

  • 配额管理：限制用户/项目的使用量

  • 计费系统：内部成本分摊

9.2 社区贡献与生态

截至目前，项目已经获得了活跃的社区支持：

赞助商生态

项目得到了多家AI服务商的赞助：

  • Z.ai（智谱AI）：提供GLM CODING PLAN支持

  • AIHubmix：多模型聚合平台

  • BurnCloud：AI云服务

  • 302.AI：AI工具集合

这些赞助商不仅提供资金支持，还贡献了：

  • 模型接入支持

  • 技术文档

  • 使用案例

  • 社区推广

开源贡献者

项目收到了大量社区贡献：

  • Transformer插件：gemini-cli、qwen-cli、rovo-cli等

  • Bug修复：各种边界情况处理

  • 文档改进：多语言文档、使用指南

  • 功能建议：UI改进、CLI增强

用户案例

真实用户的使用场景：

  • 个人开发者：用DeepSeek替代Claude，成本降低90%

  • 创业团队：统一AI网关，方便成本管理

  • 开源项目：GitHub Actions自动化代码审查

  • 教育机构：为学生提供AI编程助手

9.3 与其他工具的对比

特性 Claude Code Router LiteLLM OpenRouter 直接使用Claude
Claude Code支持 ✅ 原生支持 ❌ 需要适配 ❌ 需要适配 ✅ 原生支持
多模型路由 ✅ 智能路由 ✅ 基础路由 ❌ 单一入口 ❌ 单一模型
成本优化 ✅ 自动优化 ⚠️ 手动配置 ⚠️ 手动选择 ❌ 固定成本
本地模型支持 ✅ 完整支持 ✅ 支持 ❌ 不支持 ❌ 不支持
自定义路由 ✅ JS脚本 ⚠️ 有限 ❌ 不支持 ❌ 不支持
Agent系统 ✅ 内置Agent ❌ 无 ❌ 无 ⚠️ 官方Agent
部署难度 ⭐⭐ 简单 ⭐⭐⭐ 中等 ⭐ 极简 ⭐ 极简
地域限制 ✅ 无限制 ✅ 无限制 ⚠️ 部分限制 ❌ 有限制

Claude Code Router的独特优势：

  1. 专为Claude Code设计：完美兼容，无需适配

  2. 智能路由系统：根据任务自动选择模型

  3. 成本极致优化：混合使用本地和云端模型

  4. 高度可定制：支持自定义路由脚本和Transformer

十、总结：技术的温度与开源的力量

10.1 技术突破的意义

Claude Code Router不仅仅是一个技术项目，它代表了一种技术民主化的理念：

打破地域壁垒：让中国大陆的开发者也能享受顶级AI工具

降低使用门槛：从每月几十美元降到几美元，甚至免费

保护数据隐私：支持本地模型，敏感代码不出本地

促进技术创新：开放的架构激发社区创造力

10.2 从逆向到创新的启示

这个项目的诞生过程给我们几点启示：

1. 技术无国界：虽然有地域限制，但技术本身是开放的

2. 逆向不是目的：理解原理是为了更好地创新

3. 开源的力量：一个人的想法，变成了社区的成果

4. 用户至上：真正解决用户痛点的项目才有生命力

10.3 实用建议

如果你想尝试Claude Code Router，这里是一些建议：

新手入门：

  1. 先用UI模式配置，熟悉基本概念

  2. 从简单的default路由开始

  3. 逐步添加background、think等高级路由

  4. 尝试自定义路由脚本

进阶使用：

  1. 研究不同模型的特点，优化路由策略

  2. 开发自定义Transformer，适配特殊需求

  3. 集成到CI/CD流程，实现自动化

  4. 贡献代码或插件，回馈社区

企业部署：

  1. 评估安全性和合规性要求

  2. 设计多租户架构

  3. 建立监控和审计机制

  4. 制定成本控制策略

10.4 写在最后

Claude Code Router的故事告诉我们：技术的本质是服务人，而不是限制人。

当官方服务因为各种原因无法触达所有用户时，开源社区用技术搭建了一座桥梁。这座桥不仅连接了用户和AI，更连接了不同地域的开发者，连接了商业和开源，连接了现在和未来。

或许有一天，地域限制会消失，成本会降到可以忽略。但Claude Code Router所代表的开放、创新、共享的精神，将永远激励着技术社区前行。

附录：快速开始指南

安装

# 安装Claude Code
npm install -g @anthropic-ai/claude-code

# 安装Claude Code Router
npm install -g @musistudio/claude-code-router

最小配置

{
  "Providers": [
    {
      "name": "deepseek",
      "api_base_url": "https://api.deepseek.com/chat/completions",
      "api_key": "sk-your-key",
      "models": ["deepseek-chat"]
    }
  ],
  "Router": {
    "default": "deepseek,deepseek-chat"
  }
}

启动使用

# 启动服务
ccr start

# 使用Claude Code
ccr code "帮我写一个Hello World"

# 或者设置环境变量后直接用claude命令
eval "$(ccr activate)"
claude "帮我写一个Hello World"

常用命令

ccr status      # 查看服务状态
ccr ui          # 打开Web界面
ccr model       # 交互式选择模型
ccr restart     # 重启服务
ccr stop        # 停止服务

获取帮助

  • GitHub仓库：https://github.com/musistudio/claude-code-router

  • Discord社区：https://discord.gg/rdftVMaUcS

  • 中文文档：README_zh.md

  • 问题反馈：GitHub Issues

更多AIGC文章

RAG技术全解：从原理到实战的简明指南

更多VibeCoding文章

# 人工智能
Logo
2048 AI社区

有“AI”的1024 = 2048，欢迎大家加入2048 AI社区

更多推荐

cover

2025继续教育必备8个降AI率工具测评榜单

avatar 2048 AI社区

AI原生应用领域用户体验优化的案例分析

回到文章开头的问题：为什么很多AI应用没人用？因为它们的AI“不懂用户”——不懂用户的场景、不懂用户的需求、不懂用户的焦虑。Notion AI用“场景化模板”，懂用户“不知道该问什么”；Figma AI用“渐进式生成”，懂用户“需要可控感”；Slack GPT用“场景感知”，懂用户“需要相关的回答”。AI原生应用的UX优化，从来不是“优化AI的技术”，而是“优化AI与用户的关系”——让AI从“技术

avatar 2048 AI社区
cover

科研绘图不用愁！虎贲等考 AI 打破 “专业壁垒”，让数据可视化更高效出彩

avatar 2048 AI社区