farion1231 / cc-switch

farion1231/cc-switch

open_in_new前往仓库

跨平台桌面一体化助手，支持Claude Code、Codex、OpenCode、OpenClaw、Grok Build及Hermes Agent。唯一官网：ccswitch.io

项目概览

项目概述

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：

brew install --cask cc-switch

或从 Releases 下载 .dmg。

Arch Linux：

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 仓库 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 日期）。