Codex command not found 命令不存在解决教程

Codex command not found 的典型现象

这个问题一般出现在刚装完 Codex CLI，或者换了新终端、新机器之后。你在命令行里执行：

### token云桥中转 0029.org ###
codex --version

结果提示类似下面这样：

zsh: command not found: codex

或者在 Linux 里看到：

bash: codex: command not found

Windows PowerShell 里可能是：

codex : The term 'codex' is not recognized as the name of a cmdlet

这类错误的核心意思很简单：当前终端找不到名为 codex 的可执行命令。优先不要怀疑接口、账号或者模型配置，先查安装是否成功、命令是否在 PATH 里。

先判断：到底是没安装，还是 PATH 没生效

1. 查看当前系统能不能找到 codex

macOS / Linux 执行：

which codex

如果没有任何输出，说明系统当前 PATH 里找不到它。

Windows PowerShell 执行：

Get-Command codex

如果提示找不到命令，也基本可以确定不是 Codex 本身运行报错，而是命令入口没有被识别。

2. 确认 Node.js 和 npm 是否正常

很多 Codex CLI 是通过 npm 全局安装的，所以先确认 Node 环境：

node -v
npm -v

如果这里都报错，先安装 Node.js。建议使用 LTS 版本，不要用太旧的 Node，否则后面即使装上了 CLI，也可能因为运行时版本不兼容继续报错。

常见原因和修复步骤

原因一：根本没有安装 Codex CLI

如果你是按照 npm 方式安装，可以重新执行一次全局安装：

npm install -g @openai/codex

安装结束后再验证：

codex --version

如果还是提示 command not found，不要重复安装很多遍，继续看 npm 全局 bin 路径。

原因二：npm 全局 bin 目录不在 PATH

查看 npm 全局命令安装位置：

npm bin -g

部分 npm 版本可能不支持这个命令，可以用：

npm config get prefix

macOS / Linux 下，全局命令通常在类似这些目录：

/usr/local/bin
/opt/homebrew/bin
~/.npm-global/bin
~/.nvm/versions/node/v20.x.x/bin

如果 codex 已经安装在某个目录里，但这个目录不在 PATH，就会出现 command not found。

查看当前 PATH：

echo $PATH

假设你的 npm 全局 bin 是 ~/.npm-global/bin，可以把它加入 shell 配置。

zsh 用户编辑 ~/.zshrc：

export PATH="$HOME/.npm-global/bin:$PATH"

bash 用户编辑 ~/.bashrc 或 ~/.bash_profile：

export PATH="$HOME/.npm-global/bin:$PATH"

然后让配置立即生效：

source ~/.zshrc

或者：

source ~/.bashrc

原因三：使用 nvm 后切换 Node 版本导致命令丢失

如果你用的是 nvm，Codex CLI 是安装在某个 Node 版本下面的。切换 Node 版本后，全局包不一定还在。

nvm current
npm list -g --depth=0

如果列表里没有 @openai/codex，在当前 Node 版本下重新安装：

npm install -g @openai/codex

另外建议设置默认 Node 版本，避免每次打开终端版本不一致：

nvm alias default 20

原因四：Windows 环境变量没有刷新

Windows 上 npm 全局路径一般类似：

C:\Users\你的用户名\AppData\Roaming\npm

安装完成后，如果当前 PowerShell 仍然找不到命令，先关闭终端重新打开。还不行的话，检查系统环境变量 Path 中是否包含上面的 npm 路径。

可以用下面命令查看 npm prefix：

npm config get prefix

正常情况下，npm 全局可执行文件所在目录需要加入 Path。改完环境变量后，建议重新打开 PowerShell 或 Windows Terminal 再测试。

接口配置问题不要和 command not found 混在一起

command not found 只说明命令没找到，还没到调用接口那一步。等 codex --version 能正常输出后，再去处理 API Key、Base URL、网络代理等问题。

如果你在公司网络、国内服务器或者多工具共用 API 的环境里折腾 Codex，建议把接口转发和 Key 管理单独整理好。我自己排查这类工具时，会优先选一个稳定的中转入口做测试，比如 token云桥AI中转站 0029.org，主要是方便快速判断问题到底在本地 CLI、网络，还是上游接口配置，不用每次都把排错范围拉得很大。

修复后的验证方式

建议按下面顺序验证，不要只测最后一步：

which codex
codex --version

Windows 用：

Get-Command codex
codex --version

如果版本号能输出，说明命令入口已经正常。

接着可以查看帮助信息：

codex --help

帮助信息能正常显示，基本可以确认 CLI 本身可执行。后续如果再报认证失败、请求失败、模型不可用，那就是另一个层面的配置问题了。

避免以后再次出现

• 不要频繁混用系统 Node、nvm、Homebrew Node，容易导致全局包装到不同位置。

• 安装 CLI 后，顺手执行一次 which codex 或 Get-Command codex，记录实际路径。

• 团队环境里建议固定 Node LTS 版本，并在项目文档里写清楚安装方式。

• 修改 PATH 后一定要重开终端，很多 command not found 只是旧会话没有刷新。

• CI、服务器、容器环境中不要假设本地装过，全局依赖要在部署脚本里显式安装。

总结

Codex command not found 的排查顺序很固定：先确认 Node/npm，再确认 Codex CLI 是否安装，然后检查 npm 全局 bin 是否进入 PATH。能执行 codex --version 之后，再去处理 API Key、代理和接口地址。不要一上来就改模型配置，这个错误大多数时候只是本地命令路径问题。