安裝與更新 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 token 以及以 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 junction 指向使用中的版本。它透過 %LOCALAPPDATA%\Programs\OpenAI\Codex\bin（可用 CODEX_INSTALL_DIR 覆寫）暴露 codex.exe，那本身又是指向 current\bin 的 junction；而且它不用 profile 區塊，而是把那個 bin 路徑寫進你的使用者 PATH，供之後的 PowerShell 工作階段使用。先移除 standalone 目錄，再移除此時已懸空的 bin junction，最後到「環境變數」把該項目從使用者 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 junction，以及你使用者 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 上是否有另一份副本遮住了它。