CC Switch 用户手册导航：五大模块结构与 v3.16.0 新特性全解析-二趣网

CC Switch 用户手册导航：五大模块结构与 v3.16.0 新特性全解析

【免费下载链接】cc-switchA cross-platform desktop All-in-One assistant for Claude Code, Codex, OpenCode, OpenClaw, Grok Build & Hermes Agent. Only official website: ccswitch.io项目地址: https://gitcode.com/GitHub_Trending/cc/cc-switch

CC Switch（README）是面向 Claude Code / Claude Desktop / Codex / Gemini CLI / OpenCode / OpenClaw / Hermes 的跨平台 All-in-One 桌面助手，其英文版用户手册位于 docs/user-manual/en/README.md。本文以该手册总览页为主体，完整继承其目录骨架、26 篇子文档索引与版本信息，并结合仓库源码佐证 v3.16.0 各项高亮特性的实现，帮助你按正确的阅读路径掌握这个工具的配置、扩展与高可用能力。

手册定位与适用版本

docs/user-manual/en/README.md 是英文版用户手册的入口页（该手册在仓库内同时提供中文与日文版本，结构一致）。手册明确标注：

文档版本：v3.16.0
最后更新：2026-05-29
适用客户端：CC Switch v3.16.0+

因此本文以下内容均以 v3.16.0 为基准；若你使用的是更早版本，部分特性（如 Codex Chat Completions 路由、轻量模式、托管 CLI 工具管理）可能尚不存在，请以对应版本的发布说明为准。

手册目录骨架：五大模块

手册总览页给出的完整目录树如下，它也是理解 CC Switch 功能版图的最快方式：

CC Switch User Manual │ ├── 1. Getting Started │ ├── 1.1 Introduction │ ├── 1.2 Installation Guide │ ├── 1.3 Interface Overview │ ├── 1.4 Quick Start │ └── 1.5 Personalization │ ├── 2. Provider Management │ ├── 2.1 Add Provider │ ├── 2.2 Switch Provider │ ├── 2.3 Edit Provider │ ├── 2.4 Sort & Duplicate │ ├── 2.5 Usage Query │ └── 2.6 Claude Desktop │ ├── 3. Extensions │ ├── 3.1 MCP Server Management │ ├── 3.2 Prompts Management │ ├── 3.3 Skills Management │ ├── 3.4 Session Manager │ └── 3.5 Workspace & Memory │ ├── 4. Proxy & High Availability │ ├── 4.1 Proxy Service │ ├── 4.2 App Takeover │ ├── 4.3 Failover │ ├── 4.4 Usage Statistics │ └── 4.5 Model Test │ └── 5. FAQ ├── 5.1 Configuration Files ├── 5.2 FAQ ├── 5.3 Deep Link Protocol └── 5.4 Environment Variable Conflicts

各模块在仓库中的入口与内容定位如下（链接均为仓库根目录相对路径，可直接跳转阅读）：

模块 1：Getting Started（入门）

文档	内容
1.1-introduction.md	项目定位、核心特性、支持的平台
1.2-installation.md	Windows/macOS/Linux 安装指南
1.3-interface.md	界面布局、导航栏、Provider 卡片
1.4-quickstart.md	5 分钟快速上手教程
1.5-settings.md	语言、主题、目录、云同步与托管 CLI 工具管理

据 1.1-introduction.md 描述，CC Switch 解决的核心痛点是：多 Provider 切换需要手工改配置文件、七款工具的配置文件格式各异且分散、缺乏用量监控、单点 Provider 故障导致工作流中断。其技术栈为 React 18 + TypeScript + Tailwind CSS 前端、Tauri 2 + Rust 后端、SQLite（providers/MCP/Prompts）+ JSON（设备设置）存储，与仓库实际结构一致——前端代码位于 src/，Rust 后端位于 src-tauri/src/，数据库模块在 src-tauri/src/database/。

1.4-quickstart.md 给出了最小上手路径：点击右上角+按钮添加 Provider（选择 Preset 或 Custom，填入 API Key）→ 在主界面点击 "Enable" 或通过系统托盘快捷切换 → 按应用类型完成激活。各应用的激活方式差异如下表，这也是新手最常踩坑的地方：

Application	激活方式
Claude Code	即时生效（支持热加载）
Codex	需要关闭并重开终端
Gemini	即时生效（每次请求重新读取配置）
OpenCode	需要关闭并重开终端
OpenClaw	需要关闭并重开终端

验证方式是在重启后的 CLI 中各输入一句测试问题（claude/codex/gemini/opencode/openclaw），AI 正常应答即配置成功。

模块 2：Provider Management（供应商管理）

文档	内容
2.1-add.md	使用预设、自定义配置、通用 Provider
2.2-switch.md	主界面切换、托盘切换、激活方式
2.3-edit.md	编辑配置、修改 API Key、回填机制
2.4-sort-duplicate.md	拖拽排序、复制 Provider、删除
2.5-usage-query.md	用量查询、余额显示、多方案展示
2.6-claude-desktop.md	Claude Desktop 第三方 Provider、直连模式与模型映射

预设数据在仓库中可直接查看，例如 Claude 预设 src/config/claudeProviderPresets.ts、Codex 预设 src/config/codexProviderPresets.ts、OpenClaw 预设 src/config/openclawProviderPresets.ts 等，前端表单与这些预设一一对应（组件位于 src/components/providers/forms/）。

模块 3：Extensions（扩展）

文档	内容
3.1-mcp.md	MCP 协议、添加服务器、应用绑定
3.2-prompts.md	创建预设、激活/切换、智能回填
3.3-skills.md	技能发现、安装/卸载、仓库管理
3.4-sessions.md	会话管理：浏览、搜索、恢复、删除
3.5-workspace.md	工作区文件与每日记忆（OpenClaw）

后端实现分别对应 src-tauri/src/mcp/、src-tauri/src/prompt.rs、src-tauri/src/session_manager/ 等模块，前端面板位于 src/components/mcp/、src/components/prompts/、src/components/sessions/ 与 src/components/workspace/。

模块 4：Proxy & High Availability（代理与高可用）

文档	内容
4.1-service.md	启动代理、配置、运行状态
4.2-routing.md	应用路由（App Takeover）、配置变更、状态指示
4.3-failover.md	故障转移队列、熔断器、健康状态
4.4-usage.md	用量统计、趋势图、定价配置
4.5-model-test.md	模型测试、健康检查、延迟测试

这一模块是整个代理层的入口，后端实现集中在 src-tauri/src/proxy/，其中故障转移对应 failover_switch.rs 与 circuit_breaker.rs，请求转发在 forwarder.rs，用量统计位于 src-tauri/src/proxy/usage/。

模块 5：FAQ（常见问题）

文档	内容
5.1-config-files.md	CC Switch 存储位置、各 CLI 配置文件格式
5.2-questions.md	常见问题集
5.3-deeplink.md	Deep Link 协议、生成与使用
5.4-env-conflict.md	环境变量冲突检测与解决

Deep Link 导入的后端实现位于 src-tauri/src/deeplink/，并有独立的集成测试 src-tauri/tests/deeplink_import.rs。

手册 Quick Links 使用建议

总览页给出的 Quick Links 针对不同角色：

新用户：从 1.1 Introduction 开始；
安装出问题：查 1.2 Installation Guide；
配置 Provider：看 2.1 Add Provider；
使用 Claude Desktop：看 2.6 Claude Desktop；
启用代理：看 4.1 Proxy Service；
遇到疑难：查 5.2 FAQ。

安装方面，1.2-installation.md 覆盖了三平台的完整流程：Windows 使用 MSI 安装包或 Portable 压缩包（解压即用、不写注册表）；macOS 推荐brew install --cask cc-switch（v3.16.0 起进入官方 Homebrew cask 仓库，升级用brew upgrade --cask cc-switch），手动安装则拖入 Applications，官方构建已 Apple 签名与公证；Linux 提供.deb/.rpm/.AppImage三种格式，x86_64 与 ARM64 架构在文件名中区分，Arch 系可通过 AUR 的cc-switch-bin安装。CLI 工具（Claude Code / Codex / Gemini CLI）需要 Node.js 18+ 环境。官方文档特别提示：任何索要付费、充值或登录凭据的"CC Switch"站点均为假冒。

v3.16.0 高亮特性：手册与源码对照

总览页 "Version Information" 一节列出了 v3.16.0 的十大亮点。以下逐项说明，并给出仓库内可验证的源码位置（特性细节另见 docs/release-notes/v3.16.0-en.md）：

1. Codex Chat Completions 路由

将 DeepSeek、Kimi、GLM、MiniMax 等仅支持 Chat Completions 协议的 Provider 路由进 Codex：本地代理把 Codex 发出的 Responses 请求转换为 Chat Completions，再把 JSON 与 SSE 流式响应重构回 Responses 形态，保留reasoning_content、工具调用与previous_response_id续接。实现位于 src-tauri/src/proxy/providers/transform_codex_chat.rs（请求侧转换）、src-tauri/src/proxy/providers/streaming_codex_chat.rs（流式响应重建），配套的模型目录投影到~/.codex/cc-switch-model-catalog.json。注意该手册条目对应的使用文档是 2.1 Add Provider，其中涵盖 "Needs Local Routing" 开关与模型映射表。

2. 托管 CLI 工具生命周期管理

Settings / About 页升级为工具管理面板，可对 Claude / Codex / Gemini / OpenCode / OpenClaw / Hermes 执行安装、更新、全部更新与冲突诊断。手册条目指向 1.5 Personalization，前端入口组件为 src/components/settings/AboutSection.tsx 与 src/components/settings/ToolInstallRow.tsx。

3. Provider 与模型矩阵刷新

新增合作方预设（APIKEY.FUN、APINebula、AtlasCloud 等），默认模型升级为 Claude Opus 4.8 与 GPT-5.5（适用处），定价种子同步刷新。

4. 路由支持徽章

Claude Code / Codex 的 Provider 卡片上会显示该 Provider 是否可经 Local Routing 提供服务——"从源码结构看"这一能力由 src/utils/providerCapabilities.ts 计算，展示组件为 src/components/providers/FailoverPriorityBadge.tsx 与 src/components/providers/ProviderCard.tsx。

5. Codex OAuth 实时模型发现

ChatGPT Codex Provider 可即时从 ChatGPT 后端拉取可用模型，前端对应 src/components/CodexOauthAccountQuota.tsx。

6. 过滤驱动的 Usage Hero

用量面板显示经缓存归一化的真实总 token 数与缓存命中率，并随日期 / Provider / 模型过滤联动刷新，见 4.4 Usage Statistics。前端实现为 src/components/usage/UsageHero.tsx；v3.16.0 起后端在用量落盘时发出usage-log-recorded事件，面板通过 src/hooks/useUsageEventBridge.ts 即时失效查询，不再等待轮询间隔。

7. Lightweight Mode（轻量模式）

最小化到托盘时销毁主窗口，实现近零闲置内存占用。源码可直接验证：src-tauri/src/lightweight.rs 中enter_lightweight_mode保存窗口状态后调用window.destroy()销毁main窗口并置位LIGHTWEIGHT_MODE标志；恢复时由exit_lightweight_mode从窗口配置重新构建窗口。命令入口注册在 src-tauri/src/commands/lightweight.rs。

8. 配额与余额显示

官方订阅（Claude/Codex/Gemini/Copilot/Codex OAuth）自动展示配额；Token Plan 与第三方余额通过内置模板一键启用，见 2.5 Usage Query，相关前端组件包括 src/components/SubscriptionQuotaFooter.tsx 与 src/components/UsageFooter.tsx。

9. Codex OAuth 反向代理

在 Claude Code 内复用 ChatGPT 账号的 Codex 服务，入口见 2.1 Add Provider。发布说明中明确的风险提示同样适用于此：该路径可能违反 OpenAI 服务条款，使用前请阅读 docs/release-notes/v3.16.0-en.md 中的 Risk Notice。

10. 每应用托盘子菜单与技能批量更新

Claude / Codex / Gemini 托盘子菜单显示当前 Provider 与可用用量摘要（见 2.2 Switch Provider，托盘实现在 src-tauri/src/tray.rs）；Skills 模块新增 SHA-256 更新检测、批量更新与 skills.sh 公开注册表搜索（见 3.3 Skills Management）。

11. Full URL Endpoint 模式与 Stream Check 覆盖面

高级选项可将base_url直接当作完整上游端点处理（2.1 Add Provider）；Stream Check 已覆盖 Claude / Codex / Gemini / OpenCode / OpenClaw / Hermes 六类应用（4.5 Model Test，前端入口 src/hooks/useStreamCheck.ts）。

版本迁移注意事项

按 v3.16.0 发布说明（docs/release-notes/v3.16.0-en.md），升级到 v3.16.0 时需要注意：

一次性 Codex 历史迁移：首次启动会把第三方 Provider 的历史会话（JSONL 与state_5.sqlitethreads 表）归一化到稳定的custombucket，原始文件备份在~/.cc-switch/backups/codex-history-provider-migration-v1/，解决"切换 Provider 后历史会话消失"的问题；
Codex 目录变更需重启：Codex 在启动时加载model_catalog_json，修改模型映射表后必须重启 Codex 才生效；
reasoning effort 可能无效：对只暴露 thinking 开关的 Provider（Kimi、GLM、Qwen、MiniMax、MiMo、SiliconFlow），Codex 的model_reasoning_effort设置不会透传，仅 DeepSeek、OpenRouter 与 StepFun 的step-3.5-flash-2603真正支持 effort 档位。

结语

docs/user-manual/en/README.md 以"入门 → 供应商管理 → 扩展 → 代理与高可用 → FAQ"的骨架组织了 CC Switch 的 26 篇子文档。建议的路径是：先按 1.4-quickstart.md 跑通第一个 Provider，再依据实际痛点深入对应模块——需要多方案高可用时读模块 4，需要扩展 AI 能力时读模块 3。每篇子文档在仓库中均有对应前端组件与 Rust 后端实现可供交叉验证，配合 docs/release-notes/v3.16.0-en.md 即可完整理解当前版本的能力边界与注意事项。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析