06. ccswitch 配置国产大模型

⚠️ 本章你需阅读官方文档最新版本

本教程引用 https://ccswitch.io/zh/docs?section=getting-started 请参考最新版本。 CC-Switch 是一个用于 Claude Code 路由到第三方大模型的工具。 可通过图形化配置正常使用，本章内容为原理解释加深理解。

本章会:

1. 介绍 Claude Code 路由到第三方大模型的通用原理(可验证的事实)，配置 ccswitch/代理 请参考官方最新版本。本章其他内容做原理和深入解释。

2. 给出基于通用做法的配置示例(可直接照搬)

3. 标注了需要您对照 ccswitch 官方文档确认的具体细节(命令、配置项路径等)

如果你熟悉 ccswitch,欢迎在文档仓库提 PR 修正。

🔒 安全提示:本文档所有示例中的 YOUR_API_KEY / sk-xxx 都为占位符。绝不要把真实 API Key 提交到 Git 仓库或公开文档。如果已经泄露,请立即到对应 provider 控制台撤销并重新生成。
sk-ba24595f581c44b99f422c4af76fbe15

一、为什么需要"切换"?

Claude Code 默认只和 Anthropic 的 API 通信:

[Claude Code] → https://api.anthropic.com → Claude 模型

在国内网络环境下:

• Anthropic API 难以直接访问
• 想要用国产大模型(Qwen/DeepSeek/Kimi/GLM)替代 Claude 模型
• 想要在不同模型间快速对比

解决思路:在 Claude Code 和真正的 LLM 之间,加一层"中间人",把请求翻译成对应 LLM 的格式。

[Claude Code] → [ccswitch / 代理] → 真正的 LLM(国产或 Claude)

二、Claude Code 路由的通用原理

无论用 ccswitch 还是其他工具,核心就两个环境变量:

加上 ccswitch/代理后,流程变成:

1. Claude Code 按 Anthropic API 格式 发请求
2. 请求发到 ANTHROPIC_BASE_URL 指定的地址(就是 ccswitch/代理的地址)
3. ccswitch/代理把请求翻译成目标 LLM 的格式(OpenAI 兼容 / 自定义)
4. 转发到真正的 LLM(DeepSeek/Qwen/...)
5. 响应按原路返回

这意味着:Claude Code 本身不需要改,所有切换在 ccswitch 那一层做。

三、ccswitch 工具介绍

官网:https://ccswitch.io/
官方文档(待您确认):https://ccswitch.io/zh/docs?section=getting-started
GitHub(待确认):请在官网底部或搜索 ccswitch 找到源代码仓库

定位

一款管理 Claude Code 后端的桌面 / CLI 工具,帮用户在 Anthropic 官方与国产/海外多家 LLM provider 之间一键切换。

从命名(cc switch = Claude Code switch)与同类工具(CCR、claude-code-router)对比,它的核心卖点是:给非技术教师一个低门槛的图形界面——点点鼠标就能切换后端模型,不用碰配置文件。

主要功能(基于同类工具 + 用户反馈)

具体功能以 ccswitch 官方文档为准。

谁该用 ccswitch?

与"手动配 ANTHROPIC_BASE_URL"的对比

如果 ccswitch 是闭源且不能审计代码,生产环境建议仍用 claude-code-router 这类开源方案。教学场景用 ccswitch 完全没问题。

四、安装 ccswitch

请以下方"通用 npm 工具"模式作为参考,具体安装命令以 ccswitch 官方文档为准。

通用做法(如果 ccswitch 是 npm 发布的 CLI)

# macOS / Linux
npm install -g ccswitch

# Windows (PowerShell)
npm install -g ccswitch

如果 ccswitch 提供自己的安装脚本(类似 Claude Code 官方脚本),则:

# 仅作示意,实际命令以官网为准
curl -fsSL https://ccswitch.io/install.sh | bash

Windows + npm 验证安装:

ccswitch --version
# 期望输出形如: ccswitch 1.x.x

如果命令找不到,确认 npm 全局 bin 目录在 PATH:

# 查看 npm 全局 bin 目录
npm config get prefix
# 通常是: C:\Users\<你>\AppData\Roaming\npm
# 把它加到"系统环境变量 → Path"中

💡 提示:ccswitch 官方可能同时提供桌面 GUI 安装包(.exe / .dmg / .AppImage),如果不想用 npm,可以到 https://ccswitch.io/download 直接下载安装。教师/学生强烈推荐这种方式——双击安装,跟装 QQ 一样简单。

五、图形化(GUI)配置 ⭐ 推荐教师使用

本节是面向零基础教师的主要上手路径。 全程鼠标点选,不需要敲命令。

以下为基于同类 GUI 工具(CCR UI、ChatBox 等)经验的标准流程,具体界面以 ccswitch 实际版本为准。

步骤 1:打开 ccswitch

安装后:

• Windows:开始菜单 → 找到 "ccswitch" → 单击启动
• macOS:启动台(Lauchpad)→ 找到 "ccswitch" → 单击
• Linux:应用菜单 → ccswitch,或在终端跑 ccswitch --gui

启动后应该看到类似这样的窗口(布局示意):

┌────────────────────────────────────────────────┐
│  ccswitch                              [— □ ×]│
├────────────────────────────────────────────────┤
│  Provider 列表        │  当前激活              │
│  ● DeepSeek  ←选中    │  当前:DeepSeek         │
│  ○ Qwen 通义千问      │  模型:deepseek-chat    │
│  ○ Kimi 月之暗面      │  状态:🟢 运行中       │
│  ○ GLM 智谱           │                        │
│  ○ Claude 官方        │  [设为默认] [测试连接] │
│  [+ 添加 Provider]    │                        │
├────────────────────────────────────────────────┤
│  路由规则:                              [编辑]│
│  · 默认 → DeepSeek / deepseek-chat           │
│  · 长上下文 → Kimi / moonshot-v1-128k        │
│  · 思考模式 → DeepSeek / deepseek-reasoner   │
├────────────────────────────────────────────────┤
│  [切换 Provider]  [打开 Claude Code]  [设置]  │
└────────────────────────────────────────────────┘

步骤 2:添加你的第一个 Provider(以 DeepSeek 为例)

2.1 准备好 API Key

先去 DeepSeek 开放平台 注册并创建 API Key:

1. 注册/登录(手机号即可)
2. 左侧 "API Keys" → "创建新 Key"
3. 复制 Key,妥善保存(只显示一次!)
4. 充值(新用户通常有免费额度)

2.2 在 ccswitch 里添加

1. 点击左下角 "+ 添加 Provider" 按钮

2. 在弹出的对话框里填写:

   字段	填写示例(DeepSeek)
   名称(自定义)	DeepSeek 教学用
   类型	OpenAI 兼容
   Base URL	https://api.deepseek.com/v1
   API Key	sk-YOUR_DEEPSEEK_KEY ← 粘贴刚才复制的
   默认模型	deepseek-chat
   备选模型	deepseek-coder / deepseek-reasoner

3. 点击 "测试连接" —— ccswitch 会发一个 hello 请求验证 Key 是否有效

4. ✅ 看到 "连接成功" 后,点击 "保存"

2.3 设为当前激活

回到主界面,选中刚才添加的 Provider,点击 "设为默认" 或 "切换"。

ccswitch 会自动:

• 设置 ANTHROPIC_BASE_URL 环境变量(指向 ccswitch 的本地代理,如 http://127.0.0.1:xxxx)
• 设置 ANTHROPIC_API_KEY 为对应 provider 的 Key
• 启动本地代理服务(后台)

步骤 3:验证 Claude Code 走新后端

打开终端(PowerShell / cmd),在任何目录跑:

claude
# 现在看到的 Claude Code 界面,请求实际由 DeepSeek 处理

试一个中文任务验证:

> 用中文给我写一段"递归计算斐波那契数列"的 Python 代码

如果返回正确的中文回答 → 配置成功 ✅

步骤 4:添加更多 Provider(可选)

按同样流程,添加 Qwen / Kimi / GLM。推荐先加 2-3 个常用:

添加后,在主界面点选即可切换,无需重启 Claude Code。

步骤 5:配置路由规则(可选但推荐)

ccswitch(类似 CCR)支持任务感知路由——不同类型的请求自动走不同模型。

在主界面点击 "路由规则 → 编辑",典型配置:

路由规则的具体名称和触发条件,以 ccswitch 官方文档为准。

常见 GUI 操作

六、命令行(CLI)配置

习惯用命令行的开发者可以走 CLI。本节保留 CLI 用法,作为 GUI 的备选。

一般性流程

一般性流程

# 1. 初始化(创建配置文件)
ccswitch init
# 通常会在 ~/.ccswitch/ 或 ~/.claude/ 下创建配置文件

# 2. 添加一个 provider
ccswitch add deepseek
# 按提示输入:
#   - API Key: sk-xxxxxxxxxxxxxx
#   - 自定义名称: My DeepSeek(可选)
#   - 选模型: deepseek-chat / deepseek-coder / deepseek-reasoner

# 3. 设置为当前激活的 provider
ccswitch use deepseek
# 这会把 ANTHROPIC_BASE_URL 改成 ccswitch 的本地代理地址
# 并把 ANTHROPIC_API_KEY 设成你刚配置的 Key

# 4. 验证
claude --version   # Claude Code 本身不变
claude             # 现在请求会通过 ccswitch 转到 DeepSeek

典型配置文件位置

七、手动配置(不依赖 ccswitch 也能用)

如果 ccswitch 暂时不可用,或者你想完全自己控制配置,可以直接配环境变量。

方案 A:用支持 Anthropic 格式的代理服务

有些第三方服务(OneAPI、new-api、自建网关)提供Anthropic 兼容端点,把 ANTHROPIC_BASE_URL 指向它即可:

# PowerShell
$env:ANTHROPIC_BASE_URL = "https://你的代理地址/v1"
$env:ANTHROPIC_API_KEY = "你的统一 Key"
claude

或者直接用支持 OpenAI 兼容 + Anthropic 转发的服务,把后端接到 DeepSeek / Qwen / GLM。

方案 B:用 claude-code-router(开源替代品,确实存在)

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

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

配置 ~/.claude-code-router/config.json:

{
  "Providers": [
    {
      "name": "deepseek",
      "api_base_url": "https://api.deepseek.com/v1/chat/completions",
      "api_key": "sk-YOUR_DEEPSEEK_KEY",
      "models": ["deepseek-chat", "deepseek-coder"]
    },
    {
      "name": "qwen",
      "api_base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions",
      "api_key": "sk-YOUR_QWEN_KEY",
      "models": ["qwen-plus", "qwen-coder-plus"]
    },
    {
      "name": "kimi",
      "api_base_url": "https://api.moonshot.cn/v1/chat/completions",
      "api_key": "sk-YOUR_KIMI_KEY",
      "models": ["moonshot-v1-128k"]
    },
    {
      "name": "glm",
      "api_base_url": "https://open.bigmodel.cn/api/paas/v4/chat/completions",
      "api_key": "YOUR_GLM_KEY",
      "models": ["glm-4-plus", "glm-4-flash"]
    }
  ],
  "Router": {
    "default": "deepseek,deepseek-chat",
    "background": "deepseek,deepseek-chat",
    "think": "deepseek,deepseek-reasoner",
    "longContext": "kimi,moonshot-v1-128k"
  }
}

启动:

ccr start
# ccr 会启动一个本地代理,默认监听 http://127.0.0.1:3456

设置 Claude Code:

$env:ANTHROPIC_BASE_URL = "http://127.0.0.1:3456"
$env:ANTHROPIC_API_KEY = "随便填(本地的,不会校验)"
claude

八、配置详解:每个 provider 怎么接

DeepSeek

{
  "api_base_url": "https://api.deepseek.com/v1/chat/completions",
  "api_key": "sk-从 https://platform.deepseek.com 获取",
  "models": ["deepseek-chat", "deepseek-reasoner", "deepseek-coder"]
}

特点:OpenAI 兼容,直接换 base_url 即可。

通义千问(阿里云百炼)

{
  "api_base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions",
  "api_key": "sk-从 https://bailian.console.aliyun.com 获取",
  "models": ["qwen-plus", "qwen-max", "qwen-coder-plus", "qwen2.5-72b-instruct"]
}

特点:阿里云百炼提供 OpenAI 兼容模式,需要把 base_url 加 /compatible-mode。

Kimi(月之暗面)

{
  "api_base_url": "https://api.moonshot.cn/v1/chat/completions",
  "api_key": "sk-从 https://platform.moonshot.cn 获取",
  "models": ["moonshot-v1-8k", "moonshot-v1-32k", "moonshot-v1-128k", "kimi-k2"]
}

特点:OpenAI 兼容,有 8K/32K/128K 三档上下文。

GLM(智谱)

{
  "api_base_url": "https://open.bigmodel.cn/api/paas/v4/chat/completions",
  "api_key": "从 https://bigmodel.cn 获取",
  "models": ["glm-4-plus", "glm-4-flash", "glm-4-long", "codegeex-4"]
}

特点:OpenAI 兼容,注意 base_url 是 /v4/chat/completions(百炼是 /compatible-mode/v1/)。

九、推荐配置(教学场景)

机房/学生机部署的"省心"方案:

{
  "default": "deepseek,deepseek-chat",
  "longContext": "kimi,moonshot-v1-128k",
  "think": "deepseek,deepseek-reasoner"
}

理由:

• 默认用 DeepSeek——便宜、够用,大量普通对话不心疼
• 长上下文任务(读整本 PDF)走 Kimi
• 需要思考(复杂算法/数学题)走 DeepSeek-Reasoner

十、常见问题

Q1:切换后 Claude Code 报错"模型不存在"?

不同 provider 的 model 名称不同。检查:

• 你在 ccswitch/路由里配置的模型名是否在 provider 那边真实存在
• 比如 DeepSeek 就没有 claude-sonnet-4-6,要用 deepseek-chat

Q2:想用一段时间 Claude,一段时间国产模型

ccswitch 类工具的设计就是为了这个:

• 多个 profile 保存
• 一条命令切换
• 比如 ccswitch use claude 切回官方

Q3:代理有安全风险吗?

有。任何中间代理都能看到你的请求内容。原则:

• 用知名开源的代理(如 claude-code-router 代码可审计)
• 自建代理不要对外开放
• API Key 只在本地用,不要上传到云代理

Q4:在 Windows PowerShell 怎么持久化环境变量?

# 用户级(推荐)
[System.Environment]::SetEnvironmentVariable('ANTHROPIC_BASE_URL', 'http://127.0.0.1:3456', 'User')

# 系统级(需管理员)
[System.Environment]::SetEnvironmentVariable('ANTHROPIC_BASE_URL', 'http://127.0.0.1:3456', 'Machine')

# 立即生效(本会话)
$env:ANTHROPIC_BASE_URL = "http://127.0.0.1:3456"

Q5:学生怎么用?要不要给每个学生分配 Key?

推荐:

• 每个学生用各自的 API Key——避免一个刷爆全班的额度
• 在 ccswitch/路由里限制可用模型——避免学生用昂贵的
• 给学生讲清楚"这个 Key 是你的,自己保管,丢了找我"

十一、动手做一遍(推荐流程)

1. 装 Node.js(LTS 版)
2. 注册一个 DeepSeek 账号,领免费额度
3. 装 ccswitch(命令以官方文档为准)
4. ccswitch add deepseek 配进去
5. ccswitch use deepseek 切换
6. 在项目目录跑 claude,看是否正常工作
7. 测试一个中文任务:让它帮你写段中文注释,验证中文能力
8. 测试一个编程任务:让它帮你 debug 一段 Python,验证代码能力

如果第 6 步报错,看 ccswitch 日志(通常在 ~/.ccswitch/logs/ 或类似位置)。

十二、教学实战案例:用 DeepSeek 做编程课教学

⚠️ 安全提醒:本节所有 API Key、模型名均为占位符示例。绝不要把真实 Key 写进文档/提交到 Git。

案例背景

某高校计算机系教师开设"Python 程序设计"课程,学生 60 人,机房统一 Windows 10。

目标:让学生用 Claude Code 辅助编程练习,降低使用门槛 + 控制成本。

方案:教师统一配置 ccswitch 指向 DeepSeek,学生开机即用,无需关心底层配置。

配置清单(以 GUI 为例)

1. 教师在机房教师机配置

启动 ccswitch,添加 Provider:

关于模型名:deepseek-chat 是 DeepSeek-V3 系列对话模型;deepseek-coder 是代码专用模型;deepseek-reasoner 是带思考过程的推理模型(对应 R1)。

⚠️ 如果您指的是其他模型(例如某个叫"deepseek4"的内部或第三方模型),请把准确的 模型 ID 填入 ccswitch 的"模型"字段,模型 ID 必须与 provider 那边完全一致,否则会报"模型不存在"。

点 "测试连接" → 看到 "成功" 后保存。

2. 设置路由规则

3. 导出配置,分发给 60 台学生机

ccswitch 通常支持:

设置 → 导出配置 → 生成 ccswitch-export.json

把这个文件 + 安装包,放到机房文件服务器/共享盘。

4. 学生机一键导入

学生机(已经有 ccsswitch)上:

ccswitch import ccswitch-export.json

或者在 GUI 里:

设置 → 导入配置 → 选择文件 → 完成

5. 学生使用

学生打开 PowerShell,任意目录:

cd D:\projects\my-homework
claude
# 出现 Claude Code 界面
# 问:"帮我用 Python 写一个冒泡排序"
# → 实际由 DeepSeek 回答

学生完全不知道背后是 DeepSeek,体验和用 Claude 一样。

成本估算

DeepSeek 极低成本是它在教学场景的核心优势。

注意事项

• 教师自己的 Key 有额度上限:建议监控用量,在 ccswitch 里设每日上限
• 学生可以本地切换回"无 LLM"或测试模式:教学评估时关掉
• 不要把教师 Key 分给学生用:用一个学生刷爆全班额度就尴尬了
• 每学期初更新一下 Key,避免泄露后被滥用

十三、本章需要您确认的部分(对照 ccswitch 官方文档)

把 ccswitch 的官方文档打开,逐项核对以下内容,如果有出入请告知或在仓库提 PR:

• ccswitch 官方下载链接(是 https://ccswitch.io/download 还是别处?)
• ccswitch 是否提供桌面安装包(Windows .exe / macOS .dmg / Linux .AppImage?)
• ccswitch 导出/导入配置的菜单项名称
• ccswitch 路由规则的字段名(default / longContext / think 这种命名对吗?)
• ccswitch 用量统计的具体指标(按 token? 按请求? 按 provider?)
• ccswitch 是否开源?(决定了生产环境可信度)
• ccswitch 是否支持自定义 Base URL 还是只能选预置 provider?
• "deepseek4" 是不是一个真实模型 ID?(如果不是,正确的模型名是?)

下一步

• 想知道怎么自己写 Skill → 09. 自定义 Skill 开发
• 想看实际教学场景应用 → 04. 教学场景实战