OpenAI Codex CLI 是 OpenAI 於 2025 年中推出的終端 AI 編程助手。它將強大的程式碼生成能力直接帶入命令列環境。作為與 Anthropic Claude Code 競爭的核心產品，Codex CLI 憑藉其開源免費、沙盒安全模型、MCP 協議整合和靈活的 Profile 配置系統，迅速成為開發者 2026 年的必備工具。
什麼是 Codex CLI？
不只是「終端版 ChatGPT」
許多開發者初次接觸 Codex CLI 時，會簡單地把它當作「在終端運行的 ChatGPT」。但這種看法嚴重低估了它的設計深度。Codex CLI 是一個完整的互動式 Code Agent。它不僅能理解自然語言指令，還能：
- 讀取專案上下文：自動分析當前目錄的檔案結構、依賴關係和程式碼風格
- 執行多步驟任務：從需求分析到程式碼實現再到測試驗證，形成完整工作流
- 沙盒隔離：使用三層沙盒模式和四級審批策略，確保 AI 操作不會損壞系統
- 會話持久化：支援會話恢復、fork 實驗和歷史追蹤，永不丟失工作進度
核心架構設計
Codex CLI 使用 Rust 構建，採用模組化架構：
codex-cli/
├── core/ # 核心引擎：模型調用、上下文管理
├── sandbox/ # 沙盒層：檔案系統隔離、命令執行限制
├── mcp/ # MCP 協議整合：外部工具連接
├── config/ # 配置系統：Profile 管理、別名解析
└── ui/ # 互動介面：TUI、斜線命令解析這種設計讓 Codex CLI 保持輕量的同時，提供了企業級的安全性和可擴展性。與傳統 IDE 插件相比，其優勢包括：
- 無編輯器綁定：無論你偏好 Vim、Emacs 還是 VS Code，都能在終端中無縫使用
- 遠端友好：在 SSH 連接的伺服器或 Docker 容器內都能流暢運行
- 低資源佔用：Rust 構建的二進制文件啟動快速，記憶體佔用遠低於 Electron 應用
安裝與基本配置
四種安裝方式
1. npm 安裝（推薦大多數用戶）
npm install -g @openai/codex這是最通用的安裝方式，適用於 macOS、Linux 和 Windows（WSL2）。安裝後運行 codex --version 確認成功。
2. Homebrew 安裝（macOS 用戶首選）
brew install --cask codexHomebrew 安裝會自動處理依賴和 PATH 配置。升級只需 brew upgrade codex。
3. 二進制下載
前往 GitHub Releases 下載對應平台的預編譯二進制文件：
- macOS Apple Silicon：
codex-macos-arm64 - macOS Intel：
codex-macos-x86_64 - Linux x86_64：
codex-linux-x86_64 - Linux ARM64：
codex-linux-arm64 - Windows：
codex-windows-x86_64.exe
下載後授予執行權限並移至 PATH 目錄：
chmod +x codex-linux-x86_64
sudo mv codex-linux-x86_64 /usr/local/bin/codex4. WSL2 安裝（Windows 用戶）
原生 Windows 支援仍在完善中，建議透過 WSL2（Windows Subsystem for Linux）安裝：
# 在 WSL2 Ubuntu 內
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs
npm install -g @openai/codex認證：ChatGPT 訂閱 vs API Key
Codex CLI 支援兩種認證方式，各有適用場景：
ChatGPT 訂閱登入（適合個人用戶）
如果你擁有 ChatGPT Plus、Pro、Team、Edu 或 Enterprise 訂閱，可以直接透過瀏覽器登入：
codex login這會打開預設瀏覽器，完成 OAuth 授權後 token 會自動保存。訂閱用戶福利：
- Plus 用戶：每月 $5 免費 API 額度（30 天滾動）
- Pro 用戶：每月 $50 免費 API 額度（30 天滾動）
超出免費額度的使用量按標準 API 定價計費。
API Key 環境變數（適合團隊/自動化）
對於團隊協作或 CI/CD 整合，建議使用 API Key：
export OPENAI_API_KEY="your-key-here"將此行加入 ~/.bashrc 或 ~/.zshrc 使其永久生效。你可以在 OpenAI Platform 創建和管理 API Keys。
安全提示：切勿在程式碼倉庫中硬編碼 API Keys。請使用 .env 文件或密鑰管理服務。
系統需求與預檢
安裝前請確保系統滿足以下需求：
| 組件 | 最低版本 | 推薦版本 |
|---|---|---|
| Node.js | 18.x | 20.x LTS |
| npm | 9.x | 10.x |
| Git | 2.x | 2.40+ |
| OS | macOS 12+/Ubuntu 20.04+/WSL2 | 最新穩定版 |
運行以下命令檢查前置條件：
node --version # 應輸出 v18.x 或更高
npm --version # 應輸出 9.x 或更高
git --version # 應輸出 git version 2.x如果 Node.js 版本過低，請前往 Node.js 官網 下載安裝最新 LTS 版本。
三種操作模式詳解
Codex CLI 提供三種操作模式，分別對應不同級別的自動化和安全性：
suggest 模式（最安全）
codex --mode suggest在 suggest 模式下，Codex 只提供程式碼建議和解釋，不會自動修改任何檔案。你需要手動複製建議的程式碼並應用到專案中。
適用場景：
- 學習新框架，想理解每一步的原因
- 審查需要手動確認的敏感程式碼變更
- 初次使用 Codex 的用戶熟悉其輸出風格
auto-edit 模式（平衡）
codex --mode auto-editauto-edit 是預設模式。Codex 會自動編輯檔案，但在執行可能有副作用的命令（如 rm 或 git push）前會請求確認。
適用場景：
- 日常開發工作流
- 需要 AI 快速迭代程式碼，同時保留對關鍵操作的審批權
- 重構中等複雜度的專案
full-auto 模式（最快）
codex --mode full-auto在 full-auto 模式下，Codex 自動執行所有操作，包括檔案編輯和命令運行，無需任何確認。這是最高效但也最有風險的模式。
適用場景：
- 隔離的開發環境（如 Docker 容器）
- 完全信任 Codex 判斷並追求最大效率時
- 批量程式碼生成任務
警告：在生產環境使用 full-auto 前，請務必配置沙盒模式限制其權限範圍。
沙盒安全模型深度解析 ⭐ 核心差異
沙盒是 Codex CLI 的核心安全機制。它隔離檔案系統和命令執行權限，防止 AI 失誤或惡意行為損壞系統。理解沙盒模型是在生產環境使用 Codex 的關鍵。
三種沙盒模式對比
Codex 提供三層沙盒模式，透過 --sandbox 參數指定：
| 模式 | 檔案系統權限 | 命令執行 | 適用場景 |
|---|---|---|---|
read-only | 唯讀；不允許寫入 | 允許唯讀命令（ls, cat, grep） | 程式碼審查、文件分析 |
workspace-write | 僅允許在當前專案目錄寫入 | 允許正常命令；阻止系統級操作 | 日常開發（推薦） |
danger-full-access | 完全讀寫 | 允許所有命令 | 隔離環境、實驗任務 |
預設模式：workspace-write，平衡安全性與便利性。
四級審批策略精細度
除了沙盒模式，Codex 還提供細粒度的命令審批策略，透過 --ask-for-approval 參數控制：
| 策略 | 行為 | 適用場景 |
|---|---|---|
untrusted | 僅不受信任的命令需要審批（預設） | 日常開發 |
on-failure | 僅在命令失敗時請求審批 | 除錯場景 |
on-request | 僅在 Codex 明確請求時審批 | 對 AI 高度信任 |
never | 從不請求審批 | 配合沙盒使用 |
不受信任命令的定義：
- 網路操作（
curl、wget） - 套件管理（
npm install、pip install） - 版本控制（
git push、git reset --hard） - 系統配置（
sudo、chmod）
—full-auto 與 —yolo 的本質區別
許多用戶混淆 --mode full-auto 和 --yolo 參數。它們在不同層面運作：
--mode full-auto：控制 Codex 是否需要用戶確認程式碼編輯--yolo：跳過所有命令執行的審批提示（等同於--ask-for-approval never）
# 這兩條命令效果相同
codex --mode full-auto --yolo
codex --mode full-auto --ask-for-approval never24 個斜線命令全解析 ⭐ 核心差異
Codex CLI 提供 24 個斜線命令，涵蓋會話控制、模型切換、權限管理、檔案操作等。熟練掌握這些命令能顯著提升生產力。
會話控制（/new, /resume, /fork, /compact）
/new：清除當前上下文，開始全新對話/resume：打開歷史會話選擇器，支援按日期和目錄篩選/fork：創建當前會話的副本，在新分支中嘗試不同方案/compact：壓縮上下文，保留關鍵信息，清除冗餘對話
模型與風格（/model, /personality, /plan）
/model：運行時切換模型（gpt-5.3-codex、gpt-5、o4-mini 等）/personality：調整回應風格（concise、verbose、professional、friendly）/plan：在執行前輸出詳細執行計劃
權限與狀態（/permissions, /status, /debug-config）
/permissions：顯示當前沙盒模式和審批策略/status：顯示模型、token 使用量、會話時長等詳細信息/debug-config：診斷配置載入鏈，顯示全局配置、專案配置和環境變數覆蓋
會話恢復與歷史管理
Codex CLI 內建強大的會話管理功能：
/resume 深入
/resume打開互動式會話選擇器，列出所有歷史會話。支援：
- 按日期篩選
- 按工作目錄篩選
- 搜尋會話內容關鍵字
會話持久化機制
Codex 將每個會話的完整上下文（包括檔案修改、命令輸出、AI 回應）保存到本地存儲。即使終端關閉或系統重啟，也能透過 /resume 恢復到之前的工作狀態。
Profile 配置系統
Profile 是 Codex CLI 的高級配置機制，允許為不同專案設定不同的行為：
創建和使用 Profile
# 創建名為 "react-dev" 的 profile
codex --profile react-dev
# 在 profile 中設定預設行為
codex --profile react-dev --sandbox workspace-writeProfile 載入順序
Codex 按以下順序載入配置（後面的覆蓋前面的）：
- 內建預設值
- 全局配置（
~/.codex/config.toml） - 專案配置（
.codex/config.toml） - Profile 配置
- 命令行參數
- 環境變數
實用 Profile 範例
# ~/.codex/profiles/react-dev.toml
[model]
default = "gpt-5.3-codex"
[sandbox]
mode = "workspace-write"
[approval]
policy = "untrusted"
[aliases]
t = "npm test"
b = "npm run build"MCP 協議整合
Codex CLI 原生支援 MCP（Model Context Protocol），可以連接外部工具和服務：
配置 MCP 伺服器
# .codex/config.toml
[mcp.servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_TOKEN = "${GITHUB_TOKEN}" }
[mcp.servers.postgres]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-postgres"]
env = { DATABASE_URL = "${DATABASE_URL}" }使用 MCP 工具
配置完成後，Codex 可以自動調用 MCP 伺服器提供的工具：
> 查看我的 GitHub 倉庫列表
[CODEx] 正在調用 github:list_repos...
找到以下倉庫：
- my-project (private)
- open-source-lib (public, 1.2k stars)
...與 Claude Code 的全面對比
作為終端 AI 編程工具的兩大競爭者，Codex CLI 和 Claude Code 各有優勢：
| 特性 | Codex CLI | Claude Code |
|---|---|---|
| 開發商 | OpenAI | Anthropic |
| 開源 | ✅ 完全開源 | ❌ 閉源 |
| 基礎模型 | GPT-5 系列 | Claude 系列 |
| 沙盒安全 | 三層模式 | 內建沙盒 |
| MCP 支援 | ✅ 原生 | ✅ 原生 |
| 會話管理 | /resume, /fork | 內建歷史 |
| 配置系統 | Profile + TOML | CLAUDE.md |
| 免費額度 | ChatGPT 訂閱用戶有 | Pro 用戶包含 |
| 價格 | API 計費 | $20/月（Pro） |
選擇建議
- 選擇 Codex CLI：如果你偏好開源、需要靈活的沙盒配置、或已有 ChatGPT 訂閱
- 選擇 Claude Code：如果你更看重程式碼品質、需要更強的推理能力、或偏好 Anthropic 的生態
常見問題與排錯
Q: codex: command not found
確認 npm 全局安裝目錄在 PATH 中：
npm config get prefix
# 確保輸出的路徑/bin 在 $PATH 中Q: 認證失敗
檢查 API Key 是否正確設定：
echo $OPENAI_API_KEY
# 或重新運行 codex loginQ: 沙盒權限錯誤
如果遇到檔案寫入權限問題，檢查當前沙盒模式：
# 切換到更寬鬆的模式
codex --sandbox workspace-writeQ: MCP 連接失敗
確認 MCP 伺服器命令可用且環境變數已設定：
# 測試 MCP 伺服器
npx -y @modelcontextprotocol/server-github總結
OpenAI Codex CLI 是一個功能強大且靈活的終端 AI 編程工具。它的開源特性、三層沙盒安全模型、24 個斜線命令、Profile 配置系統和 MCP 協議整合，使其成為 2026 年開發者工具箱中不可或缺的成員。
無論你是個人開發者還是團隊用戶，Codex CLI 都能透過靈活的配置適應你的工作流程。建議從 auto-edit 模式和 workspace-write 沙盒開始，逐步探索更高级的功能。
