【Claude Code Router】 Claude Code 兼容 OpenAI 格式 API, Claude code 接入本地部署模型

1. Claude Code Router 功能介绍

Claude Code Router GitHub: https://github.com/musistudio/claude-code-router

参考博客1: https://rosetears.cn/archives/61/
cc switch ：https://github.com/farion1231/cc-switch

Claude Code 是 Anthropic 官方推出的 AI 编程助手 CLI 工具，默认使用 Claude 模型。Claude Code Router 是一个开源的路由工具，允许我们将 Claude Code 的请求转发到其他兼容 OpenAI API 格式的模型服务，实现灵活的模型切换和统一管理。

本文将介绍 Claude Code Router 的功能特点，并详细讲解安装配置步骤。

1.1 核心功能

Claude Code Router 主要提供以下能力：

功能	说明
多模型路由	支持配置多个模型提供商，按需切换使用不同模型
请求转发	将 Claude Code 的请求转换为 OpenAI 兼容格式，转发到目标模型服务
统一认证	支持设置统一的 API Key，简化认证管理
Web 管理界面	提供可视化配置界面，方便管理 Providers 和路由规则
日志记录	完整的请求日志，便于调试和问题排查

1.2 典型使用场景

• 使用本地部署的 LLM 模型（如 vLLM、Ollama）
• 接入国内大模型服务（如通义千问、智谱 AI、字节跳动）
• 多模型负载均衡和切换测试
• claude code router 配置不是热更新，每次完成之后需要利用ccr restart 重启才会生效

2. 安装步骤

2.1 前置条件

首先确保已安装 Claude Code：

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

2.2 安装 Claude Code Router

通过 npm 全局安装：

npm install -g @musistudio/claude-code-router

3. 配置详解

3.1 配置文件位置

配置文件位于 ~/.claude-code-router/config.json。

{
  "PORT": 3456,
  "Providers": [],
  "Router": {}
}

3.2 base_url 路径说明

配置中的 api_base_url 需要填写完整的 API 端点路径：

服务类型	base_url 示例	说明
OpenAI 官方	https://api.openai.com/v1/chat/completions	OpenAI 官方 API
通义千问 OpenAI 兼容	https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions	阿里云 DashScope
通义千问 Coding	https://coding.dashscope.aliyuncs.com/v1/chat/completions	阿里云编码专用
字节跳动火山引擎	https://ark.cn-beijing.volces.com/api/coding/v3/chat/completions	火山引擎编码 API
本地 vLLM	http://localhost:8000/v1/chat/completions	本地部署模型
Ollama OpenAI 兼容	http://localhost:11434/v1/chat/completions	Ollama 服务

注意 ：api_base_url 必须包含完整的 API 路径 /v1/chat/completions 或对应服务的完整端点，不能只填写域名。

3.3 最小配置示例

以下是一个配置本地 vLLM 服务的基础示例：

{
  "APIKEY": "your-secret-key",
  "LOG": true,
  "API_TIMEOUT_MS": 600000,
  "NON_INTERACTIVE_MODE": false,
  "Providers": [
    {
      "name": "local-vllm",
      "api_base_url": "http://localhost:8000/v1/chat/completions",
      "api_key": "sk-dummy",
      "models": ["Qwen2.5-72B"]
    }
  ],
  "Router": {
    "default": "local-vllm,Qwen2.5-72B"
  }
}

3.4 多提供商配置示例

配置多个模型提供商，实现灵活切换：

{
  "PORT": 3456,						    // 登陆ui界面的端口
  "APIKEY": "your-router-key", 			// 这个是用于登陆ui界面用的
  "LOG": true,
  "API_TIMEOUT_MS": 600000,
  "NON_INTERACTIVE_MODE": false,
  "Providers": [
    {
      "name": "volcano",
      "api_base_url": "https://ark.cn-beijing.volces.com/api/coding/v3/chat/completions",
      "api_key": "sk-volcano-xxx",
      "models": ["doubao-pro-32k"]
    },
    {
      "name": "aliyun-qwen",
      "api_base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions",
      "api_key": "sk-aliyun-xxx",
      "models": ["qwen-plus", "qwen-max"]
    },
    {
      "name": "local-vllm",
      "api_base_url": "http://10.2.5.7:8000/v1/chat/completions",
      "api_key": "sk-dummy",
      "models": ["Qwen2.5-72B-Instruct"]
    }
  ],
  "Router": {
    "default": "aliyun-qwen,qwen-plus",
    "background": "local-vllm,Qwen2.5-72B-Instruct"
  }
}

3.5 配置字段说明

字段	必填	说明
PORT	否	Router 服务端口，默认 3456
APIKEY	否	Router 认证密钥，客户端需在 Header 中提供
LOG	否	是否启用日志，默认 true
API_TIMEOUT_MS	否	API 调用超时时间（毫秒），默认 600000
NON_INTERACTIVE_MODE	否	非交互模式，适用于 CI/CD 环境
Providers	是	模型提供商列表
Router	是	路由规则配置

Router 配置说明：

• default: 默认使用的模型，格式为 提供商名称,模型名称
• background: 后台任务使用的模型（可选）

4. 启动与使用

4.1 启动 Claude Code

使用 ccr code 命令启动：相当于启动claude

ccr code

这会启动 Router 服务并运行 Claude Code CLI。

4.2 Web 管理界面

启动后可通过浏览器访问管理界面：

http://127.0.0.1:3456/ui/

或使用命令启动 UI 模式：

ccr ui

在 Web 界面中可以可视化地管理配置：

4.3 重启服务

重要提示 ：Claude Code Router 不支持热更新。修改配置文件后，必须重启服务才能生效。

重启命令：

ccr restart

如果在运行 ccr code 期间修改了配置，需要退出当前会话后重新启动。

5. 日志文件

Claude Code Router 使用两个独立的日志系统：

日志类型	位置	内容
服务器日志	~/.claude-code-router/logs/ccr-*.log	HTTP 请求、API 调用、服务器事件
应用日志	~/.claude-code-router/claude-code-router.log	路由决策、业务逻辑事件

可通过 LOG_LEVEL 配置项调整日志级别：fatal、error、warn、info、debug、trace，默认 debug。

6. 常见问题

# 这样启动clade coe不会触发ccr的默认 默认用之前的配置
claude
# 这样才会启动ccr 的配置
ccr code

6.1 配置后无法连接模型服务

解决方案：

1. 检查 api_base_url 是否包含完整路径 /v1/chat/completions
2. 确认网络可达性，本地部署需检查端口是否开放
3. 查看 ~/.claude-code-router/logs/ 目录下的日志文件

6.2 如何在 CI/CD 环境中使用

解决方案 ：

设置 NON_INTERACTIVE_MODE 为 true：

{
  "NON_INTERACTIVE_MODE": true
}

这会自动设置 CI=true 和 FORCE_COLOR=0 等环境变量。

6.3 多个模型如何切换

解决方案 ：

通过修改 Router.default 配置切换默认模型，或在 Web 界面中直接选择。

7. 同类产品：CC-Switch

除了 Claude Code Router，还有一款功能更丰富的同类工具------CC-Switch。

7.1 CC-Switch 简介

cc switch GitHub 地址 ：https://github.com/farion1231/cc-switch

参考博客2: https://blog.csdn.net/qq_45056135/article/details/160694324?spm=1001.2014.3001.5502

CC-Switch 是一个桌面应用程序，可以统一管理 Claude Code、Codex、Gemini CLI、OpenCode 和 OpenClaw 五个 CLI 工具。它提供了可视化界面，内置 50+ 供应商预设，无需手动编辑配置文件即可一键切换模型供应商。

7.2 两款工具对比

特性	Claude Code Router	CC-Switch
形式	CLI 工具	桌面应用（GUI）
支持工具	仅 Claude Code	Claude Code、Codex、Gemini CLI、OpenCode、OpenClaw
供应商预设	需手动配置	内置 50+ 供应商预设
配置方式	JSON 配置文件	可视化界面
路由功能	✅ 支持	✅ 支持（路由模式）
MCP/Skills 管理	❌ 不支持	✅ 统一管理面板
系统托盘	❌ 不支持	✅ 支持快速切换
跨平台	macOS、Linux	Windows、macOS、Linux
配置热更新	❌ 需重启	✅ Claude Code 支持热切换

7.3 选择建议

• Claude Code Router：适合习惯 CLI 操作的用户，配置简单直接，适合服务器环境或自动化脚本场景。
• CC-Switch：适合需要图形界面的用户，功能更全面，支持多工具统一管理和 MCP/Skills 配置同步，桌面体验更友好。

两款工具的核心能力都是通过路由模式让 Claude Code 使用 OpenAI 兼容格式的 API，根据个人使用习惯选择即可。

---

总结

Claude Code Router 提供了一种灵活的方式来扩展 Claude Code 的模型选择范围，特别适合以下场景：

• 需要使用国内大模型服务
• 本地部署 LLM 进行开发和测试
• 多模型对比和切换

通过简单的 JSON 配置即可完成多模型接入，Web 管理界面进一步降低了使用门槛。

参考资料

• Claude Code Router GitHub
• cc-switch
• 参考博客1
• 参考博客2

---

本文为个人学习笔记，如有错误请指正。