01 · Codex 是什麼

Codex 是 OpenAI 面向軟體開發的 coding agent。它不是單純回答“程式碼該怎麼寫”，而是能在你的專案上下文裡讀檔案、提出計劃、修改程式碼、執行命令，並把結果交給你審查。

理解 Codex 的關鍵，不是先背命令，而是先分清它和聊天助手、程式碼補全、自動化指令碼的邊界。

從 AI 到 Coding Agent

Codex 位於“AI -> 模型 -> 助手 -> Agent -> Coding Agent”這條鏈路的最後一層。

flowchart TB
    AI["AI<br/>讓機器執行智慧任務"]
    Model["大語言模型<br/>理解和生成文本、程式碼、結構化內容"]
    Assistant["AI 助手<br/>以對話形式回答問題"]
    Agent["Agent<br/>圍繞目標讀取上下文、呼叫工具、觀察結果"]
    Coding["Coding Agent<br/>在程式碼庫裡推進工程任務"]
    Codex["OpenAI Codex"]

    AI --> Model --> Assistant --> Agent --> Coding --> Codex

這一層級關係有兩個結論：

• Codex 不是一個“更會聊天的 ChatGPT”。
• Codex 也不是固定指令碼，而是會根據專案現場調整步驟的 agent。

所以你給 Codex 的任務，不能只寫“幫我最佳化一下”。你需要告訴它目標、邊界、驗證方式和不希望它碰的範圍。

Codex 進入的是工程現場

工程現場不是一段孤立程式碼，而是一整套約束。

mindmap
  root((工程現場))
    程式碼
      檔案結構
      Git diff
      依賴版本
    規則
      AGENTS.md
      專案規範
      團隊邊界
    工具
      測試
      Lint
      型別檢查
      構建
    風險
      許可權
      沙箱
      審批
      未提交改動

Codex 的價值在於它能圍繞這些約束工作：

• 先看專案結構，而不是憑空寫程式碼。
• 識別當前分支已有改動，而不是覆蓋別人的工作。
• 根據測試、型別檢查、構建結果繼續調整。
• 在許可權和審批邊界內執行命令。
• 最後給出可審查的檔案變更和驗證結果。

這也是為什麼 Codex 教程必須講 AGENTS.md、sandbox、approval、MCP、skills、hooks。它們不是附加功能，而是 coding agent 能可靠工作的基礎設施。

和聊天助手的區別

聊天助手更像“問答介面”。它能解釋概念、給程式碼片段、分析報錯，但通常不會直接進入你的工作樹完成任務。

Codex 更像“受控的工程協作者”。它會圍繞一個目標推進：

flowchart LR
    Task["任務"] --> Context["讀取上下文"]
    Context --> Plan["形成計劃"]
    Plan --> Action["呼叫工具 / 修改檔案"]
    Action --> Observe["觀察結果"]
    Observe --> Verify["驗證"]
    Verify --> Review["交給人審查"]
    Observe -. "失敗時調整" .-> Plan

這帶來一個根本差異：

• 聊天助手錯了，主要問題是“答錯”。
• Codex 錯了，可能是“做錯”，因為它可能真的改檔案、執行命令、影響專案狀態。

因此，使用 Codex 時，最重要的能力不是寫漂亮 prompt，而是設定正確邊界。

和程式碼補全的區別

程式碼補全通常發生在游標附近。它根據當前檔案和鄰近上下文補出幾行程式碼。

Codex 處理的是任務，而不是游標：

• 修一個跨檔案 bug。
• 審查一個 PR 的風險。
• 把一組文件改成統一格式。
• 執行測試並定位失敗原因。
• 根據現有架構實現一個小功能。

程式碼補全適合“下一行怎麼寫”；Codex 適合“這個任務該如何完成並驗證”。

和自動化指令碼的區別

指令碼適合固定流程。輸入穩定、步驟固定、結果可預測時，指令碼更直接。

Codex 適合需要判斷的流程。比如：

• 測試失敗後判斷是型別錯誤、依賴錯誤還是業務邏輯錯誤。
• 文件格式不統一時逐篇判斷該保留什麼、改掉什麼。
• 在不知道檔案位置時先搜尋，再決定修改點。
• 修改後根據驗證結果繼續修正。

可以這樣理解：

固定步骤 -> 脚本
需要判断 -> Codex
需要长期重复且规则稳定 -> 先让 Codex 做，再沉淀为脚本或工作流

Codex 不是要替代所有自動化。相反，好的使用方式是讓 Codex 幫你發現流程，再把穩定流程沉澱成工具。

Codex 的四種常見形態

Codex 可以出現在不同入口裡。學習時不要把入口和能力混為一談。

• CLI：適合本地專案、終端工作流、檔案修改、測試驗證。
• IDE extension：適合在編輯器裡結合程式碼閱讀和區域性修改。
• App：適合更完整的桌面工作流和任務管理。
• Cloud：適合把任務交給遠端環境處理，再審查結果。

這些入口共享同一個核心概念：讓 coding agent 在上下文、工具和許可權邊界內推進任務。

選擇入口時看場景，而不是看哪個“更高階”：

• 本地專案改動多，優先 CLI。
• 編輯器內區域性上下文強，優先 IDE。
• 需要統一任務入口，考慮 App。
• 需要遠端環境或非同步處理，考慮 Cloud。

新手最容易誤用的地方

第一，把 Codex 當聊天框。只說“最佳化一下”，不說邊界、不說驗收，就會得到不可控的改動。

第二，把 Codex 當指令碼。要求它機械執行很多固定步驟，卻不給它判斷空間，會浪費 agent 的價值。

第三，過度放權。為了省審批直接放開 sandbox 和 approval，短期方便，長期容易改壞專案。

第四，不看當前工作樹。多人或多 agent 同時修改時，Codex 必須先確認哪些檔案是自己負責的，不能覆蓋別人的改動。

第五，不做驗證。沒有測試、型別檢查、構建或人工審查，agent 的輸出只能算“改過”，不能算“完成”。

一個合格任務應該怎麼寫

差的任務：

帮我优化这个项目。

更好的任務：

检查 content/docs/codex 下的文章格式，只处理未美化页面。
每批最多改 3 个文件，不要碰其他 agent 正在修改的文件。
改完跑 types:check 和单文件格式扫描，最后汇总剩余候选。

這個任務多了四類關鍵資訊：

• 範圍：只處理 content/docs/codex。
• 邊界：每批最多 3 個檔案，不碰別人檔案。
• 標準：格式美化、不是隨意改寫。
• 驗證：跑掃描和型別檢查。

Codex 的輸入越像工程任務單，輸出越像可審查的工程產物。

繼續學習順序

理解 Codex 後，建議按這個順序繼續：

1. 先學 CLI、IDE、App、Cloud 的入口差異。
2. 再學 sandbox 和 approval，知道它能做什麼、不能做什麼。
3. 然後學 AGENTS.md 和專案上下文，讓它按你的規則工作。
4. 再學 MCP、skills、hooks、subagents，把流程逐步沉澱。

Codex 的核心不是“讓 AI 寫更多程式碼”，而是讓 agent 在工程現場裡做可控、可驗證、可審查的工作。