CC Switch 下载安装与配置教程（Windows / macOS / Linux）：一键导入 Claude Code、Codex
更新于
CC Switch 是一款开源免费的桌面工具，用来管理和切换 Claude Code、Codex、Gemini CLI 等 AI 编程工具的服务商配置，不用再手动改配置文件和环境变量。这篇从下载安装讲起，教你用 API 快连控制台「一键导入」把配置写进 CC Switch，也给出手动添加的完整写法，最后整理了常见问题。
CC Switch 是什么
- 开源免费：项目在 GitHub（farion1231/cc-switch）开源，不收费。
- 支持的工具：Claude Code、Codex、Gemini CLI，以及 Claude Desktop、OpenCode、OpenClaw、Hermes、Grok Build 等。
- 一键切换：同一个工具可以存多套服务商配置（例如官方账号和 API 快连），点一下「启用」就切换，也可以在系统托盘里切。
- 本地运行：配置和密钥只保存在你自己的电脑上，CC Switch 只负责把它们写进各工具的配置文件。
第一步：下载并安装 CC Switch
截至 2026 年 10 月，最新版本是 v3.20.4。打开 GitHub 发布页，在页面下方的 Assets 里按系统选择安装包（官网下载页 ccswitch.io 的文件与 GitHub 相同）：
| 系统 | 推荐下载 | 说明 |
|---|---|---|
| Windows（普通电脑） | CC-Switch-v3.20.4-Windows.msi | 安装包，支持自动更新；不想安装可选 Windows-Portable.zip 解压即用 |
| Windows（ARM 电脑） | CC-Switch-v3.20.4-Windows-arm64.msi | 只有 ARM 处理器的电脑才选，普通电脑不要选 |
| macOS | CC-Switch-v3.20.4-macOS.dmg | 通用包，Apple 芯片和 Intel 芯片都能用 |
| Linux | .deb / .rpm / .AppImage | 按发行版和架构（x86_64 / arm64）选择 |
| 系统 | 最低要求 |
|---|---|
| Windows | Windows 10 及以上 |
| macOS | macOS 12（Monterey）及以上 |
| Linux | glibc 2.35+ 和 WebKitGTK 4.1，例如 Ubuntu 22.04+、Debian 12+ |
Windows 安装
- 双击运行 .msi，按提示完成安装。
- 如果双击后没有任何反应：在安装包上点右键 → 属性 → 常规，勾选底部的「解除锁定」，确定后再双击。
macOS 安装
有 Homebrew 的话一行命令最省事：
也可以下载 .dmg，打开后把 CC Switch 拖进「应用程序」文件夹。macOS 版已经过 Apple 签名和公证，可以直接打开。
Linux 安装
242776592，群文件里有安装包。第二步：确认要管理的工具已安装
CC Switch 只管理配置，不包含 Claude Code、Codex 这些工具本身。还没装的，可以在 CC Switch 的「设置 → 关于」里一键安装，或者按各自教程安装：
- Claude Code 安装与国内使用教程（含安装命令）
- Codex 安装与国内使用教程（CLI / 桌面版 / VS Code）
- Gemini API / CLI 接入教程
第三步：从 API 快连控制台一键导入（推荐）
API 快连的控制台可以把密钥和地址直接导入 CC Switch，不需要手动复制粘贴，也不会填错 /v1。
1. 创建密钥，选对分组
登录 控制台，进入左侧菜单「API 密钥」，点「创建密钥」，填一个名字，然后在「分组」里选择：
| 你要用的工具 | 创建密钥时选的分组 | 导入后出现在 CC Switch 的 |
|---|---|---|
| Claude Code | Claude 类分组（如 Claude-Max） | Claude 页 |
| Codex（CLI / 桌面版） | GPT 类分组（如 GPT-Pro） | Codex 页 |
| Gemini CLI | Gemini 类分组 | Gemini 页 |
2. 点「导入到 CCS」
- 确认 CC Switch 已经安装，并且至少打开过一次（这样浏览器才认得它）。
- 在密钥列表里找到刚建的密钥，点这一行操作区的 「导入到 CCS」。
- 浏览器询问「是否打开 CC Switch」时，点允许 / 打开。
- CC Switch 弹出导入确认窗口，核对供应商名称（apikl.ai）、端点地址和密钥，点确认导入。
3. 在 CC Switch 里启用
- 在 CC Switch 顶部切到对应的应用页（Claude、Codex 或 Gemini）。
- 找到名为 apikl.ai 的供应商卡片，鼠标移上去，点 「启用」。卡片出现蓝色边框就表示正在使用。
- 按下表让工具读取新配置，然后发一句话测试。
| 工具 | 启用后怎么生效 |
|---|---|
| Claude Code | 即时生效，正在运行的会话会自动读取新配置 |
| Codex | 关掉当前终端，重新打开再运行 codex；桌面版要彻底退出再打开 |
| Gemini CLI | 退出后重新运行 gemini |
导入时自动写入了什么
| 应用 | 端点地址 | 其他 |
|---|---|---|
| Claude Code | https://apikl.ai | — |
| Codex | https://apikl.ai | 默认模型 gpt-5.5，可点「编辑」改成 gpt-5.6-sol 等常用模型 |
| Gemini CLI | https://apikl.ai | — |
Codex 这里不带 /v1 也能正常使用，因为新版 Codex 走的 /responses 接口在 API 快连上带不带 /v1 都可以访问。另外，导入时会自动打开用量查询，卡片上会显示你的剩余额度，每 30 分钟刷新一次。想在自己的脚本里查余额，看 API 余额查询教程。
方法二：在 CC Switch 里手动添加
不方便用一键导入时（例如在另一台电脑上），可以手动添加：
- 在 CC Switch 顶部切到要配置的应用页。
- 点右上角的 「+」，选「应用专属供应商」。
- 「预设」下拉选择 「自定义」，名称填「API 快连」。
- 按下面对应的写法填写配置，点「添加」，再在卡片上点「启用」。
Claude Code
Claude Code 的地址不带 /v1。密钥变量用 ANTHROPIC_AUTH_TOKEN 或 ANTHROPIC_API_KEY 都可以，推荐前者：用后者时 Claude Code 第一次启动会询问是否使用这个密钥，默认选项是「否」，直接回车会被拒绝。
Codex
Codex 的编辑框分两部分：上面的 API Key 部分填密钥，下面的 config.toml 部分填：
手动填写时 Codex 地址带 /v1（这也是 CC Switch 官方模板的写法），wire_api 保持 responses。切换到第三方服务商时，CC Switch 会把密钥写进 config.toml，不会改动你的 ChatGPT 官方登录信息。
Gemini CLI
自动获取可用模型
填好密钥和地址后，点模型输入框旁边的下载图标，CC Switch 会读取这把密钥能用的全部模型，直接从下拉里选，就不会写错模型名。也可以对照 模型广场。
测试连通与备用线路
- 鼠标移到供应商卡片上，点「检测连通」，可以看到地址是否可达和延迟（只测地址，不消耗额度）。
- 控制台还提供不经过 CDN 的直连线路
https://dc.apikl.ai。网络不稳定、长任务容易超时时，可以在编辑里把端点换成它（Codex 手动写法同样加 /v1），用法完全一样。
在官方账号和 API 快连之间切换
- 每个应用页里可以同时存多张供应商卡片，点哪张的「启用」就用哪张。
- 想切回官方账号：添加对应的官方预设（例如「Claude 官方」「OpenAI 官方」）并启用。
- 不打开主界面也能切换：右键点系统托盘里的 CC Switch 图标 → 选应用 → 点要用的供应商。
CC Switch 改了哪些文件
启用供应商时，CC Switch 只改下面这些文件里的地址、密钥、模型等关键字段，其他设置不动：
| 应用 | 配置文件 |
|---|---|
| Claude Code | ~/.claude/settings.json |
| Codex | ~/.codex/config.toml |
| Gemini CLI | ~/.gemini/.env、~/.gemini/settings.json |
这些文件第一次被 CC Switch 改写前的原样，会备份在 ~/.cc-switch/backups/ 里，需要时可以找回。
常见问题
点「导入到 CCS」没反应，或提示「CC-Switch 未安装或协议处理程序未注册」
先确认 CC Switch 已安装并打开过一次；浏览器拦截了「打开外部应用」时，点地址栏的提示允许。仍不行就用上面的「手动添加」。
启用了，但工具还是走原来的配置
最常见的原因是系统环境变量冲突：如果你以前在系统或 ~/.zshrc 里设置过 ANTHROPIC_BASE_URL、OPENAI_API_KEY、GEMINI_API_KEY 这类变量，它们会盖掉 CC Switch 写入的配置。CC Switch 检测到时会在界面顶部显示黄色警告，点「查看详情」勾选冲突变量删除即可（删除前会自动备份）；也可以手动删掉 shell 配置文件里对应的 export 行，或 Windows「系统属性 → 高级 → 环境变量」里的对应项。其次，Codex 和 Gemini CLI 需要重开才会读取新配置。
401 / invalid_api_key
密钥不完整、已删除，或分组选错（例如用 GPT 分组的密钥配 Claude Code）。在控制台确认密钥状态和分组，重新导入。更多看 401 排查。
404，或报错里出现网页内容
地址填错了。Claude Code 和 Gemini CLI 填 https://apikl.ai（不带 /v1）；Codex 手动填写带 /v1，并保持 wire_api = "responses"。
model not exist / 模型不存在
模型名写错，或密钥所在分组没有这个模型。用上面的「自动获取可用模型」重新选择，或看 模型不存在排查。
卡片上的余额显示「查询失败」
不影响正常使用。通常是密钥被删除、停用，或你手动改过用量查询脚本。重新从控制台导入一次即可恢复。
CC Switch 收费吗？安全吗？
官方版本开源免费。配置和密钥只存放在你自己的电脑上（~/.cc-switch/），只要从官网或 GitHub 下载就是安全的。
换电脑了怎么办
在新电脑上安装 CC Switch，再从控制台点一次「导入到 CCS」即可，密钥可以继续用。