OpenAI Codex 安装与使用教程：客户端 + CLI 从下载到第一次实战

随着 AI 编程工具越来越成熟，开发者不再只是把 AI 当成"问答助手"，而是开始让它直接参与项目阅读、代码修改、测试执行和代码审查。OpenAI Codex 就是面向软件开发场景的编码智能体。

这篇文章会从零开始介绍 Codex 的本地安装与基础使用，包括 Codex 客户端、Codex CLI、不同系统的安装选择、Windows 常见问题，以及第一次让 Codex 参与项目开发的实战方式。

一、Codex 有哪些使用方式

Codex 不只有一种入口。按照使用场景，可以分成几类：

• Codex 客户端：适合喜欢图形界面、希望管理多个任务和多个 Agent 的用户。
• Codex CLI：适合开发者在终端中直接操作项目，让 Codex 读取代码、修改文件、运行命令。
• IDE / 云端入口：适合已经在 ChatGPT、IDE 或云端工作流里使用 Codex 的用户。

本篇重点讲两条最常用的本地路线：

1. 安装 Codex 客户端
2. 安装 Codex CLI

官方入口：

• Codex 产品页：https://openai.com/codex/
• Codex App 介绍：https://openai.com/index/introducing-the-codex-app/
• Codex CLI 文档：https://developers.openai.com/codex/cli
• Codex CLI GitHub：https://github.com/openai/codex

二、不同系统怎么安装 Codex

截至 2026 年 5 月，官方公开信息中 Codex App 已支持 macOS 和 Windows；Linux 用户更适合使用 Codex CLI，或在 WSL2 / Linux 终端环境中使用 CLI。

系统	推荐安装方式	适合人群
macOS	Codex App + Codex CLI	想用图形界面管理 Agent，也想在终端里处理代码
Windows	Codex App + Codex CLI	Windows 主力开发用户，注意 PowerShell 执行策略问题
Linux	Codex CLI	服务器、WSL2、纯终端开发环境

如果是第一次体验，推荐顺序是：

• 想快速上手：先装 Codex 客户端
• 想直接让它处理项目代码：再装 Codex CLI
• 如果是 Windows 用户：优先掌握 npm.cmd 和 codex.cmd 的写法

三、Codex 客户端安装流程

Codex 客户端更像一个"Agent 工作台"。可以在图形界面中创建任务、查看进度、管理多个并行工作流。它适合做较长的开发任务，例如：

• 阅读一个模块并给出改造方案
• 同时开多个任务处理不同文件
• 跟踪 Bug 修复和代码审查
• 管理需要多轮沟通的开发工作

通用步骤如下：

1. 打开 Codex 官方页面：https://openai.com/codex/
2. 根据系统选择下载入口，例如 macOS 或 Windows
3. 下载并安装客户端
4. 打开 Codex App
5. 使用 ChatGPT 账号登录
6. 选择工作目录或创建任务

客户端适合"看得见任务进度"的场景；CLI 适合"直接在项目目录里干活"的场景。两者不是互斥关系，可以一起使用。

四、Codex CLI 安装前准备

Codex CLI 可以直接在本地终端中操作项目，是开发者最常用的入口之一。

安装前建议准备好：

1. Node.js 和 npm
2. 一个可用的 ChatGPT 账号，或 OpenAI API Key
3. PowerShell / Windows Terminal / macOS Terminal / Linux Shell
4. 一个用于测试的本地项目目录

先检查 Node.js：

node -v

示例输出：

v24.9.0

再检查 npm。Windows PowerShell 下建议使用：

npm.cmd -v

示例输出：

11.6.0

五、安装 Codex CLI

Windows PowerShell 中可以使用：

npm.cmd i -g @openai/codex

macOS / Linux 中通常可以写成：

npm install -g @openai/codex

macOS 用户也可以使用 Homebrew：

brew install --cask codex

如果已经安装过，想升级到最新版本，可以执行：

npm.cmd i -g @openai/codex@latest

安装完成后，检查版本：

codex.cmd --version

示例输出：

codex-cli 0.121.0

Codex CLI 更新比较频繁，如果版本号和示例不一样，不一定是问题。只要命令能正常运行，就可以继续下一步。

六、第一次运行和登录

进入一个项目目录，例如：

cd D:\your-project
codex.cmd

第一次运行时，Codex 会提示登录。常见方式有两种：

• 使用 ChatGPT 账号登录
• 使用 API Key 登录

如果有 ChatGPT Plus、Pro、Business、Enterprise 或 Edu 等账号，可以优先选择 ChatGPT 登录方式。登录完成后，Codex 会进入终端交互界面，就可以开始输入需求。

七、第一次让 Codex 帮你工作

第一次使用不建议直接让它"大改项目"，可以先从低风险任务开始：

请先阅读当前项目结构，告诉我这个项目主要由哪些模块组成，不要修改任何文件。

等它理解项目之后，再进一步让它做具体任务：

请检查登录模块是否有明显的逻辑问题，只分析，不要修改。

如果准备让它修改代码，可以写得更明确：

请修复 src/auth/login.ts 中登录失败提示不准确的问题。
要求：
1. 不要修改接口返回结构
2. 保持现有 UI 文案风格
3. 修改后运行相关测试

这里的关键是：需求越具体，Codex 越容易做对。不要只写"优化一下代码"，而是告诉它范围、目标、限制和验证方式。

八、一个简单实战：让 Codex 写 README

假设项目里缺少 README，可以在项目根目录运行：

codex.cmd

然后输入：

请阅读当前项目结构，帮我补充一份 README.md。
内容包括：
1. 项目简介
2. 本地启动方式
3. 常用脚本说明
4. 目录结构说明
5. 注意事项
先给我计划，确认后再修改文件。

这个提示词有两个好处：

• 让 Codex 先读项目，再写文档，避免凭空编造。
• 让它先给计划，再修改文件，方便确认方向。

如果计划没问题，可以继续输入：

按这个计划生成 README.md。

生成后再让它自查：

请检查刚才生成的 README.md 是否有和项目实际不一致的地方，并列出需要确认的内容。

九、Windows 常见问题

1. PowerShell 提示无法加载 npm.ps1 / codex.ps1

这是 Windows PowerShell 的执行策略导致的。报错类似：

无法加载文件 npm.ps1，因为在此系统上禁止运行脚本
无法加载文件 codex.ps1，因为在此系统上禁止运行脚本

临时解决方式是使用 .cmd：

npm.cmd i -g @openai/codex
codex.cmd --version
codex.cmd

如果希望长期解决，可以单独了解 PowerShell 的 ExecutionPolicy，但不建议为了安装工具随便放开系统策略。

2. 安装后提示 codex 不是内部或外部命令

一般是 npm 全局目录没有加入 PATH。可以先查看 npm 全局目录：

npm.cmd prefix -g

确认里面是否有 codex.cmd，再把对应目录加入系统 PATH。

3. Codex 会不会直接乱改代码

Codex 的行为取决于权限和提示。新手建议遵循三个原则：

• 一开始先让它"只分析，不修改"。
• 需要修改时限定具体文件和目标。
• 修改后自己看 diff，再决定是否提交。

4. 客户端和 CLI 应该选哪个

建议如下：

• 只想体验和管理任务：先用 Codex 客户端
• 想在项目目录中直接改代码：使用 Codex CLI
• 想长期使用：客户端 + CLI 都装

十、使用建议

Codex 更适合用在这些场景：

• 快速理解陌生项目
• 定位 Bug 可能发生的位置
• 写重复性脚本
• 补充 README、注释和测试
• 做代码审查前的第一轮检查
• 把明确的小需求落到具体文件里

不建议一开始就让它做这些事情：

• 一次性重构整个项目
• 修改不了解的核心业务逻辑
• 直接运行高风险删除命令
• 在没有测试的情况下批量改文件

十一、总结

如果想体验完整的 Codex，本地安装可以按这个顺序：

1. 先从官方页面下载 Codex 客户端，适合图形界面管理任务。
2. 再安装 Codex CLI，适合进入项目目录执行开发任务。
3. Windows 用户优先使用 npm.cmd 和 codex.cmd，避免 PowerShell .ps1 执行策略干扰。

CLI 核心命令如下：

node -v
npm.cmd i -g @openai/codex
codex.cmd --version
codex.cmd

真正影响使用效果的不是安装命令，而是如何给 Codex 任务。新手可以从"读项目、解释代码、生成 README、检查逻辑问题"这些低风险任务开始，逐步过渡到修复 Bug、补测试和小范围重构。