30 分钟 Quickstart：安装、登录与第一个任务

第一步：选入口（30 秒决策）

Codex 有四个常用入口，差别在操作界面和代码执行位置，不是四个不同的产品。

入口	适合谁	代码执行位置	首次安装成本
桌面 App	想可视化管项目、多对话并行	本机	下载安装包
IDE 扩展	已在 VS Code / Cursor 里写代码	本机	安装扩展
CLI	习惯终端、脚本化工作流	本机	一条安装命令
Cloud	不想占本机资源、直接开 PR	OpenAI 云端环境	浏览器 + GitHub 连接

下面按 App → IDE → CLI → Cloud 给出最小路径；你只需走完其中一条。App 安装细节见「桌面 App 安装」。

第二步：登录（两种计费方式）

登录方式	计费	典型场景
ChatGPT 账号	消耗套餐内 Codex 额度	日常开发、Cloud、完整功能
OpenAI API Key	按 API 用量计费	CI/CD、自动化脚本

Cloud 必须用 ChatGPT 登录；App、CLI、IDE 两种方式都支持。选型与无头环境见「登录与认证」；套餐与额度见「订阅 ChatGPT 套餐」。

路径 A · 桌面 App（推荐新手）

A1. 安装并打开

macOS（Apple Silicon）：下载 DMG
macOS（Intel）：下载 x64 DMG
Windows：Microsoft Store 安装

图文步骤与常见安装问题见「桌面 App 安装」。

A2. 登录并选择项目

打开 App，用 ChatGPT 或 API Key 登录。
选择本地项目文件夹（或新建空目录作为练习仓库）。
确认模式为 Local，让 Codex 在本机读写文件。

A3. 发第一条任务

从下面选一条结果可验证的提示词（比「帮我写代码」更容易判断成功与否）：

告诉我这个项目是做什么的，用 5 条 bullet 概括主要模块。

在这个仓库里找出 README 没写到的启动步骤，补一段「本地开发」小节，改动尽量小。

以最小改动修复当前测试失败（如果有），先说明根因再改代码。

路径 B · IDE 扩展

B1. 安装扩展

按编辑器安装 OpenAI Codex 扩展：

B2. 打开面板并登录

扩展出现在侧边栏（可能在折叠区）。用 ChatGPT 或 API Key 登录后，默认以 Agent mode 启动，可读写项目文件。

B3. 第一条任务

在已打开的项目根目录发送与路径 A 相同的示例提示词之一。

路径 C · CLI

C1. 安装

macOS / Linux：

curl -fsSL https://chatgpt.com/codex/install.sh | sh

Windows（PowerShell）：

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

也可用 npm install -g @openai/codex 或 brew install --cask codex。

无人值守安装：

curl -fsSL https://chatgpt.com/codex/install.sh | CODEX_NON_INTERACTIVE=1 sh

C2. 登录并运行

codex login
codex

在终端里输入与路径 A 相同的任务描述即可。认证缓存与 App 共享，详见「登录与认证」。

路径 D · Cloud

D1. 打开并配置环境

浏览器访问 chatgpt.com/codex。
用 ChatGPT 账号登录（API Key 不支持 Cloud）。
在环境设置连接 GitHub 仓库。

也可以在 PR 评论里 @codex 委派任务。

D2. 启动任务并审查 diff

发起任务后可在日志里看进度。完成后在 diff 视图审查改动，满意再开 PR；需要本地验证时：

git fetch
git checkout <branch-name>

Cloud 适合异步任务和 PR 流程，不适合需要本机私有网络或本地服务的场景。

第三步：验证你确实跑通了（检查清单）

完成任意一条路径后，对照下面清单：

已成功登录（App / CLI / IDE 状态栏或 Cloud 页面可见账号）
Codex 能读取当前项目（回答了与仓库相关的问题，或产生了文件改动）
任务前创建了 Git 检查点：git status 干净或已 git stash / 提交
若产生代码改动，你已人工审查 diff，而不是直接合并
知道如何回滚：git checkout . 或回到任务前 commit

为什么强调 Git 检查点

Codex 以 Agent 模式运行时可能修改多个文件。没有检查点时，一次宽泛的提示词就可能让仓库进入难以恢复的状态。这是新手最常见、也最容易预防的问题。

常见问题

Q：免费 ChatGPT 账号能用 Codex 吗？

能用，但额度和功能受限，Cloud 与桌面 App 的完整能力通常需要 Plus 及以上。见「订阅 ChatGPT 套餐」。

Q：API Key 和 ChatGPT 登录可以同时装吗？

可以安装，但同一时刻通常用一种计费方式。企业环境可能通过托管配置限制登录方式，见「登录与认证」。

Q：四条路径都要学吗？

不用。先精通一个入口，再在「使用方式」章节按需扩展。

Q：第一条任务写什么最好？

优先选「读仓库」「小范围文档补充」「带测试约束的 bug 修复」这类可验收任务，避免一上来要求「重写整个项目」。