【Bug已解决】Codex CLI 报 command not found：从 npm 全局路径到 PATH 的排查与修复

1. 先别急着重装，command not found 到底卡在哪一步

codex: command not found这个报错，本质上是 shell 在 PATH 列出的所有目录里翻了一遍，没找到名叫codex的可执行文件。它跟 Codex CLI 本身能不能跑、模型能不能调通完全是两码事——命令都还没被找到，后面的逻辑根本没机会执行。

Codex CLI 是通过 npm 分发的命令行工具，安装时 npm 会做两件事：在全局 bin 目录放一个入口脚本，同时拉取对应平台的原生二进制。这两件事任何一件没落地，你敲codex都会得到 command not found。所以排查思路就三条线索：npm 全局 bin 目录在哪、这个目录有没有进 PATH、原生二进制有没有真的下载下来。

适合谁看：刚用npm install -g @openai/codex装完却发现命令用不了的开发者；在 CI 或公司内网环境装完同样报错的同学；以及混用过 npm、pnpm、yarn 导致环境混乱的人。下面按顺序走一遍，基本能定位到你的具体原因。

2. 用 TaoToken 把 Codex CLI 跑起来的前置准备

Codex CLI 装好之后要真正干活，得有一个能调模型的入口。我这边习惯用 TaoToken 做统一接入，它的 API 地址是https://taotoken.net/api，兼容常见的 OpenAI 风格调用方式，Codex CLI 这类工具配置起来比较省事。

在动手排查 PATH 之前，建议先把两样东西准备好：一个是可用的 API Key，另一个是确认你的 Node.js 和 npm 版本别太老。Node 建议 18 以上，npm 建议 9 以上，老版本 npm 的全局目录行为和现在差异较大，容易让排查更绕。

获取 Key 的入口在控制台的 API Keys 页面，登录后新建一个即可。如果你还没决定用哪种方式接入，可以先到模型对话页面体验一下调用是否通顺，确认账号和额度没问题，再回到本地折腾 CLI。这样能避免把「命令找不到」和「Key 无效」两类问题混在一起排查。

提示：先把 Key 拿到手再排查 PATH，是因为 PATH 修好之后你马上要验证codex能不能真正发起请求，两步连着做效率最高。

3. 可复制的排查与修复配置

3.1 确认 npm 全局 bin 目录并检查 PATH

第一步永远是看 npm 把全局命令放哪了：

npm config get prefix

这个命令会输出一个路径，Linux/macOS 下全局可执行文件通常在<prefix>/bin，Windows 下通常在<prefix>本身。拿到路径后，看它在不在 PATH 里：

echo $PATH

如果输出里没有<prefix>/bin，那 command not found 的原因就找到了。把它追加进 shell 配置：

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

用 bash 的话把~/.zshrc换成~/.bashrc。改完新开一个终端，再敲which codex验证：

which codex

能打印出路径就说明 shell 已经能找到它了。

3.2 检查原生二进制是否下载完整

PATH 没问题但执行仍然异常，就要看包目录里的原生二进制在不在：

npm root -g ls "$(npm root -g)/@openai/codex"

正常应该能看到入口脚本和对应平台的二进制文件。如果目录里空荡荡或者缺了平台相关的文件，说明安装时的下载环节没完成。可以手动触发重建：

npm rebuild -g @openai/codex

3.3 排查 postinstall 脚本是否被跳过

有些环境会全局设置ignore-scripts，导致依赖原生二进制的 postinstall 脚本被跳过，安装日志看着成功，实际关键文件没落地：

npm config get ignore-scripts

如果返回true，临时关掉再重装：

npm config set ignore-scripts false npm install -g @openai/codex

3.4 统一包管理器，避免混装

pnpm 和 yarn 的全局目录跟 npm 不一样，混用很容易出现「装了但找不到」。先逐个卸载，再统一用 npm 重装：

npm uninstall -g @openai/codex pnpm remove -g @openai/codex yarn global remove @openai/codex npm install -g @openai/codex

3.5 配置 Codex CLI 指向 TaoToken

命令能找到之后，把模型接入配好。Codex CLI 一般通过环境变量读取 API 地址和 Key：

export OPENAI_API_KEY="你的 TaoToken Key" export OPENAI_BASE_URL="https://taotoken.net/api"

想让它长期生效，把这两行也写进~/.zshrc或~/.bashrc。如果你更习惯用 Coding Plan 的方式管理长期编码任务，可以在控制台里对应配置，思路是一样的——把地址和凭证交给 CLI。

4. 验证请求与成功结果

配置完成后，先确认命令本身可用：

codex --version

能打印版本号，说明 PATH 和二进制都没问题。接着发一个最小请求验证链路：

codex "用一句话解释什么是递归"

如果模型正常返回内容，说明从 CLI 到 TaoToken 的整条链路是通的。这一步很关键，因为它把「命令找不到」和「请求失败」两类问题彻底分开了——前者是环境问题，后者是配置或网络问题。

实测下来，大部分 command not found 在 3.1 那一步就解决了，剩下的小部分集中在 postinstall 被跳过和包管理器混用上。验证通过后，建议把codex --version加进你的环境初始化脚本，新机器一装完就跑一次，早发现早处理。

5. 本篇常见错排查

改了 .zshrc 但没生效：确认你改的是当前 shell 对应的配置文件。用echo $SHELL看默认 shell，zsh 改.zshrc，bash 改.bashrc。改完必须source或新开终端。

Windows 下提示无法识别：除了 PATH，还要确认全局目录里生成了.cmd或.ps1脚本。PowerShell 执行策略可能拦截.ps1，这类报错通常是「找到了但拒绝执行」，跟纯 command not found 不同，需要单独处理执行策略。

Docker 构建时找不到命令：构建容器的网络环境跟主机不同，npm install -g那一层可能没真正下载成功。在 Dockerfile 里加一行RUN codex --version，让问题在构建阶段就暴露，而不是等到运行容器才发现。

之前能用突然不行了：某些软件安装会重写 shell 配置文件，把 PATH 覆盖掉。检查.zshrc的最近修改时间，确认 PATH 那行还在不在。

安装日志一堆 warning 但显示成功：重点看 warning 里有没有 postinstall 失败或网络超时的字样，这类警告往往是后续 command not found 的前兆，出现就主动重装一次确认。

6. 把 Codex CLI 接进日常编码流程

命令能跑通只是起点。真正提升效率的做法，是让 Codex CLI 承担日常的代码补全、重构建议和脚本生成，把重复劳动交出去。我一般会在项目根目录放一个简短的说明，写清楚团队统一用 npm 安装、统一走 TaoToken 接入，新成员照着做就能少踩环境坑。

如果你打算长期在编码和 Agent 场景里用，可以了解下 Coding Plan 的配置方式，把额度和管理集中起来；只是临时验证模型效果，模型对话页面就够用。接入过程中遇到 Key 或地址相关的问题，接入文档里有更细的参数说明，配合 API Keys 页面一起看会更快定位。

最后留一个自检习惯：每次换机器或重装环境，先跑npm config get prefix、which codex、codex --version这三条，三十秒就能确认环境是否健康，比等到写代码时才发现命令用不了要从容得多。