适用读者正在使用或打算使用Claude Code、Codex、Gemini CLI 等 AI 编程工具并且需要在多个模型服务商 / API 之间切换的开发者。阅读完你将学会安装 CC Switch、清理环境变量冲突、把 {AI大模型} 一键接入 Claude Code、在多个供应商之间秒级切换以及 MCP / Skills / 用量统计等进阶玩法。一、CC Switch 是什么在日常使用 AI 编程工具时你大概率遇到过这些痛点切换供应商麻烦想从官方 API 切到第三方服务商必须手动改配置文件改完还要重启配置格式混乱Claude Code 用 JSON、Codex 用 TOML各工具各一套改错一个字符就罢工用量是笔糊涂账不知道今天调了多少次、花了多少钱单点故障唯一的供应商挂了整个工作流就得中断。CC Switch 是一款开源MIT 协议的跨平台桌面应用专门解决上面这些问题。它基于 Tauri 2 Rust React 构建轻量、原生、数据全部存储在本地。核心功能功能模块说明供应商管理50 内置预设主流大模型服务商、云厂商、社区中转一键切换、托盘快捷切换、拖拽排序、导入导出统一供应商一份配置同时同步到 Claude Code、Codex、Gemini CLI 等多个工具本地代理与故障转移热切换、格式转换、自动故障转移、熔断器、健康监控MCP 管理统一面板管理 MCP 服务器跨多个工具双向同步Prompts 管理Markdown 编辑器维护系统提示词跨应用同步Skills 管理从 GitHub 仓库或 ZIP 一键安装技能扩展用量统计花费 / 请求数 / Token 追踪、趋势图表、请求日志、自定义模型单价会话管理跨源浏览、搜索、恢复对话历史支持的 AI 编程工具工具说明Claude Code终端 AI 编程 Agent本教程的主角Claude DesktopClaude 桌面应用CodexOpenAI 的代码生成 CLIGemini CLIGoogle 的 AI 命令行工具OpenCode开源 AI 编程终端工具OpenClaw开源 AI 助手多供应商网关Grok Build / Hermes Agent其他受支持的 AI 编程工具支持的平台Windows10 及以上x64macOS12 (Monterey) 及以上Intel / Apple Silicon已通过 Apple 公证LinuxUbuntu 22.04 / Debian 11 / Fedora 34 / Archx64 / ARM64官方渠道资源链接官方网站https://ccswitch.ioGitHub 仓库https://github.com/farion1231/cc-switch版本下载https://github.com/farion1231/cc-switch/releases用户手册https://github.com/farion1231/cc-switch/blob/main/docs/user-manual/zh/README.md问题反馈https://github.com/farion1231/cc-switch/issues⚠️安全提醒请只从官网或 GitHub Releases 获取 CC Switch。任何要求付费、充值或索取登录凭据的CC Switch网站或客户端都不是官方渠道。二、安装 CC SwitchmacOS推荐 Homebrew# 安装brewinstall--caskcc-switch# 后续升级brew upgrade--caskcc-switch也可以从 Releases 下载.dmg推荐或.zip手动安装。macOS 版本已通过 Apple 代码签名和公证可直接打开无需额外操作。Windows前往 Releases 页面 下载CC-Switch-v{版本号}-Windows.msi双击运行按提示完成安装。若双击无反应右键安装包 →「属性」→「常规」→ 勾选「解除锁定」后再运行也可以下载便携版CC-Switch-v{版本号}-Windows-Portable.zip解压后直接运行CC-Switch.exe。Linux# ArchLinuxAURparu-Scc-switch-bin# Debian / Ubuntu下载 .deb 后sudodpkg-iCC-Switch-v{版本号}-Linux-x86_64.deb# Fedora / RHEL下载 .rpm 后sudorpm-iCC-Switch-v{版本号}-Linux-x86_64.rpm# 通用 AppImagechmodx CC-Switch-v{版本号}-Linux-x86_64.AppImage ./CC-Switch-v{版本号}-Linux-x86_64.AppImage前置要求CC Switch 管理的 CLI 工具需要 Node.js 18 环境。以 Claude Code 为例# HomebrewmacOS 推荐brewinstallclaude-code# 或 npm 安装npminstall-ganthropic-ai/claude-code# 国内网络较慢时使用镜像源npminstall-ganthropic-ai/claude-code--registryhttps://registry.npmmirror.com验证安装启动 CC Switch 后应用窗口正常显示、系统托盘出现 CC Switch 图标即安装成功。CC Switch 内置自动更新也可以在「设置 → 关于」中手动检查。三、开始前的准备清理环境变量冲突这一步非常关键也是最容易踩的坑。环境变量的优先级高于一切配置文件。如果你的 shell 配置文件~/.zshrc、~/.bashrc等里曾经导出过下面这类变量exportANTHROPIC_BASE_URL...# Claude API 端点exportANTHROPIC_AUTH_TOKEN...# API 密钥exportANTHROPIC_API_KEY...那么无论 CC Switch 里怎么切换供应商Claude Code 都会优先读取环境变量导致配置了却不生效。处理方式二选一手动清理编辑~/.zshrc/~/.bashrc删除或注释掉相关的export语句然后执行source ~/.zshrc重新加载让 CC Switch 帮你清理CC Switch 会自动检测冲突界面顶部出现黄色警告横幅时点击「展开」→ 勾选冲突变量 →「删除选中」。删除前会自动备份到~/.cc-switch/env-backups/可以放心操作。四、实战用 CC Switch 把 {AI大模型} 接入 Claude Code下面以最典型的场景为例让 Claude Code 使用兼容 Anthropic 协议的 {AI大模型} 服务。整个过程 5 步2 分钟完成。第 0 步获取 API Key登录你所使用的 {AI大模型} 服务商开放平台在「用量 / 付费 / Token 计划」页面购买或领取额度并创建 API Key复制备用。第 1 步添加供应商配置启动 CC Switch点击主界面右上角的「」按钮在「预设」下拉框中选择你的大模型服务商内置 50 预设会自动填好端点地址然后粘贴你的API Key。 如果预设列表里没有你的服务商选择「自定义」手动填写名称、端点地址和密钥即可。官方仓库中的添加供应商界面英文 UI供对照第 2 步配置模型名称在配置表单中将所有模型名称统一改为{AI大模型}然后点击右下角**「添加」**。 部分服务商支持在模型名后加[1m]后缀如{AI大模型}[1m]以启用 1M 超长上下文是否支持以服务商文档为准。 可选优化如果想让自动压缩阈值与 1M 上下文对齐可以在~/.claude/settings.json的env中加入CLAUDE_CODE_AUTO_COMPACT_WINDOW: 1000000。第 3 步启用配置回到 CC Switch 首页找到刚添加的供应商卡片点击**「启用」**。也可以右键系统托盘图标直接点击供应商名称完成切换——这是日常使用中最快的方式。第 4 步跳过首次登录引导新装 Claude Code 必看Claude Code 首次启动会进入官方登录引导。使用第三方供应商时可以跳过它两种方式任选方式 A推荐CC Switch「设置 → 通用」→ 开启「跳过 Claude Code 初次安装确认」开关方式 B手动编辑~/.claude.jsonWindows 在用户目录下确保包含{hasCompletedOnboarding:true}第 5 步启动并验证进入你的工作目录启动 Claude Code选择信任此文件夹claude在会话中依次执行两条命令验证命令预期结果/statusBase URL 显示为服务商提供的 Anthropic 兼容端点而非官方地址/model显示{AI大模型}也可以直接问一句你好请简单介绍一下自己能正常回复即配置成功。扩展思考{AI大模型} 默认开启 Extended Thinking 深度思考模式可通过/config调整或用快捷键OptionTmacOS/AltTWindows/Linux快速开关。附等价的手动配置对照参考不使用 CC Switch 时上述效果等价于手动编辑~/.claude/settings.json{env:{ANTHROPIC_BASE_URL:https://服务商 API 端点/anthropic,ANTHROPIC_AUTH_TOKEN:你的 API Key,ANTHROPIC_MODEL:{AI大模型},ANTHROPIC_DEFAULT_SONNET_MODEL:{AI大模型},ANTHROPIC_DEFAULT_OPUS_MODEL:{AI大模型},ANTHROPIC_DEFAULT_HAIKU_MODEL:{AI大模型}}}对比一下就知道 CC Switch 的价值这些配置它替你写了而且切换供应商时还能一键换掉。五、日常使用切换、排序与生效方式两种切换方式主界面切换点击供应商卡片上的「启用」按钮托盘切换右键系统托盘图标直接点击供应商名称全程不用打开主窗口。各工具的生效方式切换供应商后各 CLI 工具的生效方式不同应用生效方式Claude Code✅ 即时生效支持热重载无需重启Gemini CLI✅ 即时生效每次请求重新读取配置Codex需要关闭并重新打开终端OpenCode / OpenClaw需要关闭并重新打开终端其他常用操作拖拽排序按使用频率把常用供应商拖到列表顶部复制供应商基于现有配置快速派生一份新配置比如换一个 Key导入 / 导出在多台机器之间同步供应商配置恢复官方登录添加「官方登录」预设并启用重启 CLI 后走官方 OAuth 流程即可。⚠️ 当前处于启用状态的供应商不可删除——这是 CC Switch 的最小侵入设计所有写入都是可回滚的即使卸载 CC SwitchCLI 工具依然按最后写入的配置正常工作。六、进阶功能速览统一供应商Universal Providers一份配置同时应用到 Claude Code、Codex、Gemini CLI改一处全局生效MCP 管理统一面板管理 MCP 服务器可按应用开关同步支持 Deep Link 一键导入PromptsMarkdown 编辑器维护提示词预设一键同步到CLAUDE.md/AGENTS.md/GEMINI.mdSkills从 GitHub 仓库或 ZIP 包一键安装技能支持 symlink 与文件复制两种方式本地代理与故障转移开启代理服务后支持自动故障转移、熔断器与健康监控主供应商挂掉时自动切到备用工作不中断用量统计按天 / 按模型查看花费、请求数、Token 趋势图表支持自定义模型单价云同步配置可通过 Dropbox / OneDrive / iCloud / WebDAV 在多设备间同步。数据都存在哪CC Switch 的所有数据集中在~/.cc-switch/目录~/.cc-switch/ ├── cc-switch.db # SQLite 数据库供应商、MCP、Prompts 等 ├── settings.json # 设备级设置 ├── backups/ # 配置自动备份保留 10 份 ├── skills/ # 已安装的技能 └── skill-backups/ # 技能备份保留 20 份七、常见问题FAQQ1切换供应商后不生效按顺序检查① 是否有第三章提到的环境变量冲突② 该工具是否需要重启终端见第五章生效方式表③ 用/status确认当前实际加载的 Base URL。Q2预设列表里找不到我的服务商选择「自定义」手动填写端点和密钥。只要服务商兼容 Anthropic 协议就能用。Q3界面顶部出现黄色环境变量冲突警告说明系统环境变量会覆盖 CC Switch 的配置点击横幅「展开」→ 勾选冲突变量 →「删除选中」会先自动备份到~/.cc-switch/env-backups/。Q4想回到官方订阅登录怎么办添加「官方登录」预设并启用重启 CLI 后按官方 OAuth 流程重新登录即可。Q5卸载 CC Switch 会影响我的 CLI 工具吗不会。CC Switch 采用最小侵入设计卸载后 Claude Code 等工具会继续使用最后写入的配置正常运行。Q6Linux 下 AppImage 黑屏或点击无效Wayland NVIDIA 环境的已知问题用环境变量切回原生 Wayland 启动CC_SWITCH_GDK_BACKENDwayland ./CC-Switch.AppImage。八、参考资料CC Switch GitHub 仓库含多语言用户手册docs/user-manual/CC Switch 官方网站 与 官方文档CC Switch Releases 下载页模型服务商平台文档《在 Claude Code 中使用大模型》之使用 CC Switch章节本教程第四章实操流程的主要来源本教程截图来自上述官方文档与仓库仅作学习用途