Claude Code 采用cc-switch配置第三方模型的完全指南

-

从零开始，手把手带你安装 Claude Code 和 cc-switch，实现无需翻墙、一键切换国产大模型，丝滑开启 AI 编程。

0. 写在前面：这篇教程解决什么问题

你可能已经听说过 Claude Code —— Anthropic 官方的终端 AI 编程助手，能直接在命令行里读代码、写代码、跑测试、操作 Git。但国内用户上手时，往往卡在三道坎上：

  1. 网络不通：Claude Code 需要连接 Anthropic API，国内直连基本超时
  2. 账号难搞：Anthropic 官方账号需要海外手机号注册
  3. 模型切换麻烦：今天想用 Claude，明天想试 DeepSeek，每次手动改配置文件

cc-switch 就是来填这些坑的。它是一个跨平台桌面应用，专为 Claude Code 等 AI 命令行助手设计，核心能力是：图形化管理多个 API 供应商，一键切换模型，自动完成协议转换。

读完这篇，你将拥有一个开箱即用的 AI 编程环境 —— 无论选择 Claude 中转还是国产大模型，都能在终端里直接 claude 开干。

一、cc-switch 是什么？适不适合你？

1.1 一句话说清楚

cc-switch 是一个本地运行的 API 路由 + 配置管理器。它不卖模型额度，也不替你聊天，而是帮你：

  • 管理多个 API 供应商的配置（Key、地址、模型名）
  • 一键切换不同供应商，不用手改 settings.json
  • 自动完成协议转换（Anthropic 格式 ↔ OpenAI 格式 ↔ 国产模型格式）
  • 支持本地代理模式，让 Claude Desktop 也能用第三方模型

数据流长这样：

Claude Code (终端)
    ↓ 发起 Anthropic 格式请求
cc-switch (本地代理)
    ├─ 解析请求头与 Body
    ├─ 匹配当前启用的供应商
    ├─ 协议转换：Anthropic → 目标模型兼容格式
    ├─ 替换鉴权 Key、注入 System Prompt
    ├─ 转发至目标 API
    └─ 接收响应 → 逆向转换 → 返回 Claude Code 期望的格式

1.2 你需要 cc-switch 吗

场景 需要？
只有官方 Claude 账号，只用 Claude 模型 ❌ 不需要，直接登录即可
想用国产大模型（DeepSeek、Kimi 等）跑 Claude Code ✅ 需要
同时用多个 API 供应商，频繁切换 ✅ 需要
想让 Claude Desktop 也能接第三方模型 ✅ 需要
公司有统一 API 网关 ✅ 需要

💡 新手建议：如果你刚开始用 Claude Code，建议先把官方安装跑通，再考虑 cc-switch。否则分不清是 Claude Code 没装好，还是 cc-switch 配置没生效。

1.3 支持的 AI 编程工具

cc-switch 不仅管 Claude Code，它支持一整套 AI 命令行工具：

工具 热切换支持 配置文件位置
Claude Code ✅ 即时生效 ~/.claude/settings.json
Codex ❌ 需重启终端 ~/.codex/auth.json + config.toml
Gemini CLI ✅ 即时生效 ~/.gemini/
OpenCode ❌ 需重启终端 对应配置文件
OpenClaw ❌ 需重启终端 对应配置文件

二、前置准备

2.1 系统要求

项目 最低要求 推荐
操作系统 Windows 10+ / macOS 12+ / Linux Windows 11 / macOS 14+
Node.js v18 LTS v20+ LTS
网络环境 能访问国内互联网 稳定网络

2.2 安装 Node.js

Claude Code 和 cc-switch 管理的工具都需要 Node.js 环境。

Windows：

  1. 访问 Node.js 官网
  2. 下载 LTS 版本
  3. 双击安装，一路下一步
  4. 验证：
node -v    # v20.x.x 或更高
npm -v     # 10.x.x 或更高

macOS：

# Homebrew 安装
brew install node

# 或用 nvm（推荐开发者）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install --lts

Linux：

# Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs

# 或用 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install --lts

三、安装 Claude Code

3.1 Windows 一键安装

irm https://claude.ai/install.ps1 | iex

这是 Anthropic 官方推荐的 Windows 安装方式。

3.2 npm 全局安装（通用）

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

国内下载慢？用淘宝镜像：

npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com

💡 如果经常下载慢，可以全局设置镜像源：npm config set registry https://registry.npmmirror.com

3.3 macOS Homebrew 安装

brew install claude-code

3.4 验证安装

claude --version

看到版本号就说明安装成功。

3.5 常见安装问题

claude 命令找不到：

npm 全局 bin 目录没加到 PATH。临时修复：

# PowerShell
$env:PATH += ";C:\Users\<你的用户名>\AppData\Roaming\npm"

永久修复：系统属性 → 高级 → 环境变量 → 用户变量 Path → 添加 C:\Users\<用户名>\AppData\Roaming\npm。

权限不足（Windows）： 右键 PowerShell → 以管理员身份运行。

四、安装 cc-switch

⚠️ 安全提醒：只从 ccswitch.io 或 GitHub Releases 下载。任何要求付费充值、索取账号密码的 "CC Switch" 都不是官方渠道。

4.1 Windows 安装

方式一：安装包（推荐）

  1. 访问 GitHub Releases
  2. 下载 CC-Switch-v{版本号}-Windows.msi
  3. 双击运行安装

如果安装程序双击无反应，右键文件 → 属性 → 常规 → 勾选 " 解除锁定 "

方式二：绿色版（免安装）

# 下载便携版
Invoke-WebRequest -Uri "https://github.com/farion1231/cc-switch/releases/latest/download/CC-Switch-Windows-Portable.zip" -OutFile "$env:USERPROFILE\Downloads\CC-Switch-Portable.zip"

# 解压到桌面
Expand-Archive -Path "$env:USERPROFILE\Downloads\CC-Switch-Portable.zip" -DestinationPath "$env:USERPROFILE\Desktop\CC-Switch"

# 启动
Start-Process "$env:USERPROFILE\Desktop\CC-Switch\CC Switch.exe"

4.2 macOS 安装

方式一：Homebrew（推荐）

# 添加 tap
brew tap farion1231/ccswitch

# 安装
brew install --cask cc-switch

# 后续更新
brew upgrade --cask cc-switch

方式二：手动下载

  1. 下载 CC-Switch-v{版本号}-macOS.dmg
  2. 打开 DMG，拖入「应用程序」

macOS 版已通过 Apple 代码签名和公证，可直接打开。

4.3 Linux 安装

Debian/Ubuntu：

# 下载 .deb 包后
sudo dpkg -i CC-Switch-v{版本号}-Linux-*.deb
# 如有依赖问题
sudo apt-get install -f

ArchLinux：

paru -S cc-switch-bin
# 或
yay -S cc-switch-bin

AppImage（通用）：

chmod +x CC-Switch-v{版本号}-Linux-*.AppImage
./CC-Switch-v{版本号}-Linux-*.AppImage

4.4 验证 cc-switch 安装

启动后确认三点：

  1. ✅ 应用窗口正常显示
  2. ✅ 系统托盘出现 CC Switch 图标
  3. ✅ 左侧面板能看到 Claude Code 等受管应用

五、配置 API 供应商（核心步骤）

这是整篇教程最关键的部分。cc-switch 支持两种接入方案，按你的需求选择。

方案 A：Claude API 中转（推荐新手）

适用人群：想用原版 Claude 模型，但不想折腾网络环境。

第一步：获取中转 API Key

注册一个 Claude API 中转服务（如 LinoAPI、CC Club 等），获取 sk- 开头的 API Key。

💡 选择中转服务时注意：确认隐私政策、价格透明、稳定性口碑。敏感项目建议用官方 API。

第二步：在 cc-switch 中添加供应商

  1. 打开 cc-switch，点击右上角 + 按钮
  2. 预设下拉框中选择你的中转服务商（或选 " 自定义 "）
  3. 填写配置：
字段 填什么
供应商名称 自定义，如 " 我的 Claude 中转 "
API Key 中转服务给你的 sk- 开头密钥
请求地址 中转服务的 Base URL（末尾不带 /）
API 格式 选择 Anthropic Messages（原生）
  1. 展开高级选项，配置模型映射：
模型类型 推荐填写
主模型 claude-sonnet-4-6
推理模型 claude-sonnet-4-6-thinking
Haiku 模型 claude-haiku-4-5-20251001
  1. 点击「添加」

第三步：启用供应商

回到主界面，点击供应商卡片右侧的「启用」按钮。Claude Code 支持热重载，无需重启终端即可生效。

方案 B：接入国产大模型（低成本方案）

适用人群：想用国产模型（DeepSeek、Kimi 等），成本更低、网络更稳定。

国产模型供应商推荐：

供应商 免费额度 特点 注册地址
Kimi（月之暗面） 15 元 长文本、代码能力强 platform.moonshot.cn
硅基流动 16 元 模型多、响应快 cloud.siliconflow.cn
DeepSeek 有免费额度 性价比极高 platform.deepseek.com
通义千问 有免费额度 中文能力强 dashscope.aliyun.com

以硅基流动为例的配置步骤：

第一步：注册获取 API Key

  1. 访问 硅基流动，注册并完成实名认证
  2. 进入 API Key 管理，创建新 Key
  3. 复制保存（只显示一次）

第二步：在 cc-switch 中添加

  1. 点击 + 添加供应商
  2. 预设下拉框选择 SiliconFlow
  3. 填入 API Key
  4. 填写模型名称，如 Pro/moonshotai/Kimi-K2.5 或 Pro/deepseek-ai/DeepSeek-V3
  5. 点击「添加」

💡 预设会自动填充端点地址，你只需要填 API Key 和模型名。

第三步：启用并测试

  1. 点击供应商卡片的「启用」按钮
  2. 打开终端，运行 claude
  3. 输入 " 你好，请简单介绍一下自己 " 测试

如果 AI 正常回复，说明配置成功。

方案 C：官方 Claude 登录

如果你有官方 Claude 账号，也可以直接用：

  1. 在 cc-switch 预设中选择「Claude 官方登录」
  2. 启用后重启终端
  3. 运行 claude，按官方流程登录

六、解决首次启动问题

6.1 跳过 Claude Code 初次安装确认

首次启动 Claude Code 时，如果提示需要登录或显示初始化引导，可以跳过：

  1. 打开 cc-switch → 设置 → 通用
  2. 开启「跳过 Claude Code 初次安装确认」
  3. 重新启动 Claude Code

这会写入 ~/.claude/settings.json 的 skipIntroduction 字段。

6.2 修复 400 报错："thinking type should be enabled or disabled"

这是国内用户最常见的报错。原因是新版 Claude Code（v2.1.97+）默认发送 thinking:{type:"adaptive"} 参数，而第三方 API 不支持。

解决方法：

在 cc-switch 中编辑 Claude Code 的通用配置，添加以下内容：

{
  "env": {
    "claude_code_disable_adaptive_thinking": "1"
  }
}

或者直接编辑 ~/.claude/settings.json，在 env 中加入同一行。

重启 Claude Code 后生效。

6.3 先导入现有配置（重要！）

新手最容易犯的错：一打开 cc-switch 就新建空供应商，结果原来的 MCP、Skills、提示词全没了。

正确顺序：

  1. 先打开 cc-switch
  2. 找到「导入现有配置」入口
  3. 让它读取你已经跑通的 Claude Code 配置
  4. 确认默认配置存在后，再新增供应商

这样即使后面配错了，也能切回原来的配置。

七、Claude Desktop + cc-switch（桌面版方案）

如果你更喜欢图形界面，可以把 Claude Desktop 也接入 cc-switch。

7.1 前置条件

  • 已安装最新版 Claude Desktop
  • Windows 已启用 Virtual Machine Platform
  • cc-switch 正在运行，且已导入可用的 Claude 供应商
  • cc-switch 开启了本地代理（地址一般是 http://127.0.0.1:15721）

7.2 开启 3P 模式

  1. 打开 Claude Desktop
  2. Help → Troubleshooting → Enable Developer mode
  3. Developer → Configure third-party inference
  4. 选择 Gateway 连接方式

7.3 填写连接字段

字段 填什么
Gateway base URL http://127.0.0.1:15721（以你实际本地代理地址为准）
Gateway API key PROXY_MANAGED
Gateway auth scheme bearer
Skip login-mode chooser ✅ 建议开启
其他字段 留空

7.4 添加 inferenceModels（关键！）

inferenceModels 这一行必须在面板外手动添加，否则模型下拉框会是空的。

方法一：导出 .reg 修改

  1. 面板填好后点 Export 导出 .reg 文件
  2. 用记事本打开，在 [HKEY_CURRENT_USER\SOFTWARE\Policies\Claude] 下加一行：
"inferenceModels"="[\"haiku\",\"sonnet\",\"opus\"]"
  1. 保存后双击导入注册表

方法二：PowerShell 直接写入

New-Item -Path 'HKCU:\SOFTWARE\Policies\Claude' -Force | Out-Null
Set-ItemProperty -Path 'HKCU:\SOFTWARE\Policies\Claude' -Name 'inferenceProvider' -Value 'gateway'
Set-ItemProperty -Path 'HKCU:\SOFTWARE\Policies\Claude' -Name 'inferenceGatewayBaseUrl' -Value 'http://127.0.0.1:15721'
Set-ItemProperty -Path 'HKCU:\SOFTWARE\Policies\Claude' -Name 'inferenceGatewayApiKey' -Value 'PROXY_MANAGED'
Set-ItemProperty -Path 'HKCU:\SOFTWARE\Policies\Claude' -Name 'inferenceGatewayAuthScheme' -Value 'bearer'
Set-ItemProperty -Path 'HKCU:\SOFTWARE\Policies\Claude' -Name 'inferenceModels' -Value '["sonnet","haiku","opus"]'
Set-ItemProperty -Path 'HKCU:\SOFTWARE\Policies\Claude' -Name 'isClaudeCodeForDesktopEnabled' -Value 1 -Type DWord

7.5 验证 3P 是否接通

检查以下文件：

C:\Users\<用户名>\.cc-switch\logs\cc-switch.log      # 应有请求记录
C:\Users\<用户名>\.claude\sessions\最新.json           # entrypoint 应为 claude-desktop-3p

关键指标：entrypoint=claude-desktop-3p、source=proxy、status_code=200

八、进阶优化

8.1 Prompt 适配

国产模型对 Claude Code 的系统提示词结构可能不完全兼容。在 cc-switch 中开启 prompt_inject 功能，追加系统提示词可大幅提升准确率：

system_prompt_suffix: |
  - 始终使用中文注释
  - 优先输出可运行的完整代码块
  - 遇到文件修改时，严格遵循 diff 格式输出
  - 不输出与代码无关的解释性文字

8.2 流式响应优化

部分国内网关默认关闭 SSE 长连接。在 cc-switch 配置中启用：

streaming: true
chunk_buffer: 4096

可避免终端卡顿与断流。

8.3 上下文窗口管理

国产模型对超长上下文处理策略不同，建议限制上下文长度。编辑 ~/.claude/settings.json：

{
  "max_context_tokens": 8192
}

并在 cc-switch 中启用 context_truncate 策略，防止 OOM 或响应截断。

8.4 多供应商智能路由

同时配置 Claude 中转 + 国产模型，根据任务类型选择：

任务类型 推荐模型 理由
复杂架构设计 Claude Sonnet（中转） 推理深度最强
日常代码编写 DeepSeek V3（国产） 性价比高、速度快
长文本分析 Kimi K2.5（国产） 长上下文窗口优势
快速查询 Claude Haiku 响应最快

切换方式：cc-switch 主界面点击切换，或右键系统托盘图标快速切换。

九、常见问题排查

Q1：切换供应商后不生效？

可能原因 解决方法
旧终端没重启 关闭旧终端，重新打开，再运行 claude
环境变量覆盖了配置 检查 ANTHROPIC_API_KEY 等环境变量是否冲突
改了另一个工具的配置 确认左侧面板切换到了 Claude Code 分组

Q2：401 Unauthorized

检查 API Key 是否完整复制，没有多余空格或换行。确认 Key 对应的供应商和格式正确。

Q3：模型不存在 / 模型名报错

这不是 cc-switch 的问题，是供应商给的模型名和工具请求的对不上。处理步骤：

  1. 确认供应商支持 Anthropic / OpenAI / Gemini 哪种格式
  2. 确认模型名完全一致（区分大小写）
  3. 如果是中转站，问清楚是否做了模型别名映射

Q4：MCP 或 Skills 不见了

通常是直接新建了空配置，没有先导入原来的。处理方式：

  1. 切回默认配置，看原来的 MCP / Skills 是否还在
  2. 如果还在，用 " 导入现有配置 " 的方式重新建供应商
  3. 不要反复新建供应商，否则更难判断哪份是对的

Q5：终端频繁断连 / Timeout

在 cc-switch 配置中调高 timeout（建议 120s），开启 keep_alive 连接池。

Q6：代码块不闭合 / 格式错乱

国产模型未完全识别 Claude Code 的标记语法。解决方案：

  1. 在 system_prompt_suffix 中强化格式约束
  2. 或切换至 deepseek-coder 等代码专项模型

Q7：如何恢复官方登录？

在 cc-switch 预设中选择「Claude 官方登录」，启用后重启终端，按官方登录流程操作。

Q8：计费异常飙升？

配置 retry_limit: 3，定期检查 cc-switch 日志中的请求命中率。

十、快速上手检查清单

安装完成后，逐项确认：

  • [ ] Node.js v18+ 已安装（node -v 验证）
  • [ ] Claude Code 已安装（claude --version 验证）
  • [ ] cc-switch 已安装并能正常启动
  • [ ] 已导入现有 Claude Code 配置（避免丢失 MCP/Skills）
  • [ ] 已添加至少一个 API 供应商
  • [ ] 已启用目标供应商
  • [ ] 已解决 400 thinking 报错（如适用）
  • [ ] 终端中 claude 能正常对话
  • [ ] Claude Desktop 3P 模式正常（如使用桌面版）

评论

发表评论

此博客中的热门博文

Claude Code 国内安装与配置全指南

-
从零开始，手把手教你在国内网络环境下安装、配置并高效使用 Claude Code。 一、Claude Code 是什么 Claude Code 是 Anthropic 推出的命令行 AI 编程助手。它不是网页聊天框，而是直接嵌入你终端的 " 资深搭档 "——读代码、写代码、跑测试、操作 Git，全在命令行完成。 简单说三句话： 终端原生 ：在 PowerShell / Terminal 里直接 claude 启动，不用切换窗口 理解项目 ：自动读取你的代码库，理解上下文后再动手 自主执行 ：不只是生成代码片段，而是直接修改文件、运行命令、修复 Bug 它的核心能力包括： 🔍 代码搜索与理解（读懂整个 repo） ✏️ 智能编辑（精确修改，不乱改） 🐛 自主调试（定位 Bug 并修复） 📋 Git 工作流（提交、PR、代码审查） 🤖 子代理编排（复杂任务自动拆分） 🔌 MCP 扩展（连接外部工具和服务） 二、安装前的准备 2.1 系统要求 项目 最低要求 推荐配置 操作系统 Windows 10+ / macOS 12+ / Linux Windows 11 / macOS 14+ Node.js v18 LTS v20+ LTS npm 随 Node.js 安装 最新版 网络环境 需要访问 Anthropic API 稳定代理 内存 4 GB 8 GB+ 2.2 安装 Node.js Claude Code 基于 Node.js 运行，这是唯一的前置依赖。 Windows 用户推荐方式： 访问 Node.js 官网 下载 LTS 版本（长期支持版，最稳定） 双击安装，一路 " 下一步 " 即可 验证安装： node -v # 应显示 v20.x.x 或更高 npm -v # 应显示 10.x.x 或更高 💡 如果你已经安装了 Node.js，版本在 v18 以上就行，不用重新装。 三、安装 Claude Code 3.1 Windows 推荐安装方式（官方一键脚本） 打开 PowerShell，执行： irm https://claude.ai/...
阅读全文

GUI.for.SingBox 配置指南：告别 JSON，图形界面搞定一切

-
从下载安装到规则分流，手把手教你用 GUI.for.SingBox 图形界面客户端——不用手写一行 JSON，轻松管理 sing-box 全部功能。 一、GUI.for.SingBox 是什么 一句话定义 ：GUI.for.SingBox 是 sing-box 内核的图形界面配置管理前端。它本身不是代理程序，而是通过 GUI 操作自动生成 sing-box 的 JSON 配置文件并驱动内核运行。 为什么需要它 ：sing-box 原生只提供命令行 + JSON 配置，手写 JSON 配置对大多数人来说门槛太高。GUI.for.SingBox 把所有配置项变成可视化表单，点击填选即可，完全不需要接触 JSON。 1.1 核心功能一览 功能 说明 多协议支持 VLESS / VMess / Trojan / Shadowsocks / Hysteria2 / TUIC / Reality / NaiveProxy 订阅管理 支持 sing-box JSON、Clash YAML、URI 列表格式的一键导入 节点转换插件 自动将 V2Ray/Clash 格式订阅转为 sing-box 格式 分流控制 规则分流 / 直连 / 全局代理三种模式 TUN 透明代理 创建虚拟网卡，接管全部系统流量 策略组 手动选择 / 自动测速（urltest）/ 负载均衡 路由规则 域名 / IP / 进程 / 协议 / 规则集，完整可视化配置 DNS 管理 服务器 / DNS 规则 / FakeIP，全图形化 规则集 远程规则集自动下载更新，支持 SRS 二进制格式 插件系统 Sub-Store / 广告拦截 / 速度测试 / IP 查询等 配置导出 一键生成完整 sing-box JSON 配置文件 跨平台 Windows / macOS / Linux 1.2 与其他客户端对比 对比维度 GUI.for.SingBox Karing Clash Verge Rev V2RayN 内核 sing-box sing-box mihomo v2ray/xray 配置方式 GUI 表单 → 自动生成 JSON GUI +...
阅读全文