Codex CLI 完整教學

這是一份寫給新手的教學。Codex CLI 是 OpenAI 推出、住在你終端機裡、會自己讀檔、改檔、跑指令的 AI 工具。就算你從沒打過一行程式，也能先從認識終端機、建立練習資料夾、安裝與登入開始。

從第 0 章開始 →

第一次來，只要先走第 0～3 章。

你會認識工具、打開終端機、完成安裝與登入。多代理、雲端協作等內容是後續選讀，不是起步門檻；今天看不懂或還用不到都可以先略過。

還不確定為什麼要從聊天網頁換到 CLI？

先讀跨工具的〈為什麼要用 AI CLI？〉：用 10 分鐘看懂適用情境、第一次安全任務，以及長開發怎麼靠 Plan、Git、驗證與交棒接起來，再回來選工具。

本教學依撰稿當時的 Codex CLI 版本與官方文件整理。CLI 工具更新頻繁，指令旗標、設定欄位、登入流程可能隨版本調整。遇到與實際畫面不符時，請以官方文件與資源地圖（附錄 C）列出的官方來源為準。

這份教學會帶你學什麼？

Codex CLI 不只是回你文字，而是能真的讀你的檔案、改你的程式、在你的終端機跑指令。這份教學從零開始，帶你從安裝登入，一路走到自動化、多代理工作流、安全強化與雲端協作。

下面是完整章節地圖，分成六篇循序漸進。第一次先完成第 0～3 章；有實際專案後，再從工作流、自動化或團隊協作挑需要的內容。第 5 篇是深入 prompt 工程、多代理與 MCP 的選讀專章；第 6 篇則是疑難排解與速查附錄。

常用指令與情境推薦

Codex 的推薦主線是「互動模式做規劃與審查，長任務先由安全 launcher 固定 sandbox／approval 邊界，再讓 Auto-review 審查 eligible escalation、用 /goal 固定完成條件，穩定的一次性工單才交給 codex exec」。需要深度決策時，可用官方 model_reasoning_effort 搭配你的 ultrathink 提示語；但推理強度不會取代 sandbox、授權與驗收證據。

速記：model_reasoning_effort=xhigh 是 Codex 的最高深想設定；CLI 一次性覆寫用 -c model_reasoning_effort=xhigh，設定檔則寫 model_reasoning_effort = "xhigh"。不要把 model_reasoning_effort/xhigh 當成可執行語法。

情境	推薦指令	怎麼用
互動式先規劃	`/plan`	讓 Codex 先讀脈絡、問問題、提出實作計畫；適合你還想人工拍板的任務。
安全長任務	Auto-review launcher＋`/goal`	先固定 `workspace-write + on-request + auto_review`，再寫 outcome、constraints、verification；完整詠唱見第 7 章 7.6。
自動深想後派工	`codex exec -c model_reasoning_effort=xhigh`	非互動模式內先拉高推理預算，再用 `ultrathink` prompt 要求比較方案、選最佳解、spawn subagents、整合、實作與驗證。
兩段式安全執行	`codex exec` + `codex exec resume --last`	第一段唯讀分析與決策，第二段沿用上一輪脈絡自動實作，風險比 one-shot 低。
平行審查	prompt 內寫 `spawn one agent per point`	Codex 官方 subagents 只會在你明確要求時啟動；適合安全、測試、維護性分頭查。
收尾驗證	`/diff`、`/review`、`/status`	互動模式看 diff、請 Codex review 工作樹、檢查模型/權限/context；自動化則用 `--json` 抓事件。

# 一段式 fail-closed：never 不會啟動 Auto-review；越界直接失敗
codex \
  --sandbox workspace-write \
  --ask-for-approval never \
  -c model_reasoning_effort=xhigh \
  exec \
  "ultrathink。先讀 AGENTS.md 與相關檔案，列出 2-3 個可行方案並選最佳解；不等我確認，選定後再實作。需要時 spawn parallel subagents：一個探索架構、一個檢查風險、一個規劃測試。等全部回報後整合、改檔、跑最相關驗證，最後回報變更、驗證結果與殘留風險。"

# 兩段式：第一輪只決策，第二輪沿用脈絡自動落實
codex --sandbox read-only -c model_reasoning_effort=xhigh exec \
  "ultrathink。只做方案比較與最佳解決策，輸出可執行工單、檔案範圍、驗收標準與派工切分。"
codex --sandbox workspace-write --ask-for-approval never exec resume --last \
  "按照上一輪選定方案派工並實作；必要時 spawn subagents，完成後跑驗證並回報。"

官方 codex exec、--sandbox、--ask-for-approval、--json、resume --last、subagents 與 model_reasoning_effort 來自 OpenAI Codex manual；詠唱 ultrathink 在 Codex 這裡是提示語，不是官方旗標。

別把上面的 -a never 範例當成 Auto-review：它適合不允許任何新越界的封閉 CI。若工作需要 reviewer 自動判斷 eligible escalation，改走第 7 章的安全 Auto-review 工作流。

小提醒

不用急著一次讀完。建議照順序，邊讀邊在自己終端機上跟著做一次，學起來最快。右上角的 A−／A＋ 可以調整文字大小，調好之後翻到別章也會記得。