CC Switch：一键接管 7 款主流 AI 客户端，是 AI 重度用户突破官方格式限制的桌面代理神器。
如今 AI 编程助手、桌面端大模型客户端越来越多，但不同客户端只兼容特定厂商的 API 格式，想切换国产大模型、统一管理多家服务商的密钥与用量，一直是件麻烦事。在 GitHub 开源社区广受关注的本地代理工具 CC Switch，正是为解决这个痛点而生的桌面级代理网关。
本文带你全面了解这款工具的作用、价值、全平台安装方法，以及支持的 AI 客户端的完整配置流程。
一、CC Switch 到底是什么？
CC Switch 是一款完全免费、开源的桌面应用，本质是运行在你本地电脑上的AI 请求代理网关。它架设在你的 AI 客户端（Claude 系列、Codex、OpenCode、Gemini CLI 等）与大模型服务商之间，负责协议格式转换、请求转发、密钥统一管理与用量统计。
简单来说，它能让原本只支持特定厂商原生格式的客户端，无缝接入几十家不同的大模型服务商，不用再等客户端官方适配，也不用在每个软件里反复配置密钥。
它的核心价值在哪里？
- 打破格式壁垒
很多主流 AI 客户端只支持官方原生接口，想换成国产大模型要么用不了，要么需要复杂的手动配置。CC Switch 内置了格式转换与原生接口适配，v3.16.4 中千问、火山豆包、小米 MiMo、MiniMax 等多家厂商的 Codex 请求，已经可以直连原生 Responses 端点，省去格式转换环节，链路更短更稳定。 - 多供应商统一管理
你可以在 CC Switch 里集中添加 Kimi、豆包、DeepSeek、通义千问等几十家服务商的 API 密钥，不用在每个 AI 客户端里分别填写。切换模型只需要在软件内切换启用的供应商，本地代理自动完成转发。 - 精准用量与成本统计
内置用量看板，支持按模型、按时间段统计调用消耗；还可以批量导入模型定价，自动计算成本。对于有免费额度、多套餐的服务商（比如火山方舟 Coding/Agent Plan），也支持直接查询配额余量。 - 本地运行安全可控
所有密钥、请求数据都保存在本地，代理转发全程在你自己的电脑上完成，不经过任何第三方中转服务器，数据隐私与密钥安全更有保障。 - 全平台原生兼容
覆盖 Windows、macOS、Linux 三大系统，同时支持 x64 与 ARM64 架构，v3.16.4 新增原生 Windows ARM64 构建，ARM 设备不用再靠 x64 模拟运行。
二、哪些人适合用 CC Switch？
如果你属于以下几类用户，CC Switch 会是非常实用的效率工具：
– 重度 AI 编程开发者：日常使用 Codex、Claude 系列、OpenCode 等 AI 编程客户端，希望灵活切换不同大模型，对比效果与成本；
– 多模型使用者：同时开通了多家大模型服务，需要统一管理 API 密钥、统计整体调用成本；
– 进阶技术用户：需要自定义请求头、模型映射规则，或者调试 AI 接口的进阶玩家；
– 跨平台设备用户：尤其是使用 Windows ARM 设备、国产 ARM 芯片电脑的用户，可获得原生适配体验；
– 注重数据可控的用户：不希望 AI 请求经过第三方中转服务，要求本地完成代理转发的隐私敏感用户。
三、全平台安装部署指南
官方渠道提醒
CC Switch 完全免费，所有收费、要求充值、索要登录凭据的"CC Switch"网站或客户端均为假冒。请仅通过以下官方渠道获取：
– 官网：ccswitch.io
– 源码与下载：GitHub 仓库 farion1231/cc-switch 的 Releases 页面
系统要求
| 系统 | 最低版本 | 支持架构 |
|---|---|---|
| Windows | Windows 10 及以上 | x64 / ARM64 |
| macOS | macOS 12 (Monterey) 及以上 | Intel x64 / Apple Silicon |
| Linux | 主流发行版 | x64 / ARM64 |
Windows 安装
- 推荐安装方式（MSI 包）
下载CC-Switch-v3.16.4-Windows.msi，双击运行按向导安装即可，该版本支持后续自动更新。 - 便携版
下载CC-Switch-v3.16.4-Windows-Portable.zip，解压后直接运行，不会写入系统注册表，适合 U 盘携带或不想安装的用户。注意：Windows ARM64 设备请选择文件名中带有
arm64标识的对应安装包。
macOS 安装
- 图形化安装（DMG 包）
下载CC-Switch-v3.16.4-macOS.dmg，打开后将应用拖入「应用程序」文件夹即可完成安装。 - Homebrew 命令安装
官方已简化安装步骤，无需提前添加仓库源，直接在终端执行：
brew install --cask cc-switch后续更新执行：
brew upgrade --cask cc-switchLinux 安装
Linux 同时提供 x86_64 与 ARM64 两种架构版本，可通过uname -m命令查看自己的架构后选择对应包：
– Ubuntu/Debian/Mint 系列：下载.deb包，执行sudo dpkg -i CC-Switch-*.deb或sudo apt install ./CC-Switch-*.deb
– Fedora/RHEL/CentOS 系列：下载.rpm包，执行sudo dnf install ./CC-Switch-*.rpm
– openSUSE：下载.rpm包，执行sudo zypper install ./CC-Switch-*.rpm
– 通用方案（所有发行版）：下载.AppImage文件，添加执行权限后直接运行：
chmod +x CC-Switch-.AppImage && ./CC-Switch-.AppImage四、全客户端配置实战
CC Switch 共支持 7 款主流 AI 客户端的本地代理接管，按协议类型分为三大类，在软件内对应不同的配置标签页，核心配置逻辑一致：添加供应商预设、填入 API 密钥、启用本地接管、重启对应客户端即可生效。
配置前请确认：目标客户端已安装并至少启动过一次，本地已生成对应配置目录；同时准备好目标大模型服务商的 API 密钥。
4.1 OpenAI 协议类客户端（Codex / OpenCode）
这类客户端原生基于 OpenAI 协议体系，CC Switch 提供专门的配置入口与格式适配，支持原生 Responses 直连与 Chat 格式转换两种模式。
4.1.1 Codex 客户端完整配置
Codex 是 CC Switch 支持的核心客户端之一，v3.16.4 对其代理链路做了重点优化，多家国产供应商已支持原生 Responses 直连，无需格式转换。
配置前准备
- 已安装 Codex CLI 或 Codex 桌面版，且至少启动过一次，生成本地配置目录：
- Windows：
C:\Users\你的用户名\.codex\ - macOS / Linux：
~/.codex/ - 已从目标服务商官网获取有效 API Key
- 已在 CC Switch 中添加并保存好对应的供应商配置
第一步：启用供应商，激活路由接管
只添加供应商不会自动生效，必须手动点击启用，CC Switch 才会修改 Codex 的本地配置文件，把请求导向本地代理。
1. 打开 CC Switch，点击顶部导航栏的 「Codex」 标签，进入 Codex 专属的供应商管理页。
2. 在列表里找到你已经配置好的供应商（比如 Kimi、火山豆包、DeepSeek 等），点击卡片上的 「启用/切换」 按钮。
3. 按钮点击后，该供应商卡片会高亮显示，代表它已经被设为 Codex 当前使用的服务。
– 此时 CC Switch 会自动备份你原本的 Codex 官方配置，同时把本地代理地址、认证密钥写入 Codex 的 config.toml 和 auth.json 文件，全程不需要手动编辑任何代码。
第二步：确认路由格式与映射开关
v3.16.4 把「上游格式」和「本地路由映射」拆成了两个独立设置，不同类型的供应商对应不同的开关状态，选错会导致请求失败。
类型 A：原生 Responses 供应商（推荐，无需额外开转换）
千问/百炼、小米 MiMo、火山豆包、美团 LongCat、MiniMax 国内/国际版，这几家在 v3.16.4 中已经直连原生 Responses 端点，不需要开启格式转换路由，链路最短最稳。
– 进入供应商「编辑 → 高级选项」，确认「上游格式」选择的是 Responses。
– 「本地路由映射」开关保持默认关闭即可，不用手动开启。
类型 B：Chat Completions 格式供应商
如果你的服务商只提供标准 OpenAI Chat 接口（/v1/chat/completions），则必须开启本地路由，由 CC Switch 完成 Responses → Chat 的格式转换，否则 Codex 会直接报 400/404 错误。
– 进入供应商「编辑 → 高级选项」，打开 「启用本地路由（模型映射与格式转换）」 开关。
– 开启后 CC Switch 会自动完成协议转换，不需要手动修改任何接口地址。
全局总开关确认
点击 CC Switch 右上角的设置图标，进入「代理」设置页，确认「全局代理总开关」已开启，并且在应用接管列表中，「Codex」对应的开关已勾选。只有勾选后，CC Switch 才会真正接管 Codex 的配置文件。
第三步：重启 Codex 客户端，使配置生效
配置写入后必须重启 Codex 才能加载新配置，只关闭窗口不算完全退出：
– Codex CLI（终端版）：关闭当前终端窗口，重新打开一个新终端即可生效。
– Codex 桌面版：右键任务栏托盘图标 → 选择「退出」，确保后台进程完全关闭，再重新打开软件。
– 注意：桌面版默认关闭窗口后会后台驻留，必须完全退出才会读取新配置。
第四步：验证路由是否真的生效
有两种方法可以确认请求已经走 CC Switch 代理：
方法1：查看配置文件（最准确）
打开 Codex 的配置文件目录，找到 config.toml 文件：
– Windows：C:\Users\你的用户名\.codex\config.toml
– macOS / Linux：~/.codex/config.toml
打开文件后找到 base_url 字段，如果值变成了 CC Switch 的本地代理地址（默认 http://127.0.0.1:15721/v1），就说明接管成功，所有请求都会先发到本地代理再转发。
方法2：查看调用记录
在 Codex 里发送一条测试消息，正常收到回复后，切回 CC Switch 的「用量」面板，看是否出现了对应的调用记录和 token 消耗。有记录就说明转发链路完全正常。
常见问题：桌面版看不到自定义模型怎么办？
这是最高频的疑问，官方明确说明：这是 Codex 桌面端自身的官方门控机制，不是 CC Switch 的配置问题。Codex 桌面版会根据你登录的官方账号权限显示模型列表，第三方模型不会出现在下拉菜单里。
官方推荐的解决方式：
1. 保持 Codex 的官方账号登录状态，不要退出登录，不要尝试绕过官方认证。
2. 开启 CC Switch 路由接管后，实际发出的请求会被代理转发到你配置的第三方模型，界面上显示的模型名不影响实际调用。
3. 切换模型：回到 CC Switch 的 Codex 面板，切换启用不同的供应商即可，无需在 Codex 内操作。
4. CLI 版本可以直接用 /model 模型名 命令指定你配置的模型，不受列表限制。
4.1.2 OpenCode 客户端配置
OpenCode 是另一款基于 OpenAI 兼容协议的 AI 编程客户端，配置逻辑与 Codex 类似，同样支持一键接管。
1. 在 CC Switch 顶部切换到对应标签页，点击加号添加供应商，可直接选择 OpenCode Go 等官方预设，自动适配接口格式。
2. 填入 API 密钥后保存，点击「启用」按钮，CC Switch 会自动写入 OpenCode 的本地配置文件。
3. 完全重启 OpenCode 客户端即可生效，调用记录会同步显示在用量面板中。
4.2 Anthropic 协议类客户端（Claude Code / Claude Desktop / OpenClaw / Hermes Agent）
Claude Code、Claude Desktop、OpenClaw、Hermes Agent 四款客户端均基于 Anthropic 协议，在 CC Switch 中统一通过「Claude」标签页管理，配置流程完全一致，启用后分别对对应客户端生效。
4.2.1 通用配置流程
- 打开 CC Switch，切换到顶部「Claude」标签页，点击右上角加号新建供应商。
- 在预设列表中选择目标服务商，预设已自动适配 Anthropic 接口格式，填入 API Key 即可完成基础配置。
- 进阶设置（可选）：展开高级选项，可配置模型映射规则、自定义请求头/请求体覆盖，调整推理参数等，适配不同服务商的接口特性。
- v3.16.4 已内置 DeepSeek 端点兼容性修复：当 Claude Code 子代理发送
thinking: disabled请求时，代理会自动剥离冲突的 effort 参数，避免返回 400 错误，无需用户手动处理。 - 点击保存后，在供应商列表中点击「启用」，CC Switch 会自动修改对应客户端的本地配置文件。
- 重启对应客户端即可生效；其中 Claude Code 支持热切换，启用后无需重启终端即可立即生效，桌面端客户端建议完全退出后重开。
4.2.2 Claude Code 与 Claude Desktop 配置要点
两款官方 Claude 客户端是最常用的 Anthropic 协议客户端，配置后支持全功能代理，包括工具调用、多轮会话等。
– 配置文件路径：
– Windows：C:\Users\你的用户名\.claude\
– macOS / Linux：~/.claude/
– 验证方式：发送测试消息后，在 CC Switch 用量面板查看调用记录，或检查配置文件中的代理地址是否已替换为本地代理地址。
– MCP 服务支持：当配置了自定义 Claude 配置目录时，MCP 服务器的读写会自动同步到对应目录下，按配置文件隔离状态。
4.2.3 OpenClaw 与 Hermes Agent 配置说明
OpenClaw 与 Hermes Agent 同样遵循 Anthropic 协议规范，无需单独的配置入口，复用 Claude 标签页的供应商配置：
– 当你在 Claude 标签页启用某个供应商后，本地的 OpenClaw 与 Hermes Agent 客户端会自动应用对应的代理配置，无需重复设置。
– 所有预设供应商均同时支持这两款客户端，比如豆包 Seed 2.1 Pro 预设会同时覆盖 Claude、Claude Desktop、OpenClaw、Hermes 四款 Anthropic 协议客户端。
4.3 Gemini CLI 客户端配置
Gemini CLI 是 Google 官方的命令行 AI 工具，CC Switch 支持通过 Gemini 兼容协议对其进行代理接管。
1. 添加支持 Gemini 协议的供应商预设（如 SubRouter 等），选择对应 Gemini 兼容端点。
2. 填入 API 密钥并保存，启用对应供应商后，CC Switch 会自动修改 Gemini CLI 的本地配置，将请求导向本地代理。
3. 重启终端中的 Gemini CLI 进程即可生效，所有调用都会经过本地代理转发。
五、核心功能进阶使用
5.1 用量统计与成本管理
CC Switch 的用量面板是很多用户的核心需求：
– 实时用量看板：可以按模型、按时间段查看调用量与消耗成本；
– 批量导入定价：在「添加定价」面板可以直接从 models.dev 批量导入模型定价，自动匹配本地模型，不用手动一个个输入价格；
– 专属套餐查询：火山方舟用户可以单独配置 AK/SK，直接查询 Coding Plan、Agent Plan 的配额剩余；
– 实时时间范围：自定义日期范围时可以开启「结束时间跟随当前时间」，随时查看从某一时刻到当下的实时消耗。
5.2 进阶代理配置
如果你有个性化需求，可以在供应商表单的「高级选项」中进行配置：
– 上游格式选择：Codex 供应商可以独立选择接口格式（Chat Completions / Responses），和模型映射开关分开控制，适配性更强；
– 本地请求覆盖：支持自定义请求头、请求体参数，本地代理转发时自动生效；同时软件内置了受保护的安全请求头名单，防止敏感参数被误修改；
– 模型映射：可以自定义模型名称映射规则，让客户端里的模型名对应到服务商的实际模型 ID。
5.3 实用细节功能
- 会话文件定位：会话详情页会显示日志文件名，点击即可复制路径，快速找到本地的 JSONL 日志文件；
- Skill 导入提示：顶部 Skills 导入按钮会在检测到本地有未托管的 Skill 时显示提示，避免遗漏本地资源；
- 数据库异常恢复：如果因为降级版本等原因导致数据库版本过新，软件不会直接报错退出，而是进入专门的恢复界面，引导你一键升级应用，数据不会丢失。
5.4 常见问题说明
- 降级软件后启动失败怎么办？
v3.16.4 新增了数据库版本过新的恢复屏，这是正常现象。按照界面提示升级到最新版本的 CC Switch，就能正常读取数据库，无需手动删除本地数据。
六、使用风险与注意事项
CC Switch 作为本地代理工具，使用时需要注意以下官方提示的风险：
1. 使用 ChatGPT 订阅的 Codex OAuth 反向代理，可能违反 OpenAI 的服务条款；
2. 将客户端请求转发到第三方大模型供应商时，需遵守对应服务商的计费、合规与数据留存规则；
3. 启用上述功能即表示你自行承担相关风险，CC Switch 不对账号限制、服务暂停等后果承担责任。
写在最后
CC Switch 不是面向普通聊天用户的工具，它精准命中了 AI 重度用户、开发者的痛点 —— 不用等待客户端官方适配，就能低成本、灵活地切换各家大模型，同时把密钥、用量、成本都管起来。
v3.16.4 版本在代理稳定性、功能丰富度、平台兼容性上都有大幅提升，新增的多项实用功能进一步降低了使用门槛。如果你日常重度依赖 AI 桌面客户端，不妨从官方渠道下载体验。