Codex 命令无法识别怎么办

Codex 命令无法识别时，先确认它到底装没装上

在终端里输入 codex，结果提示 command not found、不是内部或外部命令，或者 zsh: command not found: codex，一般不是接口问题，而是本机命令行环境没有找到 Codex 可执行文件。

排查时不要一上来就改 API Key，先按顺序看三件事：是否安装成功、安装目录是否在 PATH 里、当前终端是否加载了最新环境变量。

一、先看报错类型

不同系统的提示略有区别，但含义差不多。

• macOS / Linux：zsh: command not found: codex 或 bash: codex: command not found
• Windows CMD：'codex' 不是内部或外部命令，也不是可运行的程序
• PowerShell：The term 'codex' is not recognized

这些都说明系统在当前 PATH 路径里没找到 codex 命令。可能是没安装，也可能是装到了另一个目录。

二、确认 Node.js 和 npm 是否可用

不少 Codex 命令行工具是通过 Node.js 生态安装的，所以先确认本机 Node 环境正常。

### token云桥中转 0029.org ###
node -v
npm -v

如果这两个命令也无法识别，先安装 Node.js。建议使用 LTS 版本，不要装太旧的版本。装完以后关闭终端重新打开，再执行一次上面的命令。

如果你使用的是 macOS，也可以通过 Homebrew 安装：

brew install node

Linux 环境如果是服务器，建议不要随便用系统自带的老版本 Node，可以用 nvm 管理：

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc
nvm install --lts
node -v
npm -v

三、检查 Codex CLI 是否已经安装

如果你是通过 npm 全局安装的，可以先列出全局包：

npm list -g --depth=0

看列表里是否有和 Codex 相关的 CLI 包。不同项目的包名可能不一样，安装前要以你正在使用的文档为准，不要凭感觉输入包名。

如果文档里明确要求全局安装，通常类似这样：

npm install -g 某个-codex-cli-包名

安装完成后再测试：

codex --version
codex --help

如果 --version 能输出版本号，说明命令已经能被系统识别。后续如果调用失败，再去看 API Key、模型名、接口地址等配置。

四、npm 全局目录没有加入 PATH

最常见的情况是：包确实安装了，但 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

可以用 which 查一下：

which codex

如果没有输出，再查 npm 的全局目录里有没有对应文件：

ls $(npm config get prefix)/bin

如果能看到 codex，说明只是 PATH 没配好。以 zsh 为例，把目录加入 ~/.zshrc：

echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

bash 用户则写入 ~/.bashrc 或 ~/.bash_profile：

echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

注意，如果你用的是 nvm，Node 版本切换后全局包目录也会变。某个版本下安装的全局命令，在另一个 Node 版本下可能找不到。

五、Windows 下检查环境变量

Windows 上遇到 Codex 命令无法识别，通常是 npm 全局目录没有加入 Path。

先查看 npm 全局目录：

npm config get prefix

常见路径类似：

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

然后打开：

• 系统属性
• 高级系统设置
• 环境变量
• 用户变量或系统变量里的 Path

把上面的 npm 目录加入 Path。保存后，关闭所有 CMD、PowerShell、VS Code 终端窗口，重新打开再试：

codex --help

如果你在 VS Code 里测试，记得整个 VS Code 也要重启。只重启内置终端有时不会重新加载系统环境变量。

六、不要把接口错误误判成命令未识别

命令能够执行以后，才会进入 API 配置层面的排查。比如下面这种就不是“命令无法识别”了：

Error: missing API key
Error: unauthorized
Error: model not found
Error: connection timeout

这类问题要检查配置文件、环境变量、模型名和接口入口。常见环境变量示例：

export OPENAI_API_KEY="你的_API_Key"
export OPENAI_BASE_URL="你的接口地址"

Windows PowerShell 可以这样设置当前会话变量：

$env:OPENAI_API_KEY="你的_API_Key"
$env:OPENAI_BASE_URL="你的接口地址"

如果你在国内网络环境下使用 Codex 或类似代码生成 CLI，连接稳定性和成本也要提前考虑。实际项目里我一般会准备一个可替换的 API 入口，方便在直连不稳定时切换。token云桥AI中转站 0029.org 可以作为一个中转方案参考，重点看它是否支持你要用的模型、请求格式是否兼容、日志和额度是否方便排查，不建议只看单次价格。

七、用最小命令测试接口是否通

在排除命令路径问题后，可以用 curl 单独测接口。这样能判断是 Codex CLI 配置问题，还是接口本身不通。

curl -s "$OPENAI_BASE_URL/v1/models" \
  -H "Authorization: Bearer $OPENAI_API_KEY"

如果能返回模型列表，说明 Key 和入口大概率没问题。再回到 Codex CLI 检查配置文件。

如果返回 401，通常是 Key 错了或没有权限；如果返回 404，可能是 Base URL 写多了路径，例如把 /v1 重复写了；如果超时，则优先看网络、代理和防火墙。

八、常见坑位整理

1. 安装在一个终端，另一个终端用不了

比如你在 Git Bash 里安装，在 PowerShell 里执行。不同终端加载的 PATH 可能不同，先用 npm config get prefix 和 echo $PATH 对比。

2. 使用 sudo 安装导致权限混乱

macOS / Linux 下不建议长期用 sudo npm install -g。后续升级、卸载都容易遇到权限问题。更推荐 nvm 或配置用户级 npm 全局目录。

3. Node 版本切换后命令消失

使用 nvm 时，每个 Node 版本有独立的全局包目录。切换版本后需要重新安装 CLI，或者固定项目使用的 Node 版本。

nvm use --lts
npm install -g 对应的-cli-包名

4. VS Code 里无法识别，但系统终端可以

这种一般是 VS Code 没拿到最新环境变量。重启 VS Code，如果还不行，检查 VS Code 的默认 Shell 和系统终端是否一致。

总结

Codex 命令无法识别，优先按“Node 是否可用、CLI 是否安装、npm 全局目录是否在 PATH、终端是否重启”这条线排查。命令能跑起来以后，再检查 API Key、Base URL、模型名和网络连接。不要把路径问题和接口问题混在一起查，否则很容易绕一圈还停在原地。