用說人話叫它寫程式

Codex CLI 是一個住在你終端機裡、聽你說「人話」就會自己讀檔、改檔、跑程式的 AI 工程師。

想像你旁邊坐了一位不會累、不會抱怨的工程師。你不用幫它寫一行 code，只要像交辦同事那樣開口：「幫我把這個錯誤修好」「照這張設計稿切版」「解釋一下這個專案在幹嘛」。它會自己去翻你的檔案、擬個計畫、動手做，然後把結果攤在你眼前。

這一章，我們就來學怎麼「開口」。重點不是背指令，而是學會把需求講清楚——講得越具體，它做得越準。你會學到：

• 怎麼啟動互動模式，看懂它的畫面長什麼樣。
• 怎麼下第一個 prompt（指令），用官方推薦的「四要素」寫法。
• 怎麼用 @ 一個鍵就把專案裡的檔案塞給它讀。
• 怎麼選用哪個模型、讓它「想深一點」或「快一點」。
• 怎麼把截圖、設計稿直接丟給它看。

4.1 啟動互動模式，看懂它的畫面

最簡單的開場：打 codex

在你想工作的專案資料夾裡，打開終端機，輸入這個字、按 Enter：

codex

就這樣。Codex 會在你目前所在的資料夾啟動一個互動式畫面（官方叫 TUI，Terminal UI，就是「終端機裡的操作介面」），然後跟你「結對」工作——它能在這個資料夾裡讀檔、改檔、跑指令。

想在別的資料夾工作？用 -C

如果你人不在那個專案資料夾、又懶得先 cd 切過去，可以用 -C（或寫全名 --cd）直接指定：

codex -C /path/to/project

-C, --cd PATH 會在 Codex 開始工作前，先把工作目錄切到你指定的地方。

TUI 畫面有哪幾塊

進去之後，畫面大致分三塊，先認識一下名字（後面常用到）：

不想進畫面，只問一句話

有時你只想問一個問題、要一個答案，不想進那個互動畫面。那就把問題用引號直接接在 codex 後面：

codex "explain this codebase"

Codex 會讀你的工作目錄、擬計畫、把回應印在終端機上，然後結束。這叫「一次性（one-off）」用法，很適合快速問一句。

codex -C /specific/dir -m gpt-5.5 "your prompt"

更精確一點：這樣算不算「進去了」？

上面說「不想進畫面，那就打 codex "explain this codebase"」，但嚴格來說，這句話還是把你帶進了同一個互動畫面——只是它幫你把第一句話先講好了，你不用自己再對著空白的 composer 打字。Codex 讀完這句話會照樣擬計畫、動手、跟你來回，跟純打 codex 再手動輸入是同一個流程，只差在「開場白」先幫你打好了而已。

如果你要的是真正「不進畫面、跑完就結束、回到終端機」的那種一次性——例如寫進腳本、丟給 CI 跑——官方另外準備了一個獨立指令：

# 非互動、跑完自動結束，別名可簡寫成 e
codex exec "幫 src/utils/date.ts 補上單元測試"

codex exec（別名 e）才是不進互動畫面、專門給自動化場景用的版本。這條指令水很深（非互動模式下核可規則會整個變樣，坑也不少），本書把它獨立成一整章講，見第 10 章。這裡你只要記得：有沒有引號帶 prompt，決定的是「要不要先幫你打第一句話」；要不要真的離開互動畫面，看你打的是 codex 還是 codex exec。

4.2 第一個 prompt：官方「四要素」寫法

為什麼「講清楚」這麼重要

Codex 很強，但它不會通靈。你給的指令越模糊，它就越要自己「猜」你的意思，猜錯了你還得重來。把需求講清楚，是你能做的最划算的事。

先看一組對比，感受一下差別：

❌ 太模糊：把登入修一下。
✅ 夠具體：登入頁按下「送出」沒反應，幫我修好；改完登入流程要能正常導向首頁。

官方推薦的四要素

OpenAI 在官方最佳實務文件裡給了一個好記的範本：稍微複雜一點的任務，prompt 最好包含四個要素。

官方原文是這樣描述四要素的（逐字）：

• Goal: What are you trying to change or build?
• Context: Which files, folders, docs, examples, or errors matter?
• Constraints: What standards, architecture, safety requirements apply?
• Done when: What should be true before the task is complete?

官方說，這個結構能讓 Codex「stay scoped, make fewer assumptions, and produce work that's easier to review」——也就是更聚焦、少亂猜、做出來的東西更好檢查。

目標：我要 ____
脈絡：相關的有 @____、@____，錯誤訊息是 ____
限制：要遵守 ____，不要動 ____
完成條件：當 ____ 成立就算完成

目標：在 /api/users 這支 API 加上分頁參數 limit 和 offset。
脈絡：@routes/posts.ts 裡已經有分頁寫法可以參考，照同樣的風格做。
限制：不要新增套件；回傳的 JSON 格式要跟現在一樣，只是多加分頁欄位。
完成條件：npm test -- users.pagination 這個測試檔全部跑過。

4.3 鍵盤快捷與 @ 引用檔案

一個鍵把檔案塞給它：@

這是最實用的一招。在 composer 裡打一個 @，Codex 會跳出一個模糊搜尋選單，讓你在專案根目錄底下快速找檔案；選好按 Tab 或 Enter，那個檔案路徑就被放進你的訊息裡。

官方原文（逐字）：Type @ in the composer to open a fuzzy file search over the workspace root; press Tab or Enter to drop the highlighted path into your message.

除了打 @，你也可以用 slash 指令 /mention 把一個檔案附到對話裡（官方描述：Attach a file to the conversation），效果類似。

常用鍵盤快捷鍵

下面這些是官方 features 頁逐字列出的快捷鍵，在 TUI 裡很常用：

4.4 選模型與推理強度（minimal–xhigh）

模型是什麼、為什麼要選

「模型」就是背後那顆真正在思考的 AI 大腦。不同模型有不同的速度、聰明程度、費用。Codex CLI 讓你自由選用哪一顆。

官方目前（2026-06 觀測）推薦的幾個模型：

選模型的三種方法

方法一：啟動時用 -m（只影響這一次）

# 短旗標
codex -m gpt-5.5

# 長旗標（等價）
codex --model gpt-5.5

-m <model> 是暫時切換，不會寫進設定檔。

方法二：對話中用 /model（隨時切）

在互動畫面裡打：

/model

會跳出選單，讓你即時切換模型，以及（若該模型支援）推理強度。

方法三：寫進設定檔（永久預設）

在 ~/.codex/config.toml（你的個人設定檔）裡寫一行：

model = "gpt-5.5"

之後每次啟動都預設用它。設定檔的完整玩法第 8 章會專門講。

推理強度：讓它「想深一點」還是「快一點」

有時候你想讓它想得更深（複雜重構、難纏的 bug），有時候只想要快（簡單小改）。這個旋鈕叫推理強度（reasoning effort）。

設定鍵叫 model_reasoning_effort，官方允許這幾個值（由淺到深）：

minimal  <  low  <  medium  <  high  <  xhigh

越往右，它想得越深、越久、越仔細；越往左，回得越快。一個好記的心法：

• 互動式快速回合 → 用淺的（minimal / low）。
• 複雜重構、除錯、設計決策 → 用深的（high / xhigh）。

設定方法也有幾種，最常用兩種：

寫進設定檔（永久）：

model_reasoning_effort = "high"

或啟動時用 -c 臨時覆寫一次（-c 是「覆寫單一設定」，可重複用）：

codex -m gpt-5.5 -c model_reasoning_effort="high"

4.5 附圖前先做資料分級（-i 與貼圖踩坑）

Codex 看得懂圖

Codex CLI 能同時接收「文字 + 圖片」。先確認圖片可安全提供後，再把錯誤畫面截圖、設計稿或流程圖附上；它會連同你的文字指示一起閱讀。典型用途：

• 把報錯畫面截圖丟過去，問「這個錯誤怎麼回事」。
• 附一張設計稿，要它照著切版。
• 丟兩張圖，要它比對。

最可靠的方法：命令列 -i / --image

這是最穩、最不會出錯的方式。用 -i（或寫全名 --image）把已分級、已遮罩的圖片檔附上：

# 單張已遮罩的圖 + 問題
codex -i sanitized-error.png "說明這個錯誤可能的原因；只提出排查步驟，不要修改檔案。"

# 多張圖（逗號分隔，中間不要有空格）
codex --image public-diagram-1.png,public-diagram-2.jpg "整理這兩張公開流程圖的重點。"

官方對這個旗標的逐字說明：Attach one or more image files to the initial prompt. Separate multiple paths with commas or repeat the flag.

傳多張圖有兩種寫法，都行：

# 寫法一：逗號分隔（路徑之間「不要」有空格）
codex -i path1.jpg,path2.png

# 寫法二：重複旗標
codex -i path1.jpg -i path2.png

codex -i design-spec-redacted.png -i current-screenshot-redacted.png \
  "第一張是設計稿，第二張是目前畫面。先列出可驗證的差異，不要修改檔案；等我確認後再提出最小修改計畫。"

TUI 裡直接貼圖（最容易踩坑）

你也可以在互動畫面的 composer 裡，直接從剪貼簿貼上圖片。但這一塊跨平台、跨終端機的相容性有坑，要特別小心。

一個典型的 macOS 截圖→貼圖流程：

1. 🍎 Mac：用 Cmd + Shift + 4 截圖到剪貼簿。
2. 回到 Codex CLI 的輸入框，按 Ctrl+V 貼上。
3. 加上文字指示，送出。

各平台貼圖鍵：

變通招與格式注意

• 貼不上圖，就改用 --image：先確認本機檔案已遮罩，再用 --image 指定它；單純貼上路徑字串不是可靠的附圖方式。
• 支援格式：官方明確背書 PNG 和 JPEG（Codex accepts common formats such as PNG and JPEG.）。BMP / TIFF / SVG / HEIC 這類建議先轉成 PNG / JPEG 再丟。

4.6 🎓 高手進階

1️⃣ 四要素深用：Goal 寫「結果」、Done-when 寫「可驗的事實」

4.2 教了四要素的「格式」。高手的差別在每一段怎麼寫才讓 Codex 不偷工：

官方最佳實務文件對「驗證」給的逐字指引是：create tests when needed, run the relevant checks, confirm the result, and review the work before you accept it——該寫測試就寫、跑相關檢查、確認結果、你自己 review 過再收下。

2️⃣ 冷門快捷鍵：讓 TUI 更順手

4.3 列了常用快捷鍵。下面這幾個官方有逐字列出、但比較少人知道，熟了很省事（以下皆官方 features 頁逐字精神）：

3️⃣ 用 /keymap 查真實鍵位、甚至自訂

4.3 提過：有些第三方教學說的按鍵（像 Alt+, / Alt+. 調思考深度）官方沒逐字寫死確切鍵，版本之間還會變。要查你這個版本當下真正的鍵位，最權威的方法是在 TUI 打：

/keymap

/keymap 不只能重新綁定快捷鍵，還能 inspect（檢視） 目前每個情境下生效的鍵位，並把你的自訂存進 config.toml。所以「這版到底按哪個鍵」——別查文件，問 /keymap 最準。

4️⃣ 推理強度的「成本面」：xhigh 不是免費的

4.4 教了 minimal–xhigh 五級「怎麼設」。高手還會算一筆帳：

• xhigh 比 medium 大約多燒 3–5 倍 token（同一個 prompt）。想得越深 = 推理（thinking）token 越多 = 越貴、越慢。簡單小修開到 xhigh 是純浪費。
  ⚠️

  這個 3–5x 是社群量測的量級概念，不是官方保證值，實際依模型/版本變動。以實機用量為準（在 TUI 打 /usage 可看每日/每週/累積的 token 活動；打 /status 看當前 session 的 token 用量）。

• model_reasoning_effort 只在 Responses API 的模型上有效（官方逐字 Responses API only）。接走 Chat Completions 的第三方/本地模型可能完全沒感覺。
• xhigh 還是「看模型而定」（model-dependent）——不是每個模型都吃這一檔，不支援時可能無效。

進階旋鈕：規劃用深、執行用淺。高手會把「想方案」和「動手做」的思考深度分開設。官方 config.toml 有一個獨立鍵 plan_mode_reasoning_effort，讓你只在規劃（plan）階段給高 effort，真正寫 code 時用一般 effort，省下大筆 thinking token（Plan 模式本身怎麼進入、怎麼用，第 7 章 7.1有完整一節）：

model_reasoning_effort = "medium"        # 平常執行：省
plan_mode_reasoning_effort = "high"      # 只有規劃階段：深

model_reasoning_effort = "medium"     # 一般任務的平衡點
model_reasoning_summary = "none"      # 不需要推理摘要就關，省 output token
model_verbosity = "low"               # 回應更精簡，再省一點 output

5️⃣ slash 指令的進階語意（挑幾個常被誤會的）

4.1 提過 / 會跳出 40 多個 slash 指令。這裡補幾個容易誤會或藏比較深的（官方 slash-commands 頁逐字）：

6️⃣ 改到一半卡住、或一直重試？先查兩個常見兇手

大多數時候 Codex 改檔案很順，但偶爾你會遇到它對同一個地方改了又改、或核可視窗一直跳出來要你重新確認，感覺卡在迴圈裡出不來。這裡列兩個實務上常見的成因，遇到時先往這邊查：

如果以上兩個都對不上你遇到的狀況，完整的疑難排解工具箱（codex doctor、RUST_LOG 除錯、網路與憑證問題排查）留給第 16 章整章處理，這裡只先點出跟「叫它寫程式、結果卡住」直接相關的兩個常見狀況。

7️⃣ 任務大到不知道怎麼下手？找另一顆模型幫你先擬 prompt

四要素講起來簡單，但遇到真的複雜、你自己都還沒完全想清楚脈絡的大任務（例如「把整個認證流程換掉」這種），要一次寫出一份講到位的四要素反而很難——你可能連 Context 該列哪些檔案都還沒摸清楚。

一個實務上好用的技巧叫 meta-prompting：先不要急著自己手刻這份 prompt，改成另開一個對話（隨便哪個 LLM 都行），把你的任務描述給它，請它：

1. 先研究一下這個功能／模組現在是怎麼運作的；
2. 針對你的專案，生出 2–3 個候選的四要素 prompt 版本；
3. 你自己逐一檢查每個版本的「完成條件」是不是真的可驗證、任務是不是該拆成多輪而不是一次做完。

挑一個看起來最扎實的版本，再丟進 Codex。這聽起來像繞遠路，但對「你自己都還沒想清楚」的任務，先讓另一顆模型幫你把問題想過一輪，往往比自己憑感覺手刻一份 prompt 更準，省下來的返工時間通常划算。

小結

這一章你學會了和 Codex「開口對話」的基本功：打 codex 進互動畫面、用「四要素」把需求講清楚、用 @ 一鍵把檔案塞給它、選模型和調思考深度、把截圖設計稿丟給它看。記住核心心法——講得越具體，它做得越準。

動手試試

1. 在一個小專案裡打 codex，然後問一句 解釋這個專案在做什麼，看它怎麼讀檔回應。
2. 用四要素寫一個小任務（例如「幫某個函式加上錯誤處理」），記得用 @ 把相關檔案指給它。
3. 用自己做的測試畫面或公開圖片練習。若有任何真實資料，先遮罩並另存為 sanitized.png，再跑 codex -i sanitized.png "這張圖裡有什麼可改善之處？只列建議，不要修改檔案。"。
4. 找一個你熟悉網站的兩張模擬或已遮罩圖片——一張目前畫面、一張改過顏色或文字的「模擬設計稿」——用 codex -i a-sanitized.png -i b-sanitized.png "列出這兩張圖的差異，不要修改檔案" 練習雙圖比對。

本章官方文件參考

• CLI 功能與快捷鍵（features）：https://developers.openai.com/codex/cli/features
• CLI 指令列旗標（reference）：https://developers.openai.com/codex/cli/reference
• Slash 指令清單：https://developers.openai.com/codex/cli/slash-commands
• 模型清單（Models）：https://developers.openai.com/codex/models
• 設定參考（config-reference，含 model_reasoning_effort）：https://developers.openai.com/codex/config-reference
• 最佳實務（四要素 prompting）：https://developers.openai.com/codex/cli
• CLI 版本號（GitHub releases，看 rust-vX.Y.Z）：https://github.com/openai/codex/releases