cc-switch 详细指南

版本 3.20.0~3.20.0 ｜分类 session ｜安全（已审查）｜素材：项目官方文档（ccswitch.io，中英双语）+ 本市场实测（2026-08-28 结构确认）
配套：站内文档（manifest + guide + 证据）｜快速版：站内文档

1. 场景：什么时候会用它

CC Switch（farion1231 出品，MIT，约 13 万星）是跨平台桌面 All-in-One 管理器：Claude Code、Claude Desktop、Codex、Gemini CLI、Grok Build、OpenCode、OpenClaw、Hermes 的供应商/模型配置切换。它直接读写各 agent 的配置文件，GUI 一键切换，另带会话用量统计、技能/MCP 管理、WebDAV 同步。

一句话：国产"供应商切换神器"——不用手改 ~/.claude.json 和 ~/.codex/config.toml。

你同时用 Claude Code 和 Codex，各配了两三个供应商，每次切换要手动改配置文件（~/.claude.json 的 provider、~/.codex/config.toml 的模型商），改错一个逗号整个 CLI 就起不来。CC Switch 就是干这个的：一个桌面 GUI，统一切换多个 Agent 的会话与供应商，还带用量统计。它本质是个「配置改写器」——点一下，帮你改写 ~/.claude.json / ~/.codex/config.toml。注意：本条目是桌面 GUI，本环境无 GUI 库未实际运行，安装路径与写面基于二进制审计 + 官方文档，如实标注。

什么时候用：

你要在多个供应商/模型之间快速切换（GUI 点点就换）；
你要管理 Codex 配置（OpenAI OAuth 或第三方供应商）；
你要看各 Agent 的会话用量统计。

什么时候别用：只用单一 Agent 单一供应商；或纯命令行环境（它是桌面 GUI，需要桌面）。

2. 能力清单

能力	作用
多 agent 供应商切换	见 Agent 执行版 guide
Claude Code/Codex 配置管理	见 Agent 执行版 guide
模型/API 配置切换	见 Agent 执行版 guide
会话用量统计（SQLite）	见 Agent 执行版 guide
技能/MCP 管理	见 Agent 执行版 guide
WebDAV 同步	见 Agent 执行版 guide

3. 快速安装

note: AppImage 免安装形态（本环境结构确认）；国内 GitHub 直连慢必须 gh-proxy 加速

# 来源: Trove 详细指南 · 验证于 2026-08-31
curl -sL -o cc-switch.AppImage https://gh-proxy.com/https://github.com/farion1231/cc-switch/releases/download/v3.20.0/CC-Switch-v3.20.0-Linux-x86_64.AppImage
chmod +x cc-switch.AppImage && ./cc-switch.AppImage

预期输出: 应用窗口（桌面环境）

因为是 GUI 条目（本环境未实测运行），确认分两层：

安装层（可机器验证）：command -v cc-switch 有路径；AppImage 模式则文件可执行且 ldconfig -p | grep webkit2gtk 有输出；
功能层（桌面环境验证）：启动后配置面板能列出已装 Agent；做一次切换，确认对应配置文件被改写、Agent CLI 用新配置能正常起会话（依据官方文档）。

安装变体

路径	命令	实测
主路径（实测）	`curl -sL -o cc-switch.deb https://gh-proxy.com/https://github.com/farion1231/cc-…`	✅ 本市场实测
镜像/代理	见快速版与 semi_auto_note；国内安装按 cc-switch 指引	实测

半自动说明：实测命令 = deb 包结构确认（2026-08-28 本环境验证，v3.20.0，gh-proxy 加速 13.5MB；Tauri 桌面应用，二进制 31MB，依赖 libwebkit2gtk-4.1——本环境无 GUI 库未运行）；官方资产 19 个全平台（AppImage/deb/rpm/win/mac）；管理面 = ~/.claude.json（Claude Code provider）+ ~/.codex/config.toml（Codex）+ opencode 配置 + ~/.cc-switch/config.json（自身）+ SQLite（会话用量）；桌面 GUI 形态

Windows / macOS：官方提供对应平台安装器（本条目只实测 Linux 资产结构）。
纯命令行环境：跑不了 GUI，别用它——直接手改 ~/.claude.json / ~/.codex/config.toml。
与其它改配置工具共装：oh-my-claudecode / claude-code-router / claude-mem 都碰 ~/.claude.json，判定 possible-conflict（共享写面推断，未实测）——先备份再逐个评估。
headless 服务器：同「纯命令行环境」，GUI 不可用。

4. 为什么会这样（机制与共享面）

桌面应用（Linux deb / AppImage / 其它平台安装器），Linux 依赖 libwebkit2gtk-4.1。它的核心机制是配置面板 → 改写目标 Agent 的配置文件：切 Claude Code 供应商就改 ~/.claude.json，管 Codex 就改 ~/.codex/config.toml；用量统计走 SQLite 持久化。

关键概念：

供应商切换：改写 ~/.claude.json 的 provider 配置；
Codex 面板：管理 ~/.codex/config.toml（OAuth token 过期提示重登）；
用量统计：各 Agent 会话统计（SQLite 持久化）。

装完它动哪里：~/.cc-switch/（自身数据）+ ~/.claude.json / ~/.codex/config.toml（切换时改写——共享配置，注意备份）。

实测命令 = deb 包结构确认（2026-08-28 本环境验证，v3.20.0，gh-proxy 加速 13.5MB；Tauri 桌面应用，二进制 31MB，依赖 libwebkit2gtk-4.1——本环境无 GUI 库未运行）；官方资产 19 个全平台（AppImage/deb/rpm/win/mac）；管理面 = ~/.claude.json（Claude Code provider）+ ~/.codex/config.toml（Codex）+ opencode 配置 + ~/.cc-switch/config.json（自身）+ SQLite（会话用量）；桌面 GUI 形态

5. 常用操作

第 1 步：装（deb 还是 AppImage？）

讲解：deb 适合 Debian/Ubuntu 长期安装（dpkg 管理、可卸载）；AppImage 免安装、下载即用，适合先试。国内 GitHub 直连慢，下载地址统一走 gh-proxy 前缀。GUI 启动需要桌面环境。

# 来源: Trove 详细指南 · 验证于 2026-08-31
curl -sL -o cc-switch.AppImage https://gh-proxy.com/https://github.com/farion1231/cc-switch/releases/download/v3.20.0/CC-Switch-v3.20.0-Linux-x86_64.AppImage
chmod +x cc-switch.AppImage && ./cc-switch.AppImage

预期输出: 应用窗口（桌面环境）

装好确认：

AppImage 文件可执行、能启动到窗口（需要桌面环境）；
依赖检查：libwebkit2gtk-4.1 存在（ldconfig -p | grep webkit2gtk）。

卡住怎么办：

AppImage 起不来 → ldconfig -p | grep webkit2gtk 确认 libwebkit2gtk-4.1；缺就 apt-get install -y libwebkit2gtk-4.1-0；
headless 环境 → 纯命令行环境跑不了 GUI，改用各 Agent 自己的 CLI 配置方式；
GitHub 下载慢 → 确认下载地址带 gh-proxy 前缀。

第 2 步：切换供应商（写面操作，先备份）

讲解：这是它最核心也最需要注意的一步——切换会改写共享配置文件。切 Claude Code 供应商 = 改 ~/.claude.json 的 provider；管 Codex = 改 ~/.codex/config.toml。操作前先备份这两个文件，切错还能还原。

# 来源: Trove 详细指南 · 验证于 2026-08-31
cp ~/.claude.json ~/.claude.json.bak-$(date +%F) 2>/dev/null || true
cp ~/.codex/config.toml ~/.codex/config.toml.bak-$(date +%F) 2>/dev/null || true

预期输出: 两个配置文件各有带日期的备份（如已有则跳过）

# 来源: Trove 详细指南 · 验证于 2026-08-31
# GUI：配置面板选择目标供应商/模型 → 应用

预期输出: ~/.claude.json 的 provider 配置被改写（切换生效；本环境未实测 GUI，依据官方文档）

装好确认：

切换后，对应 Agent CLI 能正常使用新供应商（claude / codex 跑一个会话）；
配置文件语法仍合法（python3 -c "import json; json.load(open(\"~/.claude.json\".replace(\"~\", \"$HOME\")))" 无报错）。

卡住怎么办：

切换后 CLI 报配置错 → 用备份还原（cp ~/.claude.json.bak-<日期> ~/.claude.json）；
Codex OAuth 过期 → GUI 提示重登，按提示重新授权；
切换没生效 → 确认 GUI 里选的是目标 Agent 的供应商，且对应 CLI 已重启会话。

启动与入口

AppImage：./cc-switch.AppImage；deb：应用菜单或 cc-switch。
入口面板：配置面板（供应商切换）、Codex 面板、用量面板。

常用操作

操作一：切换 Claude Code 供应商

# 来源: Trove 详细指南 · 验证于 2026-08-31
# GUI：配置面板选择目标供应商/模型 → 应用

预期输出: ~/.claude.json 的 provider 配置被改写（切换生效）

操作二：管理 Codex 配置

# 来源: Trove 详细指南 · 验证于 2026-08-31
# GUI：Codex 面板添加供应商（OpenAI OAuth 或第三方）

预期输出: ~/.codex/config.toml 被管理（OAuth token 过期提示重登）

操作三：会话用量查看

# 来源: Trove 详细指南 · 验证于 2026-08-31
# GUI：用量面板

预期输出: 各 agent（Claude/Codex/Gemini/OpenCode 等）会话统计（SQLite 持久化）

数据与目录

自身数据：~/.cc-switch/（含用量统计 SQLite）；
共享配置（切换时改写）：~/.claude.json、~/.codex/config.toml。

6. 冲突逐条（摘要）

与工具页矩阵同源，共 19 对（0 实测兼容 / 15 推断可能兼容 / 4 推断可能冲突）；完整对子、状态与证据见冲突对子（共装矩阵）。

7. 排障速查

症状：dpkg -i 依赖缺失：libwebkit2gtk 等（Linux 安装/启动失败）
症状：GitHub Release 下载 TLS 断连 / 超时
症状：架构不匹配（香橙派等 ARM 设备）
症状：启动失败 / 白屏排查
症状：安装来源混淆：npm 同名包 / 其它 cc-switch 项目
症状：卸载后共享配置不还原（~/.claude.json / ~/.codex/config.toml）

四段式全文（症状→原因→解法→验证证据）：站内文档

8. 卸载与残留检查

# 来源: Trove 详细指南 · 验证于 2026-08-31
sudo dpkg -r cc-switch 2>/dev/null || true; rm -rf ~/.cc-switch

note: dpkg 卸载；注意 ~/.claude.json 与 ~/.codex/config.toml 是共享配置，卸载不还原

# 来源: Trove 详细指南 · 验证于 2026-08-31
sudo dpkg -r cc-switch 2>/dev/null || true
rm -rf ~/.cc-switch
command -v cc-switch >/dev/null 2>&1 && echo '残留: cc-switch 仍存在' || echo 'cc-switch removed: OK'

预期输出: cc-switch removed: OK

9. FAQ

运行环境预检（Linux x86_64 桌面；依赖 libwebkit2gtk-4.1）
官方 release 资产（本环境结构确认）；国内 GitHub 直连慢必须 gh-proxy 加速
GUI 操作；每条 = 目标 + 预期效果；官方文档 ccswitch.io（英文/中文）
dpkg 卸载；注意 ~/.claude.json 与 ~/.codex/config.toml 是共享配置，卸载不还原
共享写面：它改写 ~/.claude.json 与 ~/.codex/config.toml——与 omc（Claude 插件注册）、claude-code-router（路由配置）存在同面改写风险（本市场判定 possible-conflict）；切换前建议备份这两个文件

问：GUI 起不来？答：确认桌面环境与 libwebkit2gtk-4.1（ldconfig 检查）；纯 headless 环境跑不了 GUI。
问：切换会改我的什么？答：改写 ~/.claude.json（Claude Code）与 ~/.codex/config.toml（Codex）的供应商配置；切换前先备份这两个文件。
问：和 claude-code-router / claude-mem 能一起装吗？答：三者都碰 ~/.claude.json 写面，当前判定 possible-conflict（共享写面推断，未实测）；建议先备份再逐个评估。
问：使用问题向谁反馈？答：本市场安装/卸载问题走条目反馈入口；项目自身问题请向作者仓库反馈。

版本：[3.20.0, 3.20.0] 锁定（收录结构确认版本）。
环境：Linux x86_64 桌面；依赖 libwebkit2gtk-4.1；AppImage 免安装但同样需要桌面环境。
网络：GitHub 直连慢，必须 gh-proxy 前缀（实测路径）。
写面（大）：~/.cc-switch/ + 共享配置 ~/.claude.json、~/.codex/config.toml——切换会改写共享配置，先备份。
共装：与 oh-my-claudecode / claude-code-router / claude-mem 判定 possible-conflict（共享 ~/.claude.json 写面推断，未实测）。

10. 出处

条目签名：farion1231/cc-switch（MIT，原样收录 v3.20.0）

实测：实测记录（本地留存）（2026-08-28，release 资产结构确认：deb/AppImage 下载地址与版本）。
未实测：GUI 运行与切换操作（本环境无 GUI 库）——预期效果来自官方文档 ccswitch.io，如实标注。

外部教学（来源未实测）

第三方教学未逐条实测，仅供学习；有出入以本页与官方文档为准。

官方 README：Quick Start（Add Provider / Switch / 生效 / 回官方） [官方文档 · cc-switch 官方 · 2026-08-30（v3.20.1 抓取）]
4 步核心用法——添加供应商（预设或自定义）→ 主界面/托盘切换 → 重启终端或 CLI 生效（Claude Code 免重启）→ 用「官方登录」预设回官方账号
官方 README：MCP / Prompts / Skills / Sessions 用法 [官方文档 · cc-switch 官方 · 2026-08-30（v3.20.1 抓取）]
进阶能力——MCP 服务器添加（模板/自定义/按应用同步）、Prompts 预设（Markdown 编辑器 + 激活同步）、Skills 一键安装（浏览 GitHub 仓库）、Sessions 会话浏览/搜索/恢复
官方 README：Download & Installation（系统要求/平台差异） [官方文档 · cc-switch 官方 · 2026-08-30（v3.20.1 抓取）]
Windows（安装包/便携版）、macOS（dmg）、Arch Linux（AUR/手动）、Linux（deb/rpm/AppImage）四平台安装路径

收录来源（已合并）

本页内容由多篇来源文章按哈希去重、实测验证、AI 重写后合并而来——来源不散落，全部挂在这一个页面上。

暂无已合并来源：本页为本地实测与多来源重写的沉淀；来源与验证细节见站内对应方案页。

← 返回 cc-switch 方案页｜会话与记忆问题域