CC Switch 常见问题
先确认问题发生在哪一步：浏览器唤起 → 导入配置 → 切换供应商 → 工具调用。前一步成功不代表后一步已经完成。
点击「打开 CC Switch」没有反应
- 确认 CC Switch 已安装，并手动打开一次。
- 返回光迹控制台，重新打开导入窗口，检查浏览器是否弹出「打开外部应用」提示。
- 如果此前取消过提示，再次点击导入并允许打开。浏览器需要把
ccswitch://链接交给 CC Switch。 - 便携版或系统协议关联异常时，可按官方安装说明重新安装以修复关联；暂时无法恢复时，使用 手动添加。
不要把包含密钥的完整导入链接发给别人排查，也不要粘贴到第三方“链接检测”网站。
导入成功，但工具仍在使用旧平台
- 检查是否导入到了正确应用；Claude、Codex、Gemini 的配置分别管理。
- 找到光迹 API 卡片并启用。保存或导入配置后，仍应检查当前使用状态。
- 关闭旧工具会话，重新打开终端和工具，再确认当前模型。
- 如果存在环境变量冲突提示，点击详情核对变量来源。旧的 API 地址或密钥可能覆盖配置。
处理环境变量前，先确认它是否还被其他程序使用；只修改确认过的冲突项，保留备份，再重启受影响的应用。不要直接删除所有环境变量。
已经发出请求，但返回错误
| 现象 | 优先检查 |
|---|---|
401 / 鉴权失败 | 是否使用光迹 API 密钥，密钥是否完整、已启用且未过期；更新后是否重新启用配置 |
403 / 无权限 | 密钥分组、模型权限、IP 限制或账户状态；以具体错误内容为准 |
404 / 返回网页 | 是否误填控制台地址、重复添加 /v1，或所用接口协议不受支持 |
| 模型不存在 / 无可用渠道 | 模型 ID 是否准确，当前密钥分组是否可用该模型 |
429 / 限流或额度不足 | 阅读错误正文，核对余额、密钥额度及请求频率 |
| 连接本机地址失败 | 路由或聚合模式下，CC Switch 本地服务是否正在运行 |
| 超时 / 连接重置 | 先检查网络与代理设置，再区分是访问光迹失败还是访问本地路由失败 |
更多处理步骤见 通用错误排查。协议不匹配时，单纯更换模型名称或随意增删 /v1 不一定能解决问题。
关闭 CC Switch 后就不能用了
如果启用了路由或聚合，目标工具的请求会先经过本地服务，需要保持 CC Switch 的相关服务运行。
想改回直接连接时，在 CC Switch 中执行 回到直连，选择协议匹配的光迹 API 配置，再重启目标工具。不要仅退出 CC Switch 而保留本地路由地址。
测速正常，为什么还是不能对话
测速主要帮助判断网络连接情况。真正调用还需要通过密钥鉴权、模型权限、额度和接口协议检查。
在目标工具里发一条短消息，并查看光迹控制台是否产生对应请求日志，才能进一步判断业务请求是否成功。
恢复原来的配置
如果只是临时切换，可重新启用原供应商；需要恢复官方账号登录时，选择对应的官方配置，再按工具自身的登录流程操作。
如果误改了多项设置，可从 CC Switch 的备份中恢复。恢复前先导出当前配置，具体步骤见 备份与换电脑。
联系支持时提供什么
提供 CC Switch 版本、操作系统、目标应用、直连或路由模式、模型 ID、出错时间和错误截图。地址可提供域名与路径，密钥、登录凭据和含密钥的链接要遮挡。
- 光迹账户、模型权限、余额或接口问题：联系光迹 API QQ 智能客服。
- CC Switch 安装或软件自身问题：官方手册 / GitHub Issues。公开提交问题前检查截图和日志是否含敏感信息。