先关闭所有终端再新开PowerShell执行node -v和npm -v；若npm报脚本策略错误，运行Set-ExecutionPolicy RemoteSigned -Scope CurrentUser；版本需≥v20，中文用户名建议换英文账户或用WSL2。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
确认Node.js是否真正就位
打开 PowerShell（无需管理员权限），执行：node -v 和 npm -v。若任一命令报“不是内部或外部命令”，说明 Node.js 未被系统识别，【PATH 环境变量根本没加载成功】。
此时不要重装，先彻底关闭所有终端窗口——包括 VSCode 内置终端、Windows Terminal、CMD 和 PowerShell 所有实例，再全新打开一个 PowerShell，重新运行那两条命令。很多用户卡在这一步，只是因为旧会话仍缓存着安装前的环境变量。
检查 npm 脚本执行策略（Windows 独有致命坑）
如果 node -v 正常但 npm install -g @openai/codex 报错：npm : 无法加载文件 C:\Program Files\nodejs\npm.ps1，因为在此系统上禁止运行脚本，这是 PowerShell 默认策略拦截了本地脚本执行。
执行以下命令解除限制（仅当前用户生效，安全且无需管理员）：Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
这一步必须做，否则所有全局 npm 包安装都会失败，且错误提示完全不提“策略”二字，纯靠经验定位。
验证 Node.js 版本是否满足 Codex 硬性要求
第一步：运行 node -v，确认输出为 v20.11.0 或 v22.2.0 这类 ≥20 的版本号。Codex 明确要求 Node.js ≥18，但实测 v18.x 在 Windows 上存在 fetch API 兼容性缺陷，会导致 codex login 卡在回调页。
第二步：若版本低于 v20，去 nodejs.org 下载最新 LTS（当前为 v22.12.0），安装时务必勾选 “Add to PATH” 选项。旧版残留不卸载会导致多版本冲突，PATH 中可能优先读到老版本。
ZenHeart zenlink 与 zenlink-mcp 为 OpenClaw，涵盖安装、MCP 注册、钩子接线、入站轮询及升级维护。
第三步：装完后，在全新终端中再次执行 node -v → npm -v → npm install -g @openai/codex@latest，三步全部通过才算过关。
排查中文用户名导致的静默失败
如果你的 Windows 用户名含中文（如“张三”），Codex 在初始化时会尝试创建 C:\Users\张三\.codex 目录，但 Node.js 的 fs 模块在 Windows 上对该路径编码处理异常，结果是命令看似执行完成，实际中途静默退出，.codex 文件夹根本没生成。
方法一（推荐）：启用 WSL2，用 Ubuntu 子系统全程操作，彻底避开 Windows 路径层问题；
方法二：新建纯英文本地账户（如 codexdev），登录后重走安装流程；
⚠️ 绝对禁止直接重命名 C:\Users\中文文件夹 ——这会破坏系统权限链和注册表映射，微软明确列为不可逆高危操作。
定位 npm 全局 bin 路径是否已加入系统 PATH
执行 npm config get prefix，典型输出为：C:\Users\你的英文用户名\AppData\Roaming\npm。
把这个完整路径手动添加进系统环境变量的 Path 列表（不是用户变量，是系统变量），然后彻底关闭所有终端再重开。
验证是否生效：在新终端中输入 codex --version。若仍报 command not found，说明 PATH 没生效或路径拼写错误——比如漏掉了 \npm 后缀，只填了 C:\Users\xxx\AppData\Roaming。
