OpenAI Codex 使用教程：从下载、安装到基础配置完整指南

本文基于 OpenAI Codex 官方文档整理，适合第一次接触 Codex 的开发者。内容覆盖 Codex 是什么、下载安装到哪里、如何登录、CLI 如何安装、Windows/macOS/Linux 怎么选，以及常见配置文件怎么写。

一、Codex 是什么？

Codex 是 OpenAI 推出的编程协作智能体，可以帮助开发者阅读代码、修改文件、运行命令、解释项目、修复 Bug、生成测试、做代码审查，也可以把任务委托到云端后台执行。

简单理解，Codex 不是普通的聊天机器人，而是一个能进入项目目录、理解代码上下文并协助完成开发任务的 AI 编程助手。

目前 Codex 常见使用方式主要有四种：

1. Codex App：桌面端应用，适合可视化管理多个项目和多个任务。
2. Codex IDE Extension：IDE 插件，适合在 VS Code、Cursor、Windsurf、JetBrains 等编辑器中使用。
3. Codex CLI：命令行工具，适合习惯在终端里开发的用户。
4. Codex Web / Cloud：浏览器云端版本，适合把任务交给 Codex 在云环境中后台执行。

如果你刚开始使用，建议优先选择 Codex App 或 IDE 插件；如果你更习惯命令行，可以直接安装 Codex CLI。

二、使用前需要准备什么？

在安装之前，先准备好下面几项：

1. 一个可用的 ChatGPT / OpenAI 账号。
2. 可以访问 OpenAI 服务的网络环境。
3. 一个本地代码项目目录，最好已经使用 Git 管理。
4. 如果使用 CLI，建议提前安装好终端环境，比如 Windows PowerShell、Windows Terminal、macOS Terminal、Linux shell 等。
5. 如果通过 npm 安装 CLI，需要提前安装 Node.js 和 npm。

官方文档中说明，ChatGPT 的常见订阅计划包含 Codex 使用入口，也可以通过 OpenAI API key 使用 Codex。但如果使用 API key 登录，部分云端能力可能不可用，具体以官方页面和账号权限为准。

三、下载和安装 Codex App

Codex App 是最适合新手的安装方式，因为它提供了图形界面，不需要一开始就处理太多命令行参数。

1. Windows 安装方式

Windows 用户可以通过 Microsoft Store 安装 Codex App。

官方也提供了命令行安装方式：

winget install Codex -s msstore

安装完成后，打开 Codex App，使用 ChatGPT 账号或 OpenAI API key 登录即可。

Windows 版本支持原生 PowerShell 工作流，也可以结合 WSL2 使用。如果你的项目依赖 Linux 环境，例如使用某些 Linux-only 工具链，建议考虑 WSL2；如果只是普通前端、Node.js、Python、Java 等项目，原生 PowerShell 通常也可以正常使用。

2. macOS 安装方式

macOS 用户可以从 Codex 官方下载页面选择对应芯片版本：

1. Apple Silicon 版本：适合 M1、M2、M3、M4 等芯片。
2. Intel 版本：适合 Intel 芯片的老款 Mac。

下载后按正常 macOS 应用安装流程安装，启动后登录账号即可。

3. Linux 用户怎么用？

截至本文整理时，Codex App 主要面向 macOS 和 Windows。Linux 用户更推荐使用 Codex CLI，或者通过浏览器使用 Codex Web / Cloud。

四、安装 Codex CLI

Codex CLI 是命令行版本，可以直接在终端里运行。它适合喜欢使用命令行、希望在当前项目目录中快速让 Codex 读代码、改代码、跑命令的开发者。

1. macOS / Linux 安装

官方推荐使用独立安装脚本：

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

如果需要非交互安装，可以使用：

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

2. Windows 安装

Windows 可以在 PowerShell 中运行：

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

非交互安装可以使用：

$env:CODEX_NON_INTERACTIVE=1; irm https://chatgpt.com/codex/install.ps1 | iex

3. 使用 npm 安装

如果你已经安装了 Node.js 和 npm，也可以使用 npm 安装：

npm install -g @openai/codex

安装完成后，检查版本：

codex --version

如果能正常输出版本号，说明安装成功。

4. 使用 Homebrew 安装

macOS 用户也可以使用 Homebrew：

brew install --cask codex

五、第一次启动 Codex

安装完成后，在项目目录中打开终端，例如：

cd your-project
codex

第一次启动时，Codex 会提示你登录。通常有两种方式：

1. 使用 ChatGPT 账号登录。
2. 使用 OpenAI API key 登录。

登录成功后，你可以直接输入任务，例如：

帮我解释这个项目的目录结构

也可以让它完成具体开发任务：

帮我检查登录模块有没有明显的 Bug，并给出最小改动修复

或者：

为 src/utils/date.ts 中的函数补充单元测试

建议新手一开始先让 Codex 做“解释项目”“查找问题”“生成测试”这类风险较低的任务，熟悉它的工作方式后，再让它直接修改核心业务代码。

六、Codex 配置文件在哪里？

Codex 的配置文件使用 TOML 格式。

用户级配置文件位置：

~/.codex/config.toml

项目级配置文件位置：

项目根目录/.codex/config.toml

简单理解：

1. ~/.codex/config.toml：对当前用户的所有项目生效。
2. .codex/config.toml：只对当前项目生效。

官方文档中也说明，CLI 和 IDE 插件会共享这些配置层。因此你在 CLI 中配置的模型、审批策略、沙箱权限等，也可能被 IDE 插件读取。

七、基础配置示例

下面是一个适合入门用户的配置示例。模型名称会随着官方发布和账号权限变化而变化，实际使用时可以在 Codex 的模型选择界面或官方文档中查看当前可用模型：

model = "gpt-5.5"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

含义如下：

1. model：设置默认使用的模型。
2. approval_policy：控制 Codex 什么时候需要向你确认。
3. sandbox_mode：控制 Codex 能访问和修改哪些文件。

如果你是新手，建议先使用相对保守的配置：

approval_policy = "on-request"
sandbox_mode = "workspace-write"

这样 Codex 可以在项目目录内工作，但遇到敏感操作时会停下来让你确认。

八、常见权限和沙箱配置怎么理解？

Codex 可以读取文件、修改代码、运行命令，因此权限配置非常重要。

常见思路如下：

1. 只想让 Codex 看代码、解释项目：使用只读或较严格权限。
2. 想让 Codex 帮你改代码：允许工作区写入。
3. 想让 Codex 自己跑测试、安装依赖、执行脚本：需要根据项目情况开放命令执行权限。
4. 不建议新手一开始就给完全访问权限。

一个比较稳妥的工作流是：

先让 Codex 分析问题 -> 再让它给出计划 -> 确认后再修改 -> 修改后运行测试 -> 最后人工检查 diff

如果项目非常重要，建议先新建 Git 分支：

git checkout -b codex-demo

或者至少在使用前确认工作区是干净的：

git status

九、在 IDE 中使用 Codex

如果你使用 VS Code、Cursor、Windsurf 或 JetBrains 系列 IDE，可以安装 Codex IDE Extension。

大致流程如下：

1. 打开 IDE 的插件市场。
2. 搜索 Codex。
3. 安装 OpenAI Codex 扩展。
4. 重启 IDE。
5. 在侧边栏打开 Codex 面板。
6. 使用 ChatGPT 账号或 API key 登录。
7. 选择项目上下文后开始提问或分配任务。

IDE 插件适合日常开发，因为你可以一边看代码，一边让 Codex 解释当前文件、修改某个函数、补充测试或者做代码审查。

十、在浏览器中使用 Codex Cloud

如果你希望 Codex 在云端后台执行任务，可以使用 Codex Web / Cloud。

基本流程如下：

1. 打开 https://chatgpt.com/codex。
2. 登录 ChatGPT 账号。
3. 连接 GitHub 仓库。
4. 配置运行环境。
5. 创建任务。
6. 等待 Codex 在云端完成分析和修改。
7. 查看 diff，并根据结果创建 Pull Request。

Codex Cloud 比较适合耗时较长、可以后台执行的任务，例如：

1. 修复一组测试失败。
2. 重构某个模块。
3. 给项目补充测试。
4. 根据 issue 生成 Pull Request。
5. 分析复杂项目结构。

十一、常用命令示例

进入项目目录并启动 Codex：

codex

查看帮助：

codex --help

查看版本：

codex --version

如果账号支持对应模型，也可以在启动时指定模型，例如：

codex --model gpt-5.5

使用 npm 更新 Codex CLI：

npm install -g @openai/codex

使用官方安装脚本更新 macOS / Linux 独立安装版本：

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

十二、推荐的新手使用方式

第一次使用 Codex 时，不建议直接让它“大改整个项目”。更好的方式是把任务拆小。

例如，不太推荐这样问：

帮我优化整个项目

更推荐这样问：

请先阅读这个项目的目录结构，告诉我主要模块分别负责什么，不要修改文件

或者：

请检查登录接口相关代码，找出最可能导致 token 失效的原因，先给出分析和修改计划

再比如：

请只修改 src/api/auth.ts，修复 refreshToken 失败后没有清理登录状态的问题，并补充对应单元测试

越具体的任务，Codex 越容易给出稳定结果。

十三、安全建议

使用 Codex 时建议注意以下几点：

1. 重要项目先建 Git 分支。
2. 修改前后都查看 git diff。
3. 不要把密码、私钥、数据库连接串等敏感信息直接发给 Codex。
4. 不要轻易开放全盘访问权限。
5. 让 Codex 执行删除、部署、迁移数据库等高风险命令前，一定要人工确认。
6. 对生产环境相关操作保持谨慎，最好先在测试环境验证。
7. 让 Codex 修改代码后，尽量运行测试、构建或类型检查。

一个比较实用的检查顺序：

git diff
npm test
npm run build

不同项目命令不一样，按你自己的项目实际脚本执行即可。

十四、常见问题

1. Codex 和 ChatGPT 有什么区别？

ChatGPT 更偏通用对话和知识问答；Codex 更偏工程任务，可以进入项目上下文，读文件、改代码、运行命令，并围绕代码仓库完成连续任务。

2. Codex 会自动修改我的代码吗？

取决于你的权限配置和当前模式。保守模式下，它会在关键操作前请求确认；更自动化的模式下，它可以直接修改工作区文件。因此建议新手先使用需要确认的模式。

3. Windows 用户应该用 App 还是 CLI？

如果你想简单上手，建议先用 Codex App。如果你习惯终端，可以使用 CLI。需要 Linux 原生环境时，可以结合 WSL2。

4. 配置文件改了不生效怎么办？

可以检查下面几点：

1. 文件路径是否正确。
2. TOML 格式是否正确。
3. 是否被项目级配置覆盖。
4. 是否使用了命令行参数覆盖配置。
5. IDE 或终端是否需要重启。

5. Codex 适合做哪些任务？

比较适合：

1. 阅读陌生项目。
2. 修复明确 Bug。
3. 补充单元测试。
4. 解释复杂函数。
5. 重构局部模块。
6. 生成脚手架代码。
7. 做代码审查。
8. 整理技术文档。

不太建议一开始就让它直接做：

1. 大规模无边界重构。
2. 生产数据库迁移。
3. 删除大量文件。
4. 未经确认的部署操作。
5. 涉及密钥和敏感信息的任务。

十五、总结

Codex 的核心价值是把 AI 能力带入真实开发流程：它不仅能回答问题，还能围绕代码仓库阅读、修改、运行和验证。新手可以从 Codex App 或 IDE 插件开始，熟悉之后再使用 CLI 和 Cloud 完成更复杂的自动化任务。

我的建议是：

1. 入门先用 App 或 IDE 插件。
2. 日常开发可以用 CLI。
3. 长任务可以交给 Cloud。
4. 所有重要修改都放在 Git 分支里完成。
5. 让 Codex 先分析、再计划、再执行，效果通常更稳。

参考资料

1. Codex Quickstart：https://developers.openai.com/codex/quickstart
2. Codex CLI：https://developers.openai.com/codex/cli
3. Codex IDE Extension：https://developers.openai.com/codex/ide
4. Codex Web / Cloud：https://developers.openai.com/codex/cloud
5. Codex Config Basics：https://developers.openai.com/codex/config-basic
6. Codex Windows App：https://developers.openai.com/codex/app/windows