Frequently Asked Questions

Installation Issues

macOS Installation

Olenro for macOS is code-signed and notarized by Apple. You can download and install it directly without any additional steps. If you encounter issues, try downloading the latest version from the Releases page.

Windows: App Doesn't Launch After Installation

Possible causes:

Missing WebView2 runtime
Antivirus software blocking

Solutions:

Install Microsoft Edge WebView2
Add Olenro to your antivirus software's whitelist

Linux: Startup Error

Problem: AppImage won't start

Solution:

# Add execute permission
chmod +x CC-Switch-*.AppImage

# If it still fails, try
./CC-Switch-*.AppImage --no-sandbox

Provider Issues

Provider Switch Doesn't Take Effect

Cause: The CLI tool needs to reload its configuration

Solutions:

Claude Code: Close and reopen the terminal, or restart the IDE
Codex: Close and reopen the terminal
Gemini: Tray switching takes effect immediately, no restart needed

API Key Invalid

Troubleshooting steps:

Confirm the API Key is copied correctly (no extra spaces)
Confirm the API Key hasn't expired
Confirm the endpoint URL is correct
Use the speed test to verify connectivity

Steps:

Select the "Official Login" preset (Claude/Codex) or "Google Official" preset (Gemini)
Click "Enable"
Restart the corresponding CLI tool
Follow the CLI tool's login flow

Proxy Issues

Proxy Service Fails to Start

Possible cause: Port is occupied

Solution:

Check port usage:

# macOS/Linux
lsof -i :49152

# Windows
netstat -ano | findstr :49152

Close the program occupying the port
Or try modifying the configuration to restore the default port:
- Open "Settings > Proxy Service"
- Click the "Reset to Default" button

Request Timeout in Proxy Mode

Possible causes:

Network issues
Provider server issues
Incorrect proxy configuration

Solutions:

Check network connection
Try accessing the provider API directly (disable proxy)
Check if provider configuration is correct

Configuration Not Restored After Disabling Proxy

Possible cause: Proxy exited abnormally

Solution:

Edit the current provider
Check if the endpoint URL is correct
Save to update the configuration

Failover Issues

Failover Not Triggering

Checklist:

Is the proxy service running
Is app takeover enabled
Is auto failover enabled
Are there backup providers in the queue

Failover Triggering Too Frequently

Possible causes:

Unstable primary provider
Circuit breaker threshold set too low

Solutions:

Check primary provider status
Increase the failure threshold (e.g., from 3 to 5)
Consider changing the primary provider

All Providers Are Circuit-Broken

Solutions:

Wait for the recovery wait time to expire (default 60 seconds)
Or restart the proxy service to reset states

Data Issues

Configuration Lost

Possible causes:

Configuration directory was deleted
Database corruption

Solutions:

Check if the ~/.olenro/ directory exists
Restore from backup: ~/.olenro/backups/
Or import from a previously exported configuration file

Import Configuration Failed

Possible causes:

Incorrect file format
Version incompatibility

Solutions:

Confirm the file was exported by Olenro
Check if the file content is complete
Try opening with a text editor to check format

Usage Statistics Data Is Empty

Checklist:

Is the proxy service running
Is app takeover enabled
Is log recording enabled
Have requests been going through the proxy

Quota & Balance

Why do some providers show quota automatically while others need manual enabling?

Only official subscription types (Claude / Codex / Gemini official login, GitHub Copilot, Codex OAuth reverse proxy) automatically display the quota after enabling the provider. All other providers (including Token Plan and third-party balance queries) need the Usage Query switch to be manually turned on and a built-in template selected in the provider card — because the same request URL may expose both "plan" and "balance" query modes, requiring you to pick the right one. See 2.5 Usage Query → Manual Enable.

Official subscription provider shows no quota

Check:

Confirm the provider is in "Currently Active" state (inactive providers do not trigger queries)
For Copilot / Codex OAuth, check whether the OAuth token is still valid; if the card shows "Session Expired", log in again in the OAuth Auth Center
Check network connectivity
Click the refresh icon on the card to manually re-query

Token Plan or third-party balance still not shown after enabling

Check:

Confirm the Enable Usage Query toggle is on in the "Usage Query" panel
A suitable built-in template is selected and saved
Click Test Script to see the specific error
The provider must be in "Currently Active" state for background auto-refresh

Codex usage does not match the direct-connection numbers

v3.13.0 switched Codex usage from estimation to precise parsing based on JSONL session logs, with normalized model names for consistent pricing lookup. New data aligns with official bills. If you still see old estimated data, delete the historical entries or wait for new session data to overwrite them.

Codex OAuth Reverse Proxy

How do I log in to Codex OAuth?

See the complete Device Code login flow (verification code + browser authorization), both entry points (Add Provider panel / OAuth Auth Center), multi-account management, and common failure scenarios in 2.1 Add Provider → Codex OAuth Reverse Proxy (Claude Provider).

What are the risks of enabling the Codex OAuth reverse proxy?

The Codex OAuth reverse proxy accesses your ChatGPT account's Codex service through a reverse-engineered OAuth flow. This may violate OpenAI's Terms of Service, carries the risk of account restrictions or suspensions, and provides no guarantee of long-term availability. By enabling, you assume all risks.

See the full disclaimer in the v3.13.0 Release Notes → Risk Notice and in 2.1 Add Provider → Codex OAuth Reverse Proxy.

Codex OAuth logged in but no quota shown

Solutions:

Confirm the OAuth login flow is completed in OAuth Auth Center (Settings → OAuth Auth Center, with the Beta label)
Check whether the token is still valid — if the card shows "Session Expired", the token cannot be refreshed
If expired, remove the account in the OAuth Auth Center and log in again

Other Issues

Tray Icon Not Showing

macOS:

Check menu bar icon settings in System Settings

Windows:

Check taskbar settings to ensure the Olenro icon is not hidden

Linux:

System tray support may need to be installed (e.g., libappindicator)

UI Display Issues

Solutions:

Try switching themes (light/dark)
Restart the app
Delete ~/.olenro/settings.json to reset settings

Update Failed

Solutions:

Check network connection
Manually download and install the latest version
If using Homebrew: brew upgrade --cask olenro

Lightweight Mode

How to Enter Lightweight Mode?

Toggle "Lightweight Mode" from the system tray menu. The main window closes, and Olenro runs as a tray-only app. Toggle again or click "Open main window" to exit.

App Uses Less Memory in Lightweight Mode?

Yes. Lightweight Mode destroys the main window and its web view, reducing memory usage significantly while keeping tray menu functionality available.

Can deep links still wake the main window in Lightweight Mode?

Yes. Starting from v3.13.0, Olenro covers all window re-show paths (normal launch, deep links, singleton activation, tray show_main, and Lightweight Mode return). Clicking a olenro:// link rebuilds the main window on demand and displays the import confirmation dialog. The first open is slightly slower than normal state (window rebuild required), but subsequent switches return to normal speed.

Getting Help

Submit an Issue

If none of the above solutions work:

Visit GitHub Issues
Search for similar issues
If none found, create a new Issue
Provide the following information:
- Operating system and version
- Olenro version
- Problem description and reproduction steps
- Error messages (if any)

Log Files

Attach log files when submitting an Issue:

macOS/Linux: ~/.olenro/logs/
Windows: %APPDATA%\olenro\logs\

Frequently Asked Questions

On this page