主题
Codex跨平台安装环境指南：Windows、macOS、Linux系统要求与验证（2026更新）
更新时间：2026年8月2日
这篇文章只解决一个问题：你的 Windows、macOS 或 Linux 环境是否适合运行 Codex，以及安装后怎样确认终端实际调用了正确版本。完整下载命令、ChatGPT 登录、API Key 和 config.toml 配置，请直接进入 Codex下载、安装、配置保姆级教程。
旧版页面曾把早期 Codex 模型的弃用误写成当前 Codex CLI 已停用，这是错误的。OpenAI 当前仍维护 openai/codex 官方仓库，并提供 Windows、macOS、Linux、npm、Homebrew 与 Release 安装路径。本文已经按 2026年8月2日的官方仓库状态修订。
跨平台选择结论
| 环境 | 推荐起点 | 重点检查 | 更适合的用户 |
|---|---|---|---|
| Windows 原生 PowerShell | 官方 Windows 安装脚本或 npm | PATH、执行策略、沙箱、多个 Node 环境 | 日常 Windows 开发者 |
| Windows + WSL2 | 在 WSL 发行版中按 Linux 路径安装 | Windows 与 Linux 路径边界、Git、代理、文件性能 | 已使用 Linux 工具链或企业环境的开发者 |
| macOS Apple Silicon | 官方脚本、Homebrew 或 arm64 Release | 芯片架构、Homebrew 路径、shell 启动文件 | M 系列 Mac 用户 |
| macOS Intel | 官方脚本、Homebrew 或 x86_64 Release | 架构匹配、旧工具残留、PATH | Intel Mac 用户 |
| Linux x86_64/arm64 | 官方脚本、npm 或对应 Release | 发行版、CA 证书、代理、目录权限 | 服务器与 Linux 桌面用户 |
如果你只需要网页中的云端 Codex，不一定要配置本地 CLI；如果要让 Codex 读取仓库、修改文件和运行测试，则应先把终端、Git、权限与回滚链路准备好。
Windows 原生还是 WSL2
OpenAI 官方仓库当前提供 Windows PowerShell 安装脚本，并在 Release 中提供 Windows 架构文件，因此 Windows 原生已经有明确安装路径。另一方面，官方仓库的构建文档仍把 Windows 11 via WSL2 列入系统要求之一，这说明不同使用形态、版本和沙箱能力的 Windows 支持边界仍需以当前文档与实际 CLI 提示为准。
优先选择 Windows 原生的情况：
- 项目本来就在
C:\盘，主要使用 PowerShell、Visual Studio 或 Windows 版 VS Code。 - 团队依赖 Windows SDK、PowerShell 脚本或原生工具。
- 希望减少 Windows 与 Linux 两套路径、Git 凭据和代理配置。
优先选择 WSL2 的情况：
- 项目本来就在 Linux 工具链中运行。
- 团队使用 bash、容器、Linux 包管理器和 Linux CI。
- 原生 Windows 的沙箱、依赖或命令兼容性不符合当前项目要求。
不要在同一个仓库里同时用 Windows Git 和 WSL Git 反复写入，也不要让两个环境分别安装一套 Codex 后混用配置。先决定项目实际运行在哪一侧，再把仓库、终端、Codex 和测试命令放在同一环境。
Windows 环境验证
安装前记录以下信息：
powershell
$PSVersionTable.PSVersion
git --version
node --version
npm --version
where.exe git
where.exe node
where.exe npm使用官方安装脚本或 npm 完成安装后，再运行：
powershell
codex --version
codex --help
where.exe codex若 where.exe codex 返回多个路径，应确认当前 PATH 顺序。常见冲突包括旧 npm 全局目录、手动下载的二进制文件、另一个 Node 版本管理器和第三方同名程序。不要只看“命令能运行”，还要确认运行的是哪个文件。
公司电脑如果阻止远程脚本，应先遵守组织的软件安装与终端安全策略，不要永久放宽执行策略或关闭防护。可以改用官方 npm 包、官方 Release，或交由管理员部署经过核验的版本。
macOS 架构与 Homebrew 路径
先确认芯片架构：
bash
uname -m
sw_vers
git --version常见输出：
arm64：Apple Silicon，手动下载 Release 时应选aarch64-apple-darwin。x86_64：Intel Mac，手动下载 Release 时应选x86_64-apple-darwin。
Homebrew 在 Apple Silicon 与 Intel Mac 上的常见路径不同。安装后建议检查：
bash
brew --prefix
command -v brew
command -v codex
codex --version如果 brew install --cask codex 成功但终端找不到命令，先重开终端并检查 shell 启动文件。不要同时在 .zshrc、.zprofile 和多个版本管理器中重复追加同一目录。
Linux 发行版、证书与权限
OpenAI 仓库的构建说明列出 Ubuntu 20.04+/Debian 10+ 作为参考系统要求。其他发行版是否完全适配，应结合当前 Release、依赖和实际运行结果判断。
安装前可记录：
bash
uname -a
cat /etc/os-release
git --version
curl --version
command -v node
command -v npmLinux 安装失败常见于：
- 企业代理或 TLS 检查导致下载脚本、Release 或包源连接失败。
- CA 证书过旧或容器镜像过于精简。
- 全局 npm 目录不可写，用户转而使用
sudo npm install -g，导致后续文件归属混乱。 - 项目目录属于其他用户、只读挂载或容器卷权限不一致。
- 下载了错误架构的二进制文件。
建议使用用户级工具链、明确的包管理器和可追踪的版本来源。服务器上不要把长期 API Key 写进 shell 历史或部署脚本，应使用 Secret 管理。
手动下载 Release 时怎样选文件
Codex Latest Release 包含多个平台和架构文件。常见名称可以这样判断：
| 文件名关键词 | 平台或架构 |
|---|---|
aarch64-apple-darwin | Apple Silicon macOS |
x86_64-apple-darwin | Intel macOS |
x86_64-pc-windows-msvc | x64 Windows |
aarch64-pc-windows-msvc | ARM64 Windows |
x86_64-unknown-linux-musl | x64 Linux |
aarch64-unknown-linux-musl | ARM64 Linux |
手动下载适合包管理器受限、需要固定版本或企业软件分发的场景。下载后应记录 Release 页面、标签、文件名和校验信息，并由团队统一管理，不要把二进制文件重新包装成来源不明的“绿色版”。
config.toml 在不同系统中的位置
Codex 默认状态目录是 ~/.codex，可通过 CODEX_HOME 覆盖。常见用户配置路径：
| 系统 | 常见位置 |
|---|---|
| Windows | %USERPROFILE%\.codex\config.toml |
| macOS/Linux | ~/.codex/config.toml |
| WSL2 | WSL Linux 用户目录中的 ~/.codex/config.toml |
Windows 原生和 WSL2 是两套用户目录，不要假设它们自动共享配置、登录会话和 API Key。企业环境还可能通过系统或管理配置限制可用权限，项目中的 .codex/config.toml 也可能覆盖用户默认值。
具体字段、认证与优先级请看 Codex API 与 config.toml 配置教程。
团队部署与版本统一
团队采用 Codex 时，应先确定以下内容：
- 允许使用哪些平台、安装来源和版本通道。
- 是否由个人安装，还是通过企业软件分发统一部署。
- ChatGPT 登录、API Key 或企业认证分别允许在哪些环境使用。
- 哪些仓库和目录禁止 Codex 读取。
- 默认审批、沙箱、网络和命令执行边界。
- 更新前如何测试，失败后如何回滚。
官方 Release 中还提供 DotSlash 相关文件，适合需要在源码中固定工具版本的团队进一步评估。无论采用哪种方式，都应避免每位成员随意从不同来源安装不同版本，否则登录、配置、命令行为和故障复现会快速失去一致性。
跨平台首次项目验证
平台环境通过后，再创建一个不含敏感信息的示例仓库。建议统一执行：
bash
git init
git add .
git commit -m "baseline before Codex"
codex --version
codex首次任务只要求说明目录结构和测试命令，不允许写文件。第二次任务限制为一个文件或一个测试。完成后检查 git status、git diff 并运行测试。Windows、macOS、Linux 的终端命令可能不同，但验收标准应一致：来源明确、版本可查、配置可复现、改动可审查、测试可执行、分支可回滚。
常见问题
Windows 原生 Codex 和 WSL2 Codex 可以共用吗？
它们可以访问部分相同文件，但终端、PATH、用户目录、Git 凭据、配置和登录状态通常不同。不建议在同一仓库中无规划地交替使用，应选择主要运行环境并保持工具链一致。
Apple Silicon 应下载哪个文件？
手动下载时通常选择带 aarch64-apple-darwin 的文件；Intel Mac 选择 x86_64-apple-darwin。实际名称以当前 Latest Release 为准。
Linux 一定要用 Ubuntu 或 Debian 吗？
官方构建说明把 Ubuntu 20.04+/Debian 10+ 列为参考要求。其他发行版可能可用，但需要自行核对依赖、架构、证书、沙箱和运行结果。
为什么不同终端里的 Codex 版本不同？
通常是多个 PATH、多个 Node 环境、npm 与 Homebrew 重复安装、Windows 与 WSL2 混用或手动二进制残留。先用 where.exe codex 或 command -v codex 找出实际路径。
相关阅读
官方参考
本站是独立中文教程站，不是 OpenAI 官方网站。系统要求、安装脚本、Release 文件和平台支持会随版本更新，操作前应再次核对官方页面。