cli-setup

上一篇已经把 Windows 基础环境准备好了。这一篇正式安装 Codex CLI，并完成第一次登录和启动。

> 前置教程：Windows 安装与启动

> 如果你还没有准备好 cmd、Git、Node.js 和练习项目，先完成前置教程，再回到本篇。

请注意：这篇只讲 Windows 原生命令提示符（cmd）路线。如果你的项目本来就在 WSL2 里，后面会有单独的 WSL 教程。

> 依据来源：OpenAI Codex 官方手册中 Codex CLI、Windows platform、Authentication and sessions、Installer variables 等章节。

跟着本篇做完后，你应该能做到：

1. 在 cmd 里安装 Codex CLI。

2. 用 codex --version 确认安装成功。

3. 理解 ChatGPT 登录和 API Key 登录的区别。

4. 完成一次登录。

5. 在项目目录里启动 Codex。

6. 完成第一次只读项目分析。

7. 知道登录失败时从哪里排查。

请先确认你已经完成上一篇的基础准备。

打开命令提示符，依次运行：

``

git --version

`

`

node -v

`

`

npm -v

`

至少要看到 Git、Node.js、npm 都能输出版本号。

如果这一步不通过，先回到上一篇：Windows 安装与启动。

第 1 步：确认你要安装的是 CLI

Section titled “第 1 步：确认你要安装的是 CLI”

Codex 有多个入口：

• Codex Windows 桌面版
• Codex CLI
• Codex IDE 扩展
• Codex Web/Cloud

本篇安装的是 Codex CLI，也就是你在终端里运行的 codex 命令。

适合 CLI 的任务：

• 在本地项目目录里读代码。
• 修改文件。
• 运行 npm run build、mvn test 这类命令。
• 查看 diff。
• 写提交总结。

如果你完全不熟悉终端，也可以先用桌面版；但本站后续大量实战会以 CLI 为主，因为它最适合演示真实项目交付闭环。

第 2 步：安装 Codex CLI

Section titled “第 2 步：安装 Codex CLI”

打开命令提示符。

建议你先不要用管理员权限，普通 cmd 就可以。只有遇到权限问题时，再考虑管理员权限。

复制并运行：

`

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

`

这条命令的意思是：

• 你当前输入命令的地方是 cmd。
• powershell -ExecutionPolicy Bypass -Command "..."：由 cmd 调用官方 Windows 安装脚本。
• https://chatgpt.com/codex/install.ps1：OpenAI 提供的 Codex Windows 安装脚本。

执行过程中，如果它问你是否继续，按提示确认。

不要直接点允许。

先确认 3 件事：

1. 命令里的地址是 https://chatgpt.com/codex/install.ps1。

2. 你是在自己的电脑上安装。

3. 你不是在公司安全策略禁止的电脑上安装。

如果是公司电脑，先遵守公司规定。

安装完成后，请关闭当前命令提示符窗口。

然后重新打开一个新的命令提示符窗口。

这样做是为了让系统重新加载 PATH 环境变量。

很多新手安装成功后马上运行 codex，结果提示找不到命令，原因就是终端没重开。

第 4 步：验证 Codex CLI 是否安装成功

Section titled “第 4 步：验证 Codex CLI 是否安装成功”

运行：

`

codex --version

`

预期结果：你会看到 Codex 的版本号。

示例：

`

codex 0.xxx.x

`

只要能输出版本号，就说明 codex 命令已经能被系统找到。

你可能看到：

`

'codex' 不是内部或外部命令，也不是可运行的程序或批处理文件。

`

按顺序排查：

1. 你有没有关闭并重新打开命令提示符？

2. 安装命令有没有成功跑完？

3. 你的网络是否中途失败？

4. 是否被安全软件拦截？

可以重新运行安装命令：

`

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

`

然后再次关闭并重新打开命令提示符。

Codex 支持两类常见登录方式：

这是新手推荐方式。

特点：

• 使用你的 ChatGPT 账号登录。
• CLI 默认会优先走这个登录路径。
• 适合本地交互式使用。
• 你的 Codex 使用情况跟 ChatGPT 账号、套餐、工作区权限有关。

这不是新手默认推荐方式。

特点：

• 使用 OpenAI Platform 的 API Key。
• 用量按 OpenAI Platform API 计费。
• 更适合自动化、CI/CD、脚本任务。
• 某些依赖 ChatGPT 工作区或云端能力的功能可能不可用。

新手请记住一句话：

`

你只是本地学习 Codex CLI，优先用 ChatGPT 登录；不要随便把 API Key 粘到教程、截图或聊天里。

`

运行：

`

codex login

`

正常情况下，Codex 会打开浏览器，让你登录 ChatGPT。

你需要做：

1. 在浏览器里完成登录。

2. 授权 Codex。

3. 回到命令提示符窗口。

4. 等待 CLI 显示登录完成。

看命令提示符里是否打印了一个链接。

如果有，复制链接到浏览器打开。

如果还是不行，可以尝试设备码登录：

`

codex login --device-auth

`

然后按终端提示打开网页，输入一次性代码。

登录完成后，直接运行：

`

codex

`

如果能进入 Codex 交互界面，说明登录可用。

先不要输入复杂任务。

你可以输入：

`

你好，请只回复一句话：Codex CLI 已经可以正常工作。

`

如果 Codex 正常回复，说明基础登录和交互已经成功。

退出 Codex：

`

/exit

`

如果 /exit 不生效，可以按：

`

Ctrl + C

`

现在不要在随便一个目录里用 Codex。

先进入你的练习项目：

`

cd D:\code\codex-demo

`

如果你用的是 C:\code：

`

cd C:\code\codex-demo

`

确认路径：

`

cd

`

确认 Git 状态：

`

git status

`

推荐看到：

`

nothing to commit, working tree clean

`

这样最适合让 Codex 开始第一次任务。

第 9 步：在项目里启动 Codex

Section titled “第 9 步：在项目里启动 Codex”

确保你已经在项目目录里。

运行：

`

codex

`

进入 Codex 后，先发只读任务。

复制这段：

`

请先只读分析当前项目，不要修改任何文件，不要运行会改变文件的命令。

请告诉我：

1. 你看到的当前项目路径是什么。

2. 这个项目是什么技术栈。

3. 项目入口文件有哪些。

4. package.json 里有哪些 scripts。

5. 如果我要做第一个低风险修改，你推荐哪 3 个任务。

6. 哪些地方你不确定。

不能确定就写“不确定”，不要猜。

`

第 10 步：检查 Codex 的回答

Section titled “第 10 步：检查 Codex 的回答”

你要检查 5 件事：

1. 它有没有识别当前项目路径。

2. 它有没有找到 package.json。

3. 它有没有列出 scripts。

4. 它有没有推荐低风险任务。

5. 它有没有明确写出不确定的地方。

先不要让它继续修改。

第一次 Codex CLI 项目的目标就是：

`

确认 Codex 能在正确目录里读项目。

`

退出 Codex：

`

/exit

`

退出 Codex 后，在命令提示符里运行：

`

git status

`

如果看到：

`

nothing to commit, working tree clean

`

说明这次只读任务没有修改文件。

如果看到有文件变化，运行：

`

git diff

`

先看变化，不要提交。

可能原因：

• 网络连接失败。
• 代理或安全软件拦截。
• 公司网络限制。

先确认能否在浏览器打开：

`

https://chatgpt.com/codex/install.ps1

`

如果浏览器都打不开，先解决网络问题。

可以尝试：

1. 关闭浏览器重新执行 codex login。

2. 换一个浏览器。

3. 使用设备码登录：

`

codex login --device-auth

`

Codex 会在本地缓存登录信息。官方文档说明，CLI 和 IDE 扩展会复用缓存的登录信息。

如果你每次都要登录，可能是：

• 缓存文件被清理。
• 安全软件拦截写入。
• 你在不同 Windows 用户之间切换。
• 你执行过登出。

问题 4：我能不能用 API Key 登录

Section titled “问题 4：我能不能用 API Key 登录”

可以，但新手不建议优先用。

原因：

• API Key 走 OpenAI Platform 计费。
• API Key 泄露风险更高。
• 截图和教程里容易不小心暴露。

如果你必须用 API Key，先保证：

1. 你知道 API Key 从哪里创建。

2. 你知道费用由谁承担。

3. 你不会把 API Key 发到聊天、截图、Git 仓库里。

问题 5：我在公司电脑上装不了怎么办

Section titled “问题 5：我在公司电脑上装不了怎么办”

不要强行绕过公司策略。

你可以：

• 先用个人电脑学习。
• 找管理员确认是否允许安装。
• 使用桌面版或 IDE 扩展作为替代入口。
• 后续再学习 Cloud。

问题 6：Codex 进入后提示权限或沙箱

Section titled “问题 6：Codex 进入后提示权限或沙箱”

新手阶段保持默认权限。

第一次任务只读分析项目，不应该需要高风险权限。

如果 Codex 要求权限，你可以问：

`

我现在只想做只读项目分析。请解释这个权限请求是做什么的。如果不是必须，请换成不需要额外权限的只读方式。

`

做到这里，如果满足下面 7 条，就说明这条安装登录路线已经跑通：

1. codex --version 能输出版本号。

2. codex login 能完成登录。

3. codex 能进入交互界面。

4. 你知道 ChatGPT 登录和 API Key 登录的区别。

5. 你能在项目目录里启动 Codex。

6. Codex 能完成一次只读项目分析。

7. git status 能确认没有产生文件改动。

你学会的不是单纯“装了一个命令”，而是 Codex CLI 的最小可用闭环：

`

安装 -> 验证版本 -> 登录 -> 进入项目 -> 只读分析 -> 退出 -> git status 检查

`

这条闭环跑通后，下一篇先配置大模型，确认 Codex 背后使用哪个模型、API Key 怎么保存、怎么做只读验证，然后再进入项目阅读和修改代码。

• OpenAI Codex CLI 文档：https://developers.openai.com/codex/cli
• OpenAI Codex 认证文档：https://developers.openai.com/codex/auth
• OpenAI Codex Windows 文档：https://developers.openai.com/codex/windows
• OpenAI Codex 环境变量与安装脚本文档：https://developers.openai.com/codex/codex-manual.md`

下一篇看：配置大模型总览。

那一篇会把模型、provider、Base URL、API Key 和安全边界讲清楚，为后续国内模型配置和项目实战做准备。