CC Switch 排障指南供应商切换、代理服务与用量统计的 7 个常见问题【免费下载链接】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-switchCC Switch 是一款跨平台桌面工具帮你统一管理 Claude Code、Codex、Gemini CLI 等 AI 编码 CLI 的供应商切换、本地代理与用量统计。本文按使用环节梳理启动、切换、代理、数据四个阶段的高频故障每个问题都给出验证方法。读完你可以按现象对号入座逐步修复并确认修好了。快速自检你看到的现象最可能的原因对应小节点图标没反应或启动后闪退缺少 WebView2 运行时 / 文件无执行权限 / Wayland 渲染问题安装与启动界面已切换CLI 仍在用旧供应商终端会话未重新加载配置切换后不生效请求报 401、超时或连到错误地址系统环境变量覆盖了应用配置环境变量冲突代理开关卡在启动中或提示端口占用默认端口被其他程序占用代理服务启动失败主供应商挂了没有切到备用故障转移四项前提缺一项故障转移没触发打开应用像全新安装供应商全没了数据目录被删或数据库损坏配置数据丢失用量看板全是 0不更新代理未运行、日志未开启或接管未开启用量统计为空安装与启动点图标没反应或启动后闪退确认问题双击图标无任何窗口出现或窗口一闪而过。Windows 下可先按CtrlShiftEsc打开任务管理器看进程列表里有没有cc-switch相关条目有的话说明进程在跑但窗口没出来。可能原因按概率排序Windows 缺少 Microsoft Edge WebView2 运行时Tauri 应用依赖它渲染界面Linux 下 AppImage 文件没有执行权限Linux Wayland 会话 NVIDIA 显卡时强制走 XWayland 导致界面点不动、缩放后黑屏杀毒软件拦截了主程序修复步骤 Windows安装最新版 WebView2 运行时微软官网免费下载装完重试 Linux给 AppImage 加执行权限然后直接运行# Linux chmod x CC-Switch-*.AppImage ./CC-Switch-*.AppImage预期主界面正常弹出供应商卡片列表可见。 Linux Wayland NVIDIA界面点不动或黑屏时用专用环境变量切回原生 Wayland 启动# LinuxWayland NVIDIA CC_SWITCH_GDK_BACKENDwayland ./CC-Switch-*.AppImage预期窗口内容区可以正常点击、缩放不再黑屏。⚠️ 仍失败将 CC Switch 加入杀毒软件白名单macOS 版本已做签名公证若被 Gatekeeper 拦截在系统设置 → 隐私与安全性中允许打开验证主界面能打开且托盘图标出现、托盘菜单能列出各应用的当前供应商。防再犯不要从来路不明的第三方站点下载安装后留意应用内更新提示用应用内更新或官网渠道重装。供应商切换与连接切换供应商后不生效先重启你的终端确认问题CC Switch 里供应商已显示当前启用但打开终端跑claude/codex后发出的请求仍打到旧供应商的端点。这说明配置已写入只是 CLI 没重读。可能原因终端会话是在切换前打开的进程缓存了旧的配置IDE 内置终端如 VS Code没有随之重启系统环境变量覆盖了 CLI 读到的配置见下节修复步骤 关闭所有终端窗口和 IDE重新打开一个新终端再次运行 CLI 工具观察它实际连接的端点 例外Gemini 通过托盘切换可即时生效无需重启终端。验证新终端里发起一次请求回看 CC Switch「设置 → 用量」的请求日志供应商一列应显示你刚切换的那家。防再犯养成切换后开新终端再干活的习惯多个终端窗口并存时旧窗口里的 CLI 一律当作旧配置。连接报错或连错地址先查环境变量冲突确认问题请求返回 401、连接超时或明明换了供应商日志里端点却还是旧地址。打开 CC Switch 主界面顶部若出现黄色检测到环境变量冲突横幅点「展开」即可看到冲突的变量名、当前值和来源。可能原因shell 配置文件~/.zshrc、~/.bashrc里export过ANTHROPIC_API_KEY、ANTHROPIC_BASE_URL之类的变量环境变量优先级高于配置文件会把 CC Switch 写的配置盖掉Windows 用户级/系统级环境变量残留了旧 KeyAPI Key 本身复制时带了空格或已过期修复步骤 最省事在冲突横幅里勾选要删的变量点「删除选中」。CC Switch 会先自动备份到~/.cc-switch/env-backups/再删除误删可从备份恢复手动处理macOS/Linux编辑~/.zshrc或~/.bashrc删掉相关export语句然后# macOS/Linux source ~/.zshrc这一步让当前终端立即按新配置生效。⚠️ 不想用界面删除Windows 可去系统属性 → 高级 → 环境变量里手动移除最后核对供应商编辑页里的 Key重新粘贴一遍确认首尾没有多余空格验证横幅消失后发起一次请求在用量请求日志中确认端点与 Key 对应的供应商一致、状态为成功。防再犯把 Key 交给 CC Switch 管理不再往系统环境变量里放 API 密钥。代理服务与故障转移代理服务启动失败或提示端口被占用确认问题点主界面顶部的代理开关后状态一直不变绿或报错Address already in use。代理是本地起的一个 HTTP 服务负责转发请求、记日志、做故障转移它起不来后面的用量统计和自动切换都不工作。可能原因默认监听端口被其他程序占用上次代理异常退出端口未释放防火墙拦截了本机回环连接修复步骤 先在面板确认实际使用的端口打开「设置 → 高级 → 代理服务」记下监听端口检查该端口占用情况# macOS/Linux端口换成面板实际值 lsof -i :15721预期输出占用该端口的进程名和 PID无输出说明端口空闲。:: Windows端口换成面板实际值 netstat -ano | findstr :15721预期输出最后一列是占用进程的 PID。关闭占用进程后重启代理⚠️ 若要改端口必须先停止代理改完再启动改端口后 CLI 侧配置会自动跟随无需手改验证开关变为绿色面板显示http://127.0.0.1:端口的服务地址和运行时间开始累计。防再犯避免把代理端口段留给其他本地服务每次修改监听地址/端口前先停代理再改。故障转移没有触发按四个前提逐项核对确认问题主供应商连续失败请求直接报错没有切到备用。故障转移要生效四个条件缺一不可代理运行中、应用接管开启、队列里有备用供应商、自动故障转移开关打开。可能原因自动故障转移开关没开——默认关闭时只记录失败、不切换队列里没有加任何备用供应商应用接管没开请求根本没走代理自然轮不到切换所有供应商都已进入熔断状态连续失败达到阈值后被暂时拉黑请求全部被跳过修复步骤 打开「设置 → 高级 → 故障转移」确认对应应用 Tab 下自动故障转移已开启在「故障转移队列」里点「添加供应商」把备用供应商拖到主供应商之后回到主界面确认代理开关为绿色、接管开关已开启⚠️ 若怀疑全部熔断熔断器默认 60 秒后自动尝试恢复等一分钟左右或重启代理服务直接重置状态验证手动把主供应商的 Key 改成错误值或临时断网发一个请求观察面板队列里当前使用标记是否自动跳到下一家。防再犯定期把主供应商状态设为不健康做一次演练若发现频繁切换检查主供应商本身是否不稳定而不是调低失败阈值。数据与用量统计配置数据丢失从哪里恢复确认问题打开应用后供应商、MCP、提示词全没了回到欢迎界面。CC Switch 的所有数据默认存在用户主目录下的.cc-switch文件夹Windows 为C:\Users\用户名\.cc-switch。可能原因数据目录被误删或同步工具覆盖SQLite 数据库文件损坏多设备同步冲突写坏数据修复步骤 先看自动备份每次导入配置前 CC Switch 都会自动备份最多保留最近 10 份文件名带时间戳# macOS/Linux ls -la ~/.cc-switch/backups/预期输出若干带时间戳的备份文件Windows 用文件管理器打开C:\Users\用户名\.cc-switch\backups\查看。有备份在「设置 → 高级 → 数据管理」里选择最近的备份恢复没有备份但之前导出过用导出文件走「导入」流程还原⚠️ 都不行手动编辑settings.json等零散文件无法恢复供应商只能重新添加验证恢复后供应商卡片列表完整点开一个供应商API Key 和端点都在。防再犯定期在「设置 → 高级 → 数据管理」点「导出」把包含供应商和 Key 的导出文件放到网盘或加密存储每季度做一次。用量统计为空逐项核对数据来源确认问题「设置 → 用量」页面请求数为 0或用了很久也不变。CC Switch 的用量有两个来源代理请求日志必须走代理和 CLI 会话日志v3.13 起可直接读取不依赖代理。可能原因代理没运行、应用接管没开、启用日志开关关闭代理侧数据一条都进不来时间范围选的是今日而你的请求发生在昨天会话日志导入要求对应应用已在 CC Switch 中启用且 CLI 有历史会话文件修复步骤 按顺序打开三个开关代理运行主界面变绿→ 应用接管 → 代理面板里的「启用日志」切换时间范围到最近 7 天看是否有历史数据确认 Claude / Codex / Gemini 对应应用已启用并至少跑过一次会话⚠️ 若数字与旧版对不上v3.15.0 起 Token 做了缓存归一化新口径下数值与旧估算不完全一致以当前显示为准验证发一条真实请求后刷新用量页请求总数 1趋势图出现新数据点。防再犯把代理开关为绿作为每日开工前的固定检查项需要精确账单时认准筛选后的 Hero 卡数字。收尾排查清单按顺序勾选可覆盖绝大多数场景应用能正常启动托盘图标可见顶部没有黄色环境变量冲突横幅有则先处理切换供应商后开的是新终端代理开关为绿色端口没有被其他程序占用应用接管与日志记录均已开启故障转移队列里有备用供应商且自动故障转移已开启~/.cc-switch/目录存在backups/里有近期备份用量页时间范围选择正确仍无法解决时到项目仓库的 Issue 区先搜同类问题没有再新建附上操作系统与版本、CC Switch 版本、复现步骤和错误信息并按问题类型带日志普通错误带~/.cc-switch/logs/下的cc-switch.log及轮转文件崩溃带crash.logWindows 路径为C:\Users\用户名\.cc-switch\...。提交前扫一眼日志避免泄露环境中的敏感信息。资源区用户手册目录docs/user-manual/其中 FAQ 覆盖安装、供应商、代理与数据问题更新日志CHANGELOG.md项目说明README_ZH.md【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 CC Switch 排障指南：供应商切换、代理服务与用量统计的 7 个常见问题
CC Switch 排障指南供应商切换、代理服务与用量统计的 7 个常见问题【免费下载链接】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-switchCC Switch 是一款跨平台桌面工具帮你统一管理 Claude Code、Codex、Gemini CLI 等 AI 编码 CLI 的供应商切换、本地代理与用量统计。本文按使用环节梳理启动、切换、代理、数据四个阶段的高频故障每个问题都给出验证方法。读完你可以按现象对号入座逐步修复并确认修好了。快速自检你看到的现象最可能的原因对应小节点图标没反应或启动后闪退缺少 WebView2 运行时 / 文件无执行权限 / Wayland 渲染问题安装与启动界面已切换CLI 仍在用旧供应商终端会话未重新加载配置切换后不生效请求报 401、超时或连到错误地址系统环境变量覆盖了应用配置环境变量冲突代理开关卡在启动中或提示端口占用默认端口被其他程序占用代理服务启动失败主供应商挂了没有切到备用故障转移四项前提缺一项故障转移没触发打开应用像全新安装供应商全没了数据目录被删或数据库损坏配置数据丢失用量看板全是 0不更新代理未运行、日志未开启或接管未开启用量统计为空安装与启动点图标没反应或启动后闪退确认问题双击图标无任何窗口出现或窗口一闪而过。Windows 下可先按CtrlShiftEsc打开任务管理器看进程列表里有没有cc-switch相关条目有的话说明进程在跑但窗口没出来。可能原因按概率排序Windows 缺少 Microsoft Edge WebView2 运行时Tauri 应用依赖它渲染界面Linux 下 AppImage 文件没有执行权限Linux Wayland 会话 NVIDIA 显卡时强制走 XWayland 导致界面点不动、缩放后黑屏杀毒软件拦截了主程序修复步骤 Windows安装最新版 WebView2 运行时微软官网免费下载装完重试 Linux给 AppImage 加执行权限然后直接运行# Linux chmod x CC-Switch-*.AppImage ./CC-Switch-*.AppImage预期主界面正常弹出供应商卡片列表可见。 Linux Wayland NVIDIA界面点不动或黑屏时用专用环境变量切回原生 Wayland 启动# LinuxWayland NVIDIA CC_SWITCH_GDK_BACKENDwayland ./CC-Switch-*.AppImage预期窗口内容区可以正常点击、缩放不再黑屏。⚠️ 仍失败将 CC Switch 加入杀毒软件白名单macOS 版本已做签名公证若被 Gatekeeper 拦截在系统设置 → 隐私与安全性中允许打开验证主界面能打开且托盘图标出现、托盘菜单能列出各应用的当前供应商。防再犯不要从来路不明的第三方站点下载安装后留意应用内更新提示用应用内更新或官网渠道重装。供应商切换与连接切换供应商后不生效先重启你的终端确认问题CC Switch 里供应商已显示当前启用但打开终端跑claude/codex后发出的请求仍打到旧供应商的端点。这说明配置已写入只是 CLI 没重读。可能原因终端会话是在切换前打开的进程缓存了旧的配置IDE 内置终端如 VS Code没有随之重启系统环境变量覆盖了 CLI 读到的配置见下节修复步骤 关闭所有终端窗口和 IDE重新打开一个新终端再次运行 CLI 工具观察它实际连接的端点 例外Gemini 通过托盘切换可即时生效无需重启终端。验证新终端里发起一次请求回看 CC Switch「设置 → 用量」的请求日志供应商一列应显示你刚切换的那家。防再犯养成切换后开新终端再干活的习惯多个终端窗口并存时旧窗口里的 CLI 一律当作旧配置。连接报错或连错地址先查环境变量冲突确认问题请求返回 401、连接超时或明明换了供应商日志里端点却还是旧地址。打开 CC Switch 主界面顶部若出现黄色检测到环境变量冲突横幅点「展开」即可看到冲突的变量名、当前值和来源。可能原因shell 配置文件~/.zshrc、~/.bashrc里export过ANTHROPIC_API_KEY、ANTHROPIC_BASE_URL之类的变量环境变量优先级高于配置文件会把 CC Switch 写的配置盖掉Windows 用户级/系统级环境变量残留了旧 KeyAPI Key 本身复制时带了空格或已过期修复步骤 最省事在冲突横幅里勾选要删的变量点「删除选中」。CC Switch 会先自动备份到~/.cc-switch/env-backups/再删除误删可从备份恢复手动处理macOS/Linux编辑~/.zshrc或~/.bashrc删掉相关export语句然后# macOS/Linux source ~/.zshrc这一步让当前终端立即按新配置生效。⚠️ 不想用界面删除Windows 可去系统属性 → 高级 → 环境变量里手动移除最后核对供应商编辑页里的 Key重新粘贴一遍确认首尾没有多余空格验证横幅消失后发起一次请求在用量请求日志中确认端点与 Key 对应的供应商一致、状态为成功。防再犯把 Key 交给 CC Switch 管理不再往系统环境变量里放 API 密钥。代理服务与故障转移代理服务启动失败或提示端口被占用确认问题点主界面顶部的代理开关后状态一直不变绿或报错Address already in use。代理是本地起的一个 HTTP 服务负责转发请求、记日志、做故障转移它起不来后面的用量统计和自动切换都不工作。可能原因默认监听端口被其他程序占用上次代理异常退出端口未释放防火墙拦截了本机回环连接修复步骤 先在面板确认实际使用的端口打开「设置 → 高级 → 代理服务」记下监听端口检查该端口占用情况# macOS/Linux端口换成面板实际值 lsof -i :15721预期输出占用该端口的进程名和 PID无输出说明端口空闲。:: Windows端口换成面板实际值 netstat -ano | findstr :15721预期输出最后一列是占用进程的 PID。关闭占用进程后重启代理⚠️ 若要改端口必须先停止代理改完再启动改端口后 CLI 侧配置会自动跟随无需手改验证开关变为绿色面板显示http://127.0.0.1:端口的服务地址和运行时间开始累计。防再犯避免把代理端口段留给其他本地服务每次修改监听地址/端口前先停代理再改。故障转移没有触发按四个前提逐项核对确认问题主供应商连续失败请求直接报错没有切到备用。故障转移要生效四个条件缺一不可代理运行中、应用接管开启、队列里有备用供应商、自动故障转移开关打开。可能原因自动故障转移开关没开——默认关闭时只记录失败、不切换队列里没有加任何备用供应商应用接管没开请求根本没走代理自然轮不到切换所有供应商都已进入熔断状态连续失败达到阈值后被暂时拉黑请求全部被跳过修复步骤 打开「设置 → 高级 → 故障转移」确认对应应用 Tab 下自动故障转移已开启在「故障转移队列」里点「添加供应商」把备用供应商拖到主供应商之后回到主界面确认代理开关为绿色、接管开关已开启⚠️ 若怀疑全部熔断熔断器默认 60 秒后自动尝试恢复等一分钟左右或重启代理服务直接重置状态验证手动把主供应商的 Key 改成错误值或临时断网发一个请求观察面板队列里当前使用标记是否自动跳到下一家。防再犯定期把主供应商状态设为不健康做一次演练若发现频繁切换检查主供应商本身是否不稳定而不是调低失败阈值。数据与用量统计配置数据丢失从哪里恢复确认问题打开应用后供应商、MCP、提示词全没了回到欢迎界面。CC Switch 的所有数据默认存在用户主目录下的.cc-switch文件夹Windows 为C:\Users\用户名\.cc-switch。可能原因数据目录被误删或同步工具覆盖SQLite 数据库文件损坏多设备同步冲突写坏数据修复步骤 先看自动备份每次导入配置前 CC Switch 都会自动备份最多保留最近 10 份文件名带时间戳# macOS/Linux ls -la ~/.cc-switch/backups/预期输出若干带时间戳的备份文件Windows 用文件管理器打开C:\Users\用户名\.cc-switch\backups\查看。有备份在「设置 → 高级 → 数据管理」里选择最近的备份恢复没有备份但之前导出过用导出文件走「导入」流程还原⚠️ 都不行手动编辑settings.json等零散文件无法恢复供应商只能重新添加验证恢复后供应商卡片列表完整点开一个供应商API Key 和端点都在。防再犯定期在「设置 → 高级 → 数据管理」点「导出」把包含供应商和 Key 的导出文件放到网盘或加密存储每季度做一次。用量统计为空逐项核对数据来源确认问题「设置 → 用量」页面请求数为 0或用了很久也不变。CC Switch 的用量有两个来源代理请求日志必须走代理和 CLI 会话日志v3.13 起可直接读取不依赖代理。可能原因代理没运行、应用接管没开、启用日志开关关闭代理侧数据一条都进不来时间范围选的是今日而你的请求发生在昨天会话日志导入要求对应应用已在 CC Switch 中启用且 CLI 有历史会话文件修复步骤 按顺序打开三个开关代理运行主界面变绿→ 应用接管 → 代理面板里的「启用日志」切换时间范围到最近 7 天看是否有历史数据确认 Claude / Codex / Gemini 对应应用已启用并至少跑过一次会话⚠️ 若数字与旧版对不上v3.15.0 起 Token 做了缓存归一化新口径下数值与旧估算不完全一致以当前显示为准验证发一条真实请求后刷新用量页请求总数 1趋势图出现新数据点。防再犯把代理开关为绿作为每日开工前的固定检查项需要精确账单时认准筛选后的 Hero 卡数字。收尾排查清单按顺序勾选可覆盖绝大多数场景应用能正常启动托盘图标可见顶部没有黄色环境变量冲突横幅有则先处理切换供应商后开的是新终端代理开关为绿色端口没有被其他程序占用应用接管与日志记录均已开启故障转移队列里有备用供应商且自动故障转移已开启~/.cc-switch/目录存在backups/里有近期备份用量页时间范围选择正确仍无法解决时到项目仓库的 Issue 区先搜同类问题没有再新建附上操作系统与版本、CC Switch 版本、复现步骤和错误信息并按问题类型带日志普通错误带~/.cc-switch/logs/下的cc-switch.log及轮转文件崩溃带crash.logWindows 路径为C:\Users\用户名\.cc-switch\...。提交前扫一眼日志避免泄露环境中的敏感信息。资源区用户手册目录docs/user-manual/其中 FAQ 覆盖安装、供应商、代理与数据问题更新日志CHANGELOG.md项目说明README_ZH.md【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考