Codex CLI 這類工具最容易踩的坑，不是安裝不起來，而是你看到的教學版本其實已經過時，像是把登入流程、模型切換方式或設定檔名稱寫錯。這篇我直接對照 OpenAI 官方 Codex 文件整理，所以你看到的是目前比較接近官方做法的版本。
除了基本安裝，這篇會深入 AGENTS.md 進階寫法、sandbox 安全機制、full-auto 模式、以及怎麼讓 Codex 跟 Claude Code 等其他 AI 工具搭配使用。如果你想把 Codex 放進 VPS、開發機或專案工作流裡，這篇會幫你從「能跑」升級到「真正有用」。
你會學到什麼
- 用官方目前的方式安裝 Codex CLI
- 理解首次執行時的登入方式，以及 ChatGPT 帳號與 API key 的差異
- 知道
AGENTS.md在 Codex 工作流裡扮演什麼角色，以及怎麼寫出高品質的規則 - 掌握 sandbox 執行機制與 full-auto 模式的使用時機
- 在實際開發場景中活用 Codex 做 debug、code review 和重構
什麼情況最適合先看這篇
- 想在 VPS 上建立 AI 開發環境、工具鏈或自動化流程的開發者
- 想把 Codex 放進既有 repo 工作流，而不是只在空白資料夾裡試玩的人
- 你希望看的是接近 OpenAI 官方現況的寫法
- 想了解 Codex sandbox 機制，讓 AI 在安全環境中自動執行的人
開始前先確認
- 你目前在 macOS 或 Linux 環境；官方文件提到 Windows 支援仍屬實驗性，最佳做法是用 WSL
- 你已安裝 Node.js 與 npm，因為官方安裝方式是
npm i -g @openai/codex - 先想清楚你要用 ChatGPT 帳號登入，還是用 OpenAI API key
先提醒你一件事
Codex 官方目前主推的是直接執行 codex 後完成首次登入，不是先跑一個獨立的 codex auth 指令。很多舊教學還在沿用過時寫法，這就是最容易讓新手卡住的地方。
詳細教學與操作步驟
Codex CLI 是 OpenAI 官方的本地 coding agent，可直接在終端機中讀 repo、改檔案、執行命令。根據 OpenAI 官方文件，Codex CLI 採 Rust 實作，支援在本機工作目錄中互動式執行。
為什麼現在應該直接看官方 Codex CLI 文件？
Codex CLI 這類工具更新很快，舊教學最常過時的地方包括：安裝指令、登入流程、可用模型名稱，以及專案規則檔的名稱。OpenAI 官方目前明確寫的是透過 npm i -g @openai/codex 安裝，首次執行 codex 時登入，並在 repo 內使用 AGENTS.md 提供長期規則。
步驟一：安裝 Codex CLI
OpenAI 官方文件提供 npm 與 Homebrew 兩種安裝方式；如果你是在 Linux VPS 上，最直接的方式就是 npm：
npm install -g @openai/codex
若要升級到最新版，官方文件建議使用：
npm install -g @openai/codex@latest
步驟二：第一次執行與登入
安裝完成後，直接執行：
codex
根據 OpenAI 官方 CLI 文件，第一次執行時 Codex 會提示你登入。你可以使用 ChatGPT 帳號 或 API key 完成驗證。這點很重要，因為很多舊文章還會教你找不存在或已不推薦的獨立認證子命令。
如果你選擇用 API key，可以透過環境變數設定：
export OPENAI_API_KEY="your_api_key_here"
步驟三：理解三種執行模式
Codex CLI 提供三種不同信任等級的執行模式，這是它跟其他 AI CLI 工具最大的差異之一：
| 模式 | 說明 | 適用場景 |
|---|---|---|
| suggest（預設） | 只建議修改，不自動執行 | 初次使用、敏感 repo |
| auto-edit | 自動修改檔案，但不執行命令 | 日常開發、信任的 repo |
| full-auto | 自動修改檔案並執行命令 | 測試環境、sandbox 內 |
切換模式的方式：
codex --approval-mode auto-edit "refactor this function"
codex --approval-mode full-auto "fix all lint errors and run tests"
重要提醒： full-auto 模式會在 sandbox 中執行命令。在 macOS 上使用 Apple Seatbelt，在 Linux 上使用容器隔離。這表示 Codex 無法在 full-auto 模式下存取你的整個檔案系統，它被限制在工作目錄內。
步驟四：深入 AGENTS.md — Codex 的專案大腦
Codex 會沿著目錄層級讀取 AGENTS.md。OpenAI 官方文件也明確建議把專案層規則寫在 repo root 的 AGENTS.md。但跟隨便寫幾行不同，一份好的 AGENTS.md 能顯著提升 Codex 的工作品質。
AGENTS.md 的層級架構
~/.codex/AGENTS.md # 全域預設（個人偏好）
{repo-root}/AGENTS.md # 專案根目錄（技術棧、建置指令）
{repo-root}/src/AGENTS.md # 子目錄層級（模組特定規則）
一份高品質 AGENTS.md 範例
# AGENTS.md
## Project Overview
Next.js 16 static site with App Router.
Output mode: static export (no server runtime).
## Build & Test Commands
- npm run build # Must pass before any PR
- npm run lint # ESLint check
- npm test # Jest unit tests
## Code Conventions
- TypeScript strict mode
- Use ES modules (import/export)
- Commit messages: conventional commits in Chinese
## Boundaries
- NEVER modify files in migrations/ directory
- NEVER commit .env or credentials files
- Always run build after modifying components
## Common Patterns
- API routes are in app/api/ (but not used in static export)
- Shared components in components/ui/
- Content files use .mdx format with YAML frontmatter
AGENTS.md 進階技巧
- 寫明「不要做什麼」。 Codex 會嚴格遵守禁止規則，例如「不要修改 package-lock.json」。
- 提供驗證指令。 寫明
npm run build必須通過，Codex 在 full-auto 模式下會自動執行驗證。 - 描述架構決策的原因。 不只寫「用 static export」，還要寫「因為部署到 GitHub Pages，不支援 server runtime」。
- 分層管理不同模組的規則。 前端和後端的 coding style 可能不同，用子目錄的 AGENTS.md 處理。
步驟五：Sandbox 機制深入理解
Sandbox 是 Codex 的核心安全功能。當你使用 auto-edit 或 full-auto 模式時，Codex 會限制執行環境：
macOS（Apple Seatbelt）：
- 檔案系統存取限制在工作目錄內
- 網路存取可設定為允許或禁止
- 無法存取你的家目錄其他位置
Linux（容器隔離）：
- 使用輕量容器技術隔離
- 檔案變更在容器內進行
- 你可以在 review 後決定是否套用
這代表你可以放心讓 Codex 在 full-auto 模式下嘗試修復 bug，即使它搞砸了，也不會影響 sandbox 外面的環境。
# 安全地讓 Codex 嘗試修復所有測試
codex --approval-mode full-auto "fix all failing tests, run npm test after each fix"
步驟六：實戰場景 — Codex 在日常開發中怎麼用
Debug 工作流
codex "這個 function 在輸入空陣列時會 crash，幫我找出原因並修復"
Codex 會分析程式碼、找出問題、建議修復方案。在 auto-edit 模式下會直接改好檔案。
Code Review 工作流
codex "review 目前所有未 commit 的變更，檢查安全性、效能與可讀性"
Codex 會逐一檢查修改的檔案，指出潛在問題，並建議改善方式。
重構工作流
codex --approval-mode auto-edit "把所有 callback 改成 async/await"
大範圍的語法升級特別適合用 auto-edit 模式，讓 Codex 自動改檔案，你只需要最後 review 結果。
批次修復 — full-auto 的最佳場景
codex --approval-mode full-auto "fix all TypeScript type errors, run tsc after each fix"
這是 full-auto 最閃亮的場景：讓 Codex 在 sandbox 裡反覆修改並驗證，直到所有型別錯誤都解決。
步驟七：Codex 與其他 AI 工具的協作
在實務中，你不一定只用一個 AI 工具。一個高效的搭配方式：
- 用 Claude Code 做架構分析和大範圍重構 — 因為它的上下文理解能力強
- 用 Codex 做獨立的 bug fix 和自動化修復 — 因為 sandbox 讓它可以安全地嘗試
- 用 Gemini CLI 查文件和搜尋解法 — 因為它有 Google 搜尋整合
# 先用 Claude Code 分析問題
claude "分析目前 codebase 的效能瓶頸，列出前 5 個最嚴重的問題"
# 再用 Codex 逐一修復
codex --approval-mode auto-edit "optimize the database query in users.ts"
核心功能指令
- 開啟互動模式：
codex - 指定執行模式：
codex --approval-mode full-auto "your task" - 切換模型： 在互動模式中使用
/model - 查看 up-to-date 用法： 優先參考 CLI 內建 slash commands 與官方文件
- 專案內啟動： 請在 repo 根目錄或子目錄執行，讓 Codex 讀到對應的
AGENTS.md - 靜默模式：
codex -q "task"減少輸出雜訊
常見問題
Q：現在還是用 CLAUDE.md 嗎？
如果你是給 Codex 用的專案規則，OpenAI 官方目前主推的是 AGENTS.md。如果你的 repo 也同時有給其他系統用的說明檔，請注意不要讓兩邊內容互相矛盾。
Q：可以用最新模型嗎？
官方文件寫明你可以在 CLI 內透過 /model 切換可用模型與推理等級。實際有哪些模型，會跟你當下帳號權限與 CLI 版本有關。
Q：full-auto 會不會把我的專案搞壞？ Sandbox 機制會限制 Codex 只能在工作目錄內操作。如果你還是不放心，可以先在 Git branch 上操作，全部完成後再 merge。
Q：sandbox 在 Docker 容器裡能用嗎？
在 Docker 容器內使用 Codex 的 sandbox 可能需要額外設定。如果遇到權限問題，可以考慮在容器外執行 Codex，或使用 suggest 模式避開 sandbox 限制。
Q：AGENTS.md 和 CLAUDE.md 可以共存嗎？ 可以。兩個檔案分別被不同工具讀取，互不干擾。但建議保持規則一致性，避免兩邊寫出矛盾的指令。
做完後怎麼確認自己真的有設對
- 執行一次
codex，確認可以正常進入互動模式 - 第一次登入完成後，在任一 repo 裡測一次簡單要求，確認 Codex 能讀到目前目錄的規則檔
- 如果你有設專案內的
AGENTS.md，可以直接要求它摘要目前載入的規則來源 - 測試
auto-edit模式：讓 Codex 做一個簡單的檔案修改，確認它真的有改到檔案 - 測試
full-auto模式：讓 Codex 執行一個簡單指令（例如ls），確認 sandbox 正常運作
這一題最常踩的坑
- 還在照舊教學跑不存在或不建議的子命令
- 以為 Codex 會自動讀任何檔名的專案說明，結果其實沒被當成指令來源
- 把登入方式、方案權限與模型可用性混在一起理解，導致排錯方向跑掉
- 一開始就用
full-auto模式跑在正式 branch 上，結果出問題很難回復 - AGENTS.md 寫得太空泛（「寫好的程式碼」），Codex 無法據此行動
- 不知道 sandbox 限制，以為 full-auto 可以存取任意路徑
如果你要往下一步走
裝好 Codex 後，最值得馬上補的不是更多安裝指令，而是把 repo 的 AGENTS.md 與工作規則寫好。若你還要在同一台機器上直接串 OpenAI API，可以接著看 OpenAI API (Python) 開發環境安裝教學。想了解其他 AI coding agent 的使用方式，可以看 Claude Code 安裝教學 或 Gemini CLI 安裝教學。