CC-Switch 使用 Claude Code 完整教程

CC-Switch 是一款跨平台 AI 编程 CLI 统一管理工具，核心功能是多供应商一键切换、API Key 集中管理、代理与用量追踪。它特别适合同时使用 Claude Code、Codex、Gemini CLI 等 AI 编程工具的用户，能够将分散的配置集中到一个桌面应用中管理。

一、CC-Switch 与 Claude Code 简介

1.1 CC-Switch 是什么？

CC-Switch 是一个开源免费的跨平台桌面应用，堪称 AI 编程时代的“瑞士军刀”。它的核心作用是统一管理 Claude Code、Codex、Gemini CLI、OpenCode 和 OpenClaw 这五大 AI 编程工具的 API 配置。

主要价值：

  • 告别手动繁琐地编辑各种 settings.json、.toml 或 .env 配置文件
  • 通过一个面板管理多个工具，一次配置可以反复切换
  • 出问题时有备份和回退机制

1.2 Claude Code 是什么？

Claude Code 是 Anthropic 推出的 AI 编程工具，支持代码生成、分析、调试等功能。它提供三种使用方式：Web 端、CLI（命令行）和编辑器集成。

推荐使用方式：

  • 完全新手：先访问 https://claude.ai/ 用 Web 端试试手感
  • 真正用于开发：直接学习 CLI（命令行），功能最完整
  • 日常开发者：考虑编辑器集成（VS Code / Cursor 等）

二、安装准备

2.1 系统要求

  • Windows：10+（x64）
  • macOS：12+（Intel/Apple Silicon）
  • Linux：主流 x64 发行版（Ubuntu 20.04+、Debian 11+ 等）

2.2 前置条件

  1. Claude 账号：访问 claude.ai 注册账号
  2. 命令行工具：确保系统已安装终端/命令行环境
  3. API Key：从 Anthropic 控制台获取 Claude API Key

三、CC-Switch 安装步骤

3.1 下载安装包

前往项目官方 GitHub Release 页面下载最新版本：

https://github.com/farion1231/cc-switch/releases

3.2 分系统安装

Windows 系统：

  • 推荐下载 .msi 安装包（支持自动更新）
  • 双击运行安装程序，跟随向导完成安装
  • 或选择便携版（Portable zip），解压后直接运行 cc-switch.exe

macOS 系统：

  • Homebrew 安装（推荐）：
    brew tap farion1231/ccswitch
brew install --cask cc-switch
  • 手动安装： 下载 .dmg 文件，拖入“应用程序”文件夹

Linux 系统：

  • Debian/Ubuntu： sudo dpkg -i CC-Switch-v3.14.1-Linux.deb
  • AppImage（通用）： chmod +x CC-Switch-v3.14.1-Linux.AppImage
  • Arch Linux： paru -S cc-switch-bin

3.3 安装验证

启动 CC-Switch 客户端，主界面正常加载、无报错提示，即表示安装成功。

四、Claude Code 安装

4.1 安装 Claude Code CLI

# 使用 npm 安装
npm install -g @anthropic-ai/claude-code

# 或使用 pnpm
pnpm add -g @anthropic-ai/claude-code

4.2 验证安装

claude --version

4.3 首次启动与登录

claude

程序会输出一个 URL，复制到浏览器打开，使用 Claude 账号授权（OAuth）。

五、CC-Switch 配置 Claude Code

5.1 开启 Claude Code 插件接管

  1. 打开 CC-Switch，点击左上角的齿轮图标进入设置
  2. 在“通用”设置中找到“应用到 Claude Code 插件”
  3. 把这个开关打开

重要提示： 只有开启接管，CC-Switch 才能将配置同步到 Claude Code 中。

5.2 添加供应商（Provider）

5.2.1 添加预设供应商

  1. 回到 CC-Switch 主界面，点击右上角的加号（+）
  2. 选择“预设供应商”标签页
  3. 从内置的 50+ 家供应商中选择（如 DeepSeek、SiliconFlow、OpenAI 等）
  4. 仅需填写 API Key，请求地址已预设

5.2.2 添加自定义供应商

如果使用中转站或自定义 API，选择“自定义配置”：

  • Provider Name：自定义一个名字（如：My-Claude）
  • Base URL：填写供应商的 API 接口地址（注意：末尾不要带斜杠 /）
  • API Key：填入你的密钥

5.3 配置模型信息

继续往下配置，需要为 Claude Code 填写默认模型：

  • Claude Code：claude-sonnet-4-5（以供应商后台实际支持的模型名为准）

注意： 模型名不要自己乱猜，不同中转站支持的模型名可能不一样，最好直接去中转站后台复制。

5.4 启用供应商

添加完成后，回到 CC-Switch 主界面，找到刚刚添加的供应商卡片，点击“启用”按钮。当状态变为“Active（使用中）”时，表示配置已自动写入 Claude Code 的配置文件中。

六、测试配置是否生效

6.1 重启终端

很多 CLI 工具是在启动时读取配置的，所以切换配置后最好重启终端。

6.2 测试 Claude Code

打开终端，进入一个项目目录，运行：

claude

输入测试指令：

帮我看一下这个项目的目录结构

如果 Claude Code 能正常回复，说明配置已经生效。

七、CC-Switch 核心功能详解

7.1 多供应商一键切换

CC-Switch 支持内置 50+ 家供应商预设，包括 PackyCode、MiniMax、Anthropic、OpenRouter 等。你可以轻松在不同 API 服务商之间无缝切换。

7.2 系统托盘热切换

CC-Switch 启动后会在系统托盘（右下角）常驻图标。以后想切换模型时，只需右键点击托盘图标，直接选择目标供应商即可，无需打开主窗口。

7.3 MCP（Model Context Protocol）管理

如果你同时使用 Claude Code、Codex 等多个工具，MCP 配置只需在 CC-Switch 里设置一次：

  1. 点击右上角的 MCP 标签页
  2. 点击“添加”，选择协议类型（stdio / HTTP / SSE）
  3. 填写服务器信息
  4. 保存后，所有关联的 CLI 工具都会自动共享该 MCP 配置

7.4 Skills（技能扩展）管理

Skills 是可复用的功能模块（如代码审查、前端设计等）：

  1. 点击右上角的 Skills 标签页
  2. 工具会自动扫描 GitHub 上的公开 Skills 仓库
  3. 找到需要的 Skill（如 code-review），勾选后即可一键安装到对应的 AI 工具中

7.5 Prompts（提示词）管理

  1. 点击 Prompts 标签页
  2. 使用内置的 Markdown 编辑器创建多套系统提示词预设
  3. 激活后，它会自动同步到对应工具的配置文件中（如 Claude 的 CLAUDE.md）

7.6 云同步

如果你有多台设备，可以在“设置 → 自定义配置目录”中，将路径指向 Dropbox、OneDrive、iCloud 或 WebDAV 等云盘的同步文件夹。重启应用后，所有配置（供应商、MCP、Skills）就会自动在设备间同步。

八、Claude Code 核心使用技巧

8.1 三种交互模式

  1. 默认模式（最常用）：直接输入自然语言指令
  2. 自动批准模式（-y/--yes）：适合信任 Claude 的场景，自动执行所有文件修改/命令
  3. 规划模式（--plan）：先输出完整计划，人工确认后再执行

8.2 高频内置命令

命令 作用
/help 列出所有命令
/clear 清空会话上下文
/init 在当前目录生成 CLAUDE.md
/review 评审当前改动
/compact 压缩历史释放上下文

8.3 项目级工作流

  1. 第一次进入新项目：使用 /init 生成 CLAUDE.md，手动补充技术栈、目录约定、禁止事项、验收标准
  2. 日常节奏：
    • 开始任务：三段式 prompt（目标/边界/验收）
    • 中途：每15分钟让 AI 总结进展
    • 提交前：使用 /review 评审改动
    • 结束：使用 /clear 清上下文避免污染

九、常见问题与解决方案

9.1 切换后 Claude Code 没变化？

  1. 重启终端：很多 CLI 工具是在启动时读取配置的
  2. 检查设置：确认 CC Switch 设置里打开了“应用到 Claude Code 插件”开关

9.2 报 401 错误？

  • 检查 API Key 是否复制完整
  • 检查 Key 前后有没有多余空格
  • 确认 Key 是否过期
  • 检查账号余额是否正常

9.3 报“模型不存在”错误？

一般是模型名填错。去中转站后台复制模型名，不要手打。例如：

  • 正确：claude-sonnet-4-5
  • 错误：claude-4.5-sonnet

9.4 API 地址到底要不要带 /v1？

这个要看中转站规则：

  • 有些需要：https://api.example.com/v1
  • 有些不需要：https://api.example.com
    如果报请求地址错误，优先检查这里。

9.5 Base URL 格式错误

填写 API 地址时，千万不要在末尾多加斜杠 /：

  • 错误示例：https://api.example.com/
  • 正确示例：https://api.example.com
    多加斜杠会导致 API 路径拼接出现双斜杠而请求失败。

十、最佳实践建议

10.1 配置多套供应商

建议至少配置三套供应商：

  1. 主力中转站：日常使用
  2. 备用中转站：主力通道异常时切换
  3. 官方或其他备用通道：紧急备用

10.2 安全提醒

  • API Key 不要截图公开
  • 写教程、发朋友圈或录屏时，一定先遮挡密钥
  • 配置数据保存在本机，适合重视密钥安全的用户

10.3 实战检查清单

  1. 先跑通单个 CLI：确认 Claude Code 本身能正常启动，再交给 CC-Switch 管理
  2. 只配置一个供应商测试：先保证一个供应商能完整请求成功
  3. 再配置 MCP、Prompts、Skills：这些属于增强能力，建议在主流程跑通后再同步
  4. 每次切换后重启终端：如果切换后没有变化，先重启当前终端或重新打开 CLI 工具

总结

CC-Switch 不提供 API Key，也不会让模型本身变强。它真正做的是：把多工具、多供应商、多模型的配置复杂度降下来。如果你每天都在 Claude Code、Codex、Gemini CLI 之间切换，它会非常省心。

通过本文的教程，你应该能够：

  1. 成功安装 CC-Switch 和 Claude Code
  2. 配置并管理多个 API 供应商
  3. 掌握 Claude Code 的核心使用技巧
  4. 解决常见的配置问题

CC-Switch 的价值在于把一堆分散动作收束成一套可控流程，让你可以更专注于开发工作，而不是配置管理。

Last modification：June 1, 2026
© Allow specification reprint
如果觉得我的文章对你有用，请随意赞赏