安装与更新 Codex CLI：Mac、Linux、Windows

安装 OpenAI Codex CLI 每个平台只需一条命令：macOS 与 Linux 上是 curl -fsSL https://chatgpt.com/codex/install.sh | sh，Windows 上是 powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"，npm 与 Homebrew 是受支持的替代方案；更新是 codex update，它能识别脚本、npm 与 Homebrew 安装并运行该渠道的升级。¹⁴¹¹ 大多数页面略过的，是第一条命令之后的事：五条安装路径该选哪一条、某个版本出问题时怎么锁定版本、winget 包为什么落后 npm 七个次版本，以及卸载之后 ~/.codex 里会留下什么。本页就是那份参考：每项任务一张表，以 v0.153.4（2026 年 9 月 4 日）为准。⁹

TL;DR

• 独立安装程序是 OpenAI 领先推荐的路径，README 与 CLI 文档皆然，npm 与 Homebrew 作为替代方案呈现（CLI 文档写的是“you can also install”，README 写的是“can also be installed via”）：macOS 与 Linux 用 install.sh 脚本，Windows 用 install.ps1 脚本。它下载的是编译好的二进制文件，所以不需要 Node。¹¹¹
• npm 与 Homebrew 是受支持的替代方案。 npm install -g @openai/codex 用普通的包规格（@<version>）锁定版本；撰写本文时 brew install --cask codex 与 npm 同为 0.153.4。¹²¹⁰
• 安装 Codex 本身时避开 winget。 OpenAI 确实发布了 OpenAI.Codex 包，但 0.147.0 到 0.152.0 的 manifest pull request 自 2026 年 8 月 7 日起一直积压在 microsoft/winget-pkgs 未合并，所以撰写当天可安装的最新版本是 0.146.1，而 npm 是 0.153.4。³¹⁰
• codex update 覆盖脚本、npm 与 Homebrew 安装（v0.128.0 起）：它复用 TUI 已有的安装渠道检测，并运行匹配的升级。winget 安装不是它识别的渠道；那一种请用 winget upgrade OpenAI.Codex 更新。其余的手动对应做法是重新运行安装程序、npm install -g @openai/codex@latest，或 brew upgrade --cask codex。⁴¹¹
• 锁定版本：install.sh 用 --release <version>，install.ps1 那一行之前用 $env:CODEX_RELEASE，npm 用 @<version>。 Homebrew 的 cask 只跟踪一个当前版本，无法锁定。²¹²
• 卸载包不会清除你的状态， 但在脚本安装上，rm -rf ~/.codex 也会把 CLI 本身删掉，因为安装程序把各个版本放在 ~/.codex/packages/standalone 之下。¹²

如何安装 Codex CLI？

按 OpenAI 自家文档的呈现顺序列出四条路径，¹¹¹ 再加上 OpenAI 没有文档化的 Windows winget：³

# Standalone installer, no Node required (macOS, Linux, WSL) -- the route OpenAI lists first
curl -fsSL https://chatgpt.com/codex/install.sh | sh

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

# npm (needs Node.js 16+; pins with a plain @version spec)
npm install -g @openai/codex

# Homebrew (macOS)
brew install --cask codex

# winget (Windows; lags npm, see the platform section)
winget install OpenAI.Codex

然后确认安装成功并登录：

codex --version      # codex-cli 0.153.4
codex login          # ChatGPT account (recommended) or an API key

第一次用脚本安装时，profile 块只在新开的 shell 里生效。如果在安装时所用的终端里找不到 codex，在那里运行 export PATH="$HOME/.local/bin:$PATH"，或者开一个新终端；安装程序结束时会打印同样的两行（“Current terminal”与“Future terminals”）。¹²

想直接用二进制文件？每个 GitHub release 都附带各平台的 tarball（codex-aarch64-apple-darwin.tar.gz、codex-x86_64-apple-darwin.tar.gz、codex-x86_64-unknown-linux-musl.tar.gz、codex-aarch64-unknown-linux-musl.tar.gz），而且从 v0.106.0 起，同一份 install.sh 也作为资产附在每个 release 上。每个压缩包只含一个把平台名嵌在文件名里的条目，所以解压后把它重命名为 codex。¹⁵

安装程序从 OpenAI 自家托管的发布基础设施拉取：chatgpt.com/codex/install.sh 会重定向到 releases.openai.com，这项变更在 v0.146.0 落地，GitHub Releases 保留为后备主机。⁶ 在屏蔽或限速 OpenAI 制品主机、但放行 GitHub 的网络上，改从 release 资产获取脚本，并告诉它二进制文件也从 GitHub 拉：¹¹²

curl -fsSL https://github.com/openai/codex/releases/latest/download/install.sh | CODEX_INSTALLER_USE_RELEASES_OPENAI_COM=false sh

变量要放在管道的 sh 那一侧。VAR=value curl ... | sh 这种写法只把变量作用于 curl，脚本根本看不到它，就悄悄沿用默认值。在 PowerShell 里，运行安装那一行之前先设置 $env:CODEX_INSTALLER_USE_RELEASES_OPENAI_COM = 'false'。

该选哪条路径？

Codex 支持哪些平台？

在 Windows 上，Codex 以原生方式在 PowerShell 里搭配 Windows 沙箱运行，沙箱模式有两种。elevated 是首选模式：它使用专用的低权限沙箱用户、文件系统权限边界、防火墙规则与本地策略变更，需要管理员批准的设置。unelevated 是后备：它用派生自你用户的受限 Windows 令牌以及基于 ACL 的文件系统边界来运行命令。⁸ 模式在 config.toml 里选择：

[windows]
sandbox = "elevated"   # or "unelevated"

OpenAI 的指引是默认使用原生沙箱，在你需要 Linux 原生工具、工作流本来就在 WSL2 里，或两种原生 Windows 沙箱模式都不合用时才选 WSL。⁸ 有一点要分清：Windows 设置假定机器上有 winget 供其自身的设置步骤使用；这和通过 winget 安装 Codex 是两回事。OpenAI 确实发布了那个包，发布工作流里有一个 winget 作业，会为稳定版在 microsoft/winget-pkgs 开 manifest pull request，但那些提交自 0.146.1 的 manifest 于 2026 年 8 月 7 日合并之后就一直积压未合并；撰写本文时，0.147.0 到 0.152.0 的请求全都还开着，而 0.153.0 到 0.153.4 根本没有请求。CLI 本身没坏，是包索引落后了。³⁸

Node.js 只有 npm 路径才需要。安装脚本下载的是编译好的二进制文件，而 Homebrew cask 没有声明任何依赖。¹²

如何更新 Codex CLI？

Codex 不会自我更新。TUI 会注意到新版本，并提供符合你安装渠道的命令；运行与否取决于你，内置的那条覆盖脚本、npm 与 Homebrew 安装。⁴ 启动时的检查本身是一个配置键：config.toml 里的 check_for_update_on_startup = false，参考文档把它描述为“Check for Codex updates on startup (set to false only when updates are centrally managed)”；集中管理更新的组织则在 requirements.toml 里设置 features.in_app_updates = false。¹⁶

codex --version                      # what you run now
npm view @openai/codex version       # newest published

codex update                         # built-in, v0.128.0+; detects your install channel

codex update 在 2026 年 4 月 30 日随 v0.128.0 出现；加入它的 pull request 复用了 TUI 原本用于更新提示的安装渠道检测与更新执行器。渠道映射覆盖 npm（加上 bun、pnpm 与 Vite+ 变体）、Homebrew，以及 Unix 与 Windows 上的独立安装程序；winget 安装不在其中，所以通过 winget 安装的 Codex 只能用 winget upgrade OpenAI.Codex 更新。⁴ 如果你偏好手动，或正在为机器镜像写脚本，手动对应做法如下：

curl -fsSL https://chatgpt.com/codex/install.sh | sh   # standalone: re-run the installer
npm install -g @openai/codex@latest                    # npm
brew upgrade --cask codex                              # Homebrew
winget upgrade OpenAI.Codex                            # winget (to whatever winget has)

irm https://chatgpt.com/codex/install.ps1 | iex           # standalone on Windows: re-run the installer

版本在一条快速的稳定线上发布：0.150.0 到 0.153.4 在 2026 年 8 月 26 日到 9 月 4 日之间出炉，所以“我在用的”与“最新的”之间的差距往往是一周，而不是一个季度。⁹

如何安装特定版本？

npm 与安装脚本都能按版本锁定；Homebrew 不行：²¹²

npm install -g @openai/[email protected]                                          # npm: exact version
curl -fsSL https://chatgpt.com/codex/install.sh | sh -s -- --release 0.152.1  # script: --release flag
curl -fsSL https://chatgpt.com/codex/install.sh | CODEX_RELEASE=0.152.1 sh    # script: env var, on the sh side
winget install OpenAI.Codex --version 0.146.1                                 # winget: only what it has
codex --version                                                               # verify the rollback took

注意环境变量写法的位置：CODEX_RELEASE=0.152.1 必须放在管道之后、sh 之前。写在 curl 前面，变量只作用于 curl，脚本会在你以为已经锁定的时候安装 latest。¹² 在 Windows 上，PowerShell 脚本把 $Release = $env:CODEX_RELEASE 声明为唯一的参数，为空时回退到 latest，所以锁定就是那个变量，在同一个会话里设置：¹⁷

$env:CODEX_RELEASE = '0.152.1'; irm https://chatgpt.com/codex/install.ps1 | iex

当某个版本让你出问题时，锁定版本是正确的做法：提 issue，锁回最后一个正常的版本，继续前进。每次锁定后都用 codex --version 验证，因为 PATH 上别处的第二份安装会默默继续提供它自己的二进制文件。安装脚本正是在检查这件事：当它在你的 PATH 上发现已有 Homebrew、npm 或 bun 管理的 codex 时，会警告“Multiple managed Codex installs can be ambiguous because PATH order decides which one runs”，并主动提议替你运行对应的卸载命令。¹² 事后 codex doctor 会在 Environment 之下报告同样的状况。⁷

如何卸载 Codex CLI？

用安装它的那条路径来卸载：

npm uninstall -g @openai/codex
brew uninstall --cask codex
winget uninstall OpenAI.Codex

脚本安装没有包管理器可问。安装程序在 ~/.local/bin 放一个 codex 符号链接（可用 CODEX_INSTALL_DIR 覆盖），指向 ~/.codex/packages/standalone/current 里的二进制文件（当前版本是 current/bin/codex）；current 本身又是指向 ~/.codex/packages/standalone/releases/ 的符号链接，每个下载的版本都放在那里。在 macOS 上，安装程序会在第一个链接旁边再加一个符号链接 codex-code-mode-host。¹² 全部删除：

rm -f ~/.local/bin/codex ~/.local/bin/codex-code-mode-host   # the second link exists on macOS installs only
rm -rf ~/.codex/packages/standalone

如果安装时 ~/.local/bin 不在你的 PATH 上，或安装程序发现了相互竞争的 Homebrew、npm 或 bun 安装并改写了那个条目，脚本还会在你的 shell profile 里追加一个带标记的块：~/.zprofile（macOS zsh）、~/.bash_profile、~/.zshrc、~/.bashrc 或 ~/.profile 里从 # >>> Codex installer >>> 到 # <<< Codex installer <<<。删掉那三行就完成了。¹²

在 Windows 上，install.ps1 在 %USERPROFILE%\.codex\packages\standalone（若你设置了那个变量则是 %CODEX_HOME%\packages\standalone）之下保持同样的布局：下载的版本放在 releases\，一个 current 联接点指向使用中的版本。它通过 %LOCALAPPDATA%\Programs\OpenAI\Codex\bin（可用 CODEX_INSTALL_DIR 覆盖）暴露 codex.exe，那本身又是指向 current\bin 的联接点；而且它不用 profile 块，而是把那个 bin 路径写进你的用户 PATH，供之后的 PowerShell 会话使用。先删除 standalone 目录，再删除此时已悬空的 bin 联接点，最后到“环境变量”里把该条目从用户 Path 变量中移除：¹⁷

Remove-Item -Recurse -Force "$env:USERPROFILE\.codex\packages\standalone"   # releases plus the current junction
cmd /c rmdir "$env:LOCALAPPDATA\Programs\OpenAI\Codex\bin"                  # the bin junction; rmdir removes the link, not a target

上面的包管理器卸载都不会碰 ~/.codex/。Homebrew 的 --zap 实际上也不会：cask 唯一的 zap 段落是 rmdir: "~/.codex"，而 Homebrew 只对已经为空的目录应用 rmdir:。² 那个目录存放 config.toml、你保存的凭据与每一个会话，这就是为什么重新安装后登录与历史记录会接着上次继续。只有在你真的想要一个干净的起点时才删除它，并且要知道这在脚本安装上意味着什么：

rm -rf ~/.codex   # discards config.toml, credentials, all sessions -- AND the CLI itself on a script install

保留状态的干净重装在 npm 上只要一行：npm uninstall -g @openai/codex && npm install -g @openai/codex@latest。在脚本路径上，重新运行安装程序会替换 ~/.codex/packages/standalone 之下的版本，并保留你的配置不动。¹²

一张表看完整个生命周期

codex doctor 检查什么？

codex doctor 是提交 bug 或调试一个“昨天还好好的”安装之前该运行的命令。在 0.153.4 上，它把七个部分收进一份报告：Notes、Environment（运行时与安装一致性）、Configuration（config.toml 加载状态、认证、MCP、沙箱策略）、Desktop App（v0.149.0 新增）、Updates、Connectivity 与 Background Server。--summary 给出精简视图，--json 给出脱敏的机器可读形式，--all 展开被截断的列表，--no-color 用于日志；0.153.4 的 codex doctor --help 也列出了 --ascii。⁷¹³¹⁵ 大多数“Codex 坏了”的报告都能归结为它第一屏上点名的某件事：过期的认证模式、一个解析失败的 config.toml，或一份遮住你 PATH 上那份的第二安装。逐部分的完整说明在指南里。

安装之后会变的事

全新安装第一个绊到的不是二进制文件。从 v0.149.0 起，CLI 遇到 approval_policy = "untrusted" 会拒绝启动，所以从旧机器复制过来的 config.toml 需要改一处。¹³ 从 Claude Code 过来的？迁移文章把两边的配置并排对照，hooks 文章则说明 Codex 在模型周围运行些什么。Codex CLI 指南是完整参考：沙箱与审批模式、AGENTS.md、MCP、skills 与云端任务。如果你两个工具都用，Claude Code 安装页是本页的孪生篇。

常见问题

如何把 Codex CLI 更新到最新版本？

运行 codex update（v0.128.0 起）；它会检测你是通过脚本、npm 还是 Homebrew 安装的，并运行该渠道的升级。手动对应做法是重新运行安装脚本、npm install -g @openai/codex@latest，或 brew upgrade --cask codex。winget 安装不是 codex update 识别的渠道；那一种请用 winget upgrade OpenAI.Codex。

Codex CLI 会自动更新吗？

不会。TUI 会检查是否有新版本，并提供符合你安装渠道的更新命令，而 codex update（v0.128.0 起）负责运行它；在你动手之前，不会下载或应用任何东西。

如何卸载 Codex CLI？

用安装它的那条路径：npm uninstall -g @openai/codex、brew uninstall --cask codex，或 winget uninstall OpenAI.Codex。脚本安装的话，删除 ~/.local/bin/codex 符号链接（macOS 上还有 ~/.local/bin/codex-code-mode-host）以及 ~/.codex/packages/standalone 目录。在 Windows 上，脚本安装是 %USERPROFILE%\.codex\packages\standalone、%LOCALAPPDATA%\Programs\OpenAI\Codex\bin 联接点，以及你用户 PATH 里的一个条目；三者都要删除。你的配置、凭据与会话会留在 ~/.codex/，直到你自己把那个目录的其余部分删掉。

如何在 Windows 上安装 Codex CLI？

运行 powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"。CLI 以原生方式在 PowerShell 里搭配 Windows 沙箱运行（首选 elevated，unelevated 为后备）；WSL2 是在你需要 Linux 工具或两种沙箱模式都不合用时的选项，不是必需条件。Windows 11 是推荐基线。winget install OpenAI.Codex 也能用，但落后于稳定线。

安装 Codex 需要 Node.js 吗？

只有 npm 路径需要，而且包要求 Node 16 或更新版本。安装脚本、PowerShell 脚本与 Homebrew cask 都提供编译好的 codex 二进制文件，所以没有 Node 的机器也能运行 Codex。

如何查看我装的是哪个版本的 Codex？

codex --version 会打印出来（例如 codex-cli 0.153.4）。npm view @openai/codex version 显示最新发布的版本，codex doctor 则报告安装路径，以及 PATH 上是否有另一份副本遮住了它。