在本地终端使用 Codex 模型进行代码编写、错误解释或文档生成，却卡在安装环节？npm 报错、命令找不到、Windows 下找不到 .codex 文件夹……这些常见问题其实都有简单解法。从零开始到成功运行，只需四步：安装 Node.js 18 以上版本、全局安装 Codex CLI、创建配置目录与文件、最后配置 API 密钥。
安装 Node.js 与配置基础环境
Codex CLI 基于 Node.js 运行，因此首要任务是安装 Node.js，且必须为 18 或更高版本。低于 18 会直接触发 “Unsupported engine” 错误，导致安装失败。前往 nodejs.org 下载最新的 LTS 版本（目前为 v20.15.1），双击安装包一路 Next 即可。
安装完成后立即验证：打开终端（Windows 使用 PowerShell 或 Git Bash，macOS/Linux 使用默认 Terminal），执行 node -v && npm -v。如果只显示 node 版本，而 npm 提示 command not found，说明安装时未勾选 “Add to PATH”，重新安装并确保勾选即可。
这一步千万不能省略，否则后续所有 npm 命令都无法执行——这是硬性前提，并非夸大其词。
全局安装 Codex CLI 工具
在终端中执行：
npm install -g @openai/codex
国内用户若遇到超时或 ECONNRESET 错误，建议切换至淘宝镜像源以提升速度：
npm install -g @openai/codex --registry=https://registry.npmmirror.com
安装全程静默，无交互弹窗。完成后不要立即关闭终端——继续验证。
验证安装是否成功
直接在终端中输入：
codex --version
如果看到类似 codex-cli 0.46.0 的版本号，说明安装成功。若出现 command not found，多半是 npm 的全局 bin 路径未添加至系统 PATH。Windows 用户请检查安装时是否勾选 “Automatically install the necessary tools”；macOS/Linux 用户可使用 echo $PATH | grep -q "node_modules" || echo "PATH missing" 快速自查。
创建配置目录与文件
第一步：创建 .codex 目录
macOS/Linux 执行：mkdir -p ~/.codex
Windows 执行：mkdir %USERPROFILE%\.codex（在 PowerShell 中运行）
注意：Windows 资源管理器默认隐藏以点开头的文件夹，无法通过图形界面手动新建 “.codex” 文件夹，必须使用命令行创建，否则 Codex 启动时会静默失败。
第二步：进入该目录，新建空文件 config.toml
macOS/Linux 使用：touch ~/.codex/config.toml
Windows 使用：type nul > %USERPROFILE%\.codex\config.toml
第三步：向 config.toml 写入最简可用配置
macOS/Linux（使用 nano 编辑）：nano ~/.codex/config.toml → 粘贴以下内容 → Ctrl+O 保存 → Ctrl+X 退出
Windows（使用记事本）：右键 → “编辑” → 粘贴 → 保存为 UTF-8 编码，文件名必须带英文引号以防止自动添加 .txt："config.toml"
model_provider = "openai"model = "gpt-5-codex"
配置 API 密钥（两种方式可选）
方法一：环境变量方式（推荐 macOS/Linux）
编辑 shell 配置文件：nano ~/.zshrc（macOS）或 nano ~/.bashrc（Linux）
末尾追加一行：export OPENAI_API_KEY="sk-xxx"（将 sk-xxx 替换为从 API 提供商获取的真实密钥）
保存后立即生效：source ~/.zshrc
方法二：auth.json 文件方式（Windows 用户首选）
在 %USERPROFILE%\.codex 目录下新建文件 auth.json，内容严格为：
{"OPENAI_API_KEY":"sk-xxx"}（前后无空格、无注释、无逗号，JSON 格式必须合法）
此步骤若写错引号或遗漏大括号，Codex 启动时会报 invalid character 并退出，且不提示具体行数。以上两种方法任选其一，配置完成后即可使用 codex 命令开始体验。