5.2 常见问题 FAQ

安装问题

macOS 安装

CC Switch macOS 版本已通过 Apple 代码签名和公证，可直接下载安装，无需额外操作。如遇问题，请尝试从 Releases 页面 下载最新版本。

Windows 安装后无法启动

可能原因：

• 缺少 WebView2 运行时
• 杀毒软件拦截

解决方法：

1. 安装 Microsoft Edge WebView2
2. 将 CC Switch 添加到杀毒软件白名单

Linux 启动报错

问题：AppImage 无法启动

解决方法：

# 添加执行权限
chmod +x CC-Switch-*.AppImage

# 如果仍然失败，尝试
./CC-Switch-*.AppImage --no-sandbox

供应商问题

切换供应商后不生效

原因：CLI 工具需要重新加载配置

解决方法：

• Claude Code：关闭并重新打开终端，或重启 IDE
• Codex：关闭并重新打开终端
• Gemini：托盘切换可即时生效，无需重启

API Key 无效

检查步骤：

1. 确认 API Key 正确复制（无多余空格）
2. 确认 API Key 未过期
3. 确认端点地址正确
4. 使用速度测试验证连接

如何恢复官方登录

操作步骤：

1. 选择「官方登录」预设（Claude/Codex）或「Google 官方」预设（Gemini）
2. 点击「启用」
3. 重启对应的 CLI 工具
4. 按照 CLI 工具的登录流程操作

代理问题

代理服务启动失败

可能原因：端口被占用

解决方法：

1. 检查端口占用：

   # macOS/Linux
   lsof -i :49152
   
   # Windows
   netstat -ano | findstr :49152

1. 关闭占用端口的程序
2. 或尝试修改配置恢复默认端口：

• 打开「设置 → 代理服务」
• 点击「恢复默认」按钮

代理模式下请求超时

可能原因：

• 网络问题
• 供应商服务器问题
• 代理配置错误

解决方法：

1. 检查网络连接
2. 尝试直接访问供应商 API（关闭代理）
3. 检查供应商配置是否正确

关闭代理后配置未恢复

可能原因：代理异常退出

解决方法：

1. 编辑当前供应商
2. 检查端点地址是否正确
3. 保存以更新配置

故障转移问题

故障转移没有触发

检查清单：

• [ ] 代理服务是否运行
• [ ] 应用接管是否开启
• [ ] 自动故障转移是否开启
• [ ] 队列中是否有备用供应商

频繁触发故障转移

可能原因：

• 主供应商不稳定
• 熔断器阈值设置过低

解决方法：

1. 检查主供应商状态
2. 调高失败阈值（如从 3 改为 5）
3. 考虑更换主供应商

所有供应商都熔断了

解决方法：

1. 等待熔断时长到期（默认 60 秒）
2. 或重启代理服务重置状态

数据问题

配置丢失

可能原因：

• 配置目录被删除
• 数据库损坏

解决方法：

1. 检查 ~/.cc-switch/ 目录是否存在
2. 从备份恢复：~/.cc-switch/backups/
3. 或从之前导出的配置文件导入

导入配置失败

可能原因：

• 文件格式错误
• 版本不兼容

解决方法：

1. 确认文件是 CC Switch 导出的 SQL 备份文件
2. 检查文件内容是否完整
3. 尝试用文本编辑器打开检查格式

用量统计数据为空

检查清单：

• [ ] 代理服务是否运行
• [ ] 应用接管是否开启
• [ ] 日志记录是否开启
• [ ] 是否有请求通过代理

配额与余额

为什么有的供应商自动显示配额，有的需要手动启用？

只有官方订阅类（Claude / Codex / Gemini 官方登录、GitHub Copilot、Codex OAuth 反向代理）会在启用供应商后自动显示配额。其他所有供应商（包括 Token Plan 和第三方余额查询）都需要手动到供应商卡片的「用量查询」面板中打开开关并选择内置模板，因为同一个请求地址可能同时有"套餐"和"余额"两种查询模式，需要你自行选择。详见 2.5 用量查询 → 手动启用。

官方订阅供应商没有显示配额

检查：

1. 确认供应商处于「当前启用」状态（非激活时不触发查询）
2. 对于 Copilot / Codex OAuth，检查 OAuth Token 是否仍在有效期内；如果卡片显示「会话已过期」，请到 OAuth 认证中心重新登录
3. 检查网络连通性
4. 点击卡片上的刷新图标手动重新查询

Token Plan 或第三方余额启用后仍不显示

检查：

1. 确认在「用量查询」面板中已打开「启用用量查询」开关
2. 已经选择了合适的内置模板并保存
3. 点击「测试脚本」查看具体错误信息
4. 供应商需要处于「当前启用」状态后台才会自动刷新

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 登录流程（验证码 + 浏览器授权）、两个入口（添加供应商面板 / OAuth 认证中心）、多账号管理和常见失败场景，参见 2.1 添加供应商 → Codex OAuth 反向代理（Claude 供应商）。

Codex OAuth 登录后配额没显示

解决方法：

1. 确认在 OAuth 认证中心（设置 → OAuth 认证中心，带 Beta 标记）中已完成 OAuth 登录流程
2. 检查 Token 是否仍在有效期内 — 卡片上如果显示"会话已过期"表示 Token 无法刷新
3. 如果过期，在 OAuth 认证中心移除该账号后重新登录

其他问题

托盘图标不显示

macOS：

• 检查系统设置中的菜单栏图标设置

Windows：

• 检查任务栏设置，确保 CC Switch 图标未被隐藏

Linux：

• 需要安装系统托盘支持（如 libappindicator）

界面显示异常

解决方法：

1. 尝试切换主题（浅色/深色）
2. 重启应用
3. 删除 ~/.cc-switch/settings.json 重置设置

更新失败

解决方法：

1. 检查网络连接
2. 手动下载最新版本安装
3. 如使用 Homebrew：brew upgrade --cask cc-switch

轻量模式

如何进入轻量模式？

从系统托盘菜单切换"轻量模式"。主窗口关闭，CC Switch 仅作为托盘应用运行。再次切换或点击"打开主界面"即可退出。

轻量模式下应用占用更少内存？

是的。轻量模式会销毁主窗口及其 Web 视图，显著减少内存占用，同时保留托盘菜单功能。

轻量模式下深链接还能唤起主界面吗？

可以。CC Switch v3.13.0 起会覆盖所有窗口重新显示路径（正常启动、深链接、单例激活、托盘 show_main 以及轻量模式返程），点击 ccswitch:// 链接会按需重建主窗口并显示导入确认对话框。第一次打开会比普通状态略慢（需要重建窗口），但后续切换恢复正常速度。

获取帮助

提交 Issue

如果以上方法都无法解决问题：

1. 访问 GitHub Issues
2. 搜索是否有类似问题
3. 如果没有，创建新 Issue
4. 提供以下信息：

• 操作系统和版本
• CC Switch 版本
• 问题描述和复现步骤
• 错误信息（如有）

日志文件

提交 Issue 时可附上日志文件：

• macOS/Linux：~/.cc-switch/logs/
• Windows：%APPDATA%\cc-switch\logs\