5.2 常见问题 FAQ¶
安装问题¶
macOS 安装¶
CC Switch macOS 版本已通过 Apple 代码签名和公证,可直接下载安装,无需额外操作。如遇问题,请尝试从 Releases 页面 下载最新版本。
Windows 安装后无法启动¶
可能原因:
- 缺少 WebView2 运行时
- 杀毒软件拦截
解决方法:
- 安装 Microsoft Edge WebView2
- 将 CC Switch 添加到杀毒软件白名单
Linux 启动报错¶
问题:AppImage 无法启动
解决方法:
- 添加执行权限:
- 确认系统满足要求:glibc 2.35+ 和 WebKitGTK 4.1(如 Ubuntu 22.04+、Debian 12+)。提示
GLIBC_2.xx not found说明系统版本过旧;RHEL / Rocky / Alma 8–9 暂不支持 - 如果报 FUSE 相关错误,安装发行版的 FUSE 2 兼容库(如 Ubuntu 的
libfuse2),或改用.deb/.rpm安装包
详见 1.2 安装指南 → Linux。
Linux 点击无响应 / 缩放后黑屏(Wayland + NVIDIA)¶
问题:主界面网页内容区完全点不动(标题栏的最小化/最大化/关闭仍可点),窗口缩放或最大化-还原后黑屏。常见于 Wayland 会话 + NVIDIA 显卡。
原因:AppImage 的 GTK 启动钩子会无条件强制 GDK_BACKEND=x11(走 XWayland)以规避历史上的原生 Wayland 崩溃;但在较新的 Wayland + NVIDIA 环境下,强制 XWayland 反而使 WebKitGTK 的网页内容收不到指针事件。现有的 WEBKIT_DISABLE_* 缓解措施对此无效,因为根因是被强制的窗口后端,而非渲染。
解决方法:用专用环境变量 CC_SWITCH_GDK_BACKEND 切回原生 Wayland(该开关在 GTK 初始化前生效,钩子不会覆盖它):
- 从桌面图标启动时,把它写进
.desktop的Exec=行(如env CC_SWITCH_GDK_BACKEND=wayland /path/to/AppImage),或在会话环境中设置,否则图标启动读不到该变量。 - 该变量是通用的:在 tiling Wayland 合成器(sway/Hyprland)下若反而出现点击失效,可设
CC_SWITCH_GDK_BACKEND=x11。 - 不设置时行为与现状完全一致(仍走 x11),无副作用。
供应商问题¶
切换供应商后不生效¶
原因:CLI 工具需要重新加载配置
解决方法:
- Claude Code:支持热切换,通常无需重启;如果没生效,关闭并重新打开终端,或重启 IDE
- Codex、Gemini CLI、Grok Build:关闭并重新打开终端或 CLI 工具(切换成功后会有提示)
- Claude Desktop:完全退出并重新打开 Claude Desktop;使用「模型映射」时还要保持 CC Switch 运行
- 累加式应用(OpenCode、OpenClaw、Hermes、Pi、MiniMax Code):确认已点击「添加」(Pi 为「启用」),并在工具里选择了对应的模型
路由模式下,请求会立即转发到新供应商;但如果切换改变了模型,Codex、Gemini CLI、Grok Build 仍可能需要重启。聚合模式下,Claude Code 立即生效;Codex 进入或退出聚合、改动聚合模型列表后要彻底重启,见下一条。详见 4.2 应用路由。
Codex 聚合模式下,/model 里看不到聚合的模型¶
Codex 只在启动时读取模型列表。进入或退出聚合模式、添加或移除聚合的供应商、改动某家的聚合模型之后,都要彻底重启 Codex:
- Codex CLI:只关掉终端重开
codex不够,所有终端里的codex共用一个后台守护进程。CC Switch 检测到 Codex 还在用旧列表时,会在 Codex 页面顶部提示,点提示里的「重启 Codex 守护进程」即可(会中断守护进程里正在运行的任务)。 - Codex 桌面版:彻底退出后重新打开(macOS 上按 ⌘Q,只关窗口不行)。
- 编辑器插件:重开编辑器窗口。
通过 GitHub Copilot 使用 Codex 时,回复为什么会显示两遍¶
部分 Copilot 原生 Responses 流会在同一输出条目的开始和完成事件中返回不同的消息 ID。Codex 因而可能把已流式显示的正文和完成消息当成两条回复,而不是模型实际生成了两份内容。
CC Switch 会在 Codex 的托管 Copilot Responses 路径中,按输出索引统一后续事件的 ID,保留最初由上游签发、可用于历史回放的 ID;文本仍实时输出,工具的 call_id 不变。使用包含此修复的版本并重新启动 CC Switch 后,无需为此问题切换到 Chat Completions,也无需修改 Codex 的 wire_api。
切换供应商会改掉我的插件、Hook 等设置吗¶
不会。Claude Code、Codex、Gemini CLI、Grok Build 切换供应商时,CC Switch 只替换配置文件里的关键字段(请求地址、Key、模型名、接口协议等),插件、Hook、权限、MCP、你自己加的环境变量、注释和排版都原样保留。具体改哪些键见 5.1 配置文件说明。
在工具里换了模型,切走再切回来怎么又变回去了¶
模型属于关键字段,归供应商所有。在工具里换的模型(如 Claude Code 的 /model)会一直生效到下次切换;切换时会换成目标供应商保存的那个,CC Switch 不会把你在工具里换的模型存回原来的供应商。想长期使用某个模型,请在 CC Switch 里编辑这个供应商。
为什么正在使用的供应商删不掉¶
Claude Code、Claude Desktop、Codex、Gemini CLI、Grok Build 同一时间只启用一个供应商,总会保留一个正在使用的配置,否则该应用将无法正常使用。想删它,先切换到别家。聚合模式下的默认供应商同样不能移除,先把别家设为默认。累加式应用没有这个限制。
在 Claude Code 里使用 OpenAI 兼容接口、Gemini 或本地模型¶
需要使用路由。编辑供应商时,在「高级选项」的「上游格式」里选择和供应商一致的接口格式:只提供 Chat Completions 接口的服务选「OpenAI Chat Completions」,提供 Responses 接口的选「OpenAI Responses API」,Gemini 选「Gemini Native generateContent」。然后在 Claude Code 页面的「路由」标签里点「开始路由」。格式选错或没有开始路由,通常会报 404 或 405 错误。
API Key 无效¶
检查步骤:
- 确认 API Key 正确复制(无多余空格)
- 确认 API Key 未过期
- 确认端点地址正确
- 使用「检测连通」确认地址可达(注意:连通检测不验证 Key)
如何恢复官方登录¶
操作步骤:
- 在供应商列表中找到自带的官方供应商(如 Claude Official、OpenAI Official、Google Official、Grok Official;删掉了可以从预设里重新添加)
- 点击「启用」(路由模式下不能切到官方供应商,先点「回到直连」;Codex 的 OpenAI Official 卡片除外)
- 重启对应的 CLI 工具
- 按照 CLI 工具的登录流程操作
路由与聚合问题¶
本地路由启动失败¶
可能原因:端口被占用
解决方法:
- 检查端口占用(默认端口 15721):
- 关闭占用端口的程序
- 或在「设置 → 本地路由 → 服务」中先停止路由服务(还有应用在用路由时,先让它们回到直连),在「监听端口」里改用其他端口(1024–65535),点击「保存并重启服务」
开始路由后,配置文件里的地址为什么变成了 127.0.0.1¶
路由和聚合模式下,工具的请求先发到 CC Switch 的本地路由(默认 http://127.0.0.1:15721),再转发给你选中的供应商,所以工具的配置文件里只有本地地址和占位密钥 PROXY_MANAGED;Claude Code 的模型名还会写成 claude-sonnet-5 之类的固定别名(/model 菜单里仍显示真实模型名)。真实的供应商地址、Key 和模型都保存在 CC Switch 里。路由和聚合需要 CC Switch 保持运行;退出 CC Switch 时会自动写回直连,下次启动再接上。
开启本地路由后请求超时¶
可能原因:
- 网络问题
- 供应商服务器问题
- 本地路由配置错误
解决方法:
- 检查网络连接
- 尝试直接访问供应商 API(关闭本地路由)
- 检查供应商配置是否正确
回到直连后配置未恢复¶
可能原因:CC Switch 异常退出
解决方法:
- 重新打开 CC Switch,它启动时会按本机状态恢复各工具的配置
- 或在对应应用页点「回到直连」;在「设置 → 本地路由」里点「全部回到直连」可一次处理所有应用
- 仍不对,检查当前供应商的端点地址是否正确;也可以从
~/.cc-switch/backups/live-first-write/找回 CC Switch 第一次改写前的原配置文件
故障转移问题¶
故障转移没有触发¶
检查清单:
- [ ] 对应应用是否在路由模式(聚合模式不做故障转移)
- [ ] 本地路由服务是否运行
- [ ] 该应用页「路由」页签里的自动故障转移是否开启
- [ ] 队列中是否有备用供应商
频繁触发故障转移¶
可能原因:
- 主供应商不稳定
- 熔断器阈值设置过低
解决方法:
- 检查主供应商状态
- 调高失败阈值(如从 3 改为 5)
- 考虑更换主供应商
所有供应商都熔断了¶
解决方法:
- 等待熔断时长到期(默认 60 秒)
- 或在「设置 → 本地路由 → 服务」中停止后重新启动路由服务,重置状态
数据问题¶
配置丢失¶
可能原因:
- 配置目录被删除
- 数据库损坏
解决方法:
- 检查
~/.cc-switch/目录是否存在(如果在「设置 → 数据 → 存储位置」里改过配置目录,以改后的目录为准) - 从备份恢复:「设置 → 数据 → 备份与恢复」(备份文件在
~/.cc-switch/backups/) - 或从之前导出的配置文件导入
导入配置失败¶
可能原因:
- 文件格式错误
- 版本不兼容
解决方法:
- 确认文件是 CC Switch 导出的 SQL 备份文件
- 检查文件内容是否完整
- 尝试用文本编辑器打开检查格式
用量统计数据为空¶
检查清单:
- [ ] 「自动扫描会话记录」是否开启,对应 CLI 是否有会话历史(不开本地路由时的数据来源)
- [ ] 如果依赖路由请求日志:本地路由是否运行、对应应用是否在路由或聚合模式、「设置 → 本地路由 → 服务」里的「记录请求用量」是否开启
- [ ] 该应用是否支持用量统计(OpenClaw、Hermes 暂不支持)
配额与余额¶
为什么有的供应商自动显示配额,有的需要手动启用?¶
只有 OAuth 账号类供应商(GitHub Copilot、Codex OAuth 反向代理、xAI OAuth)会在启用后自动显示配额。其他所有供应商(包括 Claude / Codex / Gemini / Grok Build 官方供应商的订阅额度、Token Plan 和第三方余额查询)都需要手动到供应商卡片的「用量查询」面板中打开「启用用量查询」并选择内置模板(官方供应商选「官方订阅」),因为同一个请求地址可能同时有"套餐"和"余额"两种查询模式,需要你自行选择。详见 2.5 用量查询 → 手动启用。
官方订阅供应商没有显示配额¶
检查:
- 确认供应商处于「使用中」状态(未使用时不触发查询)
- 对于 Copilot / Codex OAuth,检查 OAuth Token 是否仍在有效期内;如果卡片显示「会话已过期」,请到侧栏的「授权中心」重新登录
- 检查网络连通性
- 点击卡片上的刷新图标手动重新查询
Token Plan 或第三方余额启用后仍不显示¶
检查:
- 确认在「用量查询」面板中已打开「启用用量查询」开关
- 已经选择了合适的内置模板并保存
- 点击「测试脚本」查看具体错误信息
- 供应商需要处于「使用中」状态后台才会自动刷新
Codex 用量和直连时对不上¶
v3.13.0 将 Codex 用量从估算切换为基于 JSONL 会话日志的精确解析,同时对模型名称做归一化以保证定价查询一致。新数据会与官方账单对齐;若仍看到旧的估算数据,可以删除历史条目或等待新会话数据覆盖。
Codex OAuth 反向代理¶
启用 Codex OAuth 反向代理有什么风险?¶
Codex OAuth 反向代理通过逆向工程的 OAuth 流程访问 ChatGPT 账号的 Codex 服务,可能违反 OpenAI 的服务条款,存在账号被限制或暂停的风险,且长期可用性无法保证。启用即表示自行承担所有风险。
完整免责声明参见 v3.13.0 Release Notes → 风险提示 和 2.1 添加供应商 → Codex OAuth 反向代理。
如何登录 Codex OAuth?¶
完整的 Device Code 登录流程(验证码 + 浏览器授权)、两个入口(添加供应商面板 / 授权中心)、多账号管理和常见失败场景,参见 2.1 添加供应商 → Codex OAuth 反向代理(Claude 供应商)。
Codex OAuth 登录后配额没显示¶
解决方法:
- 确认在侧栏的「授权中心」中已完成 OAuth 登录流程
- 检查 Token 是否仍在有效期内 — 卡片上如果显示"会话已过期"表示 Token 无法刷新
- 如果过期,在授权中心移除该账号后重新登录
其他问题¶
托盘图标不显示¶
macOS:
- 检查系统设置中的菜单栏图标设置
Windows:
- 检查任务栏设置,确保 CC Switch 图标未被隐藏
Linux:
- 需要安装系统托盘支持(如
libappindicator)
界面显示异常¶
解决方法:
- 尝试切换主题(浅色/深色)
- 重启应用
- 删除
~/.cc-switch/settings.json重置设置(各应用当前使用的供应商指针也记在这个文件里,重置后需要重新确认)
Linux 标题栏按钮(关闭/最小化/最大化)点不到¶
原因:在 Linux(尤其是 Wayland)下,窗口首次显示或从托盘 hide() 后再 show() 时,GTK 原生 HeaderBar 的事件子表面可能未与合成器协商完成。典型表现是网页内容仍能点,但标题栏按钮全部无响应。
CC Switch 会在启动、托盘恢复、深链接和单例唤起时自动重激活焦点并重建标题栏按钮路由。若仍遇到问题,可按下面方式排障:
- 在 设置 → 通用 → 窗口与终端 → 启用应用级窗口按钮 中改用应用自绘的窗口控制按钮;
- 使用系统托盘菜单中的 退出 结束应用;
- AppImage 用户可设置
CC_SWITCH_GDK_BACKEND=x11切换窗口后端。
更新失败¶
解决方法:
- 检查网络连接
- 手动下载最新版本安装
- 如使用 Homebrew:
brew upgrade --cask cc-switch
轻量模式¶
如何进入轻量模式?¶
从系统托盘菜单切换"轻量模式"。主窗口关闭,CC Switch 仅作为托盘应用运行。再次切换或点击"打开主界面"即可退出。
轻量模式下应用占用更少内存?¶
是的。轻量模式会销毁主窗口及其 Web 视图,显著减少内存占用,同时保留托盘菜单功能。
轻量模式下深链接还能唤起主界面吗?¶
可以。CC Switch v3.13.0 起会覆盖所有窗口重新显示路径(正常启动、深链接、单例激活、托盘 show_main 以及轻量模式返程),点击 ccswitch:// 链接会按需重建主窗口并显示导入确认对话框。第一次打开会比普通状态略慢(需要重建窗口),但后续切换恢复正常速度。
获取帮助¶
提交 Issue¶
如果以上方法都无法解决问题:
- 访问 GitHub Issues
- 搜索是否有类似问题
- 如果没有,创建新 Issue
- 提供以下信息:
- 操作系统和版本
- CC Switch 版本
- 问题描述和复现步骤
- 错误信息(如有)
日志文件¶
CC Switch 的日志位于应用配置目录中。默认配置目录是用户主目录下的 .cc-switch;如果你在「设置 → 数据 → 存储位置」中修改过配置目录,请以自定义目录为准。
提交 Issue 时,请按问题类型附上:
- 普通错误、网络或代理问题:
~/.cc-switch/logs/中的cc-switch.log及其轮转文件 - 应用崩溃:
~/.cc-switch/crash.log及crash.log.1、crash.log.2 - Windows 默认路径为
C:\Users\<用户名>\.cc-switch\...
运行日志按 20 MB 轮转,并保留最近 4 个归档;重启应用不会再清空已有日志。日志可能包含运行环境信息,公开提交前建议先检查内容。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cc/cc-switch