公司动态

CC Switch 故障排除指南:启动失败、代理端口 15721 与配置数据恢复如何快速修复

📅 2026/8/28 11:45:44
CC Switch 故障排除指南:启动失败、代理端口 15721 与配置数据恢复如何快速修复
CC Switch 故障排除指南启动失败、代理端口 15721 与配置数据恢复如何快速修复【免费下载链接】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 服务供应商并内置本地代理、故障转移和用量统计。本文覆盖它最常见的四类故障启动失败、供应商切换不生效、本地代理起不来、配置数据丢失按先定位、后动手的顺序给出排查命令和修复步骤照着做即可恢复。症状速查表典型症状最可能原因紧急程度跳转章节双击图标无反应、启动即崩溃系统依赖缺失或上次运行崩溃高应用启动失败启动提示检测到旧版 v1 配置格式config.json 停留在旧版结构高配置格式报错供应商列表突然为空、设置回到初始配置文件丢失或损坏高供应商列表消失代理开关转不上去、报启动失败默认端口 15721 被占用中端口占用界面显示已切换CLI 仍走旧供应商终端/IDE 进程还持有旧配置中切换不生效主供应商挂了没有自动换备用故障转移未启用或阈值未触发中故障转移不工作用量统计不更新、成本对不上代理未运行或定价表过期低用量统计异常先分层再排查故障只会出现在某一层。按下面 4 步走每步只做一条验证通过就往下走不通过就跳到对应章节环境层应用能打开吗打开 CC Switch确认主界面能显示供应商列表。通过 → 进入第 2 步。不通过 → 跳 应用启动失败。配置层配置目录完整吗检查配置目录里的文件和 config.json 是否为合法 JSON# macOS/Linux ls -la ~/.cc-switch/ jq . ~/.cc-switch/config.json # Windows目录在 %APPDATA%\com.ccswitch.desktop如改过目录以 设置 → 目录设置 显示为准 dir %APPDATA%\com.ccswitch.desktop能看到config.json、cc-switch.db且jq输出正常 → 进入第 3 步。文件缺失或jq报错 → 跳 供应商列表消失。服务层本地代理活着吗在应用里打开代理页确认状态后另开终端访问健康检查接口curl http://127.0.0.1:15721/health返回 JSON 状态 → 进入第 4 步。连接被拒绝或无响应 → 跳 代理端口 15721 被占用。网络层请求真的走代理、真的到上游吗用 CLI 发一次真实请求如claude里问一句hi然后看应用用量页是否新增一条请求记录。有记录 → 问题已解决。无记录或报错 → 跳 切换供应商后 CLI 仍走旧供应商。供应商管理主界面点击供应商卡片完成切换这里是排查切换不生效的起点启动失败、配置格式报错与供应商列表消失三条恢复路径应用启动失败启动后白屏何时出现双击图标后窗口不出现或窗口一闪即退托盘里也没有图标。怎么确认查看崩溃日志是否存在说明上次运行确实挂过# macOS/Linux tail -n 50 ~/.cc-switch/crash.log # Windows目录按实际安装位置 type %APPDATA%\com.ccswitch.desktop\crash.log | more30 秒自救完全退出应用托盘右键退出再重新启动一次。多数偶发崩溃到此即恢复。10 分钟修复检查安全软件/杀毒软件是否拦截了 cc-switch 主程序将其加入白名单。若最近做过自动更新后开始崩溃在 设置 页关闭自动更新从官网下载上一个稳定版本覆盖安装。仍无效时保留crash.log并重装先通过系统设置 → 应用卸载再重新安装。验收标准重新打开后主界面能显示供应商列表且crash.log不再增长。配置格式报错旧版 v1 结构何时出现从很旧的版本升级上来后启动时弹窗提示检测到旧版 v1 配置格式。怎么确认打开~/.cc-switch/config.json看顶层是否有version: 2以及claude、codex、mcp等字段如果没有说明还是旧结构。30 秒自救如果弹出了迁移提示先备份config.json复制一份改名.bak再点弹窗里的确认让新版本处理一次迁移。10 分钟修复按弹窗指引把顶层结构调整为带version: 2的新格式弹窗内已给出字段示例改完前务必先复制一份原文件。改完关闭应用再重开。验收标准重启后不再弹出格式提示供应商列表与切换功能正常。供应商列表消失从备份恢复配置何时出现打开应用后供应商全部没了或提示配置文件损坏。怎么确认确认~/.cc-switch/下cc-switch.db和config.json是否存在、是否为 0 字节再看设置 → 导入/导出页的备份列表里有没有可用条目。30 秒自救在 设置 → 导入/导出 的备份列表中点最新的备份条目选择恢复然后重启应用。10 分钟修复备份列表为空时把备份文件手动放回配置目录的backups/子目录后重试恢复。连备份也没有时用 导入/导出 页的导入功能选择以前导出过的 JSON 备份文件。完全无备份时按当前版本默认配置重建重新添加供应商可参考 用户手册 的供应商章节。验收标准恢复后供应商卡片全部显示随机切一个供应商CLI 发请求能通。⚠️避坑提醒改config.json前永远先复制一份手改 JSON 缺一个逗号都会导致整个配置不可读。不要同时开两个实例写同一份配置目录会造成数据库文件损坏。本地代理起不来三条命令确认端口 15721 被谁占用代理端口 15721 被占用何时出现代理开关点下去后停在启动中或直接报启动失败。怎么确认默认监听端口是 15721查它被谁占着# macOS/Linux lsof -i :15721 # Windows netstat -ano | findstr :1572130 秒自救把占用的进程停掉或关掉那个软件再点一次启动代理。10 分钟修复占用者是必须保留的服务时到 代理 页把监听端口改成别的值该页有端口输入框默认 15721。保存后重新启动代理并检查各 CLI 工具里的代理地址是否指向新端口。若防火墙拦截将 cc-switch 主程序加入本地防火墙白名单后重试。代理设置界面端口、日志开关与启停状态都在这页操作验收标准curl http://127.0.0.1:15721/health能返回 JSON代理状态变为运行中。切换供应商后 CLI 仍走旧供应商何时出现界面上已点选新供应商但终端里 CLI 返回的内容、报错风格还是旧供应商的。怎么确认看代理页的当前目标active target是否已变成新供应商同时确认旧终端会话是什么时候打开的。30 秒自救关闭所有已打开的终端窗口和 IDE重新打开再试。CLI 进程启动时读取代理与供应商配置旧进程不会热更新。10 分钟修复新终端仍走旧供应商时检查该 CLI 是否被环境变量单独指到了别的地址如ANTHROPIC_BASE_URL、OPENAI_BASE_URL之类有的话临时unset掉再测。确认应用内该应用类型下的代理开关是打开状态且地址端口与 CLI 侧一致。仍无效时删除该 CLI 自身的配置缓存目录后重登一次。本地路由设置确认 CLI 流量确实经由 CC Switch 本地代理转发验收标准新终端发起请求后用量页立即新增一条记录且记录里的供应商名称就是刚切的那个。故障转移不触发自动切换何时出现主供应商 API 挂掉请求直接报错没有按队列切到备用供应商。怎么确认打开 代理 页的自动故障转移面板看开关是否启用、故障转移队列里是否真的排了备用供应商、连续失败阈值是多少。30 秒自救确认自动故障转移开关已打开主供应商不可用时先手动切到队列里的备用供应商顶上。10 分钟修复队列是空的在故障转移面板里把备用供应商加进队列并调整优先级。阈值过高导致还没触发把连续失败次数调小如 3 次熔断恢复间隔也同步调小。切换后一直回不去主供应商检查熔断器的恢复探测间隔主供应商恢复后需要等一次探测成功才会切回。验收标准手动断开主供应商网络后发请求能在阈值次数内自动落到备用供应商用量页里可见目标供应商变化。⚠️避坑提醒改了端口所有指向代理的 CLI 和 IDE 都要同步改漏改一个就出现半通半不通。故障转移只统计经过本地代理的请求CLI 直连官方 API没走代理时故障转移感知不到失败。阈值设太小会抖动供应商一次网络抖动就切走反复来回反而更糟。用量统计不更新与故障链路核对服务层最后一段用量统计不更新何时出现明明用了一下午用量页的 Token 数和成本纹丝不动。怎么确认统计依赖本地代理记录请求先确认代理在跑curl http://127.0.0.1:15721/health再看 代理 页的日志开关是否打开。30 秒自救打开代理日志开关重启代理再发一次请求看记录是否出现。10 分钟修复记录出现了但成本为 0到 用量/定价 配置页核对所用模型的单价或触发一次从模型目录同步定价models.dev 自动同步拉取最新价格表。供应商是私有网关、价格目录里没有的在定价配置里手动补一条该模型的输入/输出单价。完全没记录回到 切换供应商后 CLI 仍走旧供应商 一节排查流量是否真的走了代理。验收标准发一次请求后用量仪表盘新增一条记录且 Token 数、成本与本次请求量级相符。请求日志里有错但没有提示何时出现CLI 报 401/403/429 一类错误分不清是供应商凭证问题还是代理转发问题。怎么确认打开用量页的请求日志表找到对应那一条看上游返回的状态码401/403 基本是 API Key 问题429 是限流5xx 才是供应商侧故障。30 秒自救是 401/403 就回到该供应商卡片里重新粘贴一次 API Key 并保存重发请求。10 分钟修复Key 确认没过期仍 401用同一条 Key 直接curl上游地址验证绕过本代理能通说明代理侧改写了鉴权头检查供应商配置里的 Base URL 和鉴权字段。429 持续出现调低该应用的并发或把该供应商挪到故障转移队列后位。5xx 且上游直连也 5xx供应商侧故障等恢复或切备用。验收标准修复后新请求在日志表里状态码为 200且 CLI 端正常返回内容。⚠️避坑提醒别把用量页没数字直接当成统计功能坏了——九成是流量没走代理。日志开关开着会记录请求体里面可能含敏感信息截图分享前注意打码。故障分诊决策树应用能启动吗不能 → 应用启动失败能 → 第 2 步。供应商列表完整吗不完整 → 供应商列表消失 或 配置格式报错完整 → 第 3 步。代理是运行中状态吗curl http://127.0.0.1:15721/health有返回不是 → 代理端口 15721 被占用是 → 第 4 步。CLI 新请求在用量页有记录吗没有 → 切换供应商后 CLI 仍走旧供应商有 → 第 5 步。主供应商挂了会自动切备用吗不会 → 故障转移不触发自动切换。数字还对得上吗用量/成本异常 → 用量统计不更新 和 请求日志里有错但没有提示。资源与支持完整用户手册docs/user-manual/分入门、供应商、扩展、代理、FAQ 五部分。各版本改动与修复记录CHANGELOG.md。遇到问题先在 设置 页导出配置备份再带上crash.log如有、代理端口、故障时的状态码截图到仓库 Issue 区提问。需要最新源码或参与开发时git clone https://gitcode.com/GitHub_Trending/cc/cc-switch【免费下载链接】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),仅供参考