终端能运行，Codex 却找不到 npm、node、python？逐步排查任务环境

你在终端运行 npm test 正常，Codex 执行同一个任务却说找不到 npm；或者终端里的 Python 能导入项目依赖，Codex 换了一个解释器后就失败。先确认：两次命令是否在同一个执行环境里，以及实际解析到了哪个程序。 “电脑上装过”还不足以证明任务能够使用它。

当 npm: command not found 出现在 Codex 任务里，而终端正常时，要对照的是任务启动的子进程（subprocess）、shell 环境和 PATH。下文按执行位置、运行时和配置逐项检查。如果连 codex 本身都无法启动，先看 Codex 安装来源与 PATH 排查。

先按错误选择排查方向

现象	先检查	下一步
npm、node 或 python 无法识别	执行主机、命令解析	取得两侧环境对照
命令存在，但版本或解释器不同	版本管理器、虚拟环境	选择项目要求的运行时
找不到模块、pytest 或测试脚本	项目目录、项目依赖	核对安装与脚本入口
权限拒绝、脚本策略阻止	完整错误及对应文件	另查权限或策略，不按缺命令处理

Windows 常见的“不是内部或外部命令”“无法将……识别为 cmdlet”也属于命令发现线索；ModuleNotFoundError、Cannot find module 则说明已经运行到另一个阶段。保留第一条错误，别只摘录最后的“测试失败”。

1. 让 Codex 在失败的位置取得只读证据

适用情况： 终端正常，任务内失败，尚不清楚差异在哪里。

先记录客户端和版本：桌面应用、CLI 或 IDE 扩展；再记录实际执行位置：本机、WSL、SSH、容器、云端，以及当前项目或 worktree。IDE 窗口在本机，不代表任务也在本机执行。

可以给 Codex 这段诊断要求：

先不要安装软件、修改配置或切换权限。
请在刚才失败的同一执行主机、项目目录和命令工具里，
只读检查当前目录、实际使用的 shell、node/npm/python 的解析位置，
以及项目已有的运行时版本文件、虚拟环境和测试脚本。
保留原始失败命令与错误；只查看相关 PATH 和必要变量，不输出密钥。
如果检查需要换主机、目录或工具，请明确说明，先不要替换原任务。

然后在能成功的终端和 Codex 实际执行命令的工具里分别运行对应检查。桌面应用的集成终端或项目 Action 能成功，也不能替代对失败命令工具的检查。

macOS / Linux，Bash 或 zsh：

pwd -P
uname -s
printf 'shell entry: %s\n' "$0"
for runtime_name in node npm python python3; do
  printf '\n%s\n' "$runtime_name"
  command -v "$runtime_name" || true
  type -a "$runtime_name" 2>/dev/null || true
done
printf '%s\n' "$PATH" | tr ':' '\n'

command -v 和 type -a 用于区分程序路径、别名、函数及多个入口；$0 只是 shell 或脚本入口线索，还要结合任务工具显示的实际启动方式判断。找不到某个命令可以继续检查其他项，不必先安装全部四个命令。

Windows PowerShell：

Get-Location
$PSVersionTable.PSVersion
foreach ($runtimeName in 'node', 'npm', 'python', 'python3') {
  Write-Output "--- $runtimeName ---"
  Get-Command $runtimeName -All -ErrorAction SilentlyContinue |
    Select-Object CommandType, Name, Source, Path
}
$env:Path -split ';'

Get-Command 的 -All可以列出同名命令及其解析顺序。若显示的是函数、别名或脚本，要继续核对它依赖的初始化；不要把“存在这个名字”直接当成目标可执行文件可用。WSL 中使用 Linux 检查，不把这段 Windows PowerShell 命令混进去。

预期结果： 两组输出能够对应到具体主机、目录、shell 和入口。对已确认可信的程序，再分别查 node --version、npm --version，或该 Python 解释器的版本。PATH 有差异只是线索，必须结合实际命令解析和错误确认；公开求助前遮去用户名、私有路径与敏感参数。

2. 主机或目录不同：在目标环境准备项目

适用情况： 成功发生在本机，失败发生在 WSL、SSH、容器、云端，或新 worktree。

先对照第 1 步结果，进入真正要运行任务的项目目录，核对项目说明、package.json、锁文件、.nvmrc / .node-version 或 Python 版本要求。按该项目已经采用的工具链准备目标环境；本机的 Node 安装、node_modules 和 .venv 不会自动变成远程环境的依赖。

OpenAI 本地环境文档说明，桌面端 Codex 的新 worktree 可能缺少未提交进仓库的依赖或文件；创建新 worktree 时可运行 setup script。只在确实使用该功能时，按项目现有流程配置初始化，并检查脚本退出状态。其他客户端与云端需使用各自环境设置，不能照搬这个入口。

验证： 目标目录中的运行时符合项目要求，依赖准备完成，原项目脚本开始执行。如果 setup script 自己就找不到 npm，应先进入第 3 步定位运行时；单独写上安装依赖命令不会补出 npm。初始化脚本里一次 export 或激活环境，也不能未经验证就认为会传给之后所有任务命令。

若只是 worktree 位置认错，继续看 定位 Codex 实际改动目录，不用重新安装整套工具。

3. 主机相同：检查 shell 初始化与 Node 版本管理器

适用情况： 终端解析到 nvm、fnm、其他 shim 或自定义函数，任务内却没有相同入口。

Bash 启动文件规则区分登录、交互与非交互启动。不能只因为终端读取过某个启动文件，就认为任务 shell 也一定读取；也不能把所有 Codex 客户端都认定为同一种 shell。先查实际启动方式及你已经配置的初始化位置。

nvm按用户安装、按 shell 使用。已确认项目使用 nvm、存在可信的 nvm.sh 和 .nvmrc，且目标版本已安装时，可以在目标任务的同一次 Bash / zsh 命令里做一次局部验证。替换下面的实际路径，先确认项目确实定义了 npm test：

(
  . "/已核实的nvm目录/nvm.sh" &&
  nvm use &&
  node --version &&
  npm --version &&
  npm test
)

初始化与项目命令放在同一次调用中，避免只在上一个临时 shell 里切了版本。括号限定这次 shell 环境变化的范围。若 nvm use 报版本未安装，先按项目要求处理该版本，不以随便选一个最新版代替。

使用 fnm时，先确认 fnm 自身来自可信安装，且项目需要的版本已安装。Bash 的初始化是 eval "$(fnm env --shell bash)"，zsh 把其中的 shell 改为 zsh。Windows PowerShell 对应：

fnm env --shell powershell | Out-String | Invoke-Expression
fnm use

只在初始化、版本选择都成功后，在同一次任务调用里继续查 node/npm 版本并运行项目脚本。若 fnm 自己也找不到，先核对它的安装入口；不要继续执行初始化。以上是在运行可信管理器生成的 shell 代码，不是让你执行陌生脚本。从现有初始化中提取必要步骤，不默认执行整份交互 profile；普通别名或函数也不会自动成为其他 shell 的可执行文件。

预期结果： 初始化后，任务解析到项目所需运行时，原脚本可以执行。若只在这一次调用成功，新任务又失败，还需要把已验证的最小初始化放到项目可信的命令包装脚本或适用的环境入口中，再从正常任务入口复验。不要把一次手动成功写成已经永久修好。

如果可信的实际程序路径可以运行，但裸命令不行，检查该命令目录是否出现在任务 PATH 中。对普通安装可先在单次命令作用域内验证目标目录；涉及 shim 时还要核对管理器需要的变量，不能直接复制另一主机或另一个用户的整条 PATH。无需为这个问题重装 Codex。

4. Python 能启动，却不是项目的解释器

适用情况： 终端使用虚拟环境，任务中找不到 python，或已经出现模块缺失、依赖版本不符。

先检查目标目录是否真有项目的 .venv，再用其解释器查询，不先全局安装缺失模块。下面假设环境目录就叫 .venv；若项目使用其他管理器或目录，换成项目记录的实际入口。

macOS / Linux：

./.venv/bin/python -c 'import sys; print(sys.executable); print(sys.prefix); print(sys.base_prefix)'

Windows PowerShell：

& .\.venv\Scripts\python.exe -c 'import sys; print(sys.executable); print(sys.prefix); print(sys.base_prefix)'

Python 官方 venv 文档说明，可以直接调用环境内的解释器，无需先激活。普通 venv 中 sys.prefix 与 sys.base_prefix 不同；仅看 VIRTUAL_ENV 是否设置并不可靠。

预期结果： 路径指向目标项目的解释器。若项目确实使用 pytest 且已安装，再通过这个解释器执行项目规定的 -m pytest 及原参数；不要用另一个全局 pytest 验证。环境不存在时，按项目文档在目标目录重新建立并安装声明的依赖；venv 一般不能从另一主机或旧 worktree 直接搬来使用。

只有 python3 而没有 python，也不一定是安装损坏。先确认项目要求的命令与版本，再调整项目入口；不要为得到一个命令名字就覆盖系统 Python。Windows 如果解析到应用执行别名、启动商店或脚本策略错误，按那条具体错误继续处理。

5. 配置过滤了子进程环境：先确认配置真的生效

适用情况： 已排除主机、目录和运行时初始化问题，并且当前执行端确实使用 Codex 本地配置；特别是曾自定义 shell_environment_policy 的 CLI。

官方环境策略控制 Codex 传给子命令的环境变量。检查实际生效层里的 inherit、set 和 filters：空继承、缺失路径、include 白名单或后续 shell 初始化，都可能改变最终可见值。core 不是“自动补齐开发环境”，也不会替你安装 Node 或激活项目虚拟环境。

先沿用 config.toml 配置加载排查，核对执行端、配置路径和覆盖来源。若仍不清楚这一层能否传入变量，可以在已备份的目标配置中合并一个无敏感信息的临时标记；已有同名表时不要重复声明：

[shell_environment_policy.set]
CODEX_ENV_PROBE = "task-env-check"

保存工作并按当前客户端流程重新加载或新开会话，保持项目、主机和其他参数一致，让 Codex 在原命令工具里只打印该标记：

printf '%s\n' "${CODEX_ENV_PROBE:-unset}"

Windows PowerShell 中只查看 $env:CODEX_ENV_PROBE。

预期结果： 得到 task-env-check，说明该标记到了子进程；它还不能证明 PATH 正确。若没有，继续核对加载层、include 过滤和客户端支持范围，不直接放宽所有过滤。官方规定，自定义 include 可以再过滤掉 set 的值；旧 exclude / include_only 数组不能与新 filters 在同一配置层混用。

确认原因后，只调整项目确实需要的环境项，并验证没有丢掉必要的系统目录。不要把 inherit = "all"、导出全部环境、关闭安全过滤或扩大执行权限作为默认修复。验证结束移除这个临时标记，保留其他原配置；受管理策略约束时按组织允许的方式处理。

6. 用原任务验证，而不是只看版本号

适用情况： 某一项修复已经让命令可见，需要确认问题真正解决。

回到原客户端、原执行主机和目标项目，使用正常的任务入口重新运行原项目命令和原参数。若项目的检查会启动服务、写产物或访问外部系统，仍遵守原项目的运行约束。

验证层	成功依据	失败后处理
环境与入口	目录、运行时路径和版本符合项目要求	继续对照环境与初始化
项目命令	原 npm script 或 Python 项目检查实际执行	按新的第一条错误继续排查
检查结果	退出状态、日志、实际检查范围符合预期	区分环境恢复与真实测试失败

例如，原任务是 npm test，就应检查项目定义的 test script 确实运行，而不是绕过它去执行某个缓存里的测试二进制。Python 原任务依赖项目虚拟环境，也应在那个解释器下完成相同检查。没有运行的步骤要明确报告，不能把“找到 node”当成“测试通过”。

再从新的正常任务调用复验一次，确认修复没有只停留在刚才的临时 shell。如果现在命令已经能运行，但出现依赖冲突、脚本不存在或测试断言失败，说明错误阶段变了，应处理新问题；不必继续反复改 PATH。

仍失败时，提供一份足够定位的记录

保留客户端版本、实际执行位置、项目目录、shell、版本管理器、两侧命令解析结果、原命令和第一条错误，以及每次单项调整后的结果。CLI 版本无法替代桌面或扩展版本；求助前脱敏路径和参数，不提交整份环境、认证目录或包含密钥的配置。

若是任务输出或退出状态难以判断，继续查 codex exec 输出与退出排障；若 IDE 面板本身没有启动，转到 VS Code 扩展排障。

本文于 2026-10-17 核对官方资料，并在 macOS 的隔离目录中验证 Bash / zsh 命令解析、子进程 PATH 差异与 Python venv 解释器检查。没有改动真实用户的 shell 配置，没有调用真实模型或复现所有客户端故障；Windows 与版本管理器初始化依据对应官方资料，不表述为 Windows 实机修复实测。