主题
Codex下载、安装、配置保姆级教程（2026最新版图解）
更新时间：2026年8月2日
想把 Codex 真正装到电脑上并开始改项目，可以直接按这条路线操作：确认官方入口 -> 选择适合系统的安装方式 -> 核对版本和命令路径 -> 使用 ChatGPT 账号或 API Key 登录 -> 配置 config.toml -> 在测试项目中完成第一次只读分析和小范围修改。
本文聚焦当前 OpenAI Codex CLI，不把早期已经弃用的 Codex 模型、第三方同名软件、网页聊天和本地命令行工具混为一谈。安装命令以 OpenAI 官方 Codex 仓库 当前 README 为准；本文核验时，官方 GitHub Latest Release 为 rust-v0.146.0，发布时间为 2026年7月29日。版本会继续更新，实际安装时不要强行照搬本文记录的版本号。
国内开发路径
优先尝试 OpenAI 官方 Codex CLI。若你的主要需求是中文开发工作流、Codex 国内版和较高额度的 GPT 编程模型，也可以了解第三方平台 ZeoGPT。它不是 OpenAI 官方产品，使用前应先用公开或脱敏代码测试，不要上传 API Key、.env、客户数据、生产日志或私有仓库。
一张图看懂 Codex 下载、安装和配置顺序
01核对来源OpenAI 文档、openai/codex 仓库、官方 Release
02选择安装Windows 脚本、macOS/Linux 脚本、npm 或 Homebrew
03验证命令检查版本、帮助信息和实际可执行文件路径
04完成登录ChatGPT 登录、设备码登录或 API Key
05安全配置config.toml、审批策略、沙箱和项目规则
06首次实战只读分析、小改动、Git Diff、测试与回滚
图：OpenAI 官方 openai/codex 仓库中的 Codex CLI 界面示意。截图中的模型名和版本号不代表当前默认值，实际状态以你安装后的界面为准。
第 0 步：先分清 Codex Web、App、CLI 和 IDE
搜索“Codex 下载”时，最容易发生的错误不是命令输错，而是下载了错误形态。当前 Codex 可以出现在网页、桌面应用、命令行和编辑器中，它们的安装方式与权限边界不同。
| 入口 | 是否需要本地安装 | 更适合什么任务 | 从哪里开始 |
|---|---|---|---|
| Codex Web | 通常不需要 | 云端任务、阅读仓库、发起编码工作 | chatgpt.com/codex |
| Codex App | 需要按当前官方页面安装或从 CLI 启动 | 图形界面管理项目、会话和修改 | 运行 codex app 或核对官方 App 页面 |
| Codex CLI | 需要 | 在终端读取项目、修改文件、运行测试 | openai/codex |
| Codex IDE | 需要编辑器扩展 | VS Code、Cursor、Windsurf 内协作 | Codex IDE 官方文档 |
如果你只想解释一段报错，不一定需要安装 CLI；如果你希望 Codex 读取本地仓库、修改多个文件并运行命令，CLI 或 IDE 更合适。还没选好入口，可以先看站内的 Codex 官网入口选择指南。
第 1 步：只从官方来源下载 Codex
建议把下面三个页面作为核验链路：
- OpenAI Codex 官方文档：核对当前产品、认证和配置说明。
- OpenAI 官方 GitHub 仓库：核对安装命令、源码、README 和版本发布。
- Codex GitHub Releases：需要手动下载二进制文件时核对平台和架构。
不要从网盘、论坛附件、所谓绿色版、破解版、免登录版或不明镜像下载安装包。Codex 会读取本地代码并可能执行命令，下载来源错误的风险远高于普通阅读软件。看到要求关闭安全软件、输入 ChatGPT 密码、复制浏览器 Cookie 或以管理员身份运行不明脚本时，应立即停止。
第 2 步：Windows 安装 Codex
OpenAI 官方仓库当前给出了 Windows PowerShell 安装脚本。打开 Windows Terminal 或 PowerShell，先确认你使用的是自己的普通用户终端，再运行：
powershell
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"安装结束后关闭当前终端，重新打开 PowerShell，然后核对：
powershell
codex --version
codex --help
where.exe codex三个命令分别确认版本、帮助信息和实际调用路径。若 codex --version 成功，但 where.exe codex 显示多个路径，说明电脑里可能同时存在旧版 npm 安装、手动下载版本或其他同名命令。应先确认哪个路径来自 OpenAI 官方安装，再决定是否清理旧版本。
Windows 安装脚本无法运行怎么办
按以下顺序排查，不要一开始就关闭安全软件或永久放开执行策略：
- 确认 PowerShell 能访问
https://chatgpt.com/codex/install.ps1。 - 检查公司电脑是否禁止远程脚本、用户级软件安装或未知发布者程序。
- 改用官方 README 中的 npm 安装方式。
- 仍无法安装时，从官方 GitHub Release 下载与你的架构匹配的 Windows 文件。
- 如果原生 Windows 的沙箱、路径或依赖表现不符合当前文档，再考虑使用 WSL2。
需要更细的 PATH、登录回调和 Windows 排错步骤，可继续看 Codex CLI Windows 安装与首次运行排错。
第 3 步：macOS 或 Linux 安装 Codex
OpenAI 官方仓库当前给出的 macOS/Linux 安装脚本是：
bash
curl -fsSL https://chatgpt.com/codex/install.sh | sh安装后新开终端并运行：
bash
codex --version
codex --help
command -v codex如果提示 command not found，先检查 shell 类型与 PATH。macOS 常见于 zsh 启动文件尚未重新加载，Linux 常见于安装目录不在当前用户 PATH、代理拦截下载或 CA 证书异常。不要为了让命令出现而直接把未知目录放到 PATH 最前面。
Homebrew 安装
已经使用 Homebrew 管理开发工具的 macOS 用户，也可以按照官方 README 使用：
bash
brew install --cask codex安装后仍要运行 codex --version 和 command -v codex，确认 Homebrew 安装路径没有被旧版 npm 或手动二进制覆盖。
第 4 步：使用 npm 安装 Codex CLI
Windows、macOS 和 Linux 都可以使用官方 npm 包：
bash
npm install -g @openai/codex安装前先检查 Node.js 与 npm：
bash
node --version
npm --version安装后检查：
bash
codex --version
npm list -g @openai/codex --depth=0npm 安装最常见的问题是全局目录权限、Node 版本管理器冲突和多个 npm 路径。Windows 可以用 where.exe node、where.exe npm、where.exe codex 对比；macOS/Linux 可以用 command -v node、command -v npm、command -v codex 对比。三者最好来自你预期的同一套环境。
需要升级、降级或卸载时，不要反复覆盖安装，参考 Codex CLI 更新、降级与卸载教程。
第 5 步：启动 Codex 并完成 ChatGPT 登录
安装完成后进入一个不含敏感信息的测试目录，再运行：
bash
codex首次启动时，优先按界面选择 Sign in with ChatGPT。官方仓库当前建议使用 ChatGPT 账号登录，以便在账号可用范围内使用 Codex。浏览器登录成功不等于终端一定完成认证，必须回到终端确认 Codex 已收到登录结果。
远程服务器、SSH 或没有可用浏览器的环境，可以尝试官方 CLI 提供的设备码登录：
bash
codex login --device-auth完成后检查登录状态：
bash
codex login status若浏览器不断跳转、登录后终端没有反应或选错账号，先记录 Codex 版本、终端类型、浏览器状态和错误原文，再按 Codex VS Code 登录授权循环排查 中的认证分层思路处理。
第 6 步：使用 API Key 登录
ChatGPT 登录和 OpenAI API Key 是两条不同认证路径。需要 API Key 时，应从环境变量通过标准输入交给 Codex，不要把完整 Key 写进命令参数、截图、文章或仓库。
macOS/Linux：
bash
printenv OPENAI_API_KEY | codex login --with-api-keyPowerShell：
powershell
$env:OPENAI_API_KEY | codex login --with-api-key然后运行：
bash
codex login status如果提示 401、403 或没有读取到 Key，应先确认当前 Shell 是否真的存在变量，再检查 Key 所属项目、组织权限和认证方式。不要为了排错把 Key 明文写入 config.toml。完整配置与密钥排查见 Codex API、ChatGPT 登录和 config.toml 教程。
第 7 步：找到并配置 config.toml
Codex 默认把状态和用户配置放在 ~/.codex，也可以通过 CODEX_HOME 改变目录。常见用户级配置路径是：
| 系统 | 常见配置路径 |
|---|---|
| Windows | %USERPROFILE%\.codex\config.toml |
| macOS/Linux | ~/.codex/config.toml |
| 自定义目录 | $CODEX_HOME/config.toml |
项目还可以使用 .codex/config.toml。当前官方实现中，命令行会话覆盖通常高于项目配置，项目配置又高于用户配置。因此遇到“改了配置却不生效”，不要只盯着一个文件，应同时检查当前目录、命令行参数、项目级配置和用户级配置。
下面是一个偏保守的基础示例：
toml
# ~/.codex/config.toml
approval_policy = "on-request"
sandbox_mode = "workspace-write"approval_policy 控制执行命令时何时向你请求批准，sandbox_mode 控制文件与环境访问范围。具体可用值和默认行为可能随版本变化，修改前应核对 Codex 配置文档 与当前 CLI 输出。
建议遵守三个配置原则：
- API Key、Token、Cookie 和密码放环境变量或 Secret 系统，不写进仓库。
- 第一次使用保留审批，不要直接授予不受限制的系统权限。
- 项目规则放在
AGENTS.md，把允许修改的目录、测试命令和禁止范围写清楚。
需要团队规则模板，可看 Codex AGENTS.md 配置教程。
第 8 步：第一次运行不要直接改生产项目
新建一个测试目录，或者复制一个没有 .env、密钥、客户数据和生产配置的小项目。先创建 Git 基线：
bash
git init
git add .
git commit -m "baseline before Codex"启动 Codex 后，第一条任务只要求读取和解释：
text
只读取当前项目，说明目录结构、启动命令和测试命令。
不要修改文件，不要安装依赖，不要访问网络。确认只读结果正常后，再给一个极小修改：
text
只修改 tests/example.test.ts，为现有函数补一个边界测试。
不要修改依赖、配置和其他文件。完成后给出 Git Diff 摘要和测试命令。修改完成后必须自己检查：
bash
git status
git diff然后运行项目原有测试或构建。Codex 的回答不是验收结果，文件列表、Diff、测试输出和可回滚性才是。更完整的任务模板见 Codex 提示词与项目工作流。
Codex 安装和配置常见错误
| 现象 | 优先检查 | 不建议做的事 |
|---|---|---|
codex 命令找不到 | 终端是否重开、PATH、安装目录、是否有多个 Node 环境 | 反复安装不同来源的同名包 |
| 版本与预期不同 | where.exe codex 或 command -v codex、npm/Homebrew/手动版本冲突 | 只看包管理器显示，不看实际执行路径 |
| ChatGPT 登录循环 | 浏览器账号、回调端口、代理、CLI 版本、组织策略 | 复制 Cookie 或把账号密码交给第三方 |
| 401 | Key 是否撤销、变量名、当前 Shell 是否读取、认证方式 | 截图或公开完整 Key |
| 403 | 项目、组织、模型权限与策略限制 | 连续生成新 Key 掩盖权限问题 |
| 429 | 速率、并发、可用额度和重试策略 | 无限重试或并发轰炸 |
| 无法修改文件 | 沙箱模式、审批、目录权限、项目规则 | 直接启用完全访问后继续试错 |
config.toml 不生效 | 用户级、项目级、会话参数和 CODEX_HOME 优先级 | 同时改多个配置来源 |
无法修改文件时，进入 Codex 只读、沙箱与审批排查；MCP 连接失败时，进入 Codex MCP 启动与超时排查；错误码问题统一从 Codex 故障排查中心进入。
下载和配置完成后的安全检查表
- 下载来源能回到 OpenAI 官方文档、官方仓库或官方 Release。
codex --version、帮助命令和实际路径都能正常返回。- 已明确使用 ChatGPT 登录还是 API Key，不混用排错。
config.toml不包含 API Key、Token、Cookie 或生产密码。- 第一次任务在测试项目或新分支中完成。
- 已查看 Git Diff，没有无关文件、依赖或配置变化。
- 已运行与改动相匹配的测试或构建。
- 能够回滚本次修改，并知道日志与配置保存在哪里。
常见问题
Codex 下载应该优先选哪个方式？
Windows 可以先用 OpenAI 官方 PowerShell 安装脚本；macOS/Linux 可以先用官方 shell 脚本；已经统一使用 Node.js 或 Homebrew 管理工具的开发者，也可以选择 npm 或 Homebrew。无论选哪种方式，都要核对官方 README、版本和实际命令路径。
Codex CLI 和 Codex App 是同一个东西吗？
不是同一种交互形态。CLI 主要在终端工作，App 提供图形界面，Web 运行在网页或云端，IDE 入口嵌入编辑器。它们可能共享账号或部分能力，但安装、权限、项目访问和排错方式不同。
Windows 必须使用 WSL2 吗？
OpenAI 官方仓库当前已经提供 Windows PowerShell 安装脚本和 Windows Release 文件。某些运行、沙箱、依赖或团队环境仍可能更适合 WSL2，应以当前官方文档、CLI 提示和你的开发环境为准。
ChatGPT 登录和 API Key 登录选哪个？
个人本机交互可以优先按官方提示使用 ChatGPT 登录；CI、服务器或需要独立凭据管理的场景更适合 API Key。两者的权限、会话和使用条件不同，不要认为能登录 ChatGPT 网页就一定能使用 API。
config.toml 一定在用户目录吗？
默认用户配置通常位于 ~/.codex/config.toml，Windows 对应用户目录下的 .codex\config.toml。如果设置了 CODEX_HOME，目录会改变；项目还可能有 .codex/config.toml，会话参数也可能覆盖配置。
可以把第三方 API 地址写进 Codex 吗？
只有在服务明确兼容当前 Codex 请求、认证、模型名和工具调用格式时才有可能正常工作。第三方服务不是 OpenAI 官方入口，使用前要核对数据流向、日志、密钥保存和服务条款，并先用脱敏项目测试。
安装成功后可以直接让 Codex 重构整个仓库吗？
不建议。先做只读分析，再允许一个文件或一个测试的小改动，查看 Diff 并运行测试。确认权限、配置、修改范围和回滚链路都正常后，再逐步扩大任务。
相关阅读
- OpenAI Codex 中文教程总入口
- Codex CLI Windows 安装、登录与 PATH 排错
- Codex API Key、ChatGPT 登录与 config.toml 配置
- Codex CLI 更新、版本检查、降级与卸载
- Codex AGENTS.md 项目规则教程
- Codex MCP 连接失败排查
官方参考与核验时间
- OpenAI Codex 官方文档
- OpenAI Codex 认证文档
- OpenAI Codex 配置文档
- OpenAI Codex IDE 文档
- openai/codex 官方 GitHub 仓库
- Codex Latest Release
本文在 2026年8月2日核验了官方仓库 README、安装命令、登录命令、配置目录实现和 Latest Release。Codex 的安装脚本、版本、认证、系统支持和配置字段可能继续变化，实际操作前应再次查看官方页面。本站是独立中文教程站，不是 OpenAI 官方网站；内容核验方法见编辑与核验规则。