admin/CC-Switch
1
0
Fork 0
mirror of https://github.com/farion1231/cc-switch.git synced 2026-08-02 18:41:35 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
0200fe79aea82aef776bd9dca9eec97b8fd95fcd
CC-Switch/docs/user-manual/zh/5-faq/5.2-questions.md
T
Jason d9c0e4c452 docs: update user manual to v3.12.3 with new features coverage (en/zh/ja) 
Add documentation for features introduced since v3.12.0:

New docs:
- 3.4 Session Manager: browse, search, resume, delete sessions
- 3.5 Workspace & Daily Memory: OpenClaw workspace file editing

Updated docs:
- Add Lightweight Mode to interface overview and FAQ
- Add tray submenu structure (providers grouped by app)
- Add API Format selection (Anthropic/OpenAI Chat/OpenAI Responses)
- Add Auto-Fetch Models button documentation
- Add Claude Common Config quick toggles
- Add Codex 1M Context Window toggle
- Add Skill backup/restore lifecycle
- Expand Backup Management panel documentation
- Update WebDAV sync to v2 protocol with dual-layer versioning
- Add OpenCode/OpenClaw to quickstart activation table
- Update README version to v3.12.3

All changes synced across en, zh, and ja locales.
2026-04-04 22:53:20 +08:00

4.8 KiB
Raw Blame History

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
  2. 关闭占用端口的程序
  3. 或尝试修改配置恢复默认端口：
    • 打开「设置 → 代理服务」
    • 点击「恢复默认」按钮

代理模式下请求超时

可能原因：

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

解决方法：

  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 导出的 JSON 文件
  2. 检查文件内容是否完整
  3. 尝试用文本编辑器打开检查格式

用量统计数据为空

检查清单：

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

其他问题

托盘图标不显示

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 视图，显著减少内存占用，同时保留托盘菜单功能。

获取帮助

提交 Issue

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

  1. 访问 GitHub Issues
  2. 搜索是否有类似问题
  3. 如果没有，创建新 Issue
  4. 提供以下信息：
    • 操作系统和版本
    • CC Switch 版本
    • 问题描述和复现步骤
    • 错误信息（如有）

日志文件

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

  • macOS/Linux：~/.cc-switch/logs/
  • Windows：%APPDATA%\cc-switch\logs\
Reference in New Issue View Git Blame Copy Permalink