---
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="/docs/codex/official/00-getting-started/first-safe-use-checklist">
    按只读、窄改动、diff、验证的顺序完成第一次闭环。
  </Card>
  <Card title="CLI App IDE Cloud" href="/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)
