Codex CLI 安装教程

Codex CLI 是 OpenAI 的终端编程智能体，可在本地项目中读取代码、修改文件、运行命令、检查改动并协助开发。

本页范围：安装、首次启动、验证、更新、卸载与常见故障处理。Onemini API 的模型、渠道与客户端接入配置，请查看项目里的《Codex 使用教程以及功能介绍》。

一、安装方式怎么选？

使用环境	建议方式	需要提前安装 Node.js 吗？	适合谁
Windows	官方 PowerShell 安装脚本	不需要	希望直接安装的 Windows 用户
macOS / Linux	官方 Shell 安装脚本	不需要	大多数 macOS、Linux 用户
已有 Node.js / npm	npm 全局安装	需要	熟悉 npm，或需要使用国内镜像的用户
macOS 已装 Homebrew	Homebrew 安装	不需要另装 Node.js	日常使用 Homebrew 管理软件的用户
Windows 主要在 Linux 环境开发	WSL 中安装	取决于选择的方式	主要在 WSL 维护项目的用户

只想尽快安装？ Windows 看第二节的 PowerShell 命令，macOS / Linux 看第二节的 Shell 命令，安装后直接跳到第五节登录。

二、官方安装脚本（无需 Node.js）

Windows：PowerShell 安装

打开 PowerShell，执行：

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

完成后重新打开 PowerShell，检查：

codex --version

macOS / Linux：Shell 安装

打开终端，执行：

完成后重新打开终端，检查：

若提示找不到 codex，先重新打开终端，再参考第七节检查命令所在位置与 PATH。

三、npm 安装与下载源选择

1. 先确认 Node.js 和 npm

npm 安装法需要 Node.js LTS，一般安装 Node.js 时会同时装好 npm；也可查看 npm 官方安装说明。

安装后重新打开终端，运行：

两条命令均返回版本号，再继续安装。Codex 的 npm 包为 @openai/codex。

2. 选择 npm 下载源

方案	什么时候用	对其他 npm 操作的影响
官方源（默认）	网络能够正常访问 npm	不需要更改配置
仅本次使用国内镜像（推荐的替代方案）	当前下载慢，但不想改日常设置	不修改全局下载源
全局切换国内镜像	经常使用国内镜像下载 npm 包	后续 npm 下载都会走镜像源
恢复官方源	镜像版本滞后、平台包缺失或安装异常	后续恢复使用官方源

方案 A：使用官方源安装

方案 B：单次使用国内镜像安装

此命令仅对本次安装生效，不会修改原来的 npm 配置。

方案 C：全局切换国内镜像后安装

需要恢复官方源时：

查看当前源：

下载源	地址
npm 官方源	`https://registry.npmjs.org/`
npmmirror 国内镜像	`https://registry.npmmirror.com/`

国内镜像可能存在同步延迟。如果找不到最新版本或缺少平台依赖，先恢复官方源。不要再使用旧的 registry.npm.taobao.org。

四、其他安装环境：Homebrew 与 WSL

macOS：Homebrew

已安装 Homebrew 的用户，可以执行：

Windows：WSL

如果主要在 Linux 环境开发，或遇到 Windows 原生兼容问题，可进入 WSL 终端，任选一种方式：

方式	WSL 内的命令	前提
官方脚本	`curl -fsSL https://chatgpt.com/codex/install.sh \| sh`	不需要 Node.js
npm	`npm install -g @openai/codex`	WSL 内已安装 Node.js 与 npm

注意：WSL 是独立的 Linux 环境。Windows 下已经安装的 Node.js/npm，不等于 WSL 中也已安装。Windows 的 C 盘一般位于 /mnt/c/；大型 Linux 项目放在 WSL 的 Linux 文件系统中通常更合适。

五、首次启动和登录

按顺序完成以下步骤：

进入项目目录：在终端中使用 cd 切换到代码所在目录。

启动 Codex：执行 codex。

完成登录：首次运行时按提示选择 Sign in with ChatGPT 或其他可用方式并完成授权。

提交第一条任务：例如“请阅读当前项目，告诉我它如何启动”。

常用操作：

目的	操作
进入项目（macOS / Linux 示例）	`cd /path/to/your/project`
进入项目（Windows 示例）	`cd C:\path\to\your\project`
启动 Codex CLI	`codex`
退出当前交互	`Ctrl+C`

上表中的项目路径只是示例，请替换为自己电脑上的实际目录。

六、如何确认安装成功？

检查项	执行命令	正常现象
检查安装版本	`codex --version`	返回 Codex 版本号
查看 CLI 帮助	`codex --help`	显示可用参数与子命令
启动交互界面	`codex`	显示交互界面或首次登录提示
检查 Node.js（仅 npm 安装需要）	`node -v`	返回 Node.js 版本号
检查 npm（仅 npm 安装需要）	`npm -v`	返回 npm 版本号

前三项可以正常运行，就基本说明 Codex CLI 安装完成。

七、常见问题速查

现象	先检查什么	处理方法
`codex` 不是命令	新终端中执行 `codex --version`	重开终端；检查安装位置及 PATH
npm 安装成功却找不到命令	`npm list -g @openai/codex --depth=0` 和 `npm prefix -g`	确认 npm 全局命令目录已加入 PATH
下载慢、找不到最新版本	`npm config get registry`	临时换镜像或恢复 npm 官方源
终端启动的是旧 Codex	检查系统中是否存在多个 `codex`	调整 PATH 优先级，或保留一种主要安装方式
WSL 里找不到 Node.js / npm	在 WSL 中执行 `node -v`、`npm -v`	在 WSL 内部安装，不要误用 Windows 的安装结果

定位命令（根据操作系统执行）：

系统	查看当前使用的 Codex 命令
Windows PowerShell	`Get-Command codex -All`
macOS / Linux	`which -a codex`

Windows 使用 npm 全局安装时，命令目录通常为 %AppData%\npm；如果目录未加入用户 PATH，可添加后重新打开终端。macOS / Linux 若使用 nvm，请确认当前终端已经加载 nvm 配置。

八、更新与卸载（按安装方式对照）

最初的安装方式	更新命令或方法	卸载命令或方法
npm	`npm install -g @openai/codex@latest`	`npm uninstall -g @openai/codex`
Homebrew	`brew upgrade --cask codex`	`brew uninstall --cask codex`
官方独立脚本	重新运行第二节对应系统的官方脚本	先定位实际二进制文件，再按对应安装说明移除

更新完成后统一运行：

如果使用独立脚本，不要在尚未确认安装路径的情况下删除系统文件。Windows 可用 Get-Command codex -All，macOS / Linux 可用 which -a codex 定位。

九、常用命令速查表

要做什么	命令
启动 Codex	`codex`
查看 Codex 版本	`codex --version`
查看帮助	`codex --help`
npm 安装	`npm install -g @openai/codex`
npm 更新到最新	`npm install -g @openai/codex@latest`
npm 卸载	`npm uninstall -g @openai/codex`
查询 npm 下载源	`npm config get registry`
切换 npm 官方源	`npm config set registry https://registry.npmjs.org/`
切换 npm 国内镜像	`npm config set registry https://registry.npmmirror.com`
检查 npm 安装的 Codex	`npm list -g @openai/codex --depth=0`

十、官方参考资料

资源	用途
Codex CLI 官方入门文档	安装、启动和使用入门
OpenAI Codex GitHub 仓库	官方脚本、发行版本与最新说明
Codex CLI 命令参考	CLI 命令与参数
Node.js 官网下载	安装 Node.js LTS
npm 官方安装说明	npm 安装与环境准备
Codex npm 包	查看 npm 发布版本
Homebrew 官网	macOS Homebrew 安装

教程中的 codex 指 Codex CLI（终端程序），不是 Codex 网页端或 IDE 扩展。

Codex CLI 安装教程

一、安装方式怎么选？#

二、官方安装脚本（无需 Node.js）#

Windows：PowerShell 安装#

macOS / Linux：Shell 安装#

三、npm 安装与下载源选择#

1. 先确认 Node.js 和 npm#

2. 选择 npm 下载源#

四、其他安装环境：Homebrew 与 WSL#

macOS：Homebrew#

Windows：WSL#

五、首次启动和登录#

六、如何确认安装成功？#

七、常见问题速查#

八、更新与卸载（按安装方式对照）#

九、常用命令速查表#

十、官方参考资料#