Skip to content
CC Switch WikiUnofficial Community Wiki

Codex/OpenCode shows not installed - CC Switch

Quick fix

Add the npm prefix or fnm alias directory to the user PATH environment variable, then restart CC Switch.

Symptom

Section titled “Symptom”
Error output
codex 和 opencode 显示版本为空白（未安装）
English translation

codex and opencode show blank versions (not installed)

Cause

Section titled “Cause”

CC Switch has a platform asymmetry when detecting CLI tool versions on Windows. Non-Windows systems resolve PATH through a login shell ($SHELL -lic), which loads user profile scripts to obtain the full path. The Windows branch skips shell PATH resolution and relies solely on scan_cli_version for directory scanning, using the process-level std::env::var_os("PATH"). When the user has customized the npm prefix (e.g. D:\custom\npm) or uses fnm to manage Node, the PATH of the GUI-launched CC Switch process does not include these paths, causing the tools to not be detected.

For fnm users, the %LOCALAPPDATA%\fnm_multishells\<session> path exposed by fnm env is session-level and cannot be inherited by the GUI process. Issue #4237 also reported another variant: when npm installs globally on Windows, it generates two wrapper files, codex (a Unix shell script) and codex.cmd. CC Switch misidentifies this as "multiple installations" and marks the non-runnable Unix script as the default. The maintainer confirmed in #1768 that the issue of the New API usage query default endpoint pointing to the wrong location has been fixed and tracked.

Fix

Section titled “Fix”

  1. Verify that codex --version and opencode --version work correctly in the terminal to rule out installation issues.

  2. If using a custom npm prefix: add the custom prefix directory (e.g. D:\custom\npm) to the Windows user PATH environment variable (not just the terminal profile), then restart CC Switch.

  3. If using fnm to manage Node: add the fnm stable default alias directory %APPDATA%\fnm\aliases\default to the user PATH to avoid relying on the session-level fnm_multishells path.

    Windows 用户环境变量（系统设置 → 环境变量 → 用户变量）
    PATH=...;%APPDATA%\fnm\aliases\default

  4. Restart CC Switch, open Settings → About, and confirm that codex and opencode version numbers display correctly.

Affected Versions

Section titled “Affected Versions”
ToolCodex / OpenCode
Version3.12.3 - 3.20.1（受影响版本）
PlatformsWindows

Source Issues

Section titled “Source Issues”

This page is distilled from 6 real issues

FAQ

Section titled “FAQ”
codex --version works in the terminal, so why does CC Switch still show it as not installed?
The PATH inherited by CC Switch when launched as a GUI application differs from the terminal. The terminal loads profile scripts (e.g. PowerShell profile), while the GUI process does not. The tool path must be added to the system or user PATH environment variable, not just set in a shell profile.
Must fnm users add fnm\aliases\default to PATH?
This is currently the reliable workaround. The fnm_multishells path generated by fnm env is session-level and cannot be inherited by the GUI process. Adding the stable alias directory bypasses this limitation, but CC Switch's independent fnm discovery mechanism still needs to be fixed.
Does v3.17.0 fix the false positive for multiple installations?
The maintainer of Issue #4237 confirmed that no similar issues have been found in v3.17.0. If you still encounter npm wrapper scripts being misidentified as multiple installations on v3.17.0+, you can reopen an issue to report it.
Is defaulting to the first app instead of the last focused app on startup the same bug?
No. This is another issue reported in #6935, unrelated to tool detection. The root cause is that in App.tsx, when visibleApps has not finished loading, the effect resets activeApp to the first visible app, which reproduces on slower-loading Win11 systems.
Section titled “Related problems”
Not installed / not installed or not executable - CC SwitchUpgrade CC Switch to v3.20.0+ for custom npm prefix and macOS detection failures; the false "several installations" on Windows needs v3.16.5+.4 issues mergedenv: node: No such file or directoryUpgrading cc-switch to v3.18.0 or newer fixes the environment variable resolution failure caused by a stripped PATH in the GUI.4 issues mergedCannot import providers, cannot manage sessions - cc-switchUpgrade cc-switch for jsonc config support. Under WSL2, clone the database to a local Windows path on a schedule to work around SQLite locking.4 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.