CC Switch 桌面管理器实战指南：统一配置与切换 Claude Code、Codex、Gemini CLI 等 8 类 AI 编码工具

CC Switch 是一个基于 Tauri 2 的跨平台桌面"All-in-One"管理助手，面向 Claude Code、Claude Desktop、Codex、Gemini CLI、Grok Build、OpenCode、OpenClaw 与 Hermes Agent 等 8 类 AI 编码工具，提供供应商（Provider）管理、一键切换、统一 MCP/Prompts/Skills 面板、本地代理与故障转移、用量追踪等能力。本文以 README_DE.md 为核心骨架，结合仓库源码，完整讲解它的功能地图、数据存储原理、架构设计与从安装到开发测试的全流程实战要点。

为什么需要 CC Switch：多工具时代的配置碎片化

现代 AI 辅助编程依赖的工具生态越来越丰富：Claude Code、Claude Desktop、Codex、Gemini CLI、Grok Build、OpenCode、OpenClaw、Hermes——但它们各自采用完全不同的配置文件格式，常见的有 JSON、TOML 或 .env。当你想更换 API 供应商时，就意味着要手工去编辑不同格式、不同位置的配置文件；同时 MCP 服务器与 Skills 散落在各工具中，缺乏统一的管理入口。

CC Switch 的解法是：用一个桌面应用管理所有受支持的 AI 工具。它把"手工编辑配置文件"替换为"可视化界面操作"，提供 50+ 内置供应商预设、统一 MCP/Skills 管理、系统托盘一键切换，并以 SQLite 数据库 + 原子写作为底层保障，防止配置在切换过程中损坏。

从仓库源码可以确认这套设计的真实骨架：数据统一落在应用数据目录（默认 ~/.cc-switch），数据库文件为 cc-switch.db（见 src-tauri/src/config.rs 中 get_app_config_dir 的实现）；而"原子写"则体现在 src-tauri/src/config.rs 的 write_json_file_with_contents：先对 JSON 键递归排序保证确定性输出，再通过临时文件 + 重命名的原子写模式落盘。这正与 README 中"atomare Schreibvorgänge（原子写）保护配置不损坏"的承诺一一对应。

CC Switch 能力全景：8 大工具、50+ 预设、一套界面

• 一个应用管理 8 类工具：Claude Code、Claude Desktop、Codex、Gemini CLI、Grok Build、OpenCode、OpenClaw、Hermes，全部通过同一界面操作。
• 告别手工编辑：内置 50+ 供应商预设（含 AWS Bedrock、NVIDIA NIM 与各类社区中转/Relay），选择预设即可完成配置与切换。
• 统一 MCP 与 Skills 管理：单个面板即可管理 Claude、Codex、Gemini、Grok Build、OpenCode、Hermes 的 MCP 服务器与 Skills，并支持双向同步。
• 系统托盘秒切：无需打开完整应用，直接在托盘菜单点击供应商即可生效。
• 云同步：通过 Dropbox、OneDrive、iCloud 或 WebDAV 服务器跨设备同步供应商数据。
• 跨平台原生桌面：基于 Tauri 2 构建，覆盖 Windows、macOS、Linux。
• 集成辅助工具：包含首次启动的登录确认、签名绕过（Umschaltung/Login-Bestätigung）、插件扩展同步等一系列实用工具。

仓库 src/config 目录印证了"预设驱动"的设计：Claude Code、Codex、Gemini、Grok Build、OpenClaw、OpenCode、Hermes 等均有独立的 Preset 配置文件（如 claudeProviderPresets.ts、codexProviderPresets.ts、geminiProviderPresets.ts），并在 tests/config 下配套了大量测试（如 claudeProviderPresets.test.ts）来约束预设结构，从侧面保证"50+ 预设可维护、可扩展"。

下面是主界面与"添加供应商"两个关键界面（取自仓库 assets/screenshots 目录的真实运行截图）：

功能模块详解

供应商管理：从增删改查到一键切换

• 8 个受支持工具 × 50+ 预设：为 Claude Code、Claude Desktop、Codex、Gemini CLI、Grok Build、OpenCode、OpenClaw、Hermes 分别维护独立的供应商表单与配置管理；支持"复制 Key、一键导入"。
• 通用供应商（Universelle Anbieter）：一份配置即可同时同步到 Claude Code、Codex 与 Gemini CLI 的本地配置文件。
• 日常操作：一键切换、托盘快捷切换、拖拽排序、导入导出。

从源码结构看，供应商体系前后端分明：前端有独立的供应商面板与表单体系 src/components/providers（含 AddProviderDialog、EditProviderDialog、ProviderList、ProviderCard 以及 60 个左右的表单子文件）；后端对应的供应商管理与切换逻辑集中在 src-tauri/src/provider.rs 与 src-tauri/src/services。若想了解供应商数据的存取边界，可参考 src-tauri/tests/provider_commands.rs 与 src-tauri/tests/provider_service.rs 两组后端测试。

本地代理与自动故障转移

• 本地代理热切换（Hot-Switching）：本地代理会做格式转换，可自动故障转移、内置熔断器（Circuit Breaker）、供应商健康监测以及请求修正器（Request-Rectifier）。
• 应用级路由接管：可让 Claude、Codex、Gemini 或 Grok Build 分别、独立地经由代理路由，粒度甚至可以细化到单个供应商。

仓库中 src-tauri/src/proxy 目录下约 66 个 Rust 源文件是这一模块的底层实现，覆盖代理协议、故障转移、熔断与健康检查逻辑；前端面板见 src/components/proxy（如 AutoFailoverConfigPanel、FailoverQueueManager、RoutingActivationBrand 等），后端集成测试可参考 src-tauri/tests/proxy_commands.rs。

MCP、Prompts 与 Skills

• 统一 MCP 面板：为 Claude、Codex、Gemini、Grok Build、OpenCode、Hermes 统一管理 MCP 服务器，支持双向同步与 Deep Link 导入。
• Prompts：内置 Markdown 编辑器，可跨应用同步 CLAUDE.md / AGENTS.md / GEMINI.md 等 Prompt 文件，并带 Backfill 覆盖保护。
• Skills：支持从 GitHub 仓库或 ZIP 文件一键安装，可管理自建仓库，支持符号链接（Symlink）与文件复制两种落地方式。

用量与成本追踪

内置用量仪表盘（Usage Dashboard），可跟踪花费、请求数与 Token 消耗，提供趋势图、细粒度请求日志以及按模型自定义的价格配置。相关前端组件见 src/components/usage（UsageDashboard、UsageTrendChart、RequestLogTable、PricingConfigPanel 等），底层事件流由 src-tauri/src/usage_events.rs 与 src-tauri/src/usage_script.rs 支撑。

Session Manager 与 Workspace

• 跨受支持应用检索、搜索并恢复会话历史。
• Workspace 编辑器（OpenClaw）：带 Markdown 预览，可编辑 Agent 文件（如 AGENTS.md、SOUL.md）。前端实现位于 src/components/workspace，会话管理相关 UI 位于 src/components/sessions。

系统与平台能力

• 云同步：既支持自定义配置目录（Dropbox、OneDrive、iCloud、NAS），也支持 WebDAV 服务器同步。
• Deep Link（ccswitch://）：可通过 URL 直接导入供应商、MCP 服务器、Prompts 与 Skills。
• 基础能力：暗色/亮色/跟随系统主题、开机自启、自动更新、原子写、自动备份、i18n（zh / zh-TW / en / ja 四语言）。

快速上手：从添加供应商到切换生效

以下操作路径与 README_DE.md 的 Schnellstart 章节一致，可直接照做：

1. 添加供应商：点击 "Add Provider" → 选择某个预设，或自行创建一份自定义配置。
2. 切换供应商：
   • 主界面：选中供应商 → 点击 "Enable"；
   • 系统托盘：直接点击托盘菜单中的供应商名称（立即生效）。
3. 让切换生效：重启终端或对应的 CLI 工具以应用更改（例外：Claude Code 目前支持不重启热切换供应商数据）。
4. 切回官方登录：添加 "Official Login" 预设 → 重启 CLI 工具 → 按工具自身的登录 / OAuth 流程操作。

注意：首次启动时，可以把现有的 CLI 工具配置手动导入为默认供应商，作为后续切换的基础。

在项目仓库中，上述 UI 操作背后的供应商模型、预设表单与保存流程均有对应测试守护，例如 tests/components/AddProviderDialog.test.tsx、tests/components/EditProviderDialog.test.tsx 与 tests/hooks/useAddProviderMutation.test.tsx，可作为理解操作语义的补充参考。

高频 FAQ 精解

以下问答均来自 README_DE 的官方 FAQ，并补充了仓库实现层面的解释。

支持哪些 AI 工具？

8 个：Claude Code、Claude Desktop、Codex、Gemini CLI、Grok Build、OpenCode、OpenClaw、Hermes。每个工具都有专门的供应商预设与配置管理。

切换供应商后必须重启终端吗？

大多数工具需要——请重启终端或 CLI 工具使更改生效。例外是 Claude Code，它当前支持供应商数据的热切换、无需重启。

为什么切换供应商后我的"插件配置"不见了？

CC Switch 通过**共享配置片段（Gemeinsames Konfigurations-Snippet）**解决跨供应商共享数据的问题（超出 API Key 与端点之外的部分，例如插件/工具的自定义项）。恢复与预防步骤如下：

1. 进入"编辑供应商" → "共享配置面板"（Panel für gemeinsame Konfiguration）；
2. 点击"从当前供应商提取"，保存全部公共数据；
3. 新建供应商时开启"写入共享配置"（默认开启），插件数据即会被带入新供应商；
4. 首次启动应用时导入的那个默认供应商中，会一直保留你全部的历史配置项。

macOS 上安装是否安全？

CC Switch 的 macOS 版本已通过 Apple 代码签名与公证（Notarization），可直接下载安装、无需额外授权步骤；官方推荐使用 .dmg 安装包。

为什么不能删除当前正在使用的活跃供应商？

这是 CC Switch **"最小侵入深度"**设计原则的体现：即使卸载应用，你的 CLI 工具仍能正常工作。系统必须始终保留一份激活配置——如果删光全部配置，对应的 CLI 工具将无法使用。如果某个 CLI 工具很少用，可以在设置中隐藏它；如需切回官方登录，见下一条 FAQ。

如何切回官方登录？

从预设列表添加一个"官方供应商"（Official-Anbieter），切换过去后执行一次退出/登录流程，之后即可在官方供应商与第三方供应商之间自由往返。Codex 还支持在不同官方供应商之间切换，方便在多个 Plus / Team 账号间切换。

我的数据都存在哪里？

数据类别	位置	说明
数据库	~/.cc-switch/cc-switch.db	SQLite，保存供应商、MCP、Prompts、Skills
本地设置	~/.cc-switch/settings.json	设备相关的 UI 设置
备份	~/.cc-switch/backups/	自动轮换，保留最近 10 份
Skills	~/.cc-switch/skills/	默认以符号链接方式与各应用联动
Skill 备份	~/.cc-switch/skill-backups/	卸载前自动生成，保留最近 20 份

这些路径与源码实现一致：src-tauri/src/config.rs 中 get_app_config_dir() 返回 get_home_dir().join(".cc-switch")；数据库备份目录 backups 及清理逻辑见 src-tauri/src/database/backup.rs（构建备份）与 src-tauri/src/database/backup.rs（按保留数清理）。

值得补充的一点（源码细节）：config.rs 在 Windows 上特意不使用 HOME 环境变量来定位数据目录，因为 Git/Cygwin/MSYS 等工具可能注入与真实用户目录不一致的 HOME，从而导致 ~/.cc-switch/cc-switch.db 路径漂移、"看起来像数据丢失"。实现只在"默认位置不存在数据库"时才回退探测旧版本（v3.10.3 时代由 HOME 推导的）遗留路径，避免重复出现供应商"消失"问题。

Linux（Wayland + NVIDIA）：Web 内容点击无响应、缩放时黑屏怎么办？

AppImage 默认强制 GDK_BACKEND=x11（XWayland），用来规避历史上的原生 Wayland 崩溃。但在较新的 Wayland + NVIDIA 组合上，这可能造成 Web 内容不可点击（窗口标题栏按钮仍可用）以及拖拽缩放时黑屏。此时可用环境变量"逃生通道"切回原生 Wayland：

CC_SWITCH_GDK_BACKEND=wayland ./CC-Switch-*.AppImage

如果通过桌面图标启动，请把该变量写入 .desktop 文件的 Exec= 行（例如 env CC_SWITCH_GDK_BACKEND=wayland /pfad/zum/AppImage），或在会话环境中全局导出。变量是通用的：在 sway/Hyprland 等平铺式 Wayland 合成器上若出现点击无响应，可以反向尝试 CC_SWITCH_GDK_BACKEND=x11；保持变量未设置时，则维持默认行为不变。

下载与安装：Windows、macOS、Arch 与 Linux

系统要求

• Windows：Windows 10 及以上
• macOS：macOS 12 (Monterey) 及以上
• Linux：Ubuntu 22.04+ / Debian 11+ / Fedora 34+ 等主流发行版

Windows

从项目的 Releases 页面下载最新安装包：CC-Switch-v{version}-Windows.msi，或绿色便携版 CC-Switch-v{version}-Windows-Portable.zip。

macOS

方式一：Homebrew 安装（推荐）

brew install --cask cc-switch

更新：

brew upgrade --cask cc-switch

方式二：手动下载

下载 CC-Switch-v{version}-macOS.dmg（推荐）或 .zip。macOS 版本已 Apple 签名并公证，可放心直接安装打开。

Arch Linux

推荐通过 paru 从 AUR 安装：

paru -S cc-switch-bin

Linux（Debian/Ubuntu/Fedora 等）

从 Releases 下载对应构建：

• CC-Switch-v{version}-Linux.deb（Debian/Ubuntu）
• CC-Switch-v{version}-Linux.rpm（Fedora/RHEL/openSUSE）
• CC-Switch-v{version}-Linux.AppImage（通用）

Flatpak：官方 Releases 中不含 Flatpak 包。如需使用，可基于 .deb 自行构建，详细步骤见 flatpak/README.md。

如需从源码运行，可先 git clone https://gitcode.com/GitHub_Trending/cc/cc-switch，再按下一节的开发命令操作。

深入底层：数据可靠性、同步与并发设计

README_DE 在"Architekturüberblick（架构概览）"中明确给出了 6 条设计原则，它们是理解 CC Switch 可靠性的钥匙：

• SSOT（单一事实来源）：所有数据统一存放在 ~/.cc-switch/cc-switch.db（SQLite）。
• 双层存储：可同步的数据进 SQLite，设备相关的设置存 JSON。
• 双向同步：切换时写入各工具的实际配置文件（Live-Dateien）；编辑活跃供应商时则从 Live-Dateien 反向回填（Backfill）。
• 原子写：临时文件 + 重命名模式，避免配置写一半损坏。
• 并发安全：Mutex 保护的数据库连接避免竞态条件。
• 分层架构：Commands → Services → DAO → Database 的清晰分层。

源码对上述原则逐一落地：

1. 原子写与确定性输出：如前面所述，config.rs 在写 JSON 前会递归排序键（sort_json_keys），保证"相同数据永远产出相同文件内容"，减少无意义 diff 与冲突；再经原子写落盘。
2. 备份轮换：database/backup.rs 负责在操作前建立 .db 快照，随后按保留策略（effective_backup_retain_count，见 src-tauri/src/database/backup.rs）清理最旧的备份。
3. 数据库访问层：src-tauri/src/database 目录中的 DAO/Schema/Migration 文件实现了对 SQLite 的分层封装，src-tauri/tests/app_config_load.rs 与 src-tauri/tests/profile_roundtrip.rs 等测试则对"加载—切换—回写"链路做了端到端守护。
4. 配置隔离与测试：config.rs 支持通过 CC_SWITCH_TEST_HOME 覆盖 home 目录，让测试（尤其 Windows CI）能在隔离环境验证真实用户数据的读写，避免污染。

架构概览：React + Tauri 的分层结构

README_DE 给出如下总体架构：

┌─────────────────────────────────────────────────────────────┐
│                    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)       │     │
│  └─────────────┘  └──────────────┘  └──────────────────┘     │
└──────────────────────────────────────────────────────────────┘

前端的业务逻辑收敛在 src/hooks（如 useProviderActions、useProxyStatus、useSkills、useSettings），对 Tauri 命令的类型安全封装位于 src/lib/api，缓存与同步交给 TanStack Query（配置在 src/lib/query）。后端 Rust 侧则是 src-tauri/src/commands（命令/API 层）、src-tauri/src/services（业务层）与 src-tauri/src/database（DAO 层）的分层实现。

README_DE 归纳的后端关键组件（可与 src-tauri/src 中的文件一一对上）：

• ProviderService：供应商增删改查、切换、回填（Backfill）、排序；
• McpService：MCP 服务器管理、导入导出、Live 文件同步；
• ProxyService：本地代理模式，热切换与格式转换；
• SessionManager：跨所有受支持应用检索会话历史；
• ConfigService：配置导入导出与备份轮换；
• SpeedtestService：测量 API 端点延迟。

技术栈

• 前端：React 18 · TypeScript · Vite · TailwindCSS 3.4 · TanStack Query v5 · react-i18next · react-hook-form · zod · shadcn/ui · @dnd-kit（package.json 中还包含 recharts 图表、smol-toml 解析、CodeMirror 编辑器等，供用量图表、TOML 配置编辑与 Markdown/JSON 编辑使用，见 package.json）
• 后端：Tauri 2.8 · Rust · serde · tokio · thiserror · tauri-plugin-updater/process/dialog/store/log，另含 rusqlite、reqwest、axum、rustls 等（见 src-tauri/Cargo.toml）
• 测试：vitest · MSW · @testing-library/react（前端）；cargo test（Rust 后端）

开发者指南：环境、命令与测试

环境要求

• Node.js 18+
• pnpm 8+
• Rust 1.85+
• Tauri CLI 2.8+

常用开发命令

# 安装依赖
pnpm install

# 开发模式（热更新）
pnpm dev

# 类型检查
pnpm typecheck

# 格式化
pnpm format

# 格式化检查
pnpm format:check

# 前端单元测试
pnpm test:unit

# Watch 模式（开发期推荐）
pnpm test:unit:watch

# 构建应用
pnpm build

# 构建 Debug 版本
pnpm tauri build --debug

Rust 后端开发：

cd src-tauri

# 格式化 Rust 代码
cargo fmt

# Clippy 检查
cargo clippy

# 运行后端测试
cargo test

# 运行指定测试
cargo test test_name

# 携带 test-hooks feature 运行测试
cargo test --features test-hooks

测试方法论

• 前端：用 vitest 作为测试框架；用 MSW（Mock Service Worker） 模拟 Tauri API 调用（mock 定义见 tests/msw/tauriMocks.ts）；用 @testing-library/react 编写组件测试。整个 tests 目录按 components/、hooks/、config/、lib/、utils/、integration/ 分组组织。
• 后端：Rust 集成测试位于 src-tauri/tests，覆盖配置加载、供应商命令、代理命令、MCP、会话、导入导出等关键链路。

项目结构速览

├── src/                        # 前端（React + TypeScript）
│   ├── components/
│   │   ├── providers/          # 供应商管理
│   │   ├── mcp/                # MCP 面板
│   │   ├── prompts/            # Prompts 管理
│   │   ├── skills/             # Skills 管理
│   │   ├── sessions/           # Session Manager
│   │   ├── proxy/              # 代理模式面板
│   │   ├── openclaw/           # OpenClaw 配置面板
│   │   ├── settings/           # 设置（终端/备份/关于等）
│   │   ├── deeplink/           # Deep Link 导入
│   │   ├── universal/          # 跨应用统一配置
│   │   ├── usage/              # 用量统计
│   │   └── ui/                 # shadcn/ui 组件库
│   ├── hooks/                  # 自定义 Hooks（业务逻辑）
│   ├── lib/
│   │   ├── api/                # Tauri API 类型安全封装
│   │   └── query/              # TanStack Query 配置
│   ├── i18n/locales/           # 翻译（zh/zh-TW/en/ja）
│   ├── config/                 # Presets（providers/mcp）
│   └── types/                  # TypeScript 定义
├── src-tauri/                  # 后端（Rust）
│   └── src/
│       ├── commands/           # Tauri 命令层（按域划分）
│       ├── services/           # 业务逻辑层
│       ├── database/           # SQLite DAO 层
│       ├── proxy/              # 代理模块
│       ├── session_manager/    # 会话管理
│       ├── deeplink/           # Deep Link 处理
│       └── mcp/                # MCP 同步模块
├── tests/                      # 前端测试
└── assets/                     # 截图与资源

贡献指南与本地化

• 贡献前自查：提交 PR 前请确保 pnpm typecheck、pnpm format:check、pnpm test:unit 全部通过；新功能建议先开 Issue 讨论，避免提交与项目方向不符的 PR 被关闭。完整约定见 CONTRIBUTING.md。
• 多语言文档：本仓库同时维护英文、中文、日文、德文版 README（README.md、README_ZH.md、README_JA.md），功能速览与更新历史可查阅 CHANGELOG.md；各功能的完整分步讲解见用户手册（英文、中文、日文），其中中文手册另含中文专属的功能指南（如本地代理、原生契约等，见 docs/guides 与 docs/pi-* 系列）。
• 赞助与生态：README 中同时展示了一批社区 API Relay/中转服务商的赞助信息与针对 CC Switch 用户的优惠码，相关信息、使用条件与风险请以各服务商官方页面及 README_DE.md 原文为准，本文不代为转载链接。

小结

CC Switch 通过"一个 SQLite SSOT + 双层存储 + 原子写 + 双向同步"的可靠性底座，把 8 类 AI 编码工具的 JSON/TOML/.env 配置差异收敛到同一个可视化桌面应用里；50+ 供应商预设、统一 MCP/Prompts/Skills 面板、托盘热切换、本地代理与故障转移、用量统计与跨设备云同步，构成了它作为 AI 编码工具"控制面板"的完整能力矩阵。无论你是想减少重复配置的普通用户，还是想理解其架构并参与共建的开发者，都可以从本仓库的 README_DE.md、用户手册与源码（src/components、src-tauri/src、tests、src-tauri/tests）中继续深入。