Skip to content
CC Switch WikiUnofficial Community Wiki

Codex CLI failure: CC Switch

Quick fix

Upgrade cc-switch to v3.16.3 or later to fix blockers in local environment detection and the upgrade flow.

Symptom

Section titled “Symptom”
Error output
codex cli 失败：
English translation

codex cli failed:

Cause

Section titled “Cause”

In v3.16.1, cc-switch had several underlying defects in local environment detection and the CLI tool upgrade flow. The code did not correctly anchor the installation source and absolute path, causing updates to fail when a platform binary was missing. On Windows, improper character escaping also produced garbled text. In addition, the old version detection process severely blocked the About panel from rendering, preventing users from viewing the current status.

For some tools that do not include an official self-update command, such as Gemini CLI, cc-switch will also return a failure message when it tries to call their update interface. These issues stem from defects in the client’s internal upgrade pipeline and cross-platform compatibility, not user configuration errors.

Fix

Section titled “Fix”

  1. Open the cc-switch interface, go to Settings or About, and check for an upgrade to v3.16.3 or later.

  2. Fully restart the cc-switch application, then click the “Update” button next to the relevant tool again to check whether it works.

Affected Versions

Section titled “Affected Versions”
ToolClaude Code / Codex / Gemini CLI / Hermes
Version3.16.1
PlatformsWindowsmacOS

Source Issues

Section titled “Source Issues”

This page is distilled from 2 real issues

FAQ

Section titled “FAQ”
Why does clicking Update for Gemini CLI keep showing a failure message?
The official Gemini CLI does not currently provide a self-update command, so cc-switch returns a failure when it tries to call its update interface. This is an official limitation, not a software bug.
What should I do if the About panel still does not show the current version after upgrading?
This display blocking issue was fixed in v3.16.4. Make sure you have upgraded to v3.16.4 or later. If the version still does not appear, provide the latest runtime logs for further troubleshooting.
Section titled “Related problems”
CC Switch flashes once when clicking any buttonOn Windows, use WebView2 152.0.4191.62 Fixed Version only for CC Switch to avoid click flashing with WebView2 153.0.4234.32.2 issues mergedPrompt files are never rebuiltPrompt, live configuration, and caches are not fully rebuilt after database restoration. No verifiable fix is available; follow the merged discussion.1 issues mergedThe Gemini CLI reading the project .env breaks cc-switchWrap the gemini command in PowerShell to load the ~/.gemini/.env environment variables by hand.2 issues merged

This is an unofficial community wiki with no affiliation to the cc-switch authors or the project itself. Its content is compiled from the project's public GitHub issues. This site distributes no software.