会话与记忆 · session · 验证于 2026-08-31 ✓ 实测验证

cc-switch

已验证 2026-08-31装/卸循环实测通过；dpkg 报缺 libwebkit2gtk 等依赖时 apt install -f 自动修复后重装。

跨平台 All-in-One 会话/供应商切换器（Claude Code/Codex/Gemini/OpenCode 等）

详细版 → 所属问题域：会话与记忆 遇到问题？去问题空间 →

你会遇到什么

你同时用 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，需要桌面）。

本文路径：快速修复（30 秒一段命令）→ 一步步来（可跳读）→ 怎么确认修好了（成功判据）。赶时间直接跳到「快速修复」。

为什么会这样

桌面应用（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（切换时改写——共享配置，注意备份）。

快速修复（不想看讲解，直接跑）

note: AppImage 免安装形态（本环境结构确认）；国内 GitHub 直连慢必须 gh-proxy 加速
curl -sL -o cc-switch.AppImage https://gh-proxy.com/https://github.com/farion1231/cc-switch/releases/download/v3.20.1/CC-Switch-v3.20.1-Linux-x86_64.AppImage
chmod +x cc-switch.AppImage && ./cc-switch.AppImage

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

一步步来

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

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

curl -sL -o cc-switch.AppImage https://gh-proxy.com/https://github.com/farion1231/cc-switch/releases/download/v3.20.1/CC-Switch-v3.20.1-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。操作前先备份这两个文件，切错还能还原。

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

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

# 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 已重启会话。

怎么确认修好了

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

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

其它环境的表现（常见变体）

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

日常使用

启动与入口

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

常用操作

操作一：切换 Claude Code 供应商

# GUI：配置面板选择目标供应商/模型 → 应用

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

操作二：管理 Codex 配置

# GUI：Codex 面板添加供应商（OpenAI OAuth 或第三方）

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

操作三：会话用量查看

# GUI：用量面板

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

数据与目录

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

卸载与清理

note: dpkg 卸载；注意 ~/.claude.json 与 ~/.codex/config.toml 是共享配置，卸载不还原
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

依赖警告

  • 版本：[3.20.1, 3.20.1] 锁定（2026-08-31 补丁级升级重测：deb 结构 + 写面字符串审计与 3.20.0 一致，证据；GUI 未运行——无 GUI 库，如实标注）。
  • 环境：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 写面推断，未实测）。

FAQ（常见问题）

  • 问：GUI 起不来？答：确认桌面环境与 libwebkit2gtk-4.1（ldconfig 检查）；纯 headless 环境跑不了 GUI。
  • 问：切换会改我的什么？答：改写 ~/.claude.json（Claude Code）与 ~/.codex/config.toml（Codex）的供应商配置；切换前先备份这两个文件。
  • 问：和 claude-code-router / claude-mem 能一起装吗？答：三者都碰 ~/.claude.json 写面，当前判定 possible-conflict（共享写面推断，未实测）；建议先备份再逐个评估。
  • 问：使用问题向谁反馈？答：本市场安装/卸载问题走条目反馈入口；项目自身问题请向作者仓库反馈。
验证证据
  • 实测：实测记录（本地留存）（2026-08-28，release 资产结构确认：deb/AppImage 下载地址与版本）；实测复现日志（2026-08-30）（官方 README 核对 + gh-proxy 下载 v3.20.1 deb 13.6MB 实测 + dpkg 依赖与问题条目一致 + ldd 确认本环境缺 webkit 库无法启动 GUI）。
  • 未实测：GUI 运行与切换操作（本环境无 GUI 库）——预期效果来自官方文档 ccswitch.io，如实标注。

引用：cc-switch · 验证于 2026-08-31 · v3.20.1~3.20.1

相关问题（问题域）

出问题了？排障方案

排障手册：cc-switch（L34 批次 1）

症状 → 原因 → 解法 → 验证证据 四段结构。
素材来源：L33 分源记录（CSDN/掘金/知乎/B站）+ 上游 Issue 检索 + 本市场实测（2026-08-28：deb 下载/结构/dpkg 依赖层闭环）。
采集纪律：零账号匿名检索；不破解反爬；未碰 GitHub。check-words HARD 0。

基本信息

  • 条目名称：cc-switch（farion1231/cc-switch，MIT，v3.20.0 收录）
  • L33 分源信号：CSDN=6+ / 掘金=1 / 知乎=1 / B站=1（强）
  • §14 角色：core；分类：session
  • 定位：跨平台 All-in-One 会话/供应商切换器（Claude Code/Codex/Gemini/OpenCode/OpenClaw/Hermes/Pi）
  • 本市场安装路径：GitHub Release 资产（deb/AppImage，经 gh-proxy 加速）+ 管理面配置
  • 主要安装形态：Tauri 桌面应用（Linux deb/rpm/AppImage、Windows、macOS）；非 npm 包

症状 → 原因 → 解法 → 验证证据

1. dpkg -i 依赖缺失：libwebkit2gtk 等（Linux 安装/启动失败）

症状

sudo dpkg -i cc-switch.deb 报依赖错误，包无法配置：

# 来源: Trove 排障手册 · 验证于 2026-08-31
dpkg: dependency problems prevent configuration of cc-switch:
 cc-switch depends on libayatana-appindicator3-1; however: Package ... not installed.
 cc-switch depends on libwebkit2gtk-4.1-0; however: Package ... not installed.
dpkg: error processing package cc-switch (--install): dependency problems - leaving unconfigured

或安装成功但双击无反应（缺运行库）。

原因

deb 包 Depends：libayatana-appindicator3-1, libwebkit2gtk-4.1-0, libgtk-3-0（Tauri 桌面应用需要 GUI 库）；dpkg -i 不自动解决依赖，缺一个就整体配置失败。

解法

  1. 补依赖：sudo apt install -f（或 sudo apt install ./cc-switch.deb，apt 会自动拉依赖）。
  2. 不想装 GUI 依赖/无 root 场景：用官方 AppImage 资产（免安装，自包含运行）。
  3. 安装前自查：dpkg-deb -I cc-switch.deb 看 Depends 行，先装缺失库。

验证证据

  • 本市场实测 2026-08-28（实测记录（本地留存））：dpkg -i 在无 GUI 库环境完整复现该错误（exit=1）；随后 dpkg -r 清理半安装状态成功，verify 零残留。
  • 依赖清单：libayatana-appindicator3-1 / libwebkit2gtk-4.1-0 / libgtk-3-0（同日志 step 2）。

2. GitHub Release 下载 TLS 断连 / 超时

症状

从 GitHub Release 下载 deb/AppImage 反复断连（TLS/连接重置），13.5MB 的包下不完。

原因

国内直连 GitHub release 资产（objects.githubusercontent.com）不稳定；大文件传输中途断开。

解法

  1. gh-proxy 前缀加速：https://gh-proxy.com/https://github.com/<owner>/<repo>/releases/download/<tag>/<asset>（2026-08-28 实测秒级）。
  2. 或换网络/开代理错峰重试。
  3. 下载后校验：du -h 对照资产页大小（deb 13.5MB / 二进制 31MB）。

验证证据

  • 本市场实测：直连慢，gh-proxy 下载 13.5MB 成功（结构确认 + 闭环日志 step 1 exit=0）。
  • GitHub API 直连可用（资产清单核对，connectivity 记录）。

3. 架构不匹配（香橙派等 ARM 设备）

症状

ARM 设备（香橙派等）安装 x86_64 包报架构错误，或下载 arm 包后 GUI 起不来（GTK 问题）。

原因

官方 19 个资产覆盖 amd64/arm64 等全平台；装错架构包 dpkg 直接拒绝（wrong architecture）；部分 ARM 轻量系统缺桌面库。

解法

  1. 选对架构资产（资产页按 Architecture 过滤：x86_64 / arm64 / win / mac）。
  2. ARM 桌面系统装 arm64 包 + 对应 GUI 依赖（同症状 1 的 apt 方式）。
  3. 无桌面环境设备不建议装 GUI 形态（考虑 CLI 替代方案）。

验证证据

  • 网页案例：CSDN（香橙派 ARM 架构 + GTK 场景）。
  • 本市场实测：amd64 包结构确认（/usr/bin/cc-switch，ELF x86-64，31MB——）。

4. 启动失败 / 白屏排查

症状

双击/命令行启动无反应、白屏、或闪退。

原因

  1. 运行库缺失（webkit 等，见症状 1）；
  2. ~/.cc-switch/config.json 损坏或与版本不兼容；
  3. 共享配置被其它工具改写（~/.claude.json / ~/.codex/config.toml 段结构不匹配）。

解法

  1. 依赖自查：ldd /usr/bin/cc-switch | grep 'not found'——有输出说明缺库，apt 补装。
  2. 配置备份后重试：备份 ~/.cc-switch/ 后删除让其重建。
  3. 终端启动看报错：cc-switch（保留 stderr 输出）。
  4. 共享配置段异常：检查 ~/.claude.json 的 provider 段 JSON 合法性（cc-switch 只改 provider 段，不碰插件注册段）。

验证证据

  • 网页案例：CSDN 启动失败排查场景。
  • 本市场实测：无 GUI 库环境二进制不可运行（如实标注，）；管理面 = ~/.cc-switch/config.json + ~/.claude.json + ~/.codex/config.toml（二进制字符串审计，）。

5. 安装来源混淆：npm 同名包 / 其它 cc-switch 项目

症状

按 "cc-switch" 搜索装到错误的包（npm 上存在同名包，但不是本项目），或装完没有 cc-switch 命令。

原因

本项目 = farion1231/cc-switch（Tauri 桌面应用），分发渠道 = GitHub Release（deb/AppImage/rpm/win/mac），没有 npm 包；npm 同名包是其它项目。

解法

  1. 认准仓库：farion1231/cc-switch；命令/入口 = cc-switch 或桌面图标。
  2. 安装一律走 GitHub Release 资产（或本市场收录的 deb 路径），不要 npm install cc-switch。

验证证据

  • 网页案例：CSDN（npm 包名混淆场景）。
  • 本市场实测：deb 包元数据 Package: cc-switch / Version: 3.20.0 / Maintainer: Jason Young（闭环日志 step 2）。

6. 卸载后共享配置不还原（~/.claude.json / ~/.codex/config.toml）

症状

卸载 cc-switch 后，之前被切换/改写的 Claude Code / Codex 供应商配置没有恢复原样。

原因

cc-switch 的功能就是改写这些共享配置文件（~/.claude.json provider 段、~/.codex/config.toml 等）；卸载只删自身（dpkg -r + ~/.cc-switch），不还原它改过的共享文件。

解法

  1. 卸载前备份：cp ~/.claude.json ~/.claude.json.bak（同理 ~/.codex/config.toml）。
  2. 卸载后按备份还原，或按 guide.md 手动把 provider 段改回。
  3. 其它工具（omc/ccr/claude-mem 等）也写这些文件时，先备份再切换。

验证证据

  • 本市场实测：字符串审计确认管理面含 ~/.claude.json / ~/.codex/config.toml / opencode.json；卸载命令 = dpkg -r + rm -rf ~/.cc-switch，不包含还原步骤（manifest uninstall.note）。

本市场实测安装面（2026-08-28）

下载与依赖层验证（隔离 HOME，GUI 无显示环境按卡判据验证到依赖层）：

# 来源: Trove 排障手册 · 验证于 2026-08-31
[step1] curl -sL cc-switch.deb（gh-proxy 加速）→ 13M，exit=0
[step2] dpkg-deb -I：Package: cc-switch / Version: 3.20.0 / amd64
        Depends: libayatana-appindicator3-1, libwebkit2gtk-4.1-0, libgtk-3-0
[step3] dpkg-deb -c：/usr/bin/cc-switch（ELF x86-64，31MB）+ icons/.desktop
[step4] dpkg -i：依赖缺失 → 配置失败（exit=1，预期：无 GUI 库环境如实记录）
[step5] dpkg -r 清理半安装状态 → 成功
[step6] verify：dpkg 未注册 + cc-switch 命令不存在 + ~/.cc-switch 已清 → 零残留
  • 完整日志：实测记录（本地留存）。
  • 结构与写面：实测记录（本地留存）（ELF 架构 + 管理面字符串审计）。
  • 连通性：实测记录（本地留存）（gh-proxy 可用；直连慢）。
  • 未能实测：GUI 运行（无显示环境）、WebDAV 同步、Windows/macOS 资产。

冲突标注

  • possible-conflict（推断态）：oh-my-claudecode / claude-code-router / claude-mem——都与 cc-switch 共享 ~/.claude.json（cc-switch 改 provider 段，对方改注册/路由段，同文件不同段，共装需注意顺序与备份）。
  • possible-compatible（推断态）：其余收录条目（cc-switch 专属写面 ~/.cc-switch/ + SQLite，无 daemon，按需启动）。
  • 注意：cc-switch × skilldock 在矩阵中为 possible-conflict（skilldock 管理各 agent 技能目录，双方同管配置文件段）。

名称混淆

  • 安装来源：本项目只有 GitHub Release 资产（deb/AppImage/rpm/win/mac），npm 上同名包是别的项目（见症状 5）。
  • 命令名 cc-switch 与包名 CC Switch 大小写：Linux 命令为小写 cc-switch，桌面入口为 "CC Switch"。

判据（验证状态）

  • 症状清单：
  • [x] libwebkit2gtk 依赖缺失（Linux 启动失败，CSDN；本市场 dpkg -i 实测复现）
  • [x] GitHub Release TLS 断连（CSDN；gh-proxy 加速实测）
  • [x] 香橙派等 ARM 架构不匹配 + GTK（CSDN；架构选择说明）
  • [x] 启动失败排查（CSDN；ldd/配置备份/终端报错）
  • [x] npm 包名混淆：cc-switch vs npm 同名包（CSDN；分发渠道澄清）
  • [x] 共享配置不还原（本市场写面审计 + manifest 卸载语义）
  • 实测步骤：

本站实测记录

  • [x] 卸载验证（dpkg -r 清理半安装状态 → dpkg 未注册 + 命令不存在 + 目录已清）
  • [x] 网络/镜像场景（gh-proxy 下载 13.5MB 实测；GitHub API 直连）
  • [x] 未能实测项：GUI 运行（WSL 无显示环境）、WebDAV 同步、win/mac 资产

验收

  • [x] 症状 → 原因 → 解法 → 验证证据 四段齐全（6 症状）
  • [x] 名称混淆已点名（npm 同名包；大小写）
  • [x] check-words HARD 0
  • [x] validate 通过
  • [x] 未碰 GitHub / 未用任何账号

矩阵暂无该工具对子。

← 返回工具货架 ｜ 遇到其它问题？去 问题空间 提交求助卡 ｜ 预检与证据记录由维护流程本地留存，仅公开结论与来源