安裝 Codex CLI

想像你要請一位很厲害的助手來家裡幫忙。第 0 章我們認識了這位助手是誰、會做什麼；第 1 章學會了打開「跟電腦對話的視窗」（終端機）。這一章，我們要做的就是把這位助手正式接進來——讓你的電腦從此聽得懂 codex 這個指令。

別怕！安裝其實只有一行指令的事。好消息是：Codex CLI 現在是用 Rust 寫的原生程式（你不用懂這是什麼，只要知道：它不一定需要先裝別的東西），所以入口有好幾個，你挑最順手的那條走就好。

這一章你會學到：

• 四種安裝法分別適合誰，怎麼選一條不踩雷的；
• 在 🍎 Mac、🐧 Linux、🪟 Windows 上逐字照打的安裝指令；
• 想完全手動、或在 CI（自動化管線）裡安裝時怎麼做；
• 裝完怎麼驗證成功、怎麼升級、怎麼移除，以及「明明裝了卻不動」該怎麼排除。

第一次碰終端機的話，先確認自己有可用的 ChatGPT／OpenAI 登入方式、網路與練習資料夾；Git 強烈建議先裝。這些共同前置與「什麼情況才需要 Node.js」可先看從零開始的共同清單，再回來選一條安裝法。

2.1 四種安裝法（哪個適合你）

你可以把這四種安裝法想像成買同一台工具的四個通路：有的去專賣店（Homebrew）、有的官網下單（官方腳本）、有的去綜合商城（npm）、有的乾脆自己去儲存庫扛貨（手動下載二進位）。買到的都是同一台 Codex CLI，差別只在過程順不順手。

先用一張表幫你選。新手只要看「新手建議」那欄即可：

簡單一句話建議：

• 第一次安裝 → 先選自己系統對應的官方 standalone installer（2.2 節第一招），確認網址後再執行一行指令。
• Mac 而且已經在用 Homebrew → 用 brew install --cask codex。
• 你本來就是寫 JS / 用 npm 的人 → 用 npm 也行。
• 其他全部不適用、或想手動 → 看 2.3 節。

安裝前先 checklist：系統夠不夠格

招式選好了，正式動手前，花 10 秒對一下你的系統夠不夠格。這不是嚇唬人的門檻，只是讓你萬一裝完卡住時，能快速排除「根本是系統太舊」這個可能性：

2.2 逐平台逐字指令（含 CI 無人值守）

這一節給你可以直接複製貼上的指令。請對照你的作業系統，找到對應的 🍎 / 🐧 / 🪟 小標，照著打就好。每招都標好「適合誰」，你挑一招做完就算裝好了，不必每招都做。Windows 新手請先開「Windows Terminal → PowerShell」，不必用系統管理員身分；若你選 WSL，則在 Ubuntu 裡一路安裝與使用，不要回 PowerShell 再找同一份程式。

招式一：官方 install 腳本（最推薦）

這是官方主推、也最省事的一招。它會下載並執行安裝程式，因此只在網址完整等於 https://chatgpt.com/codex/… 時使用；不要把別人訊息、短網址或搜尋廣告改寫成這條指令，也不要在公司電腦繞過管理政策。

🍎 Mac：

curl -fsSL https://chatgpt.com/codex/install.sh | sh

🐧 Linux：

curl -fsSL https://chatgpt.com/codex/install.sh | sh

🪟 Windows（PowerShell）：

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

裝完先關掉並重開同一種終端機，再檢查版本；Windows 是重新開 Windows Terminal 的 PowerShell，WSL 是重新開 Ubuntu。版本能印出來才進下一步，不要因為第一個舊視窗找不到指令就重複安裝。

codex --version
codex

招式二：Homebrew（只限 🍎 Mac）

如果你 Mac 上已經有 Homebrew（一個 Mac 上很常見的「軟體安裝管家」），先跑 brew --version 有結果，這招才最自然：

🍎 Mac：

brew install --cask codex

brew uninstall codex --formula
brew install --cask codex

招式三：npm 全域安裝（需要 Node.js）

如果你本來就在用 Node.js（寫網頁、跑 npm 的人），這招對你最熟悉：

🍎 Mac / 🐧 Linux / 🪟 Windows 都一樣：

npm install -g @openai/codex

npm 是「你本來就有 Node.js」的路線，不是 Codex 的必經路。如果 node --version 顯示找不到指令，最簡單是回到上面的 standalone installer；真的因課程或既有專案必須用 npm，才從 Node.js 官方下載頁安裝目前 LTS，重開終端機後確認 node --version 與 npm --version，再回來安裝。不要因為想執行一條 npm install 就臨時混裝 Homebrew、nvm 與系統 Node。

已經在用 Homebrew 的 Mac 使用者，也可以用它安裝 Node，再裝 Codex：

🍎 Mac：

brew update
brew install node
npm install -g @openai/codex

關於 Node 版本，有個小重點放在這個提示框：

npm config set prefix '~/.npm-global'

🪟 Windows 補充：原生 vs WSL2

Windows 使用者有兩條路，先用一張表看差別：

如果走 WSL2，先在 Windows 開好 WSL，再進去當成 Linux 用：

🪟 Windows（先開 WSL）：

wsl --install
wsl

接著在 WSL 終端機裡（這時等於 Linux 環境）照 🐧 Linux 那招裝：

curl -fsSL https://chatgpt.com/codex/install.sh | sh
codex

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

CI / 無人值守安裝（進階，自動化才需要）

如果你要在 CI（持續整合，自動化管線） 或任何沒有人坐在旁邊按確認的環境裝 Codex，腳本不能停下來等人回答。這時加上 CODEX_NON_INTERACTIVE=1 讓它非互動地跑完：

🍎 Mac / 🐧 Linux：

curl -fsSL https://chatgpt.com/codex/install.sh | CODEX_NON_INTERACTIVE=1 sh

💡 高手小撇步：CI / cron 裡「釘版」防事件 schema 漂移（進階）

前面 2.2 教的安裝指令（腳本、Homebrew、npm @latest）都會抓當下最新版。在自己電腦上這很好——隨時最新。但放進自動化管線就藏了一個高手才會踩的雷：

Codex CLI 更新非常頻繁（官方說「新版本會定期釋出」，社群觀察甚至常常數天一版），旗標、config 鍵、甚至 --json 吐出的事件欄位都還沒被官方凍結成穩定契約。 也就是說，你今天寫好一個會去讀 --json 事件的腳本，過幾天 Codex 自動升到新版後，事件格式可能變了，腳本就靜默壞掉。這種「格式變了害腳本爆掉」就是所謂的事件 schema 漂移。

做法一：npm 安裝時釘死版本號

在 CI 裡如果走 npm 安裝，把 @latest 換成指定版本號（格式是 @openai/codex@<版本>）：

🍎 Mac / 🐧 Linux / 🪟 Windows：

npm install -g @openai/codex@0.140.0

做法二：GitHub Action 用 codex-version 釘版

如果你用官方的 GitHub Action（openai/codex-action），它有一個專門的輸入欄位 codex-version，作用是「指定要安裝哪一版的 @openai/codex」。把它填上你驗證過的版本，這條 Action 就不會偷偷升級：

- uses: openai/codex-action@v1
  with:
    codex-version: "0.140.0"   # 釘在驗證過的版本，不隨上游漂移

2.3 二進位手動安裝與檔名對照（Intel Mac 警告）

這一節是進階備案：當套件管理器都不能用（例如離線環境、公司鎖死安裝權限），你可以自己去官方儲存庫把檔案扛回來。新手如果上面三招有一招成功了，這節可以先跳過。

手動安裝就三步：

1. 到 GitHub Releases（最新版） 找到對應你平台的 .tar.gz 檔下載。
2. 解壓縮，把裡面的執行檔改名為 codex。
3. 把這個 codex 放進系統的 PATH（系統會去找指令的那些資料夾），這樣在終端機打 codex 才找得到。

下面這張表是逐字檔名對照，務必照抄（打錯一個字就抓不到檔）：

sudo apt-get update && sudo apt-get install -y bubblewrap

git clone https://github.com/openai/codex.git
cd codex/codex-rs
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
source "$HOME/.cargo/env"
rustup component add rustfmt clippy
cargo build

cargo run --bin codex -- "explain this codebase to me"

2.4 驗證、升級、解除安裝

裝完別急著用，先花 10 秒確認真的裝好了；順便學會之後怎麼更新、怎麼移除。

驗證：它真的裝好了嗎？

在終端機打這一行，看它有沒有吐出一個版本號：

codex --version

✅ 預期會看到： 一串版本號（例如 0.140.0 之類的數字），代表安裝成功、終端機認得 codex 了。

如果反而看到 codex: command not found（找不到指令）別慌，最常見原因是「安裝路徑沒被加進 PATH」，通常出現在 npm 全域安裝權限出狀況時。最省事的解法是改用 Homebrew 或官方腳本重裝一次，可以避開大多數 npm 權限坑。

codex --version 只能確認「有沒有裝起來」。如果你想再多做一步、確認整體環境（登入狀態、設定檔、常見相依套件）健不健康，官方另外提供一個更完整的健檢指令：

codex doctor

它會印出一份分區塊的診斷報告，之後不管遇到什麼疑難雜症，先跑這個幾乎是官方與社群公認的第一步。這個指令完整的旗標（摘要模式、機器可讀的輸出格式等）與詳細判讀方式，留到第 16 章疑難排解專章細講；這裡你只要記得「裝完之後，codex doctor 是你的第二道健檢」就夠了。

裝了但抓錯：多重安裝管道 PATH 打架

如果你曾經今天用 npm 裝過一次、改天又手滑用 Homebrew 裝一次，或是照著不同教學重複裝了兩三種方式——這是非常容易發生的事，尤其是遇到問題到處找解法、每篇教學招式都試一遍的時候。後果是：終端機打 codex 永遠只認 PATH 裡排最前面那一個，你以為升級成功了，其實只是升級了排在後面、根本沒人在用的那一份。

排查方式是把 PATH 上所有叫 codex 的執行檔全部列出來，而不是只看「終端機現在跑的是哪一個」：

🍎 Mac / 🐧 Linux（含 WSL2）：

which -a codex

🪟 Windows（PowerShell）：

Get-Command codex -All | Select-Object -Expand Source

如果這招印出不只一行路徑，代表你的系統上同時躺著好幾份 codex。最乾淨的解法不是想辦法調整 PATH 順序，而是整台機器只留一種安裝管道：挑一個順手的（通常官方腳本或 Homebrew 最省事），把其他管道全部用各自對應的解除安裝指令清掉（見稍後「解除安裝」），只留一份，之後升級才不會再打架。

升級：讓它保持最新

比較新的 Codex CLI（官方說法是 v0.128 起）內建了一個統一的升級指令 codex update，它會自動偵測你當初是用哪個管道裝的（官方腳本 / npm / Homebrew），直接套用對應的升級方式，不用你自己去記：

codex update            # 檢查並直接套用更新
codex update --check    # 只檢查有沒有新版，不實際更新
codex update --force    # 強制更新（版本檢查卡住時用）

本書對照版本 0.140.0 晚於這個門檻，一般情況下升級只要記 codex update 這一招就好。官方也提醒 Codex CLI 更新很頻繁，值得養成三不五時跑一次的習慣。如果你的版本比較舊、跑起來說沒有這個指令，或想針對特定安裝管道手動操作，下面這張對照表仍然管用：

🍎 Mac / 🐧 Linux（用官方腳本裝的）：

curl -fsSL https://chatgpt.com/codex/install.sh | sh

解除安裝：把它請出去

不想用了，移除方式一樣看當初怎麼裝的：

rm -rf ~/.codex

安裝這件事講到這裡差不多了，最後補一個跟終端機無關、但很多人不知道的小知識：

小結

走到這裡，你已經把 Codex CLI 請進電腦了：你知道四種安裝法各適合誰、會在自己的系統上逐字裝好、也學會了驗證 / 升級 / 移除。最關鍵的兩個防雷口訣別忘記——Homebrew 要 --cask、npm 要 @openai/ 前綴。

下一章我們就真正第一次啟動它、完成登入，讓這位 AI 工程師正式上工。

動手試試

1. 照 2.2 節挑一招把 Codex CLI 裝起來（不用全做，挑最順的那招）。
2. 跑 codex --version，確認看得到版本號。
3. （進階）如果你是 Intel Mac，試著回想：為什麼這章叫你不要去手動下載二進位，而是走 npm / Homebrew / 腳本？
4. （進階）跑一次 codex doctor，再跑一次 🍎/🐧 的 which -a codex（或 🪟 的 Get-Command codex -All），看看診斷報告長什麼樣、你的系統上到底有幾份 codex。