OpenAI Codex CLI 安裝指南：跨平台設定與自動化應用

Codex CLI 是 OpenAI 針對終端機設計的程式碼代理。它能讀取您的儲存庫、編輯檔案、執行指令並解釋其操作，所有這些都只需一個提示詞即可完成。安裝它只需一個指令，但要有效使用它，則需要一些大多數指南會忽略的選擇，例如如何登入、代理在未經詢問下可執行多少操作、如何保持更新以及如何從腳本執行。

本指南涵蓋所有這些內容，從 macOS、Linux 或 Windows 的安裝指令，到檢查和更新版本、首次會話、沙盒與審批設定、配置，以及用於自動化的 codex exec。指令基於截至 2026 年 10 月的官方 Codex 儲存庫和指令參考。

安裝 Codex CLI

請選擇一種方法。它們都會安裝相同的 codex 指令。

• npm (任何有 Node.js 的系統)：npm install -g @openai/codex
• macOS 上的 Homebrew：brew install --cask codex
• 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"

您也可以從最新的 GitHub 版本下載適用於 macOS (arm64 或 x86_64) 或 Linux (x86_64 或 arm64) 的二進位檔，解壓縮後將執行檔重新命名為 codex。

檢查是否成功

開啟一個新的終端機並執行：codex --version。如果它印出版本號碼，表示安裝成功。如果您的 shell 顯示 codex: command not found，表示新的終端機尚未載入更新的 PATH；請關閉並重新開啟一個。

如果使用 npm 安裝，請檢查您的全域 npm bin 目錄是否在 PATH 中 ( npm prefix -g 會顯示全域套件的安裝位置)。

Windows 上的 Codex CLI

在 Windows 上，Codex CLI 會在其自己的 Windows 沙盒中原生執行於 PowerShell，因此您不需要 WSL 或虛擬機器。根據 Windows 沙盒文件，沙盒有兩種模式可以在 config.toml 中設定：elevated (首選，使用專用的低權限沙盒使用者和防火牆規則) 和 unelevated (備用，使用您自己使用者的受限權杖)：

```toml

[windows]

sandbox = "elevated"

```

當您的工具鏈已存在於 Linux 中，或者您需要 Linux 原生工具時，請改用 WSL2。在這種情況下，請使用 npm 或安裝腳本方法在 WSL 發行版中安裝 Codex，並從您的 Linux shell 啟動它。

更新 Codex CLI

Codex 變化很快，因此請定期更新。CLI 有自己的更新指令：codex update。當已安裝的版本支援時，它會將 Codex 更新到最新版本。

如果您偏好透過安裝時使用的套件管理器進行更新，請使用相應的指令：

| 安裝方式 | 更新指令 |

|---|---|

| Codex 本身 | codex update |

| npm | npm install -g @openai/codex@latest |

| Homebrew | brew upgrade --cask codex |

| GitHub 版本二進位檔 | 下載較新的版本並替換 codex 檔案 |

之後執行 codex --version 以確認新版本。每台機器請堅持使用一種安裝方法：PATH 上有兩個副本 (例如一個來自 npm，一個來自 Homebrew) 是更新似乎沒有作用的常見原因。

登入

在任何資料夾中執行 codex。首次執行會詢問您要如何登入。使用 ChatGPT 登入會使用您的 ChatGPT 方案，README 列出了 Plus、Pro、Business、Edu 和 Enterprise 方案。使用量將計入該方案的 Codex 配額。

API 金鑰會將使用量計費到 OpenAI API 帳戶，並且需要更多設定。從腳本中，codex login --with-api-key 會從標準輸入讀取金鑰，例如 printenv OPENAI_API_KEY | codex login --with-api-key。

哪些方案包含 Codex 以及允許多少使用量會隨時間變化，因此請查看官方 Codex 定價頁面以獲取最新詳細資訊。您可以稍後使用 codex logout 和 codex login 切換帳戶。

您的首次會話

從專案根目錄啟動 Codex：cd ~/code/my-app 然後執行 codex。接著執行 /init。它會在目前目錄中生成一個 AGENTS.md 骨架檔案，這是 Codex 每次執行時都會讀取的檔案，用於了解您的建置指令、佈局和慣例。將其編輯成重要的內容；我們的 Codex AGENTS.md 指南解釋了 Codex 如何發現和組合這些檔案。

現在給 Codex 一個小型、具體的任務，例如「在 src/cart.ts 中為空購物車情況添加一個測試」。在您給它任何更大的任務之前，請觀察它讀取和提議的內容。您最常使用的斜線指令有：

| 指令 | 功能 |

|---|---|

| /init | 生成 AGENTS.md 骨架 |

| /model | 選擇模型和推理工作量 |

| /plan | 在編輯前切換到規劃模式 |

| /permissions | 設定 Codex 在未經詢問下可執行的操作 |

| /diff | 顯示 git 差異，包括未追蹤的檔案 |

| /review | 要求 Codex 審查您的工作樹 |

| /status | 顯示會話配置和權杖使用量 |

| /compact | 總結對話以釋放上下文 |

| /resume | 繼續已儲存的對話 |

| /new | 在同一會話中開始新的對話 |

從 Claude Code 遷移過來嗎？/import 會匯入您的 Claude Code 設定、專案檔案和最近的聊天記錄。

沙盒與審批：Codex 可執行的程度

兩個獨立的設定決定了 Codex 的自由行動程度。正確設定它們是區分有用代理和一個要麼事事詢問要麼觸碰不該觸碰之物的關鍵。沙盒限制了指令在技術上可以執行的操作：

• read-only：Codex 可以讀取檔案但不能寫入。適用於探索不熟悉的程式碼庫或提問。
• workspace-write：Codex 可以在專案內部編輯檔案。這是互動式會話的預設值，也是大多數工作的正確選擇。
• danger-full-access：完全沒有沙盒。僅在可拋棄的環境中使用，例如您可以丟棄的容器。

審批策略決定了 Codex 何時會停下來詢問您：on-request 會在 Codex 需要超出沙盒範圍時暫停以等待審批，而 never 則從不暫停。每個執行都可以透過旗標設定：

codex --sandbox read-only

codex --sandbox workspace-write --ask-for-approval on-request

較舊的 --full-auto 旗標已棄用；請改用 --sandbox workspace-write。還有 --dangerously-bypass-approvals-and-sandbox (別名 --yolo)，它會移除這兩種保護。請將其視為以您自己的權限執行未知腳本。我們的 Codex 沙盒指南深入探討了網路存取、額外可寫入資料夾以及何時完全存取是合理的。

有用的旗標

一些旗標可以讓日常執行更快：

• -m 或 --model 選擇本次執行的模型，而不是配置的模型。
• -C 或 --cd 設定工作目錄，當您從其他地方啟動 Codex 時很方便。
• -i 或 --image 將螢幕截圖或設計檔案附加到您的提示詞中。
• --search 讓 Codex 可以使用即時網路搜尋來完成任務。

其他值得了解的子指令：codex resume --last 重新開啟您最近的會話 (我們的 codex resume 指南涵蓋了選擇器、分支和恢復腳本執行)，codex mcp 管理 Model Context Protocol 伺服器，而 codex completion 生成 shell 補全。

一次性配置 Codex

與其重複旗標，不如將您的預設值放入 ~/.codex/config.toml 中：

```toml

sandbox_mode = "workspace-write"

approval_policy = "on-request"

```

任何單次執行仍然可以使用 -c key=value 覆寫設定，而 /debug-config 會顯示當某些行為出乎意料時，哪些配置層是活躍的。同一個資料夾也存放您的全域 AGENTS.md，用於適用於每個儲存庫的個人偏好設定。

使用 codex exec 進行自動化

codex exec 在沒有互動式介面的情況下執行任務。這是您從 shell 腳本、git 鉤子和 CI 工作中使用 Codex 的方式。

codex exec "summarize the changes on this branch"

codex exec --json "list the failing tests and their causes" > events.jsonl

codex exec --sandbox workspace-write "fix the failing test in tests/api.test.ts"

codex exec 預設在唯讀沙盒中執行。當任務必須編輯檔案時，請添加 --sandbox workspace-write。--json 會串流機器可讀的事件，因此腳本可以對 Codex 的操作做出反應。-o 或 --output-last-message 只將最終訊息寫入檔案，這非常適合摘要和報告。

--skip-git-repo-check 允許 Codex 在 git 儲存庫之外執行。我們的 codex exec 完整指南涵蓋了標準輸入、--output-schema、codex exec resume 和在 CI 中執行 Codex。

常見問題

如何檢查我擁有的 Codex 版本？

執行 codex --version。如果您不確定更新是否成功，請將其與 Codex GitHub 發布頁面上的最新版本進行比較。

如何更新 Codex CLI？

執行 codex update，或使用您安裝時使用的套件管理器進行更新：npm install -g @openai/codex@latest 或 brew upgrade --cask codex。

Codex CLI 可以在 Windows 上運行嗎？

是的。使用上面提供的 PowerShell 指令安裝後，它會在 Windows 沙盒中原生運行。如果您的專案和工具已存在於 Linux 中，請使用 WSL2。

安裝後如何啟動 Codex？

進入您的專案資料夾並執行 codex。首次執行會要求您使用 ChatGPT 或 API 金鑰登入。

Codex 與其他代理的定位

Codex 是幾個強大的終端機代理之一。如果您正在它們之間做選擇，我們對 Codex 與 Claude Code、OpenCode 與 Codex 以及 OpenCode 與 Claude Code 的比較涵蓋了模型存取、沙盒、指令檔案以及哪些任務適合每個代理。當您達到方案的使用限制時，我們的 Codex 速率限制頁面解釋了如何規劃工作以應對。

VibeiDE 的定位

VibeiDE 是一款桌面應用程式，它協調您已安裝的 Codex、Claude Code 和 OpenCode CLI，並且您使用自己的帳戶登入 Codex。Codex 在嵌入式終端機中運行，顯示原始 CLI 介面，因此本指南中的所有內容在其中都以相同方式運作。

每個專案都有自己的任務佇列，使用量顯示提供商報告的使用量和重置倒數計時 (如果 Codex 有報告)，當 Codex 達到使用限制時，終端機將解釋您可以在重置後在同一終端機中繼續。請參閱 Codex 頁面或在約三分鐘內設定它，享受 14 天試用，無需信用卡。

重點摘要

• 透過 npm、Homebrew、安裝腳本或 PowerShell 安裝；它們都會提供相同的 codex 指令。
• 使用 codex --version 檢查安裝，並使用 codex update 或您的套件管理器更新。
• 在 Windows 上，Codex 會在其自己的沙盒中原生運行；僅當您的工具位於 Linux 中時才使用 WSL2。
• 使用 ChatGPT 方案或 API 金鑰登入，並查看官方定價頁面以獲取當前方案。
• 首先執行 /init，以便 Codex 有一個 AGENTS.md 可供使用。
• 日常工作將沙盒保持在 workspace-write，探索時使用 read-only；避免在可拋棄環境之外使用 --yolo。
• 腳本和 CI 使用 codex exec；它預設為唯讀，除非您提高沙盒權限。