## 项目概述

CC Switch 是一款跨平台桌面端 AI 工具统一管理应用，由 farion1231 开发，采用 Rust 与 TypeScript 构建，基于 Tauri 2 框架。它旨在解决 Claude Code、Claude Desktop、Codex、Gemini CLI、Grok Build、OpenCode、OpenClaw 与 Hermes Agent 等八种 AI 编程工具各自配置格式不同、切换 API 供应商需手动编辑 JSON、TOML 或 .env 文件的问题。CC Switch 提供可视化界面，支持一键导入供应商、即时切换、50+ 内置供应商预设、统一的 MCP 与 Skills 管理，以及系统托盘快速切换。项目采用 MIT 许可证，官方唯一网站为 ccswitch.io。

## 核心功能

- **多工具统一管理**：在一个界面管理 Claude Code、Claude Desktop、Codex、Gemini CLI、Grok Build、OpenCode、OpenClaw 与 Hermes 八种工具。
- **供应商管理**：支持 50+ 内置预设（含 AWS Bedrock、NVIDIA NIM 及社区中转），一键复制密钥导入，支持拖拽排序、导入导出。
- **本地代理与故障转移**：提供本地代理服务，支持格式转换、自动故障转移、熔断、供应商健康监测与请求整流。
- **MCP、提示词与技能管理**：统一 MCP 面板，跨应用双向同步；Markdown 编辑器管理提示词（CLAUDE.md / AGENTS.md / GEMINI.md）；技能支持从 GitHub 仓库或 ZIP 一键安装。
- **用量与成本追踪**：仪表盘展示支出、请求数与 token 用量，含趋势图、请求日志与自定义模型定价。
- **会话管理**：浏览、搜索、恢复支持的会话源历史记录。
- **云同步**：通过 Dropbox、OneDrive、iCloud 或 WebDAV 同步供应商数据。
- **系统集成**：系统托盘快速切换、深链接（ccswitch://）、深色/浅色主题、自动更新、原子写入、自动备份、多语言（中/英/日）。

## 适用与不适用场景

**适用场景**：
- 开发者频繁切换多个 AI 编程工具（Claude Code、Codex 等）及多个 API 供应商。
- 需要统一管理 MCP 服务器、提示词与技能，避免手动编辑配置文件。
- 使用第三方 API 中转或聚合服务，需要协议转换（如 Responses 与 Chat Completions 互转）。
- 需要保留 Codex 官方登录态（远程操作、官方插件）同时使用第三方模型。
- 跨设备同步供应商配置。

**不适用场景**：
- 仅使用单一工具且不切换供应商的用户，可能无需此应用。
- 对官方 API 有严格合规要求，禁止通过代理访问官方服务的场景（CC Switch 会阻止在本地路由模式下切换官方供应商）。
- 需要桌面 GUI 显示自定义模型但上游客户端（如 Codex 桌面应用）不支持时，CC Switch 无法根治。

## 技术架构与依赖

- **前端**：React 18、TypeScript、Vite、TailwindCSS 3.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。
- **数据存储**：SQLite（`~/.cc-switch/cc-switch.db`）存储供应商、MCP、提示词、技能；JSON 存储设备级设置。
- **架构模式**：SSOT（单一数据源）、双层存储、双向同步、原子写入、互斥锁保护数据库连接、分层架构（Commands → Services → DAO → Database）。

## 安装与快速开始

**系统要求**：Windows 10+、macOS 12+、Linux（Ubuntu 22.04+ / Debian 11+ / Fedora 34+）。

**Windows**：从 Releases 下载 `.msi` 安装包或 `.zip` 便携版。

**macOS**：
```bash
brew install --cask cc-switch
```
或从 Releases 下载 `.dmg`。

**Arch Linux**：
```bash
paru -S cc-switch-bin
```

**Linux**：从 Releases 下载 `.deb`、`.rpm` 或 `.AppImage`。

**快速开始**：
1. 添加供应商：点击“添加供应商”→ 选择预设或自定义配置。
2. 切换供应商：主界面选择并启用，或系统托盘直接点击。
3. 生效：重启终端或对应 CLI 工具（Claude Code 支持热切换）。
4. 恢复官方登录：添加“官方登录”预设，重启 CLI 后按 OAuth 流程登录。

## 典型使用方法

**在 Claude Code 中使用 GPT 模型**：
1. 添加供应商，选择“Codex”预设（方式二）或自定义 Responses 网关（方式一）。
2. 设置 API 格式为 OpenAI Responses，配置模型映射。
3. 开启本地路由并接管 Claude Code。
4. 切换供应商，重启终端，验证 `/model` 菜单。

**在 Codex 中使用 Claude 模型**：
1. 添加 Codex 供应商，上游格式选 Anthropic Messages。
2. 配置认证字段、模拟客户端（如需）、最大输出 tokens。
3. 开启本地路由并接管 Codex。
4. 切换供应商，重启 Codex。

**保留 Codex 官方登录同时使用第三方 API**：
1. 先切回 OpenAI Official 并完成官方登录。
2. 开启“切换第三方时保留官方登录”。
3. 添加第三方供应商，必要时开启本地路由。
4. 切换并重启 Codex。

## 配置与部署要点

- **数据存储位置**：数据库 `~/.cc-switch/cc-switch.db`，设置 `~/.cc-switch/settings.json`，备份 `~/.cc-switch/backups/`，技能 `~/.cc-switch/skills/`。
- **本地路由**：默认地址 `127.0.0.1:15721`，需开启路由总开关并启用对应应用接管。
- **协议转换**：支持 Responses ↔ Chat Completions ↔ Anthropic Messages 互转，需在供应商高级选项中设置上游格式。
- **Codex 官方登录保留**：需开启“Codex 应用增强”中的开关，避免覆盖 `auth.json`。
- **Linux Wayland 问题**：若点击无效或黑屏，可设置 `CC_SWITCH_GDK_BACKEND=wayland` 或 `x11`。
- **备份与恢复**：迁移会话历史前自动备份，恢复时按备份账本精确回滚。

## 限制、风险与许可证

- **许可证**：MIT，© Jason Young。
- **限制**：
  - Codex 桌面应用无法显示自定义模型（上游门控），CC Switch 无法根治。
  - 跨供应商恢复会话可能失败（加密内容无法跨后端解密）。
  - 本地路由模式下禁止切换官方供应商，以防账号风险。
  - 部分供应商限制 Claude API 仅限 Claude Code 使用，需模拟客户端或咨询供应商。
- **风险**：
  - 使用第三方中转服务需自行评估合规与数据留存条款。
  - 用量看板金额为估算值，可能与实际扣费不符。
  - 官方登录态可能过期，需重新登录。

## 官方链接

- GitHub 仓库：https://github.com/farion1231/cc-switch
- 官方网站：https://ccswitch.io
- 最新版本：v3.19.2（发布于 2026-08-06）

## 信息来源和分析时间

- 信息来源：GitHub 仓库 README、CONTRIBUTING.md、docs/guides/ 目录下的多语言指南（claude-codex-routing-guide、codex-claude-routing-guide、codex-deepseek-routing-guide、codex-kimi-routing-guide、codex-official-auth-preservation-guide、codex-desktop-custom-model-visibility、codex-unified-session-history-guide）。
- 分析时间：2026-08-06（基于最新 release 日期）。