结论先说
- 报错不是工具没装,而是 Codex 派生子进程拿到的
PATH和你的交互终端不一样。常见有三大原因:非交互 Shell 跳过.bashrc/.zshrc、图形界面桌面端只继承系统默认最小PATH、以及config.toml的环境变量策略过滤了部分变量。 - 命令行用户最快见效的方法:先激活环境再启动
codex,并配好shell_environment_policy。在终端里先执行nvm use或conda activate,配合~/.codex/config.toml里的[shell_environment_policy]设为inherit = "all",子进程就能直接继承当前生效的可执行文件路径。 - 桌面端用户与长期工程化方案:用显式路径代替 Shell Hook 函数。图形界面应用不会读交互式
.zshrc,建议通过[shell_environment_policy.set]固定补充PATH,或在仓库AGENTS.md里约定直接使用./.venv/bin/python、conda run -n <环境名>等绝对或自包含调用。 - 切忌为了省事关闭敏感变量过滤。开放
inherit = "all"时保持ignore_default_excludes = false,可让 Codex 自动剔除名称里带TOKEN、SECRET、KEY的机密变量,只把运行工具链交给子进程。 - 把工具链修顺后连续跑单测和构建更容易进入高配额消耗阶段。国内无外币卡的用户可在本站开通 ChatGPT Plus 或高配额 ChatGPT Pro,团队多人研发可了解 ChatGPT Business 团队定制。

图:本站根据 OpenAI Codex 官方文档:Configuration Reference 与环境继承机制整理的示意图
本文根据 OpenAI Codex 官方文档《Configuration Reference》《Environment variables》《Codex CLI》及官方 GitHub 仓库配置说明整理,资料核对于 2026-11-19。配图为本站整理的示意图,不是界面截图。本站(bigolab.com)不是 OpenAI 官方网站。
适用于谁
- 在本地终端里手工运行
node、pnpm、python、pytest、conda或uv都正常,但让 Codex CLI 或桌面端执行命令时频繁报command not found或「不是内部或外部命令」的开发者; - 使用
nvm、fnm、conda、pyenv或 Apple Silicon Homebrew 管理多版本运行时的 macOS / Linux / WSL 用户; - 想在保留密钥过滤安全性的前提下,把项目工具链
PATH稳定透传给 Codex 子进程的人。
一、为什么自己终端找得到,Codex 却报 command not found
理解下面三层机制,就能一眼看出自己卡在哪一步:
- 非交互子 Shell 不执行
.bashrc/.zshrc:像nvm、conda、pyenv默认把初始化函数和动态改写PATH的语句插在交互式配置文件里。Codex 执行命令时拉起的是非交互子进程,这些钩子函数根本不会运行,导致nvm管理的node、npm与conda里的python全部隐身。 - macOS / Windows 桌面端继承精简系统路径:从 macOS 程序坞(Dock)或聚焦搜索直接点开的桌面 App,只拿到系统级最小
PATH(通常是/usr/bin:/bin:/usr/sbin:/sbin),默认不包含 Apple Silicon 的/opt/homebrew/bin、~/.local/bin或用户自装的语言工具链目录。 - 环境变量继承策略收紧:出于安全考虑,Codex 允许在
config.toml中通过[shell_environment_policy]控制只继承核心变量(core)或白名单变量(include_only);若曾经为了隔离环境变量改动过该段落,就容易顺带把NVM_BIN、CONDA_PREFIX或自定义路径挡在外面。更多变量缺失报错也可对照 /guides/codex-missing-environment-variable。
二、四步修复 Shell PATH 继承(CLI 与桌面端通用)
以下为本站建议的 4 步修复流程,兼顾多版本切换灵活性与环境变量安全边界:

图:本站根据 OpenAI Codex 官方文档:Environment variables 与仓库实践整理的示意图
第 1 步:先验证 Codex 子进程实际看到的 PATH
在 Codex 对话里直接让它执行 echo $PATH(Windows PowerShell 下执行 $env:Path)与 which node python(Windows 下用 where.exe node python),再和你自己普通终端的输出对比,一眼就能看出少了哪几段目录。
第 2 步:在 ~/.codex/config.toml 配置 [shell_environment_policy]
打开 ~/.codex/config.toml(Windows 位于 %USERPROFILE%\.codex\config.toml),配置环境变量继承策略,同时保持默认的敏感变量排除规则开启:
toml
[shell_environment_policy]
inherit = "all"
ignore_default_excludes = false
# 如仅需兼容自定义 Shell Profile 初始化,可按当前版本支持情况开启:
# experimental_use_profile = true
也可以先在命令行临时测试单次覆盖而不改动配置文件:
bash
codex -c shell_environment_policy.inherit=all
如果你使用的是桌面端 App,且希望固定把 Homebrew、nvm 默认版本或 Conda 环境目录注入子进程,可使用 [shell_environment_policy.set] 显式指定(按你的实际路径替换,建议先在终端用 dirname $(which node) 查出真实目录):
toml
[shell_environment_policy.set]
PATH = "/opt/homebrew/bin:/Users/你的用户名/.nvm/versions/node/v22.12.0/bin:/usr/local/bin:/usr/bin:/bin"
关于 config.toml 其余参数说明,可进一步参考 /guides/codex-config-toml-complete-guide。
第 3 步:针对 nvm / conda / Python 虚拟环境的专项加固(本站建议)
- Node / nvm 用户:启动 Codex CLI 前先在当前终端跑好
nvm use,或者给默认版本建立固定路径并放入登录级配置(macOS zsh 为~/.zprofile,bash 为~/.profile)。 - Python / Conda / uv 用户:在项目内优先使用本地
.venv虚拟环境,或者要求 Codex 用conda run -n <环境名> pytest替代必须依赖交互式conda activate的写法。 - Windows 用户:修改完「系统环境变量」里的
Path(例如补充 Node 安装目录、Python 及其Scripts目录)后,必须彻底关闭并重新打开终端窗口和 Codex 桌面端,新Path才会生效。
第 4 步:把项目指定解释器写进 AGENTS.md(本站建议)
为了防止多成员协作或新开会话时再次找错工具,在项目根目录 AGENTS.md 里补充两行约定:
markdown
## 运行环境与工具链
- Python 测试统一通过 `./.venv/bin/pytest`(或 `uv run pytest`)执行,不要直接调用系统 `python`。
- Node 命令使用当前目录 `pnpm`,如找不到请先检查 `.nvmrc` 指定版本路径。
关于规则文件加载逻辑可看 /guides/codex-agents-md-how-it-reads。
排障与订阅提示:环境工具链打通后,Codex 自动执行测试、类型检查与多轮修复的效率会大幅提高,同时推理配额消耗也会随之上升。若 Plus 额度吃紧,可按需升级 ChatGPT Pro 充值 或选购 ChatGPT Pro 5x iOS 可覆盖档;新号登录遇到手机号校验拦路可了解 Codex 注册手机验证服务。
三、仍提示找不到命令时的补充排查
- 核对命令是否装在另一套环境里:Windows 开发者常混用本机 PowerShell、Git Bash 和 WSL2;装在 WSL2 里的
node在 Windows 原生 PowerShell 里查不到,反之亦然。运行which -a/where.exe确认当前终端与目标工具处于同一套系统内。 - 确认不是命令拼写或可执行权限问题:自编脚本若缺少
chmod +x权限或 shebang 行带了 Windows CRLF 换行符(\r\n),在 Linux / macOS 下也会报类似not found的误导性错误。若伴随其他系统报错,可对照 /guides/codex-common-errors-summary 继续分流。
常见问题
问:为什么我把 export PATH=... 写进了 ~/.zshrc,从桌面端启动 Codex 还是找不到 Homebrew 的命令?
答:macOS 图形应用启动时不经过交互式 zsh,因此不读取 ~/.zshrc。可以改用终端启动 Codex CLI,或在 ~/.codex/config.toml 的 [shell_environment_policy.set] 中显式写入包含 /opt/homebrew/bin 的 PATH,也可在 AGENTS.md 中指明二进制绝对路径。
问:开启 inherit = "all" 会不会把我的 API 密钥全部暴露给沙箱子进程?
答:只要同时保持 ignore_default_excludes = false(默认行为),Codex 仍会按内置安全策略自动过滤包含常见密钥特征词(如 KEY、SECRET、TOKEN)的环境变量。如果项目脚本确实需要某个特定变量,再按最小权限原则单独放行即可,详情见 /guides/codex-missing-environment-variable。
问:国内没有外币卡,或者 Plus 额度不够想升级 Pro / 团队版怎么开通?
答:可前往本站 AI 会员充值总览 按需选购 ChatGPT Plus(含 Plus iOS 可覆盖版)或高配额 ChatGPT Pro,团队多人研发亦可选择企业定制方案。支持支付宝、微信支付及 AlipayHK,提供免交密码自助卡密兑换与增值税发票,具体以页面实时展示为准;售后遵循掉订阅按剩余天数折退、封号不在质保范围的说明。
相关教程
- Codex 报 missing environment variable 怎么办
- Codex config.toml 完整配置指南
- Codex 怎么读取 AGENTS.md 规则文件
- Codex 常见报错总表
参考资料
- OpenAI Codex 官方文档:Configuration Reference — https://developers.openai.com/codex/config-reference
- OpenAI ChatGPT Learn:Configuration Reference — https://learn.chatgpt.com/docs/config-file/config-reference
- OpenAI ChatGPT Learn:Environment variables — https://learn.chatgpt.com/docs/config-file/environment-variables
- OpenAI ChatGPT Learn:Codex CLI — https://learn.chatgpt.com/docs/codex/cli
- OpenAI Codex 官方 GitHub 仓库 — https://github.com/openai/codex
0 条评论
还没有评论,来抢沙发~