# Claude Code / Codex / Gemini CLI 全方位辅助工具 [![Version](https://img.shields.io/badge/version-3.10.2-blue.svg)](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/endpoint?url=https://api.pinstudios.net/api/badges/downloads/farion1231/cc-switch/total)](https://github.com/farion1231/cc-switch/releases/latest) farion1231%2Fcc-switch | Trendshift [English](README.md) | 中文 | [日本語](README_JA.md) | [更新日志](CHANGELOG.md) | [v3.9.0 发布说明](docs/release-note-v3.9.0-zh.md)
## ❤️赞助商 [![智谱 GLM](assets/partners/banners/glm-zh.jpg)](https://www.bigmodel.cn/claude-code?ic=RRVJPB5SII) 感谢智谱AI的 GLM CODING PLAN 赞助了本项目！GLM CODING PLAN 是专为AI编码打造的订阅套餐,每月最低仅需20元，即可在十余款主流AI编码工具如 Claude Code、Cline 中畅享智谱旗舰模型 GLM-4.6，为开发者提供顶尖、高速、稳定的编码体验。CC Switch 已经预设了智谱GLM，只需要填写 key 即可一键导入编程工具。智谱AI为本软件的用户提供了特别优惠，使用[此链接](https://www.bigmodel.cn/claude-code?ic=RRVJPB5SII)购买可以享受九折优惠。 ---
PackyCode 感谢 PackyCode 赞助了本项目！PackyCode 是一家稳定、高效的API中转服务商，提供 Claude Code、Codex、Gemini 等多种中转服务。PackyCode 为本软件的用户提供了特别优惠，使用此链接注册并在充值时填写"cc-switch"优惠码，可以享受9折优惠！
AIGoCode 感谢 AIGoCode 赞助了本项目！AIGoCode 是一个集成了 Claude Code、Codex 以及 Gemini 最新模型的一站式平台，为你提供稳定、高效且高性价比的AI编程服务。本站提供灵活的订阅计划，零封号风险，国内直连，无需魔法，极速响应。AIGoCode 为 CC Switch 的用户提供了特别福利，通过此链接注册的用户首次充值可以获得额外10%奖励额度！
AICodeMirror 感谢 AICodeMirror 赞助了本项目！AICodeMirror 提供 Claude Code / Codex / Gemini CLI 官方高稳定中转服务，支持企业级高并发、极速开票、7×24 专属技术支持。 Claude Code / Codex / Gemini 官方渠道低至 3.8 / 0.2 / 0.9 折，充值更有折上折！AICodeMirror 为 CCSwitch 的用户提供了特别福利，通过此链接注册的用户，可享受首充8折，企业客户最高可享 7.5 折！
Cubence 感谢 Cubence 赞助本项目！Cubence 是一家可靠高效的 API 中继服务提供商，提供对 Claude Code、Codex、Gemini 等模型的中继服务，并提供按量、包月等灵活的计费方式。Cubence 为 CC Switch 的用户提供了特别优惠：使用 此链接 注册，并在充值时输入 "CCSWITCH" 优惠码，每次充值均可享受九折优惠！
DMXAPI 感谢 DMXAPI（大模型API）赞助了本项目！ DMXAPI，一个Key用全球大模型。 为200多家企业用户提供全球大模型API服务。· 充值即开票 ·当天开票 ·并发不限制 ·1元起充 · 7x24 在线技术辅导，GPT/Claude/Gemini全部6.8折，国内模型5~8折，Claude Code 专属模型3.4折进行中！点击这里注册
## 界面预览 | 主界面 | 添加供应商 | | :---------------------------------------: | :------------------------------------------: | | ![主界面](assets/screenshots/main-zh.png) | ![添加供应商](assets/screenshots/add-zh.png) | ## 功能特性 ### 当前版本：v3.10.2 | [完整更新日志](CHANGELOG.md) | [发布说明](docs/release-note-v3.9.0-zh.md) **v3.8.0 重大更新（2025-11-28）** **持久化架构升级 & 全新用户界面** - **SQLite + JSON 双层架构** - 从 JSON 文件存储迁移到 SQLite + JSON 双层结构 - 可同步数据（供应商、MCP、Prompts、Skills）存入 SQLite - 设备级数据（窗口状态、本地路径）保留在 JSON - 为未来云同步功能奠定基础 - Schema 版本管理支持数据库迁移 - **全新用户界面** - 完全重新设计的界面布局 - 统一的组件样式和更流畅的动画 - 优化的视觉层次 - Tailwind CSS 从 v4 降级到 v3.4 以提升浏览器兼容性 - **日语支持** - 新增日语界面支持（现支持中文/英文/日语） - **开机自启** - 在设置中一键开启/关闭 - 使用平台原生 API（注册表/LaunchAgent/XDG autostart） - **Skills 递归扫描** - 支持多层目录结构 - 允许不同仓库的同名技能 - **关键 Bug 修复** - 修复更新供应商时自定义端点丢失问题 - 修复 Gemini 配置写入问题 - 修复 Linux WebKitGTK 渲染问题 **v3.7.0 亮点** **六大核心功能，18,000+ 行新增代码** - **Gemini CLI 集成** - 第三个支持的 AI CLI（Claude Code / Codex / Gemini） - 双文件配置支持（`.env` + `settings.json`） - 完整 MCP 服务器管理 - 预设：Google Official (OAuth) / PackyCode / 自定义 - **Claude Skills 管理系统** - 从 GitHub 仓库自动扫描技能（预配置 3 个精选仓库） - 一键安装/卸载到 `~/.claude/skills/` - 自定义仓库支持 + 子目录扫描 - 完整生命周期管理（发现/安装/更新） - **Prompts 管理系统** - 多预设系统提示词管理（无限数量，快速切换） - 跨应用支持（Claude: `CLAUDE.md` / Codex: `AGENTS.md` / Gemini: `GEMINI.md`） - Markdown 编辑器（CodeMirror 6 + 实时预览） - 智能回填保护，保留手动修改 - **MCP v3.7.0 统一架构** - 单一面板管理三个应用的 MCP 服务器 - 新增 SSE (Server-Sent Events) 传输类型 - 智能 JSON 解析器 + Codex TOML 格式自动修正 - 统一导入/导出 + 双向同步 - **深度链接协议** - `ccswitch://` 协议注册（全平台） - 通过共享链接一键导入供应商配置 - 安全验证 + 生命周期集成 - **环境变量冲突检测** - 自动检测跨应用配置冲突（Claude/Codex/Gemini/MCP） - 可视化冲突指示器 + 解决建议 - 覆盖警告 + 更改前备份 **核心功能** - **供应商管理**：一键切换 Claude Code、Codex 与 Gemini 的 API 配置 - **速度测试**：测量 API 端点延迟，可视化连接质量指示器 - **导入导出**：备份和恢复配置，自动轮换（保留最近 10 个） - **国际化支持**：完整的中英文本地化（UI、错误、托盘） - **Claude 插件同步**：一键应用或恢复 Claude 插件配置 **v3.6 亮点** - 供应商复制 & 拖拽排序 - 多端点管理 & 自定义配置目录（支持云同步） - 细粒度模型配置（四层：Haiku/Sonnet/Opus/自定义） - WSL 环境支持，配置目录切换自动同步 - 100% hooks 测试覆盖 & 完整架构重构 **系统功能** - 系统托盘快速切换 - 单实例守护 - 内置自动更新器 - 原子写入与回滚保护 ## 下载安装 ### 系统要求 - **Windows**: Windows 10 及以上 - **macOS**: macOS 10.15 (Catalina) 及以上 - **Linux**: Ubuntu 22.04+ / Debian 11+ / Fedora 34+ 等主流发行版 ### Windows 用户 从 [Releases](../../releases) 页面下载最新版本的 `CC-Switch-v{版本号}-Windows.msi` 安装包或者 `CC-Switch-v{版本号}-Windows-Portable.zip` 绿色版。 ### macOS 用户 **方式一：通过 Homebrew 安装（推荐）** ```bash brew tap farion1231/ccswitch brew install --cask cc-switch ``` 更新： ```bash brew upgrade --cask cc-switch ``` **方式二：手动下载** 从 [Releases](../../releases) 页面下载 `CC-Switch-v{版本号}-macOS.zip` 解压使用。 > **注意**：由于作者没有苹果开发者账号，首次打开可能出现"未知开发者"警告，请先关闭，然后前往"系统设置" → "隐私与安全性" → 点击"仍要打开"，之后便可以正常打开 ### ArchLinux 用户 **通过 paru 安装（推荐）** ```bash paru -S cc-switch-bin ``` ### Linux 用户 从 [Releases](../../releases) 页面下载最新版本的 Linux 安装包： - `CC-Switch-v{版本号}-Linux.deb`（Debian/Ubuntu） - `CC-Switch-v{版本号}-Linux.rpm`（Fedora/RHEL/openSUSE） - `CC-Switch-v{版本号}-Linux.AppImage`（通用） - `CC-Switch-v{版本号}-Linux.flatpak`（Flatpak） Flatpak 安装与运行： ```bash flatpak install --user ./CC-Switch-v{版本号}-Linux.flatpak flatpak run com.ccswitch.desktop ``` ## 快速开始 ### 基本使用 1. **添加供应商**：点击"添加供应商" → 选择预设或创建自定义配置 2. **切换供应商**： - 主界面：选择供应商 → 点击"启用" - 系统托盘：直接点击供应商名称（立即生效） 3. **生效方式**：重启终端或 Claude Code / Codex / Gemini 客户端以应用更改 4. **恢复官方登录**：选择"官方登录"预设（Claude/Codex）或"Google 官方"预设（Gemini），重启对应客户端后按照其登录/OAuth 流程操作 ### MCP 管理 - **位置**：点击右上角"MCP"按钮 - **添加服务器**： - 使用内置模板（mcp-fetch、mcp-filesystem 等） - 支持 stdio / http / sse 三种传输类型 - 为不同应用配置独立的 MCP 服务器 - **启用/禁用**：切换开关以控制哪些服务器同步到 live 配置 - **同步**：启用的服务器自动同步到各应用的 live 文件 - **导入/导出**：支持从 Claude/Codex/Gemini 配置文件导入现有 MCP 服务器 ### Skills 管理（v3.7.0 新增） - **位置**：点击右上角"Skills"按钮 - **发现技能**： - 自动扫描预配置的 GitHub 仓库（Anthropic 官方、ComposioHQ、社区等） - 添加自定义仓库（支持子目录扫描） - **安装技能**：点击"安装"一键安装到 `~/.claude/skills/` - **卸载技能**：点击"卸载"安全移除并清理状态 - **管理仓库**：添加/删除自定义 GitHub 仓库 ### Prompts 管理（v3.7.0 新增） - **位置**：点击右上角"Prompts"按钮 - **创建预设**： - 创建无限数量的系统提示词预设 - 使用 Markdown 编辑器编写提示词（语法高亮 + 实时预览） - **切换预设**：选择预设 → 点击"激活"立即应用 - **同步机制**： - Claude: `~/.claude/CLAUDE.md` - Codex: `~/.codex/AGENTS.md` - Gemini: `~/.gemini/GEMINI.md` - **保护机制**：切换前自动保存当前提示词内容，保留手动修改 ### 配置文件 **Claude Code** - Live 配置：`~/.claude/settings.json`（或 `claude.json`） - API key 字段：`env.ANTHROPIC_AUTH_TOKEN` 或 `env.ANTHROPIC_API_KEY` - MCP 服务器：`~/.claude.json` → `mcpServers` **Codex** - Live 配置：`~/.codex/auth.json`（必需）+ `config.toml`（可选） - API key 字段：`auth.json` 中的 `OPENAI_API_KEY` - MCP 服务器：`~/.codex/config.toml` → `[mcp_servers]` 表 **Gemini** - Live 配置：`~/.gemini/.env`（API Key）+ `~/.gemini/settings.json`（保存认证模式） - API key 字段：`.env` 文件中的 `GEMINI_API_KEY` 或 `GOOGLE_GEMINI_API_KEY` - 环境变量：支持 `GOOGLE_GEMINI_BASE_URL`、`GEMINI_MODEL` 等自定义变量 - MCP 服务器：`~/.gemini/settings.json` → `mcpServers` - 托盘快速切换：每次切换供应商都会重写 `~/.gemini/.env`，无需重启 Gemini CLI 即可生效 **CC Switch 存储（v3.8.0 新架构）** - 数据库（SSOT）：`~/.cc-switch/cc-switch.db`（SQLite，存储供应商、MCP、Prompts、Skills） - 本地设置：`~/.cc-switch/settings.json`（设备级设置） - 备份：`~/.cc-switch/backups/`（自动轮换，保留 10 个） ### 云同步设置 1. 前往设置 → "自定义配置目录" 2. 选择您的云同步文件夹（Dropbox、OneDrive、iCloud、坚果云等） 3. 重启应用以应用 4. 在其他设备上重复操作以启用跨设备同步 > **注意**：首次启动会自动导入现有 Claude/Codex 配置作为默认供应商。 ## 架构总览 ### 设计原则 ``` ┌─────────────────────────────────────────────────────────────┐ │ 前端 (React + TS) │ │ ┌─────────────┐ ┌──────────────┐ ┌──────────────────┐ │ │ │ Components │ │ Hooks │ │ TanStack Query │ │ │ │ （UI） │──│ （业务逻辑） │──│ （缓存/同步） │ │ │ └─────────────┘ └──────────────┘ └──────────────────┘ │ └────────────────────────┬────────────────────────────────────┘ │ Tauri IPC ┌────────────────────────▼────────────────────────────────────┐ │ 后端 (Tauri + Rust) │ │ ┌─────────────┐ ┌──────────────┐ ┌──────────────────┐ │ │ │ Commands │ │ Services │ │ Models/Config │ │ │ │ （API 层） │──│ （业务层） │──│ （数据） │ │ │ └─────────────┘ └──────────────┘ └──────────────────┘ │ └─────────────────────────────────────────────────────────────┘ ``` **核心设计模式** - **SSOT**（单一事实源）：所有数据存储在 `~/.cc-switch/cc-switch.db`（SQLite） - **双层存储**：SQLite 存储可同步数据，JSON 存储设备级设置 - **双向同步**：切换时写入 live 文件，编辑当前供应商时从 live 回填 - **原子写入**：临时文件 + 重命名模式防止配置损坏 - **并发安全**：Mutex 保护的数据库连接避免竞态条件 - **分层架构**：清晰分离（Commands → Services → DAO → Database） **核心组件** - **ProviderService**：供应商增删改查、切换、回填、排序 - **McpService**：MCP 服务器管理、导入导出、live 文件同步 - **ConfigService**：配置导入导出、备份轮换 - **SpeedtestService**：API 端点延迟测量 **v3.6 重构** - 后端：5 阶段重构（错误处理 → 命令拆分 → 测试 → 服务 → 并发） - 前端：4 阶段重构（测试基础 → hooks → 组件 → 清理） - 测试：100% hooks 覆盖 + 集成测试（vitest + MSW） ## 开发 ### 环境要求 - Node.js 18+ - pnpm 8+ - Rust 1.85+ - Tauri CLI 2.8+ ### 开发命令 ```bash # 安装依赖 pnpm install # 开发模式（热重载） pnpm dev # 类型检查 pnpm typecheck # 代码格式化 pnpm format # 检查代码格式 pnpm format:check # 运行前端单元测试 pnpm test:unit # 监听模式运行测试（推荐开发时使用） pnpm test:unit:watch # 构建应用 pnpm build # 构建调试版本 pnpm tauri build --debug ``` ### Rust 后端开发 ```bash cd src-tauri # 格式化 Rust 代码 cargo fmt # 运行 clippy 检查 cargo clippy # 运行后端测试 cargo test # 运行特定测试 cargo test test_name # 运行带测试 hooks 的测试 cargo test --features test-hooks ``` ### 测试说明（v3.6 新增） **前端测试**： - 使用 **vitest** 作为测试框架 - 使用 **MSW (Mock Service Worker)** 模拟 Tauri API 调用 - 使用 **@testing-library/react** 进行组件测试 **测试覆盖**： - Hooks 单元测试（100% 覆盖） - `useProviderActions` - 供应商操作 - `useMcpActions` - MCP 管理 - `useSettings` 系列 - 设置管理 - `useImportExport` - 导入导出 - 集成测试 - App 主应用流程 - SettingsDialog 完整交互 - MCP 面板功能 **运行测试**： ```bash # 运行所有测试 pnpm test:unit # 监听模式（自动重跑） pnpm test:unit:watch # 带覆盖率报告 pnpm test:unit --coverage ``` ## 技术栈 **前端**：React 18 · TypeScript · Vite · TailwindCSS 4 · TanStack Query v5 · react-i18next · react-hook-form · zod · shadcn/ui · @dnd-kit **后端**：Tauri 2.8 · Rust · serde · tokio · thiserror · tauri-plugin-updater/process/dialog/store/log **测试**：vitest · MSW · @testing-library/react ## 项目结构 ``` ├── src/ # 前端 (React + TypeScript) │ ├── components/ # UI 组件 (providers/settings/mcp/ui) │ ├── hooks/ # 自定义 hooks (业务逻辑) │ ├── lib/ │ │ ├── api/ # Tauri API 封装（类型安全） │ │ └── query/ # TanStack Query 配置 │ ├── i18n/locales/ # 翻译 (zh/en) │ ├── config/ # 预设 (providers/mcp) │ └── types/ # TypeScript 类型定义 ├── src-tauri/ # 后端 (Rust) │ └── src/ │ ├── commands/ # Tauri 命令层（按领域） │ ├── services/ # 业务逻辑层 │ ├── app_config.rs # 配置数据模型 │ ├── provider.rs # 供应商领域模型 │ ├── mcp.rs # MCP 同步与校验 │ └── lib.rs # 应用入口 & 托盘菜单 ├── tests/ # 前端测试 │ ├── hooks/ # 单元测试 │ └── components/ # 集成测试 └── assets/ # 截图 & 合作商资源 ``` ## 更新日志 查看 [CHANGELOG.md](CHANGELOG.md) 了解版本更新详情。 ## Electron 旧版 [Releases](../../releases) 里保留 v2.0.3 Electron 旧版 如果需要旧版 Electron 代码，可以拉取 electron-legacy 分支 ## 贡献 欢迎提交 Issue 反馈问题和建议！ 提交 PR 前请确保： - 通过类型检查：`pnpm typecheck` - 通过格式检查：`pnpm format:check` - 通过单元测试：`pnpm test:unit` - 💡 新功能开发前，欢迎先开 issue 讨论实现方案 ## 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