简报·YT
← 返回 GitHub 动态
farion1231/cc-switch · ⭐ 已Star 已完成

farion1231/cc-switch v4.0.15

2026-10-17 15:40 · ⭐ 14.6万 · GitHub Release 原文 ↗
#版本发布 #问题修复 #用量统计

farion1231/cc-switch v4.0.15

一句话概括:这是一个以修 bug 为主的维护版本,重点解决了 Windows 更新后 settings.json 被重置为默认值、Codex 更新时被误卸载、Claude Code 会话识别失败导致缓存键与工具调用异常等问题,并补充了用量趋势图样式切换等少量新能力。

新增能力

改进

修复问题

配置丢失(最严重) - Windows 上每次更新后隐藏应用、配置目录覆盖等设置被重置为默认值:根因是直接覆盖写 settings.json,新内容变短时旧内容尾部未被截断,下次启动整份解析失败,而读取失败又静默回退默认值,更新摘要一保存就把默认值写回。现在改为「先写临时文件再替换」;读取时去 BOM、有尾部垃圾时只读第一段 JSON、解析失败的字段单独丢弃其余保留;未完整读出的文件先备份为 settings.json.broken-<时间>.bak,备份成功前不保存。

更新与安装 - 更新 Codex 时若 --version 响应慢或启动失败,会先卸载再重装,重装失败即显示为未安装。现在只有 --version 真正运行并报错时才走该修复流程,其余情况正常升级。 - Windows「打开终端」报 'claude' 不是内部或外部命令:应用内更新自动重启后、或先开 CC Switch 再装 CLI 时,进程缺少用户级 PATH。现在打开的终端会带上完整的用户与系统 PATH。 - Windows 读不出 WSL 里的 Hermes 会话:改为在对应发行版内只读读取数据库,要求发行版内有 python3(3.7 及以上),其他路径不受影响。

路由与会话识别 - 经路由的请求认不出 Claude Code 会话:新版 Claude Code 把会话 ID 以 JSON 放在 metadata.user_id 中,旧解析逻辑失败导致同一对话每个请求都被当成新会话;Claude Desktop 请求也未读取会话头。后果是 Codex OAuth 无稳定缓存键、Claude Desktop 经路由连 Gemini 时工具调用报错。现在两种格式都能识别,Claude Desktop 也会读会话头。 - Codex 历史中存在一条参数损坏的工具调用(如输出截断、参数非完整 JSON)时,之后每轮都被 Chat 上游拒收;现在转换时把该调用改写为普通文字,正常历史不做任何改动。 - Codex 经路由连 DeepSeek 频繁 400:回放工具历史时,工具调用与结果之间的空消息、进度文字、思考内容被拆成独立消息,DeepSeek 不接受;现在仅对 DeepSeek 模型把这些内容并回工具调用那条消息,其他上游不受影响。 - Codex 聚合模式曾去掉 x-codex-beta-features 请求头,部分原生 Responses 网关需要它;现在发往原生 Responses 上游时保留,身份相关请求头仍去除。 - Claude Desktop 原生供应商配置模型映射时陷入死循环(保存映射要求先开路由,开路由又要求已有映射);现在未填模型列表的原生供应商可先进入路由,再在同一张卡上保存映射。 - 故障转移后「路由中」标记仍停留在原供应商。

同步、统计与 UI - WebDAV / S3 慢速传输在 300 秒被掐断:大 Skills 包在慢网下必然失败;现在总超时随文件大小放宽,下载另设 120 秒无数据超时,连接真卡住时仍能及时报错。 - Pi 子代理用量统计不上或记为 unknown:改为从每个子代理自己的会话文件导入,带上真实模型与供应商;从升级后第一次导入开始统计,历史不补算。 - Skills 下载失败的真实原因被「仓库或分支不存在,请检查地址」覆盖:现在只有 404 才切换分支(依次试 main、master),超时、压缩包过大、解压失败均按实际原因报错。 - DeepSeek 多币种钱包中一个余额为 0 时误显示「余额已用完」:现在只要还有钱包有余额就不列出空钱包,卡片也不再每次启动自动展开额度面板。 - 拖动排序供应商时卡片被拉伸、互相遮挡。 - 窗口较矮时 Codex 模型列表的思考等级弹窗下半截被截断:现在弹窗不超出窗口,放不下时列表在弹窗内滚动,「默认等级」始终可见。

破坏性变更与升级说明

▸ Release Notes 英文原文(5807 字符)
# CC Switch v4.0.15 本版本以修复为主:Windows 上更新后隐藏的应用、配置目录覆盖等设置会被重置为默认值的问题已修复;更新 Codex 时,`--version` 响应慢不会再把好好的 Codex 卸掉;macOS 应用图标改为白色圆角方块,macOS 26 不再把它塞进灰色底板。经路由的请求重新认得出 Claude Code 的会话,走 Codex OAuth 时的缓存键和 Claude Desktop 连 Gemini 时的签名回放都恢复正常;Codex 历史里有一条坏掉的工具调用时不再每轮都报错,DeepSeek 也不再拒收回放的工具历史。另外修复了 WebDAV/S3 慢速传输 300 秒被掐断、Windows 上「打开终端」找不到 `claude`、WSL 里的 Hermes 会话读不出、路由切换总是提示重启等问题。新增用量趋势图的柱形图 / 曲线面积图切换、Hermes 按模型声明图片输入,Claude Desktop 表单也能为 Copilot 等托管登录的供应商获取模型列表。4.0 完整的更新内容请见 [v4.0 发布说明](https://github.com/farion1231/cc-switch/blob/main/docs/release-notes/v4.0.4-zh.md)。 **[English →](https://github.com/farion1231/cc-switch/blob/main/docs/release-notes/v4.0.15-en.md) | [日本語版 →](https://github.com/farion1231/cc-switch/blob/main/docs/release-notes/v4.0.15-ja.md)** --- ## 新增 **用量趋势图可以选柱形图或曲线面积图**([#8406](https://github.com/farion1231/cc-switch/issues/8406))。在用量页「设置」页签的「显示」区,「趋势图样式」可以选柱形图(默认)或曲线面积图,两种样式的指标、坐标轴、悬停提示和币种换算都一样。「显示」区的几项设置也重新排成了对齐的两列,汇率单独一行,放在币种下面。 **Hermes 可以按模型声明支持图片输入**([#8464](https://github.com/farion1231/cc-switch/issues/8464))。Hermes 按每个模型的 `supports_vision` 判断能不能看图,没写的未知模型会被当成纯文本、图片被压成文字;以前表单里没有地方设置,手写的值保存后也会被冲掉。现在展开模型详情后有「支持图片输入」开关:打开写 `supports_vision: true`,关掉则删除这个键,交给 Hermes 自己判断。从模型列表选到已知支持图片的模型时会自动打开。 **Claude Desktop 可以为托管登录的供应商获取模型列表**([#8426](https://github.com/farion1231/cc-switch/issues/8426))。GitHub Copilot、Codex OAuth、xAI OAuth 这类供应商以前在 Desktop 表单里没有「获取模型列表」按钮,现在有了,会按登录的账号拉取;还没登录时先提示登录。换了供应商类型或账号后,列表会清空重拉,不会混进别的账号的模型。 ## 改进 **路由下切换供应商,提示写明实际做了什么**([#8347](https://github.com/farion1231/cc-switch/issues/8347))。以前路由模式下切换,Codex、Gemini CLI、Grok Build 总会提示重启客户端。现在提示会说明是记住了供应商、改了路由目标、切换了路由,还是改了聚合默认供应商;只有客户端配置文件确实改了,才提示重启。 **侧栏「今日」不再带「今日」前缀。** 只选一项时也和选两项时一样只显示数值,完整说明在悬停提示里。 **Claude Code 用量导入更快**([#8224](https://github.com/farion1231/cc-switch/issues/8224))。同一次导入里,查过的模型价格会复用,不再每条记录都查一遍;改了价格,下一次导入就会用上。 **土耳其语**:补齐了卸载和套餐额度相关的新文案([#8291](https://github.com/farion1231/cc-switch/pull/8291))。 **预设:** 新增 EveryAPI、AllTokens。 ## 修复 - **Windows 上每次更新后,隐藏的应用、配置目录覆盖等设置被重置为默认值**([#8429](https://github.com/farion1231/cc-switch/issues/8429))。以前直接覆盖写 `settings.json`,个别环境下新内容变短时,旧内容的尾巴没被截掉,下次启动整份解析失败;读取失败时又悄悄用了默认值,更新后弹出的更新摘要一保存,就把默认值写了回去。现在先写临时文件再替换;读取时会去掉 BOM,有尾巴时只读第一段 JSON,解析不了的字段单独丢掉、其余照常保留。没有完整读出的文件会先备份成 `settings.json.broken-<时间>.bak`,备份成功之前不会保存。 - **更新 Codex 时,`--version` 响应慢会把好好的 Codex 卸掉。** 以前更新前检测到 `--version` 超时或启动失败,就会先卸载再重装,重装一失败,Codex 就显示成未安装。现在只有 `--version` 真的运行并报错时才这样修复,其余情况照常升级。 - **macOS 26 把应用图标放进灰色底板并缩小**([#8401](https://github.com/farion1231/cc-switch/issues/8401))。macOS 应用图标现在自带白色圆角方块,macOS 26 和 15 显示一致;Windows 和 Linux 图标不变。 - **经路由的请求认不出 Claude Code 的会话**([#8235](https://github.com/farion1231/cc-switch/issues/8235)、[#8234](https://github.com/farion1231/cc-switch/issues/8234)、[#8418](https://github.com/farion1231/cc-switch/issues/8418))。新版 Claude Code 把会话 ID 写成 JSON 放在 `metadata.user_id` 里,路由以前解析不了,同一个对话的每个请求都被当成新会话;Claude Desktop 的请求也没有读会话头。结果是走 Codex OAuth 时没有稳定的缓存键,Claude Desktop 经路由连 Gemini 时工具调用报错。现在两种格式都认得,Claude Desktop 也读会话头。 - **Codex 历史里有一条参数坏掉的工具调用时,之后每轮都被 Chat 上游拒收**([#5197](https://github.com/farion1231/cc-switch/issues/5197))。例如输出被截断、参数不是完整的 JSON。现在转换时把这条调用改写成普通文字,正常的历史一个字节都不改。 - **Codex 经路由连 DeepSeek 经常报 400**([#8331](https://github.com/farion1231/cc-switch/issues/8331))。回放工具历史时,工具调用和结果之间夹着的空消息、进度文字或思考内容会被拆成单独的消息,DeepSeek 不接受。现在只对 DeepSeek 模型把它们并回工具调用那条消息,其他上游不受影响。 - **Codex 聚合模式去掉了 `x-codex-beta-features` 请求头**([#8435](https://github.com/farion1231/cc-switch/issues/8435))。部分原生 Responses 网关需要这个头。现在发往原生 Responses 上游时保留它,身份相关的请求头仍然去掉。 - **Claude Desktop 原生供应商配模型映射时卡在死循环**([#8441](https://github.com/farion1231/cc-switch/issues/8441))。保存映射要求先开路由,开路由又要求已有映射。现在没填模型列表的原生供应商可以先进入路由,再在同一张卡上保存映射。 - **WebDAV / S3 同步慢速传输到 300 秒就被掐断**([#8428](https://github.com/farion1231/cc-switch/issues/8428))。慢速网络下,传输超过 300 秒的大 Skills 包会失败。现在总超时随文件大小放宽,下载另设 120 秒无数据超时,连接真卡住时仍会及时报错。 - **Windows 上卡片的「打开终端」报「'claude' 不是内部或外部命令」**([#8446](https://github.com/farion1231/cc-switch/issues/8446))。应用内更新自动重启后,或先打开 CC Switch 再安装 CLI 时,进程里缺少用户级 PATH,终端沿用了它。现在打开的终端会带上完整的用户和系统 PATH。 - **Windows 上读不出 WSL 里 Hermes 的会话**([#8205](https://github.com/farion1231/cc-switch/issues/8205))。Hermes 数据在 WSL 里时,改为在对应的发行版内只读读取数据库;需要发行版里有 `python3`(3.7 及以上)。其他路径不受影响。 - **故障转移后,「路由中」标记还停在原来那家**([#7998](https://github.com/farion1231/cc-switch/issues/7998))。 - **Pi 子代理的用量统计不上,或记成 unknown**([#8298](https://github.com/farion1231/cc-switch/issues/8298))。现在从每个子代理自己的会话文件导入,带上真实的模型和供应商;从升级后第一次导入起统计,之前的不补算。 - **拖动排序供应商时卡片被拉伸、互相遮挡**([#8283](https://github.com/farion1231/cc-switch/issues/8283))。 - **Skills 下载失败时,真正的原因被「仓库或分支不存在,请检查地址」盖掉。** 以前配置的分支失败后会依次试 main、master,最后报的是 master 的 404。现在只有 404 才换分支,超时、压缩包过大、解压失败都按原因报错。 - **DeepSeek 一个币种的钱包还有余额,另一个为 0 时显示「余额已用完」**([#8170](https://github.com/farion1231/cc-switch/issues/8170))。现在只要有钱包还有余额,就不再列出空钱包,卡片也不会每次启动都自动展开额度面板。 - **窗口较矮时,Codex 模型列表的思考等级弹窗下半截被截掉**([#8094](https://github.com/farion1231/cc-switch/issues/8094))。现在弹窗不超出窗口,放不下时列表在弹窗里滚动,「默认等级」一直可见。 ## 升级说明 **数据库结构没有变化**,仍然是 20。 - Windows 上已经带尾巴的 `settings.json` 会在首次启动时恢复,原文件保留为 `settings.json.broken-<时间>.bak`;之前更新时已经被重置的设置无法找回。 - Pi 子代理用量从升级后第一次导入开始统计,之前的记录保持原样。 - 在 Windows 上读取 WSL 里的 Hermes 会话,需要发行版里装有 `python3`(3.7 及以上)。 --- ## 致谢 感谢 @Foodie05(Claude Code 会话识别)、@MonsterXia(Codex 坏工具调用历史)、@funkpopo(DeepSeek 工具历史、趋势图样式、拖动排序)、@JfanLiu(聚合模式 beta 请求头)、@ix-prism(Claude Desktop 映射循环)、@Dante-dan(WSL 里的 Hermes 会话)、@SmileMachine(路由切换提示)、@Chaoqi31(Pi 子代理用量)、@Carl723000(用量导入提速)、@alkank(土耳其语)、@NestorRay(面板过渡清理)的贡献。 感谢 @wangding0610、@DiYi1999、@CaiSre、@vincerise、@qiangyidian、@zhouys0725、@qianlongwuyong-zxl、@ElijahHong、@wx2cyj、@rvwmng9rvk-crypto、@luckday888、@ramonmi、@quntaoli、@LwTen2019、@CYRickyArAr、@edwardchenchen、@ximigoo 报告问题、提供复现信息和修复思路。 完整的技术细节请见 [CHANGELOG](https://github.com/farion1231/cc-switch/blob/main/CHANGELOG.md)。
▸ 主项目介绍 · farion1231/cc-switch
▸ README 原文(同步于 2026-07-20 03:47)
<div align="center"> # CC Switch ### The All-in-One Manager for Claude Code, Claude Desktop, Codex, Gemini CLI, Grok Build, OpenCode, OpenClaw & Hermes Agent [![Version](https://img.shields.io/github/v/release/farion1231/cc-switch?color=blue&label=version)](https://github.com/farion1231/cc-switch/releases) [![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey.svg)](https://github.com/farion1231/cc-switch/releases) [![Built with Tauri](https://img.shields.io/badge/built%20with-Tauri%202-orange.svg)](https://tauri.app/) [![Downloads](https://img.shields.io/github/downloads/farion1231/cc-switch/total)](https://github.com/farion1231/cc-switch/releases/latest) <a href="https://trendshift.io/repositories/15372" target="_blank"><img src="https://trendshift.io/api/badge/repositories/15372" alt="farion1231%2Fcc-switch | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a> <a href="https://www.star-history.com/#farion1231/cc-switch&Date"><picture><source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/badge?repo=farion1231/cc-switch&theme=dark" /><img alt="Star History Rank" src="https://api.star-history.com/badge?repo=farion1231/cc-switch" width="196" height="55" /></picture></a> ### 🌐 The Only Official Website: **[ccswitch.io](https://ccswitch.io)** English | [中文](README_ZH.md) | [日本語](README_JA.md) | [Deutsch](README_DE.md) | [Changelog](CHANGELOG.md) </div> ## ❤️Sponsor > [Want to appear here?](mailto:farion1231@gmail.com) <details open> <summary>Click to collapse</summary> [![Kimi K2.7 Code](assets/partners/banners/kimi-banner-en.png)](https://platform.kimi.ai?aff=cc-switch) Kimi K2.7 Code is an open-source, coding-focused agentic model developed by Moonshot AI. It delivers stronger coding and agent performance, with substantial improvements in real-world long-horizon coding tasks. These gains translate into higher end-to-end task success rates across complex software engineering workflows. K2.7 Code also improves reasoning efficiency, reducing thinking-token usage by approximately 30% compared with K2.6. **[Click here to start using Kimi](https://platform.kimi.ai?aff=cc-switch)** Doing mostly coding work? Try the **[Kimi For Coding plan](https://www.kimi.com/code/?aff=cc-switch)** — a subscription service built for coding! --- <table> <tr> <td width="180"><a href="https://www.packyapi.com/register?aff=cc-switch"><img src="assets/partners/logos/packycode.png" alt="PackyCode" width="150"></a></td> <td>Thanks to PackyCode for sponsoring this project! PackyCode is a reliable and efficient API relay service provider, offering relay services for Claude Code, Codex, Gemini, and more. PackyCode provides special discounts for our software users: register using <a href="https://www.packyapi.com/register?aff=cc-switch">this link</a> and enter the "cc-switch" promo code during first recharge to get 10% off.</td> </tr> <tr> <td width="180"><a href="https://aigocode.com/invite/CC-SWITCH"><img src="assets/partners/logos/aigocode.png" alt="AIGoCode" width="150"></a></td> <td>Thanks to AIGoCode for sponsoring this project! AIGoCode is an all-in-one platform that integrates Claude Code, Codex, and the latest Gemini models, providing you with stable, efficient, and highly cost-effective AI coding services. The platform offers flexible subscription plans, zero risk of account suspension, direct access with no VPN required, and lightning-fast responses. AIGoCode has prepared a special benefit for CC Switch users: if you register via <a href="https://aigocode.com/invite/CC-SWITCH">this link</a>, you'll receive an extra 10% bonus credit on your first top-up!</td> </tr> <tr> <td width="180"><a href="https://www.aicodemirror.com/register?invitecode=9915W3"><img src="assets/partners/logos/aicodemirror.jpg" alt="AICodeMirror" width="150"></a></td> <td>Thanks to AICodeMirror for sponsoring this project! AICodeMirror provides official high-stability relay services for Claude Code / Codex / Gemini CLI, with enterprise-grade concurrency, fast invoicing, and 24/7 dedicated technical support. Claude Code / Codex / Gemini official channels at 38% / 2% / 9% of original price, with extra discounts on top-ups! AICodeMirror offers special benefits for CC Switch users: register via <a href="https://www.aicodemirror.com/register?invitecode=9915W3">this link</a> to enjoy 20% off your first top-up, and enterprise customers can get up to 25% off!</td> </tr> <tr> <td width="180"><a href="https://www.shengsuanyun.com/?from=CH_4HHXMRYF"><img src="assets/partners/logos/shengsuanyun.png" alt="Shengsuanyun" width="150"></a></td> <td>Thanks to Shengsuanyun for sponsoring this project! Shengsuanyun is a super factory serving AI Native Teams — an industrial-grade AI task parallel execution platform. Its model marketplace aggregates Claude, ChatGPT, Gemini, and other domestic and international LLM and multimedia model capabilities with direct supply. Absolutely no reverse engineering or dilution — platform-wide model SLA availability reaches 99.7%, with <a href="https://watch.shengsuanyun.com/status/shengsuanyun">monitoring dashboards</a> showing green across the board. It also offers enterprise-grade custom gateways for fine-grained team cost and permission management, smart routing, security protection, and BYOK (Bring Your Own Key) hosting. The platform charges on a pay-per-use and tokens plan (coming soon) basis, with invoicing available. Register via <a href="https://www.shengsuanyun.com/?from=CH_4HHXMRYF">this link</a> as a new user to receive ¥10 in credits plus a 10% bonus on your first top-up.</td> </tr> <tr> <td width="180"><a href="https://pateway.ai/?ch=etzpm8&aff=WB6M6F67#/"><img src="assets/partners/logos/pateway.png" alt="PatewayAI" width="150"></a></td> <td>Thanks to PatewayAI for sponsoring this project! PatewayAI is an API relay service provider built for heavy AI developers, focused on directly relaying official high-quality model APIs. It offers the full Claude lineup and the Codex series, 100% sourced from official channels — no dilution, no fakes, verification welcome. Billing is transparent and every token-level invoice can be audited line by line. It also supports enterprise-grade concurrency and provides a dedicated management platform for enterprise customers — formal contracts and invoicing are available; visit the official website for contact details. Register now via <a href="https://pateway.ai/?ch=etzpm8&aff=WB6M6F67#/">this link</a> to receive $3 in trial credit. Top-ups go as low as 60% of the original price, with a two-way referral bonus of up to $150!</td> </tr> <tr> <td width="180"><a href="https://teamorouter.com/?utm_source=cc_switch&utm_medium=referral&utm_campaign=ai_directory"><img src="assets/partners/logos/TeamoRouter-banner.png" alt="TeamoRouter" width="150"></a></td> <td>Thanks to TeamoRouter for sponsoring this project! TeamoRouter is an enterprise-grade Agentic LLM gateway built for developers, AI teams, and businesses. Without requiring any subscriptions, it lets you access Claude Code, Codex, Gemini CLI, OpenAI Codex, and other popular AI agents through a single unified API, while offering API pricing at discounts of up to 90%. Unlike typical API relay services, TeamoRouter aggregates hundreds of official model providers and trusted infrastructure partners, including OpenAI, Anthropic, Vertex, Azure, and AWS bedrock. Every provider is verified for 100% Agent protocol compatibility, cache performance, and request traceability, ensuring stable quality instead of reverse-engineered or diluted endpoints. The platform delivers near-official TTFT, 99.6% SLA, enterprise-scale throughput up to 5,000 QPM, and industry-leading cache hit rates that dramatically reduce token costs for long-running agent workflows. TeamoRouter also offers enterprise features including centralized billing, team management, BYOK, smart routing, usage analytics, dynamic provider optimization, and dedicated support. For an even simpler experience, Teamo Desktop lets you use Claude Code, Codex, Gemini CLI, and other popular AI agents with one-click setup—no API key management or manual gateway configuration required. Register via <a href="https://teamorouter.com/?utm_source=cc_switch&utm_medium=referral&utm_campaign=ai_directory">this link</a> as a new user to receive 10% off your first top-up.</td> </tr> <tr> <td width="180"><a href="https://zetaapi.ai/go/ccs"><img src="assets/partners/logos/zetaapi-banner.png" alt="ZetaAPI" width="150"></a></td> <td>Thanks to ZetaAPI for sponsoring this project! ZetaAPI focuses on real model fidelity, no watered-down responses, no quality degradation, and pricing as low as 35% of official rates. The platform does not mix traffic, secretly replace models with lower-quality alternatives, or use fake model routing. It supports Claude Code, Codex, Gemini, ChatGPT, and other mainstream AI models, helping users significantly reduce API costs while maintaining reliable model quality. At the same time, ZetaAPI provides enterprise-grade SLA-backed stability, standard API compatibility, one API key for multiple models, fast integration, and pay-as-you-go billing, making it suitable for AI products, coding agents, internal business tools, customer service systems, content generation, and automation workflows. If any model is verified to be inconsistent with its stated quality, ZetaAPI backs it with a 10x compensation guarantee, giving users a more stable, transparent, and trustworthy experience. Register via <a href="https://zetaapi.ai/go/ccs">this link</a> and use the promo code CC-SWITCH during your first recharge to enjoy an exclusive 10% discount on your first top-up, just for CC Switch users!</td> </tr> <tr> <td width="180"><a href="https://www.byteplus.com/en/product/modelark?utm_campaign=hw&utm_content=ccswitch&utm_medium=devrel_tool_web&utm_source=OWO&utm_term=ccswitch"><img src="assets/partners/logos/byteplus.png" alt="BytePlus" width="150"></a></td> <td>Thanks to Dola seed for sponsoring this project! Dola Seed 2.0 is a full‑modal general large model independently developed by ByteDance for the global market. Built on a unified multimodal architecture, it supports joint understanding and generation of text, images, audio, and video. It natively enables agent collaboration, with strong reasoning, long‑task execution, tool integration, and coding capabilities. It is widely applicable to smart cockpits, personal assistants, education, customer support, marketing, retail, and other scenarios. It excels in multimodal perception, end‑to‑end complex task delivery, stable interaction, and data security, and is readily accessible and deployable via the ModelArk platform.Register via <a href="https://www.byteplus.com/en/product/modelark?utm_campaign=hw&utm_content=ccswitch&utm_medium=devrel_tool_web&utm_source=OWO&utm_term=ccswitch">this link</a> to get 500,000 tokens of free inference quota per model.<a href="https://www.volcengine.com/activity/ai618?utm_campaign=hw&utm_content=hw&utm_medium=devrel_tool_web&utm_source=OWO&utm_term=ccswitch"> >>中国大陆地区的开发者请点击这里</a></td> </tr> <tr> <td width="180"><a href="https://cloud.siliconflow.cn/i/YflgU2Ve"><img src="assets/partners/logos/silicon_en.jpg" alt="SiliconFlow" width="150"></a></td> <td>Thanks to SiliconFlow for sponsoring this project! SiliconFlow is a high-performance AI infrastructure and model API platform, providing fast and reliable access to language, speech, image, and video models in one place. With pay-as-you-go billing, broad multimodal model support, high-speed inference, and enterprise-grade stability, SiliconFlow helps developers and teams build and scale AI applications more efficiently. Register via <a href="https://cloud.siliconflow.cn/i/YflgU2Ve">this link</a> and complete real-name verification to receive ¥16 in bonus credit, usable across models on the platform. SiliconFlow is also now compatible with OpenClaw, allowing users to connect a SiliconFlow API key and call major AI models for free.</td> </tr> <tr> <td width="180"><a href="https://cubence.com/signup?code=CCSWITCH&source=ccs"><img src="assets/partners/logos/cubence.png" alt="Cubence" width="150"></a></td> <td>Thanks to Cubence for sponsoring this project! Cubence is a reliable and efficient API relay service provider, offering relay services for Claude Code, Codex, Gemini, and more with flexible billing options including pay-as-you-go and monthly plans. Cubence provides special discounts for CC Switch users: register using <a href="https://cubence.com/signup?code=CCSWITCH&source=ccs">this link</a> and enter the "CCSWITCH" promo code during recharge to get 10% off every top-up!</td> </tr> <tr> <td width="180"><a href="https://www.dmxapi.cn/register?aff=bUHu"><img src="assets/partners/logos/dmx-en.jpg" alt="DMXAPI" width="150"></a></td> <td>Thanks to DMXAPI for sponsoring this project! DMXAPI provides global large model API services to 200+ enterprise users. One API key for all global models. Features include: instant invoicing, unlimited concurrency, starting from $0.15, 24/7 technical support. GPT/Claude/Gemini all at 32% off, domestic models 20-50% off, Claude Code exclusive models at 66% off! <a href="https://www.dmxapi.cn/register?aff=bUHu">Register here</a></td> </tr> <tr> <td width="180"><a href="https://www.compshare.cn/coding-plan?ytag=GPU_YY_YX_git_cc-switch"><img src="assets/partners/logos/ucloud.png" alt="Compshare" width="150"></a></td> <td>Thanks to Compshare for sponsoring this project! Compshare is UCloud's AI cloud platform, providing stable and comprehensive domestic and international model APIs with just one key. Featuring cost-effective monthly and per-use domestic-model Coding Plan packages, alongside stable officially-relayed overseas models. Supports Claude Code, Codex, and API access. Enterprise-grade high concurrency, 24/7 technical support, and self-service invoicing. Users who register via <a href="https://www.compshare.cn/coding-plan?ytag=GPU_YY_YX_git_cc-switch">this link</a> will receive a free 5 CNY platform trial credit!</td> </tr> <tr> <td width="180"><a href="https://crazyrouter.com/register?aff=OZcm&ref=cc-switch"><img src="assets/partners/logos/crazyrouter.png" alt="Crazyrouter" width="150"></a></td> <td>Thanks to Crazyrouter for sponsoring this project! Crazyrouter is a high-performance AI API aggregation platform — one API key for 300+ models including Claude Code, Codex, Gemini CLI, and more. All models at 55% of official pricing with auto-failover, smart routing, and unlimited concurrency. Crazyrouter offers an exclusive deal for CC Switch users: register via <a href="https://crazyrouter.com/register?aff=OZcm&ref=cc-switch">this link</a> and contact customer support to claim <strong>$2 free credit</strong>, plus enter promo code `CCSWITCH` on your first top-up for an extra <strong>30% bonus credit</strong>! </td> </tr> <tr> <td width="180"><a href="https://www.right.codes/register?aff=CCSWITCH"><img src="assets/partners/logos/rightcode.jpg" alt="RightCode" width="150"></a></td> <td>Thank you to Right Code for sponsoring this project! Right Code reliably provides routing services for models such as Claude Code, Codex, and Gemini, with both pay-as-you-go and monthly subscription billing options available. Invoices are available upon top-up, and enterprise and team users can receive dedicated one-on-one support. Right Code also offers an exclusive discount for CC Switch users: register via <a href="https://www.right.codes/register?aff=CCSWITCH">this link</a>, and with every top-up you will receive pay-as-you-go credit equivalent to 5% of the amount paid.</td> </tr> <tr> <td width="180"><a href="https://www.sssaicode.com/register?ref=DCP0SM"><img src="assets/partners/logos/sssaicode.png" alt="SSSAiCode" width="150"></a></td> <td>Thanks to SSSAiCode for sponsoring this project! SSSAiCode is a stable and reliable API relay service, dedicated to providing stable, reliable, and affordable Claude and Codex model services, with same-day fast invoicing. SSSAiCode offers a special deal for CC Switch users: register via <a href="https://www.sssaicode.com/register?ref=DCP0SM">this link</a> to enjoy $10 extra credit on every top-up!</td> </tr> <tr> <td width="180"><a href="https://www.micuapi.ai/register?aff=aOYQ"><img src="assets/partners/logos/mikubanner.svg" alt="Micu" width="150"></a></td> <td>Thanks to Micu API for sponsoring this project! Micu API is a global LLM relay service provider dedicated to delivering the best cost-performance ratio with high stability. Backed by a registered enterprise for core assurance, eliminating any risk of service discontinuation, with fast official invoicing support! We champion "zero cost to try": top up from as low as ¥1 with no minimum, and get fee-free refunds anytime! Micu API offers an exclusive deal for CC Switch users: register via <a href="https://www.micuapi.ai/register?aff=aOYQ">this link</a> and enter promo code "ccswitch" when topping up to enjoy a <strong>10% discount</strong>!</td> </tr> <tr> <td width="180"><a href="https://etok.ai"><img src="assets/partners/logos/etok.png" alt="ETok" width="150"></a></td> <td>Thanks to ETok.ai for sponsoring this project! ETok.ai is dedicated to building a one-stop AI programming tool service platform. We offer professional Claude Code packages and technical community services, with support for Google Gemini and OpenAI Codex. Through carefully designed plans and a professional tech community, we provide developers with reliable service guarantees and continuous technical support, making AI-assisted programming a true productivity tool. Click <a href="https://etok.ai">here</a> to register!</td> </tr> <tr> <td width="180"><a href="https://console.claudeapi.com/register?aff=pCLD"><img src="assets/partners/logos/claudeapi.png" alt="ClaudeAPI" width="150"></a></td> <td>This project is sponsored by <a href="https://console.claudeapi.com/register?aff=pCLD">Claude API</a>. Direct Claude API access — connect Claude Code and Agent apps in 3 minutes. New users can claim a free trial credit.Powered by official Anthropic API keys + AWS Bedrock official channels. No reverse engineering, no model degradation. Full support for Opus / Sonnet / Haiku model lineup, with official capabilities preserved including Tool Use, 1M context window, and more. Built for Claude Code power users, Agent engineers, and enterprise engineering teams. Invoicing and dedicated team support available. Click <a href="https://console.claudeapi.com/register?aff=pCLD">here</a> to register!</td> </tr> <tr> <td width="180"><a href="https://code0.ai/agent/register/B2XHxGjGmRvqgznY"><img src="assets/partners/logos/code0.png" alt="code0.ai" width="150"></a></td> <td>Thanks to <a href="https://code0.ai/agent/register/B2XHxGjGmRvqgznY">code0.ai</a> for sponsoring this project! code0.ai is an AI coding service platform built for developers, supporting Claude Code, Codex, Gemini, and other mainstream AI coding capabilities. It helps individual developers and teams use AI Agents more stably and efficiently for coding, debugging, refactoring, and automation workflows. ccswitch users can contact customer support via the <a href="https://code0.ai/agent/register/B2XHxGjGmRvqgznY">code0.ai website</a> to claim test credits and experience a reliable AI coding service.</td> </tr> <tr> <td width="180"><a href="https://claudecn.top"><img src="assets/partners/logos/claudecn.jpg" alt="ClaudeCN" width="150"></a></td> <td>Thanks to ClaudeCN for sponsoring this project! ClaudeCN is an enterprise-grade AI gateway platform operated by a registered company. It delivers high-availability commercial API access to popular models including Claude, GPT, and DeepSeek, and is built around formal enterprise procurement workflows — corporate bank transfers, signed contracts, and full compliance. Register via <a href="https://claudecn.top">this link</a>!</td> </tr> <tr> <td width="180"><a href="https://runapi.co"><img src="assets/partners/logos/runapi.jpg" alt="RunAPI" width="150"></a></td> <td>Thanks to RunAPI for sponsoring this project! RunAPI is a high-performance and reliable AI model API gateway — one API key gives you access to 150+ mainstream models including OpenAI, Claude, Gemini, DeepSeek, and Grok, with prices as low as 10% of the official rate and excellent stability. It works seamlessly with Claude Code, OpenClaw, and other tools. Exclusive benefit for CC Switch users: register and contact customer support to claim a free ¥14 credit. Register via <a href="https://runapi.co">this link</a>!</td> </tr> <tr> <td width="180"><a href="https://apikey.fun/register?aff=CCSwitch"><img src="assets/partners/logos/apikey_banner.png" alt="APIKEY.FUN" width="150"></a></td> <td>Thanks to APIKEY.FUN for sponsoring this project! APIKEY.FUN is a professional enterprise-grade AI relay platform dedicated to providing stable, efficient, and low-cost AI model API access for enterprises and individual developers. The platform supports popular mainstream models such as Claude, OpenAI, and Gemini, with prices as low as 7% of official rates. Register through this project's <a href="https://apikey.fun/register?aff=CCSwitch">exclusive link</a> to enjoy an exclusive offer of up to <strong>permanent 5% off top-ups</strong>.</td> </tr> <tr> <td width="180"><a href="https://apinebula.com/02rw5X"><img src="assets/partners/logos/apinebula_banner.png" alt="APINebula" width="150"></a></td> <td>Thanks to APINEBULA for sponsoring this project! APINEBULA, an enterprise-grade AI aggregation platform under Galaxy Video Bureau, leverages extensive platform resources to provide developers, teams, and enterprises with stable, cost-effective access to large language model APIs. The platform integrates leading, full-powered models like Claude, GPT, and Gemini, allowing you to connect to the world's top AI models through a single API, with prices starting as low as 10% of the original cost. Designed for AI programming, Agent development, and business system integration, APINEBULA supports enterprise-grade high concurrency, formal contracts, corporate bank transfers, and invoicing services. APINEBULA provides special discounts for our software users: register using <a href="https://apinebula.com/02rw5X">this link</a> and enter the <strong>"ccswitch"</strong> promo code during your first recharge to get <strong>10% off</strong>.</td> </tr> <tr> <td width="180"><a href="https://www.atlascloud.ai/coding-plan?utm_source=github&utm_campaign=cc-switch"><img src="assets/partners/logos/atlascloud_banner.png" alt="Atlas Cloud" width="150"></a></td> <td>Atlas Cloud is a full-modal AI inference platform that gives developers a single AI API to access video generation, image generation, and LLM APIs. Instead of managing multiple vendor integrations, you connect once and get unified access to 300+ curated models across all modalities. Check out Atlas Cloud's new <a href="https://www.atlascloud.ai/coding-plan?utm_source=github&utm_campaign=cc-switch">coding plan</a> promotion for more budget-friendly API access!</td> </tr> <tr> <td width="180"><a href="https://www.ccsub.net/register?ref=Y6Z8DXEA"><img src="assets/partners/logos/ccsub.svg" alt="CCSub" width="150"></a></td> <td>Thanks to CCSub for sponsoring this project! CCSub is a stable, affordable AI API relay platform — your drop-in replacement for a Claude.ai subscription. One API key gives you access to Claude Opus 4.8, Sonnet, Haiku, GPT-5, Gemini, and DeepSeek at roughly 30% of direct API cost, with no VPN required from anywhere in the world. Compatible with Claude Code, Codex, Cursor, Cline, Continue, Windsurf, and all major AI coding tools. Register via <a href="https://www.ccsub.net/register?ref=Y6Z8DXEA">this link</a> and get $5 free credit on sign-up.</td> </tr> <tr> <td width="180"><a href="https://unity2.ai/register?source=ccs"><img src="assets/partners/logos/unity2.jpg" alt="Unity2.ai" width="150"></a></td> <td>Thanks to Unity2.ai for sponsoring this project! Unity2.ai is a high-performance AI model API relay platform for individual developers, teams, and enterprises. Long trusted by leading companies in China, it serves over 30 billion tokens per day and supports high concurrency at the 5,000 RPM level. It offers balance-based billing, first top-up bonuses, bundle subscriptions, corporate invoicing, and dedicated support. Register via <a href="https://unity2.ai/register?source=ccs">this link</a> to get $2 in credits, plus another $10 for joining the official group — up to $12 in free credits!</td> </tr> <tr> <td width="180"><a href="https://api.fenno.ai/register?redirect=/purchase?tab=subscription%26group=16&aff=P9MR3D3PLCNL"><img src="assets/partners/logos/fenno-banner.png" alt="Fenno.ai" width="150"></a></td> <td>Thanks to Fenno.ai for sponsoring this project! Fenno.ai is a stable and efficient API relay service provider, currently focused on Codex relay. It is compatible with the OpenAI and Anthropic protocols and can be flexibly used from Codex, Claude Code, OpenCode, and other mainstream coding tools. It reliably supports enterprise-grade workloads of hundreds of billions of tokens per day, with corporate (B2B) settlement and invoicing for both domestic and overseas entities. Fenno.ai offers an exclusive benefit for CC Switch users: subscribe via <a href="https://api.fenno.ai/register?redirect=/purchase?tab=subscription%26group=16&aff=P9MR3D3PLCNL">this link</a> to the incredible ¥9.9 Coding Plan worth $150 in credits, and earn up to 20% in referral rewards — invite more, earn more!</td> </tr> <tr> <td width="180"><a href="https://nekocode.ai?aff=CCSWITCH"><img src="assets/partners/logos/nekocode-banner.png" alt="NekoCode" width="150"></a></td> <td>Thanks to <a href="https://nekocode.ai?aff=CCSWITCH">NekoCode</a> for sponsoring this project! NekoCode provides developers with a stable, efficient, and reliable API relay service for Claude, Codex, and other AI models. With transparent pricing and flexible pay-as-you-go billing, it offers a simple and cost-effective way to access AI models. CC Switch users can enjoy an exclusive 10% discount: register via <a href="https://nekocode.ai?aff=CCSWITCH">this link</a> and enter promo code <code>cc-switch</code> during recharge to receive 10% off your top-up!</td> </tr> <tr> <td width="180"><a href="https://www.newapi.ai/"><img src="assets/partners/logos/newapi-banner.png" alt="new-api" width="150"></a></td> <td>Thanks to the open-source AI infrastructure project <a href="https://www.newapi.ai/">new-api</a> for its strong support of this project! new-api is an open-source AI infrastructure project from QuantumNous and one of the leading unified LLM access-and-distribution projects by activity and adoption, focused on helping developers, teams, and enterprises build manageable, scalable AI service platforms at lower cost. As a fellow project rooted in the open-source ecosystem, new-api hopes to sponsor and support the continued growth of more outstanding open-source projects. 🌟 Star new-api to show your support: <a href="https://github.com/QuantumNous/new-api">https://github.com/QuantumNous/new-api</a>. Website: <a href="https://www.newapi.ai/">https://www.newapi.ai/</a>.</td> </tr> <tr> <td width="180"><a href="https://subrouter.ai/register?aff=l3ri"><img src="assets/partners/logos/subrouter-banner.png" alt="SubRouter" width="150"></a></td> <td>Thanks to SubRouter for sponsoring this project! SubRouter is a marketplace and smart routing platform for AI service operators. Merchants can launch operating sites, publish packages, manage users, models, and pricing, while users discover services and access reliable AI models through one unified API. Register via <a href="https://subrouter.ai/register?aff=l3ri">this link</a>!</td> </tr> </table> </details> ## Why CC Switch? Modern AI-powered coding relies on tools like Claude Code, Claude Desktop, Codex, Gemini CLI, Grok Build, OpenCode, OpenClaw, and Hermes — but each has its own configuration format. Switching API providers means manually editing JSON, TOML, or `.env` files, and there is no unified way to manage MCP and Skills across multiple tools. **CC Switch** gives you a single desktop app to manage all supported AI tools. Instead of editing config files by hand, you get a visual interface to import providers with one click, switch between them instantly, with 50+ built-in provider presets, unified MCP and Skills management, and system tray quick switching — all backed by a reliable SQLite database with atomic writes that protect your configs from corruption. - **One App, Eight Tools** — Manage Claude Code, Claude Desktop, Codex, Gemini CLI, Grok Build, OpenCode, OpenClaw, and Hermes from a single interface - **No More Manual Editing** — 50+ provider presets including AWS Bedrock, NVIDIA NIM, and community relays; just pick and switch - **Unified MCP & Skills Management** — One panel to manage MCP servers and Skills across Claude, Codex, Gemini, Grok Build, OpenCode, and Hermes with bidirectional sync - **System Tray Quick Switch** — Switch providers instantly from the tray menu, no need to open the full app - **Cloud Sync** — Sync provider data across devices via Dropbox, OneDrive, iCloud, or WebDAV servers - **Cross-Platform** — Native desktop app for Windows, macOS, and Linux, built with Tauri 2 - **Built-in Utilities** — Includes various utilities for first-launch login confirmation, signature bypass, plugin extension sync, and more ## Screenshots | Main Interface | Add Provider | | :-----------------------------------------------: | :--------------------------------------------: | | ![Main Interface](assets/screenshots/main-en.png) | ![Add Provider](assets/screenshots/add-en.png) | ## Features [Full Changelog](CHANGELOG.md) | [Release Notes](docs/release-notes/v3.16.1-en.md) ### Provider Management - **8 supported tools, 50+ presets** — Claude Code, Claude Desktop, Codex, Gemini CLI, Grok Build, OpenCode, OpenClaw, Hermes; copy your key and import with one click - **Universal providers** — One config syncs to Claude Code, Codex, and Gemini CLI - One-click switching, system tray quick access, drag-and-drop sorting, import/export ### Proxy & Failover - **Local proxy with hot-switching** — Format conversion, auto-failover, circuit breaker, provider health monitoring, and request rectifier - **App-level takeover** — Independently proxy Claude, Codex, Gemini, or Grok Build, down to individual providers ### MCP, Prompts & Skills - **Unified MCP panel** — Manage MCP servers across Claude, Codex, Gemini, Grok Build, OpenCode, and Hermes with bidirectional sync and Deep Link import - **Prompts** — Markdown editor with cross-app sync (CLAUDE.md / AGENTS.md / GEMINI.md) and backfill protection - **Skills** — One-click install from GitHub repos or ZIP files, custom repository management, with symlink and file copy support ### Usage & Cost Tracking - **Usage dashboard** — Track spending, requests, and tokens with trend charts, detailed request logs, and custom per-model pricing ### Session Manager & Workspace - Browse, search, and restore conversation history across supported session sources - **Workspace editor** (OpenClaw) — Edit agent files (AGENTS.md, SOUL.md, etc.) with Markdown preview ### System & Platform - **Cloud sync** — Custom config directory (Dropbox, OneDrive, iCloud, NAS) and WebDAV server sync - **Deep Link** (`ccswitch://`) — Import providers, MCP servers, prompts, and skills via URL - Dark / Light / System theme, auto-launch, auto-updater, atomic writes, auto-backups, i18n (zh/zh-TW/en/ja) ## FAQ <details> <summary><strong>Which AI tools does CC Switch support?</strong></summary> CC Switch supports eight tools: **Claude Code**, **Claude Desktop**, **Codex**, **Gemini CLI**, **Grok Build**, **OpenCode**, **OpenClaw**, and **Hermes**. Each tool has dedicated provider presets and configuration management. </details> <details> <summary><strong>Do I need to restart the terminal after switching providers?</strong></summary> For most tools, yes — restart your terminal or the CLI tool for changes to take effect. The exception is **Claude Code**, which currently supports hot-switching of provider data without a restart. </details> <details> <summary><strong>My plugin configuration disappeared after switching providers — what happened?</strong></summary> CC Switch provides a "Shared Config Snippet" feature to pass common data (beyond API keys and endpoints) between providers. Go to "Edit Provider" → "Shared Config Panel" → click "Extract from Current Provider" to save all common data. When creating a new provider, check "Write Shared Config" (enabled by default) to include plugin data in the new provider. All your configuration items are preserved in the default provider imported when you first launched the app. </details> <details> <summary><strong>macOS installation</strong></summary> CC Switch for macOS is code-signed and notarized by Apple. You can download and install it directly — no extra steps needed. We recommend using the `.dmg` installer. </details> <details> <summary><strong>Why can't I delete the currently active provider?</strong></summary> CC Switch follows a "minimal intrusion" design principle — even if you uninstall the app, your CLI tools will continue to work normally. The system always keeps one active configuration, because deleting all configurations would make the corresponding CLI tool unusable. If you rarely use a specific CLI tool, you can hide it in Settings. To switch back to official login, see the next question. </details> <details> <summary><strong>How do I switch back to official login?</strong></summary> Add an official provider from the preset list. After switching to it, run the Log out / Log in flow, and then you can freely switch between the official provider and third-party providers. Codex supports switching between different official providers, making it easy to switch between multiple Plus or Team accounts. </details> <details> <summary><strong>Where is my data stored?</strong></summary> - **Database**: `~/.cc-switch/cc-switch.db` (SQLite — providers, MCP, prompts, skills) - **Local settings**: `~/.cc-switch/settings.json` (device-level UI preferences) - **Backups**: `~/.cc-switch/backups/` (auto-rotated, keeps 10 most recent) - **Skills**: `~/.cc-switch/skills/` (symlinked to corresponding apps by default) - **Skill Backups**: `~/.cc-switch/skill-backups/` (created automatically before uninstall, keeps 20 most recent) </details> <details> <summary><strong>Linux (Wayland + NVIDIA): clicks don't register and the window black-screens on resize</strong></summary> The AppImage forces `GDK_BACKEND=x11` (XWayland) to avoid a historical native-Wayland crash. On newer Wayland + NVIDIA setups this can leave the web content area unclickable (the title-bar buttons still work) and black-screen on resize. Launch with the opt-in escape hatch to switch back to native Wayland: ```bash CC_SWITCH_GDK_BACKEND=wayland ./CC-Switch-*.AppImage ``` If you launch from a desktop icon, add it to the `.desktop` `Exec=` line (e.g. `env CC_SWITCH_GDK_BACKEND=wayland /path/to/AppImage`) or set it in your session environment. The variable is generic: on tiling Wayland compositors (sway/Hyprland) where clicks don't register, try `CC_SWITCH_GDK_BACKEND=x11` instead. Leaving it unset keeps the default behavior. </details> ## Documentation For detailed guides on every feature, check out the **[User Manual](docs/user-manual/en/README.md)** — covering provider management, MCP/Prompts/Skills, proxy & failover, and more. ## Quick Start ### Basic Usage 1. **Add Provider**: Click "Add Provider" → Choose a preset or create custom configuration 2. **Switch Provider**: - Main UI: Select provider → Click "Enable" - System Tray: Click provider name directly (instant effect) 3. **Takes Effect**: Restart your terminal or the corresponding CLI tool to apply changes (Claude Code does not require a restart) 4. **Back to Official**: Add an "Official Login" preset, restart the CLI tool, then follow its login/OAuth flow ### MCP, Prompts, Skills & Sessions - **MCP**: Click the "MCP" button → Add servers via templates or custom config → Toggle per-app sync - **Prompts**: Click "Prompts" → Create presets with Markdown editor → Activate to sync to live files - **Skills**: Click "Skills" → Browse GitHub repos → One-click install to supported apps - **Sessions**: Click "Sessions" → Browse, search, and restore conversation history across supported session sources > **Note**: On first launch, you can manually import existing CLI tool configs as the default provider. ## Download & Installation ### System Requirements - **Windows**: Windows 10 and above - **macOS**: macOS 12 (Monterey) and above - **Linux**: Ubuntu 22.04+ / Debian 11+ / Fedora 34+ and other mainstream distributions ### Windows Users Download the latest `CC-Switch-v{version}-Windows.msi` installer or `CC-Switch-v{version}-Windows-Portable.zip` portable version from the [Releases](../../releases) page. ### macOS Users **Method 1: Install via Homebrew (Recommended)** ```bash brew install --cask cc-switch ``` Update: ```bash brew upgrade --cask cc-switch ``` **Method 2: Manual Download** Download `CC-Switch-v{version}-macOS.dmg` (recommended) or `.zip` from the [Releases](../../releases) page. > **Note**: CC Switch for macOS is code-signed and notarized by Apple. You can install and open it directly. ### Arch Linux Users **Install via paru (Recommended)** ```bash paru -S cc-switch-bin ``` ### Linux Users Download the latest Linux build from the [Releases](../../releases) page: - `CC-Switch-v{version}-Linux.deb` (Debian/Ubuntu) - `CC-Switch-v{version}-Linux.rpm` (Fedora/RHEL/openSUSE) - `CC-Switch-v{version}-Linux.AppImage` (Universal) > **Flatpak**: Not included in official releases. You can build it yourself from the `.deb` — see [`flatpak/README.md`](flatpak/README.md) for instructions. <details> <summary><strong>Architecture Overview</strong></summary> ### Design Principles ``` ┌─────────────────────────────────────────────────────────────┐ │ Frontend (React + TS) │ │ ┌─────────────┐ ┌──────────────┐ ┌──────────────────┐ │ │ │ Components │ │ Hooks │ │ TanStack Query │ │ │ │ (UI) │──│ (Bus. Logic) │──│ (Cache/Sync) │ │ │ └─────────────┘ └──────────────┘ └──────────────────┘ │ └────────────────────────┬────────────────────────────────────┘ │ Tauri IPC ┌────────────────────────▼────────────────────────────────────┐ │ Backend (Tauri + Rust) │ │ ┌─────────────┐ ┌──────────────┐ ┌──────────────────┐ │ │ │ Commands │ │ Services │ │ Models/Config │ │ │ │ (API Layer) │──│ (Bus. Layer) │──│ (Data) │ │ │ └─────────────┘ └──────────────┘ └──────────────────┘ │ └─────────────────────────────────────────────────────────────┘ ``` **Core Design Patterns** - **SSOT** (Single Source of Truth): All data stored in `~/.cc-switch/cc-switch.db` (SQLite) - **Dual-layer Storage**: SQLite for syncable data, JSON for device-level settings - **Dual-way Sync**: Write to live files on switch, backfill from live when editing active provider - **Atomic Writes**: Temp file + rename pattern prevents config corruption - **Concurrency Safe**: Mutex-protected database connection avoids race conditions - **Layered Architecture**: Clear separation (Commands → Services → DAO → Database) **Key Components** - **ProviderService**: Provider CRUD, switching, backfill, sorting - **McpService**: MCP server management, import/export, live file sync - **ProxyService**: Local proxy mode with hot-switching and format conversion - **SessionManager**: Conversation history browsing across supported session sources - **ConfigService**: Config import/export, backup rotation - **SpeedtestService**: API endpoint latency measurement </details> <details> <summary><strong>Development Guide</strong></summary> ### Environment Requirements - Node.js 18+ - pnpm 8+ - Rust 1.85+ - Tauri CLI 2.8+ ### Development Commands ```bash # Install dependencies pnpm install # Dev mode (hot reload) pnpm dev # Type check pnpm typecheck # Format code pnpm format # Check code format pnpm format:check # Run frontend unit tests pnpm test:unit # Run tests in watch mode (recommended for development) pnpm test:unit:watch # Build application pnpm build # Build debug version pnpm tauri build --debug ``` ### Rust Backend Development ```bash cd src-tauri # Format Rust code cargo fmt # Run clippy checks cargo clippy # Run backend tests cargo test # Run specific tests cargo test test_name # Run tests with test-hooks feature cargo test --features test-hooks ``` ### Testing Guide **Frontend Testing**: - Uses **vitest** as test framework - Uses **MSW (Mock Service Worker)** to mock Tauri API calls - Uses **@testing-library/react** for component testing **Running Tests**: ```bash # Run all tests pnpm test:unit # Watch mode (auto re-run) pnpm test:unit:watch # With coverage report pnpm test:unit --coverage ``` ### Tech Stack **Frontend**: React 18 · TypeScript · Vite · TailwindCSS 3.4 · TanStack Query v5 · react-i18next · react-hook-form · zod · shadcn/ui · @dnd-kit **Backend**: Tauri 2.8 · Rust · serde · tokio · thiserror · tauri-plugin-updater/process/dialog/store/log **Testing**: vitest · MSW · @testing-library/react </details> <details> <summary><strong>Project Structure</strong></summary> ``` ├── src/ # Frontend (React + TypeScript) │ ├── components/ │ │ ├── providers/ # Provider management │ │ ├── mcp/ # MCP panel │ │ ├── prompts/ # Prompts management │ │ ├── skills/ # Skills management │ │ ├── sessions/ # Session Manager │ │ ├── proxy/ # Proxy mode panel │ │ ├── openclaw/ # OpenClaw config panels │ │ ├── settings/ # Settings (Terminal/Backup/About) │ │ ├── deeplink/ # Deep Link import │ │ ├── env/ # Environment variable management │ │ ├── universal/ # Cross-app configuration │ │ ├── usage/ # Usage statistics │ │ └── ui/ # shadcn/ui component library │ ├── hooks/ # Custom hooks (business logic) │ ├── lib/ │ │ ├── api/ # Tauri API wrapper (type-safe) │ │ └── query/ # TanStack Query config │ ├── locales/ # Translations (zh/zh-TW/en/ja) │ ├── config/ # Presets (providers/mcp) │ └── types/ # TypeScript definitions ├── src-tauri/ # Backend (Rust) │ └── src/ │ ├── commands/ # Tauri command layer (by domain) │ ├── services/ # Business logic layer │ ├── database/ # SQLite DAO layer │ ├── proxy/ # Proxy module │ ├── session_manager/ # Session management │ ├── deeplink/ # Deep Link handling │ └── mcp/ # MCP sync module ├── tests/ # Frontend tests └── assets/ # Screenshots & partner resources ``` </details> ## Contributing Issues and suggestions are welcome! Before submitting PRs, please ensure: - Pass type check: `pnpm typecheck` - Pass format check: `pnpm format:check` - Pass unit tests: `pnpm test:unit` For new features, please open an issue for discussion before submitting a PR. PRs for features that are not a good fit for the project may be closed. ## Star History [![Star History Chart](https://api.star-history.com/svg?repos=farion1231/cc-switch&type=Date)](https://www.star-history.com/#farion1231/cc-switch&Date) ## License MIT © Jason Young