常见问题 FAQ

安装问题

macOS 安装

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

Windows 安装后无法启动

可能原因：

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

解决方法：

安装 Microsoft Edge WebView2
将 Olenro 添加到杀毒软件白名单

Linux 启动报错

问题：AppImage 无法启动

解决方法：

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

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

供应商问题

切换供应商后不生效

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

解决方法：

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

API Key 无效

检查步骤：

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

如何恢复官方登录

操作步骤：

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

代理问题

代理服务启动失败

可能原因：端口被占用

解决方法：

检查端口占用：

# macOS/Linux
lsof -i :49152

# Windows
netstat -ano | findstr :49152

关闭占用端口的程序
或尝试修改配置恢复默认端口：
- 打开「设置 → 代理服务」
- 点击「恢复默认」按钮

代理模式下请求超时

可能原因：

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

解决方法：

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

关闭代理后配置未恢复

可能原因：代理异常退出

解决方法：

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

故障转移问题

故障转移没有触发

检查清单：

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

频繁触发故障转移

可能原因：

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

解决方法：

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

数据问题

配置丢失

可能原因：

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

解决方法：

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

导入配置失败

可能原因：

文件格式错误
版本不兼容

解决方法：

确认文件是 Olenro 导出的 JSON 文件
检查文件内容是否完整
尝试用文本编辑器打开检查格式

用量统计数据为空

检查清单：

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

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