官方教程中文版新手必讀
快速上手 Codex
基於 OpenAI 官方 Quickstart，幫助新手選擇 Codex 入口，並完成第一次安全、可驗證的使用。
Quickstart 的重點不是“裝哪個最專業”，而是先選對入口、做一個低風險任務、學會檢查結果。
訂閱、套餐、可用地區和預設額度都可能變化。開始前以官方 Quickstart、Pricing 和賬號後臺顯示為準。
四個入口
flowchart LR
Task["你的任務"] --> App["App"]
Task --> IDE["IDE extension"]
Task --> CLI["CLI"]
Task --> Cloud["Cloud"]Codex 不是隻有一個用法：
- App：桌面應用，適合在本機專案裡直接使用。
- IDE extension：把 Codex 放進 VS Code、Cursor、Windsurf 這類編輯器。
- CLI：在終端裡使用，適合熟悉命令列和本地工程流程的人。
- Cloud：在瀏覽器裡的雲端環境執行任務，適合後臺執行、檢視日誌、建立 PR。
如果你還不確定，從 App 或 IDE extension 開始。CLI 和 Cloud 更適合已經知道專案結構、許可權邊界和驗證方式的人。
官方 quickstart 的共同步驟
不同入口介面不同，但第一條路徑基本一致：
- 安裝或開啟入口。
- 登入 ChatGPT account 或 API key。
- 選擇專案或連線 repository。
- 傳送第一條低風險訊息。
- 檢視 Codex 的解釋、計劃、diff 或日誌。
- 用 Git 和測試確認結果。
App、IDE extension、CLI、Cloud 都圍繞同一件事：讓 Codex 在一個明確專案裡完成受控任務。區別只是任務執行在本機、編輯器、終端還是 cloud environment。
第一次不要做什麼
第一次使用 Codex，不要直接讓它：
- 重構專案。
- 做完整產品。
- 全面最佳化。
- 升級依賴。
- 改認證、支付、許可權。
- 處理生產故障。
這些任務範圍太大，新手很難判斷結果好壞。
第一條訊息最好是隻讀任務：
请先阅读这个项目，告诉我它的主要结构、启动方式、关键目录，以及你建议我从哪里开始做一个小改动。不要修改文件。這條訊息的價值是確認三件事：Codex 是否在正確專案裡、是否理解現有結構、是否能用儲存庫證據說話。
第一個小改動怎麼選
選這樣的任務：
- 隻影響 1 到 2 個檔案。
- 有明確預期行為。
- 可以用現有測試、lint、build 或手動檢查驗證。
- 不涉及賬號、支付、許可權、部署、資料遷移。
- 即使失敗也容易回復。
示例：
请把这个页面的空状态文案改得更清楚，只修改相关组件和测试。改完后运行这个组件对应的测试。如果找不到测试，说明你检查过哪里。不建議：
请全面优化这个项目，让它达到生产级。後者沒有邊界，也沒有驗收方式。
安全上手流程
建議按這個順序完成第一次使用：
- 選擇一個真實但不關鍵的專案。
- 確認 Git 工作區乾淨，或至少知道當前有哪些改動。
- 讓 Codex 先做只讀專案介紹。
- 讓它提出一個很小的修改計劃。
- 只批准一個邊界明確的小任務。
- 檢視 diff，確認沒有無關檔案。
- 執行測試、lint、build 或專案已有驗證命令。
把 Codex 當成會改程式碼的協作者，不是一次性外包工具。每一步都要能看見邊界和證據。
各入口怎麼選
App 適合：
- 想用官方桌面應用處理本地專案。
- 不想先理解 CLI 引數。
- 希望從 local workflow 開始。
IDE extension 適合：
- 主要在 VS Code、Cursor 或 Windsurf 裡開發。
- 希望一邊看程式碼一邊對話。
- 想讓 Codex 跟隨當前編輯器上下文。
CLI 適合：
- 熟悉終端。
- 能看懂命令輸出、Git diff、測試結果。
- 希望在指令碼化或本地工程流裡使用 Codex。
Cloud 適合：
- 想把任務放到雲端環境後臺執行。
- 需要連線 GitHub 儲存庫並建立 PR。
- 能審查日誌、diff 和最終分支。
常見坑
- 在錯誤資料夾裡啟動 Codex。
- 一上來給超大任務，導致結果不可審查。
- 沒看 diff 就接受改動。
- Codex 說跑了測試，但你沒有核對輸出。
- 不知道當前是 local 還是 cloud。
- 用 API key 登入後，誤以為所有 ChatGPT 登入能力都完全一樣。
- Cloud environment 沒配好，就把問題歸因給模型能力。
判斷第一次成功
第一次成功不等於做出一個大功能，而是完成一個可控閉環：
- Codex 能正確識別專案結構。
- 你知道它在哪個目錄工作。
- 它沒有修改只讀任務裡的檔案。
- 第一個小改動隻影響預期檔案。
- diff 能看懂。
- 至少有一種驗證方式能證明改動可用。
完成這個閉環後，再繼續學習 prompt、配置、安全許可權、Cloud environment 和團隊流程。
新手常用 prompt 模板
只讀專案理解：
Read this project without editing files. Explain its purpose, main modules, run commands, test commands, and the safest first small task.小範圍修改：
Make the smallest change needed for this behavior. Before editing, list the files you expect to touch. After editing, run the narrowest validation command.結果審查：
Review your own diff. List any unrelated changes, unverified assumptions, and tests that still should be run.這些模板的重點是讓 Codex 先宣告範圍，再執行，再證明。