ClaudeCode-Deploy-Guide/README.md

# Claude Code + cc-switch 国内部署教程

通过 cc-switch 接入国内模型，零门槛部署 Claude Code。

## 目录

1. [什么是 cc-switch？](#1-什么是-cc-switch)
2. [准备工作](#2-准备工作)
3. [安装 Node.js](#3-安装-nodejs)
4. [安装 Claude Code](#4-安装-claude-code)
5. [安装 cc-switch](#5-安装-cc-switch)
6. [注册国内模型 API](#6-注册国内模型-api)
7. [配置 cc-switch](#7-配置-cc-switch)
8. [验证部署](#8-验证部署)
9. [常见问题](#9-常见问题)

---

## 1. 什么是 cc-switch？

cc-switch 是一款开源桌面工具，用于管理 AI 编程工具的模型供应商配置。

**官方资源**：
- 官网：https://ccswitch.io
- GitHub：https://github.com/farion1231/cc-switch
- 下载：https://ccswitch.io/download

**核心功能**：
- 50+ 内置供应商预设（MiniMax、DeepSeek、智谱等）
- 可视化界面管理 API 配置
- 一键切换模型供应商
- 支持 Claude Code、Codex、Gemini CLI 等多个 AI 编程工具
- 本地路由转发请求，保护 API Key 安全

---

## 2. 准备工作

### 需要准备

| 软件 | 版本要求 | 用途 |
|------|----------|------|
| Node.js | 18+ | Claude Code 运行依赖 |
| Git | 最新版 | 版本控制（可选） |
| 国内模型 API Key | - | 调用模型 |

### 环境检查

打开终端，输入以下命令验证：

```bash
node --version   # 应显示 v18 或更高
npm --version    # 应显示 9 或更高
```

---

## 3. 安装 Node.js

### 方式1：官网下载（推荐）

下载地址：https://nodejs.org/

选择 **LTS（长期支持版）**，Windows 用户下载 `.msi` 安装包。

### 方式2：winget 安装

```powershell
winget install OpenJS.NodeJS.LTS
```

### 方式3：国内镜像

如果网络慢，使用淘宝镜像：

```bash
# 设置 npm 镜像
npm config set registry https://registry.npmmirror.com

# 验证
npm config get registry
```

---

## 4. 安装 Claude Code

### 安装命令

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

### 验证安装

```bash
claude --version
```

### 首次登录

运行 Claude Code 时会提示登录：

```bash
claude
```

按提示完成认证流程。

### Windows 一键安装包（推荐）

感谢 @K1evL 提供的 Windows 一键安装包，可一键安装 Claude Code + cc-switch：
- GitHub：https://github.com/K1evL/claudecode-setup
- 自动配置 Node.js 环境

---

## 5. 安装 cc-switch

### 方式1：官网下载桌面版（推荐）

1. 访问 https://ccswitch.io/download
2. 下载对应系统的安装包（Windows / macOS / Linux）
3. 安装并启动

### 方式2：CLI 命令行版本（npm 安装）

```bash
npm install -g @cc-switch/cli
```

---

## 6. 注册国内模型 API

推荐使用以下国内模型服务商：

### 6.1 MiniMax Token Plan（推荐）

官网：
- 国内：https://platform.minimaxi.com
- 国际：https://platform.minimax.io

**特点**：
- Token Plan 订阅制，开箱即用
- 支持 M2.7-highspeed 等旗舰模型
- 全模态支持（文本、语音、图像、视频、音乐）
- 中文优化

**注册步骤**：
1. 访问 https://platform.minimaxi.com
2. 注册账号（可用手机号）
3. 进入控制台 → Token Plan → 订阅套餐
4. 获取 API Key 或直接使用 Token Plan

### 6.2 DeepSeek

官网：https://platform.deepseek.com

**特点**：
- API 兼容 OpenAI/Anthropic 格式
- 代码能力强
- 按量计费，价格实惠

**注册步骤**：
1. 访问 https://platform.deepseek.com
2. 注册账号
3. 进入控制台 → API Keys → 创建新密钥
4. 复制保存 API Key

### 6.3 其他供应商

| 供应商 | 官网 | 特点 |
|--------|------|------|
| 智谱 AI (GLM) | https://open.bigmodel.cn | 国产旗舰模型 |
| 阿里云通义 | https://qwen.ai | 稳定可靠 |
| 硅基流动 | https://www.siliconflow.cn | 50+ 预设 |

---

## 7. 配置 cc-switch

### 7.1 添加供应商

1. 打开 cc-switch
2. 点击左侧 **Providers**
3. 点击 **+ 添加**
4. 选择预设或手动配置

### 7.2 填写 API Key（以 MiniMax 为例）

1. 选择 **MiniMax** 预设
2. 填入 API Key
3. 设置模型映射：
   - **Main Model**：`MiniMax-M2.7-highspeed`
   - **Haiku**：`MiniMax-M2.7-highspeed`
   - **Sonnet**：`MiniMax-M2.7-highspeed`
   - **Opus**：`MiniMax-M2.7-highspeed`

### 7.3 一键切换

配置完成后，点击托盘图标即可在不同供应商之间切换。

---

## 8. 验证部署

### 测试 Claude Code

```bash
# 在终端输入
claude

# 测试对话
claude --print "你好，请自我介绍"
```

### 验证模型切换

1. 在 cc-switch 中切换到不同供应商
2. 再次运行 Claude Code
3. 观察响应模型是否变化

---

## 9. 常见问题

### Q1: npm 安装失败怎么办？

**A**: 尝试切换 npm 镜像源：

```bash
npm config set registry https://registry.npmmirror.com
```

或使用国内加速：

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

### Q2: cc-switch 显示连接失败？

**A**: 检查以下几点：
1. API Key 是否正确
2. 网络能否访问供应商
3. 供应商账户是否余额充足或订阅有效

### Q3: Claude Code 提示需要登录？

**A**: 首次使用需要认证：

```bash
claude
# 按提示完成浏览器认证
```

### Q4: 如何查看当前使用的模型？

**A**: 在 cc-switch 的 **Dashboard** 中可以看到：
- 当前供应商
- 请求用量
- Token 消耗统计

### Q5: 切换供应商后没生效？

**A**: 尝试：
1. 重启 cc-switch
2. 完全退出 Claude Code 后重新启动
3. 检查 cc-switch 日志

---

## 相关资源

- [cc-switch 官方文档](https://docs.ccswitch.io)
- [cc-switch GitHub](https://github.com/farion1231/cc-switch)
- [MiniMax API 平台](https://platform.minimaxi.com)
- [DeepSeek API 平台](https://platform.deepseek.com)

---

## 贡献

欢迎提交 Issue 和 Pull Request！

---

*最后更新：2026年7月*