Codex CLI教程（一） | 安装指南
Codex CLI教程（二） | 配置指南
Codex CLI教程（三） | 命令指南

一、什么是Codex CLI

Codex CLI是OpenAI推出的官方原生终端AI编程工具，基于Rust构建，开源免费，可直接在你的终端中完成代码生成、重构、BUG修复、项目分析、文档生成等全流程开发操作，支持几乎所有主流编程语言与开发场景。

---

二、必须满足的前置准备

2.1 系统与依赖要求

依赖项	最低要求	推荐配置
操作系统	Windows 10/11、macOS 12+、主流Linux发行版	Windows 11（推荐WSL2）、macOS 14+、Ubuntu 22.04+
Node.js	v20.0.0+	v22.0.0+（长期支持版）
npm	v10.0.0+	最新稳定版

2.2 安装前环境预检

安装前请先执行以下2条命令，确认你的环境符合要求，避免后续安装失败：

# 检查Node.js版本，需输出v20.0.0及以上版本
node --version

# 检查npm版本，需输出v10.0.0及以上版本
npm --version

🔴 重要提示：若Node.js版本不符合要求，请先前往Node.js官方网站下载安装对应版本，再继续后续操作。
本文不要求提前准备OpenAI账号、API Key等内容，所有认证配置均在第二篇详细讲解。

---

三、全网通用稳定安装方案

我们提供2种经过验证的稳定安装方案，优先选择npm全局安装（全系统通用、兼容性最好、更新最方便），macOS/Linux用户可选择Homebrew安装作为备用方案。

3.1 推荐方案：npm全局安装（全系统通用）

这是官方推荐、兼容性最强、最适合新手的安装方式，Windows、macOS、Linux全系统通用。

核心安装命令

# 1. 全局安装最新稳定版
npm install -g @openai/codex

# 2. 若需安装指定稳定版（避坑首选，0.91.0无已知核心bug）
npm install -g @openai/codex@0.91.0

# 3. 后续更新到最新版本
npm install -g @openai/codex@latest

# 4. 版本降级（如遇到bug时使用）
npm install -g @openai/codex@指定版本号

版本避坑提示

⚠️ 0.92版本存在已知的「粘贴内容丢失」核心bug，严禁使用，请优先选择0.91.0版本，或0.93.0及以上的稳定版本。

3.2 备用方案：Homebrew安装（macOS/Linux专属）

macOS或Linux用户，若已安装Homebrew，可通过以下命令快速安装：

# 1. 先更新Homebrew本地源
brew update

# 2. 安装Codex CLI
brew install --cask codex

---

四、安装成功验证（2步确认，无连通性要求）

安装完成后，执行以下2条命令，无需网络、无需账号，即可确认软件安装成功、可正常启动。

4.1 第一步：版本检查

执行以下命令，若正常输出版本号，说明软件已成功安装到系统中：

codex --version

✅ 成功示例输出：

0.91.0

4.2 第二步：基础功能验证

执行以下命令，若正常输出软件帮助信息，说明软件可正常启动、基础命令可正常执行：

codex --help

✅ 成功标志：终端输出Codex CLI的命令说明、参数列表、功能介绍等完整帮助内容。

---

五、安装环节高频坑速解

以下是新手安装过程中90%会遇到的问题，均提供直接可执行的解决方案，无需额外排查。

问题1：执行codex命令提示 command not found

核心原因

npm全局安装路径未添加到系统环境变量中，系统无法识别codex命令。

分系统解决方案

1. Windows系统
   1. 执行 npm config get prefix 查看npm全局安装路径
   2. 将输出的路径添加到系统「用户环境变量」的Path中
   3. 重启PowerShell/终端，重新执行命令
2. macOS/Linux系统
   1. 执行 npm config get prefix 查看npm全局安装路径
   2. 编辑终端配置文件（~/.zshrc 或 ~/.bashrc），添加以下内容：

      export PATH="npm全局安装路径/bin:$PATH"
      

   3. 执行 source ~/.zshrc（或对应配置文件）重载环境变量，重新执行命令

问题2：安装时提示权限不足/EACCES 错误

解决方案

1. Windows系统：以「管理员模式」启动PowerShell，重新执行安装命令
2. macOS/Linux系统：在安装命令前添加sudo，以管理员权限执行：

   sudo npm install -g @openai/codex
   

问题3：安装成功后，执行命令提示版本不兼容/功能异常

解决方案

优先降级到0.91.0稳定版，这是经过社区验证的无核心bug版本：

npm install -g @openai/codex@0.91.0

问题4：Windows用户专属避坑提示

1. 优先使用PowerShell（管理员模式）执行所有命令，避免CMD的兼容性问题
2. 若计划长期使用Codex CLI，强烈推荐配置WSL2环境，兼容性和稳定性远优于原生Windows环境
3. 若安装后重启终端仍无法识别命令，需重启电脑完成环境变量刷新

---