Skip to content
CC Switch WikiUnofficial Community Wiki

Local environment check reports codex is not installed - cc-switch

Quick fix

Run codex --version first. If the terminal works but cc-switch cannot detect it, the install path is outside its probe range — upgrade to v3.16.4+.

Symptom

Section titled “Symptom”
Error output
本地环境检查 提示codex未安装
English translation

Local environment check reports codex is not installed

Cause

Section titled “Cause”

The cc-switch local environment check mostly probes common install paths and PATH to find Claude Code/Codex, so a CLI installed via the Microsoft Store, a miniconda/base environment, npm global, or with several entry points may fall outside its range — hence "local environment check reports codex is not installed". A maintainer reply in #3547 indicates later versions reworked tool version probing and the about panel, including Windows probe fixes. In #3434 users also hit variants where the version number was detected as the system version, or came back garbled. #4034/#4303 reflect npm installs producing several entry points — codex, codex.cmd, codex.ps1 — which are easily misread as conflicting duplicate installs. #4345 and #4758 are duplicate reports of the same Microsoft Store path problem, and #2737 is a miniconda base environment not being loaded so Codex is not found.

Fix

Section titled “Fix”

  1. Run `codex --version` (or `claude --version`) in a terminal to confirm the command exists and runs.

  2. If the terminal works but cc-switch still says not installed, upgrade to v3.16.4 or newer first — a maintainer said in #3547 that later versions improved tool version probing.

  3. If an npm-installed Codex is diagnosed as several installs, check whether `codex`, `codex.cmd`, and `codex.ps1` all point at the same npm install. If they do, leave it and wait for the fix.

  4. If it is still not recognised, record your install method (Microsoft Store / npm / conda / Homebrew) and the actual path, and report it on #4758 or a new issue.

Affected Versions

Section titled “Affected Versions”
ToolCodex
Version3.14.1 - 3.16.4（受影响范围；v3.16.4 后可能有探测修复）
PlatformsWindowsmacOSLinux

Source Issues

Section titled “Source Issues”

This page is distilled from 8 real issues

FAQ

Section titled “FAQ”
Why is the current version detected as the system version on mac?
That was reported in #3434 and comes from a misjudgement in the version probing logic. Later versions reworked tool version probing and the about panel — upgrade and retry.
I installed Codex from the Microsoft Store — why does cc-switch say codex is not installed?
The Microsoft Store install path differs from Homebrew/npm, and older versions may not cover it. This is tracked in #4758, with #4345 as a duplicate report.
Why does the diagnosis report several installs or a conflict for an npm-installed Codex?
npm creates codex, codex.cmd, and codex.ps1 entry points on PATH, which older cc-switch mistook for several installs. Tracked in #4303/#4034.
Codex installed in a conda base environment is not detected. What now?
#2737 reports this may relate to cc-switch not loading the miniconda base environment. For now, confirm `codex --version` runs directly in a terminal and report back on the issue.
Section titled “Related problems”
AnyRouter 429 error in Claude CodeAdd "model": "opus[1m]" to the provider JSON and restart Claude Code. If 429 persists, upstream rate limiting is likely; switch networks or use haiku.1 issues mergednot installed or not executableUpgrade CC Switch to v3.16.2+, or set the CLI install directory by hand in settings, and clear noise printed by your shell at startup.4 issues mergedcc-switch Codex session history missingDisable Codex routing or unified history in cc-switch, make model_provider match old sessions, then restart Codex to restore history.1 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.