做完這篇你會得到：一個在 Terminal（終端機） 裡跑得起來的 codex、一個完成登入的帳號、跑過的第一個任務，以及你親手設過的權限等級。Codex CLI 是 OpenAI 的開源終端機編程 Agent（Apache-2.0 授權，原始碼在 github.com/openai/codex），跟雲端版的 Codex Web 是不同的東西。
動手做完大約 15 分鐘。全程都在 CLI（命令列介面） 裡，沒有圖形介面。
適用平台
官方 docs/install.md 列的系統需求：
| 項目 | 需求 |
|---|---|
| 作業系統 | macOS 12+；Ubuntu 20.04+ 或 Debian 10+；Windows 11 透過 WSL2 |
| Git（選用，建議裝） | 2.23 以上，內建的 PR 輔助功能會用到 |
| 記憶體 | 最低 4 GB，建議 8 GB |
這裡有一個新手會踩到的矛盾，先講清楚：官方 README 另外給了一條 Windows 原生的 PowerShell 安裝指令，但 docs/install.md 的系統需求表寫的是 Windows 11 via WSL2。務實做法是 Windows 使用者優先走 WSL2；若你要試原生 PowerShell 那條路，就把它當成「官方有給指令、但需求表未列」的路線。
帳號方面，官方 README 建議用 ChatGPT 帳號登入，以 Plus、Pro、Business、Edu 或 Enterprise 方案使用 Codex；也可以用 API key，但需要額外設定。
來源：github.com/openai/codex（README 與 docs/install.md）、developers.openai.com/codex。
前置需求
- 一個 ChatGPT 付費方案帳號，或一把 OpenAI 平台的 API Key。
- 你會打開終端機、貼指令、認得提示字元。不熟就先讀 Terminal、Shell、CLI：三個詞的差別。
- 用 API key 路線的人要先懂 環境變數與 .env：金鑰應該放在環境變數裡，不是寫進指令。本文範例一律是
sk-xxxxxxxx這種佔位符。不要把金鑰貼進對話視窗，也不要 commit 進 git。 - 一個專案目錄。Codex 以你啟動它時所在的目錄為工作區。
步驟
步驟一：確認你的系統與帳號
macOS 看蘋果選單 →「關於這台 Mac」；Linux 在終端機執行：
cat /etc/os-release
free -h
Windows 使用者先確認你有沒有 WSL2：在 PowerShell 執行 wsl --status。
預期輸出：cat /etc/os-release 印出發行版名稱與版本（形如 PRETTY_NAME="Ubuntu 22.04.3 LTS"）；free -h 印出一張記憶體表，看 Mem: 那一行的 total 是否超過 4 GB。wsl --status 若已裝好會印出預設發行版與版本資訊；若印出的是「不是內部或外部命令」或要你安裝，就代表你還沒有 WSL2，先裝它再回來。
步驟二：安裝
官方 README 給的獨立安裝程式，macOS 與 Linux：
curl -fsSL https://chatgpt.com/codex/install.sh | sh
Windows（PowerShell）：
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"
也可以用套件管理器：
npm install -g @openai/codex
brew install --cask codex
官方說明：獨立安裝程式預設從 https://releases.openai.com/codex 下載，若該處的中繼資料或檔案拿不到會退回 GitHub Releases；要強制走 GitHub Releases，把 CODEX_INSTALLER_USE_RELEASES_OPENAI_COM 設成 false（0 與 no 也接受）。
預期輸出：安裝程式印出下載與安裝進度後回到提示字元。npm 路線結尾會印出它新增了幾個套件；Homebrew 會印出下載與安裝過程。README 的下一句就是「Then simply run codex to get started」。
失敗長這樣：如果你改從 GitHub Releases 手動下載壓縮檔，官方說明每個壓縮檔裡只有一個執行檔，而且檔名含平台（例如 codex-aarch64-apple-darwin），你要自己把它改名成 codex 並放到 PATH 上的目錄，否則終端機找不到這個指令。
步驟三：驗證安裝
codex --version
預期輸出：印出一個版本號。Codex 的版號是 0.x.y 形式（我核對官方文件當下，npm 上的最新版是 0.159.2；你看到的數字會更新）。只要有版號就代表二進位檔在 PATH 上、可以執行。
失敗長這樣：command not found —— 回到步驟二的最後一段，確認執行檔名稱是 codex 且所在目錄在你的 PATH 與路徑 裡。
步驟四：啟動並用 ChatGPT 帳號登入
cd /path/to/your/project
codex
官方 README 的說法是：執行 codex，然後選 Sign in with ChatGPT。
預期輸出：終端機被 Codex 的全螢幕介面（TUI）接管。第一次會要你選登入方式，選 ChatGPT 之後它會啟動一個本機登入伺服器並打開瀏覽器。官方程式碼裡那段訊息的原文形狀是：
Starting local login server on http://localhost:<port>.
If your browser did not open, navigate to this URL to authenticate:
<auth_url>
On a remote or headless machine? Use `codex login --device-auth` instead.
在瀏覽器完成授權後回到終端機，TUI 就能開始用了。官方用法列還告訴你兩種啟動形式：codex [OPTIONS] [PROMPT]（直接帶任務進去）與 codex [OPTIONS] <COMMAND> [ARGS]（跑子指令）。
失敗長這樣：瀏覽器沒開 —— 把上面印出的 <auth_url> 自己複製到瀏覽器。你在遠端機器或 SSH（安全外殼） 環境裡 —— 照它自己的提示改用 codex login --device-auth，那條路不需要本機瀏覽器。
步驟五：改用 API key 登入（選用）
要用 API key 而不是 ChatGPT 帳號時，官方的做法是把金鑰從標準輸入餵進去，而不是當參數寫在指令裡：
export OPENAI_API_KEY="sk-xxxxxxxx" # 範例用的是佔位符
printenv OPENAI_API_KEY | codex login --with-api-key
預期輸出：指令安靜地成功，然後回到提示字元（它不會把你的金鑰回印到畫面上）。之後 codex 就能用這把金鑰運作。
兩個官方細節值得知道：舊的 --api-key 參數已被標記為 deprecated，官方說明它現在會直接結束並叫你改用 --with-api-key；另有 --with-access-token 走同樣的 stdin 模式。要移除已存的憑證用 codex logout（官方對它的說明是「Remove stored authentication credentials」）。
步驟六：跑第一個任務
在 TUI 裡直接打字送出，或啟動時就把任務帶進去：
codex "explain this codebase to me"
（這句 prompt 是官方 docs/install.md 裡示範用的原文。）
預期輸出：TUI 上出現模型的回覆，以及它要求執行或已經執行的動作；需要核准的動作會跳出提示等你回答。你可以繼續對話，也可以在 TUI 裡打斜線指令：官方 /model 的說明是「choose what model and reasoning effort to use」，/status 是「show current session configuration and token usage」，/init 是「create an AGENTS.md file with instructions for Codex」，/diff 是「show git diff (including untracked files)」，/quit 與 /exit 離開。
步驟七：設定權限（沙箱與核准）
在 TUI 裡打：
/permissions
官方程式碼裡內建的三個預設，連同它們的原文說明如下：
| 預設 | 官方描述（原文） |
|---|---|
| Read Only | Codex can read files in the current workspace. Approval is required to edit files or access the internet. |
| Default（內部 id 是 auto） | Codex can read and edit files in the current workspace, and run commands. Approval is required to access the internet or edit other files. (Identical to Agent mode) |
| Full Access | Codex can edit files outside this workspace and access the internet without asking for approval. Exercise caution when using. |
也可以在啟動時用旗標指定。官方目前接受的值是：
codex --sandbox read-only # 另有 workspace-write、danger-full-access
codex --ask-for-approval on-request # 另有 never
codex --sandbox workspace-write --ask-for-approval on-request
預期輸出：/permissions 打開一份可選清單，顯示上面那三個名稱與說明；選定後新的動作就依該等級決定要不要問你。用旗標啟動時，session 一開始就是那個等級。
新手建議：從 Read Only 或 Default 開始。--dangerously-bypass-approvals-and-sandbox（別名 --yolo）在官方程式碼裡的註解是「EXTREMELY DANGEROUS. Intended solely for running in environments that are externally sandboxed」—— 只在外面已經有 Sandbox（沙箱） 的環境裡用。
步驟八：非互動模式、健檢與更新
codex exec "run the tests and summarize failures"
codex doctor
codex update
預期輸出：codex exec 是官方對「Run Codex non-interactively」的說明 —— 它跑完把結果印在終端機就結束、把提示字元還給你，適合放進腳本（官方 docs/install.md 補充：這個模式預設 RUST_LOG=error，訊息直接印在畫面上，不需要另外看 log 檔）。codex doctor 的官方說明是「Diagnose local Codex installation, config, auth, and runtime health」，會印出一份診斷。codex update 把 Codex 更新到最新版。
要更詳細的執行紀錄時，官方給的做法是指定 log 目錄再開另一個終端機跟：
codex -c log_dir=./.codex-log
tail -F ./.codex-log/codex-tui.log
怎麼確認你裝對了
codex doctor
預期輸出：一份安裝與設定的診斷報告。從官方程式碼可以確定它至少會印出這幾行：CODEX_HOME: <你的 Codex 家目錄路徑>、config.toml: <路徑>，以及解析結果 —— 正常時是 config.toml parse: ok（設定檔不存在時會寫 config.toml: missing，這在全新安裝上是正常的）；它同時會檢查同一個目錄下的 auth.json，也就是你的登入憑證。看到 parse: ok 且登入狀態正常，就代表裝對了。
第二道確認是端到端的：
codex exec "Reply with exactly: CODEX_OK"
預期輸出：終端機印出 CODEX_OK（可能連同一點執行資訊），然後回到提示字元。這代表登入、模型連線與非互動模式三件事都通。
常見錯誤與修法
| 症狀 | 原因 | 修法 |
|---|---|---|
codex: command not found | 執行檔不在 PATH，或從 GitHub Releases 解壓後沒改名 | 官方說明壓縮檔內的檔名含平台，要改名成 codex；npm 全域安裝則確認 npm 的全域 bin 目錄在 PATH 上 |
照舊教學打 codex --full-auto 被報未知參數 | 我核對的官方版本（0.159.2 與 main 分支）的旗標清單裡沒有 --full-auto；網路上大量舊文章仍在教它 | 改用 /permissions 選預設，或用 --sandbox 與 --ask-for-approval 兩個旗標組合 |
codex login --api-key 直接結束並印出指引 | 該參數已被官方標為 deprecated | 改用 stdin 形式：先把金鑰放進環境變數，再把 printenv OPENAI_API_KEY 的輸出用管線接給 codex login --with-api-key |
| 登入時瀏覽器沒打開 | 本機瀏覽器交遞失敗，或你在遠端／無頭環境 | 複製終端機印出的網址手動開；遠端機器用 codex login --device-auth |
| 安裝程式下載失敗 | releases.openai.com 拿不到中繼資料或檔案 | 官方提供的開關：把 CODEX_INSTALLER_USE_RELEASES_OPENAI_COM 設為 false，強制改走 GitHub Releases |
| Windows 上裝完不能用 | 你在 Windows 原生環境，但需求表列的是 WSL2 | 改用 WSL2 裡的 Linux 安裝指令；原生 PowerShell 那條路官方有給指令，但不在需求表內 |
| 金鑰被拒（401 類錯誤） | 複製時帶到空格或換行、金鑰已失效、或帳號未開通 API | 重新產生一把，用 export OPENAI_API_KEY="sk-xxxxxxxx" 這種方式放進環境變數再餵給 codex login --with-api-key；洩漏過的金鑰要到平台撤銷重發 |
| TUI 畫面在你的終端機裡錯亂 | 全螢幕模式與某些終端機不相容 | 官方提供 --no-alt-screen，以 inline 模式執行並保留終端機的捲動歷史 |
無法從官方文件核實的部分，我在這裡明講：developers.openai.com/codex 這組頁面（auth、security、config-reference、noninteractive 等）在我撰稿時對我的抓取工具回傳 403，所以本文關於登入細節、旗標取值與 /permissions 預設的描述，全部改以官方 GitHub 倉庫的 README、docs/install.md 與 CLI 原始碼（codex-rs/cli/src/main.rs、codex-rs/cli/src/login.rs、codex-rs/utils/cli/src/、codex-rs/utils/approval-presets/src/lib.rs、codex-rs/tui/src/slash_command.rs）為依據。這些是第一手來源，但版號推進後旗標可能變動 —— 動手前用 codex --help 核對你自己的版本。
下一步
- 想比對同類型的終端機 Agent：安裝 Claude Code、安裝 DeepSeek Harness，以及 Agent 迴圈架構比較
- 想在 IDE 裡而不是終端機裡用：安裝 Cursor、安裝 Trae
- 把權限與沙箱的觀念補齊：Sandbox（沙箱）、Prompt Injection（提示詞注入）、AI 安全與紅隊測試
- 想理解它背後怎麼動：Harness（執行環境／框架）、Tool Call（工具呼叫）、AI Agent 是什麼
- 金鑰與成本管理：五分鐘設置你的 LLM 開發環境、API Key、團隊 AI 成本估算