Codex 安装完整教程：Mac、Windows、Linux 快速上手

大家好，我是 Codex 中文网的站长宇哥。

这篇教程解决什么问题

很多新手第一次搜“Codex 怎么安装”时，会混在几个入口之间：Codex App、IDE 扩展、Codex CLI、云端 Codex。它们都叫 Codex，但使用场景不同。按照 OpenAI 官方 Quickstart 的说明，Codex 可以通过桌面 App、IDE 扩展、CLI 和云端使用；CLI 适合在终端里直接让 Codex 阅读、修改和运行当前目录的代码。

如果你只是想先体验 Codex，推荐从 Codex App 或 IDE 扩展开始。如果你习惯终端、经常在本地仓库里开发，Codex CLI 是最直接的入口。

安装前先确认这些事情

开始之前，建议先确认三件事。

• 你有 ChatGPT 账号，或准备使用 OpenAI API key 登录。
• 本机能访问安装脚本或包管理器源。
• 你知道自己要在哪个项目目录里运行 Codex。

OpenAI 官方文档提到，Codex 首次运行时会提示你使用 ChatGPT 账号或 API key 登录。对大多数个人用户来说，ChatGPT 登录更省心；如果你在公司机器、CI 或特殊网络环境里使用，再考虑 API key 或供应商配置。

macOS 和 Linux 安装 Codex CLI

OpenAI 官方 CLI 页面推荐 macOS 和 Linux 使用独立安装脚本：

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

如果你需要无人值守安装，例如在自动化脚本里安装，可以设置 CODEX_NON_INTERACTIVE=1：

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

安装完成后，重新打开终端，执行：

codex

第一次运行会进入登录流程。登录成功后，进入一个测试仓库目录，让 Codex 做一个只读任务，比如：

codex "总结这个项目的目录结构，不要修改文件"

如果 Codex 能读到当前目录并给出项目结构说明，说明基础安装和登录流程已经跑通。

Windows 安装方式

OpenAI Quickstart 给出的 Windows CLI 安装命令是 PowerShell 方式：

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

如果要无人值守安装，可以在 PowerShell 中设置：

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

Windows 用户有两种常见选择：直接在 PowerShell 里使用 Codex，或者在 WSL2 里使用 Linux 环境。只做普通本地项目修改，PowerShell 通常足够；如果项目依赖 Linux 工具链、Shell 脚本、Docker 或类 Unix 路径，WSL2 会更接近生产环境。

npm 和 Homebrew 安装方式

官方 Quickstart 也列出 npm 和 Homebrew 两种安装方式：

npm install -g @openai/codex

brew install --cask codex

如果你已经有稳定的 Node.js 或 Homebrew 环境，这两种方式比较方便。需要注意的是，全局 npm 安装最常见的问题是 PATH 没有包含 npm 的全局 bin 目录。安装成功但执行 codex 提示命令不存在时，优先检查 npm bin -g 或你的 Node 版本管理器配置。

安装后怎么验证

不要只看“安装命令没有报错”。更可靠的验证流程是：

• 执行 codex，确认能启动。
• 完成 ChatGPT 账号或 API key 登录。
• 在一个真实项目目录中让 Codex 做只读分析。
• 再让 Codex 做一个小范围修改，例如改 README 的一行说明。
• 修改前后用 git diff 检查变更。

官方 Quickstart 也提醒，Codex 可以修改代码库，因此建议在任务前后创建 Git checkpoint。最简单的方式是先确认工作区干净：

git status --short

如果已经有未提交改动，先决定是否提交、stash 或至少记住哪些文件不是 Codex 改的。这样之后回滚更清楚。

App、IDE 扩展和 CLI 该选哪个

如果你是刚入门，我建议这样选：

• 想快速体验、看任务进度、管理多个任务：用 Codex App。
• 想在 VS Code、Cursor、Windsurf 里边看代码边让 Codex 修改：用 IDE 扩展。
• 想在终端里快速处理仓库任务、脚本任务、自动化任务：用 Codex CLI。
• 想把任务交给云端异步跑：使用云端 Codex。

这几个入口不是互斥的。官方文档也说明 CLI 和 IDE 扩展共享配置层；你后面配置 MCP、默认模型、审批策略时，不需要每个入口重复配置一遍。

FAQ：常见安装问题

curl 安装脚本下载失败

先确认网络是否能访问 chatgpt.com，再检查公司代理、终端代理和 DNS。不要一上来就反复执行安装脚本，先用下面命令验证网络：

curl -I https://chatgpt.com/codex/install.sh

如果公司网络限制了脚本下载，可以换网络，或者使用 npm / Homebrew 方式安装。

npm 安装成功但找不到 codex

这是 PATH 问题居多。检查全局 bin 路径是否在 PATH 中：

npm bin -g

如果你使用 nvm、fnm、volta 等 Node 版本管理工具，确认当前 shell 已经加载对应初始化脚本。

登录后仍然无法使用

先分清楚是“登录失败”还是“模型请求失败”。登录失败通常与账号、浏览器跳转、网络或 API key 有关；模型请求失败可能与套餐、组织策略、API key 权限、网络代理有关。建议先退出重新登录，再换一个简单只读任务测试。

Windows 里命令执行异常

先确认你是在 PowerShell 还是 WSL2 里执行。不要混用路径，例如在 PowerShell 中用 Linux 路径，或在 WSL2 中调用 Windows-only 工具。项目依赖 Linux 环境时，优先在 WSL2 里安装和运行。

官方资料

• OpenAI Codex Quickstart
• OpenAI Codex CLI
• Codex CLI command line options

总结

Codex 安装不难，真正容易出问题的是入口选择、登录方式、PATH、网络和项目目录权限。新手建议先跑通 codex、登录、只读分析、小范围修改、git diff 检查这条链路。等这条链路稳定后，再继续配置模型、审批策略、MCP 和自动化工作流。