---
title: "快速上手 Codex"
description: "基於 OpenAI 官方 Quickstart，幫助新手選擇 Codex 入口，並完成第一次安全、可驗證的使用。"
verifiedAt: "2026-05-07"
---

import { Cards, Card } from 'fumadocs-ui/components/card';

Quickstart 的重點不是“裝哪個最專業”，而是先選對入口、做一個低風險任務、學會檢查結果。

> [!TIP]
> 訂閱、套餐、可用地區和預設額度都可能變化。開始前以官方 Quickstart、Pricing 和賬號後臺顯示為準。

<Cards>
  <Card title="Quickstart" href="https://developers.openai.com/codex/quickstart">
    官方快速開始入口。
  </Card>
  <Card title="第一次安全使用" href="/zh-Hant/docs/codex/official/00-getting-started/first-safe-use-checklist">
    按只讀、窄改動、diff、驗證的順序完成第一次閉環。
  </Card>
  <Card title="CLI App IDE Cloud" href="/zh-Hant/docs/codex/understanding/cli-app-ide-cloud">
    先選對入口，再開始任務。
  </Card>
</Cards>

## 四個入口

```mermaid
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 的共同步驟

不同入口介面不同，但第一條路徑基本一致：

1. 安裝或開啟入口。
2. 登入 ChatGPT account 或 API key。
3. 選擇專案或連線 repository。
4. 傳送第一條低風險訊息。
5. 檢視 Codex 的解釋、計劃、diff 或日誌。
6. 用 Git 和測試確認結果。

App、IDE extension、CLI、Cloud 都圍繞同一件事：讓 Codex 在一個明確專案裡完成受控任務。區別只是任務執行在本機、編輯器、終端還是 cloud environment。

## 第一次不要做什麼

第一次使用 Codex，不要直接讓它：

- 重構專案。
- 做完整產品。
- 全面最佳化。
- 升級依賴。
- 改認證、支付、許可權。
- 處理生產故障。

這些任務範圍太大，新手很難判斷結果好壞。

第一條訊息最好是隻讀任務：

```text
请先阅读这个项目，告诉我它的主要结构、启动方式、关键目录，以及你建议我从哪里开始做一个小改动。不要修改文件。
```

這條訊息的價值是確認三件事：Codex 是否在正確專案裡、是否理解現有結構、是否能用儲存庫證據說話。

## 第一個小改動怎麼選

選這樣的任務：

- 隻影響 1 到 2 個檔案。
- 有明確預期行為。
- 可以用現有測試、lint、build 或手動檢查驗證。
- 不涉及賬號、支付、許可權、部署、資料遷移。
- 即使失敗也容易回復。

示例：

```text
请把这个页面的空状态文案改得更清楚，只修改相关组件和测试。改完后运行这个组件对应的测试。如果找不到测试，说明你检查过哪里。
```

不建議：

```text
请全面优化这个项目，让它达到生产级。
```

後者沒有邊界，也沒有驗收方式。

## 安全上手流程

建議按這個順序完成第一次使用：

1. 選擇一個真實但不關鍵的專案。
2. 確認 Git 工作區乾淨，或至少知道當前有哪些改動。
3. 讓 Codex 先做只讀專案介紹。
4. 讓它提出一個很小的修改計劃。
5. 只批准一個邊界明確的小任務。
6. 檢視 diff，確認沒有無關檔案。
7. 執行測試、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 模板

只讀專案理解：

```text
Read this project without editing files. Explain its purpose, main modules, run commands, test commands, and the safest first small task.
```

小範圍修改：

```text
Make the smallest change needed for this behavior. Before editing, list the files you expect to touch. After editing, run the narrowest validation command.
```

結果審查：

```text
Review your own diff. List any unrelated changes, unverified assumptions, and tests that still should be run.
```

這些模板的重點是讓 Codex 先宣告範圍，再執行，再證明。

## 官方資料

- [OpenAI Codex Quickstart](https://developers.openai.com/codex/quickstart)
- [OpenAI Codex App](https://developers.openai.com/codex/app)
- [OpenAI Codex IDE extension](https://developers.openai.com/codex/ide)
- [OpenAI Codex CLI](https://developers.openai.com/codex/cli)
- [OpenAI Codex Cloud](https://developers.openai.com/codex/cloud)
- [OpenAI Codex best practices](https://developers.openai.com/codex/learn/best-practices)
