OpenAI Codex 已经从最初的单一命令行工具演变为完整产品矩阵，覆盖桌面应用（Codex app）、命令行（Codex CLI）、IDE 扩展、云端 Web 与 GitHub 集成五个表面。所有 Codex 表面共享同一个 ChatGPT 账号认证体系，包含在 ChatGPT Plus、Pro、Business、Edu、Enterprise 订阅中无需额外付费。Codex 安装路径取决于你想在哪种环境下使用——终端、桌面、IDE 还是云端，本指南整理三大本地安装路径在 macOS、Windows、Linux 上的最简命令。
根据 OpenAI 官方公告，Codex 桌面应用于 2026 年 2 月在 macOS 首发，3 月 4 日上线 Windows，限时活动期间向 ChatGPT Free 与 Go 用户开放。本文按”产品矩阵—系统要求—安装方法—问题排查—验证使用—获取方式”六段，详细说明 Codex 在不同设备上的部署流程。
Codex 产品矩阵：先搞清装哪个
很多教程把”安装 Codex”等同于”安装 Codex CLI”，但实际上当前 Codex 包含五个独立但互通的表面：
- Codex 桌面应用（Codex app）：macOS 与 Windows 原生应用，定位为 “command center for agents”，支持并行 agent 线程、worktree、in-app 浏览器、computer use（macOS）等
- Codex CLI：开源命令行 agent，基于 Rust 构建，运行在本地终端，openai/codex GitHub 仓库已收获 75k+ stars
- Codex IDE 扩展：VS Code、Cursor、Windsurf 等编辑器内的 Codex agent
- Codex Cloud / Codex Web：云端异步任务模式，访问 chatgpt.com/codex 提交任务
- Codex GitHub 集成：在 PR 评论中通过 @codex 触发云端任务
选哪个：
- 偏好图形界面、需要并行管理多个 agent、做前端 / 游戏开发需要 in-app 浏览器 → 桌面应用
- 终端工作流、CI/CD、SSH 远程开发、headless 环境 → CLI
- 已有 IDE 习惯、希望 agent 直接读取打开的文件 → IDE 扩展
- 长任务后台运行、不想占用本地资源 → Cloud / Web
三个本地表面共享配置：桌面应用、CLI、IDE 扩展共用 ~/.codex/config.toml（Windows 为 %USERPROFILE%\.codex\config.toml），认证、MCP 服务器配置、自定义模型 provider 等设置在三者间自动同步。这意味着在一个表面登录后，其他两个表面无需再次认证。
系统要求与前置检查
根据 Codex 官方安装文档：
- 桌面应用：macOS（Apple Silicon 优先，Intel 也有对应构建）；Windows 10/11，通过 Microsoft Store 分发
- Codex CLI：macOS、Windows 10/11、Linux 主流发行版（Ubuntu、Debian、Fedora、RHEL、Alpine 等）
- 系统架构：x64 或 ARM64
- Node.js：仅 npm 安装路径需要 22+；Homebrew 与 GitHub Release 路径无依赖
- 账号：ChatGPT Plus（20 美元/月）、Pro（200 美元/月）、Business、Edu、Enterprise 之一，或一个有可用额度的 OpenAI API Key
- 限时活动：据 OpenAI 2026 年 2 月公告，Codex 桌面应用限时向 ChatGPT Free 与 Go 用户开放，截止时间以官方为准
- 网络：稳定连接到 OpenAI 服务端点，国内用户需配置代理
检查当前 Codex CLI 是否已安装：
codex --version如果返回版本号（如 codex-cli 0.121），说明已安装。否则按下文方法安装。
安装方法
方法一：Codex 桌面应用（macOS / Windows 推荐）
适合大多数开发者的最简路径，提供并行 agent 线程、in-app 浏览器、worktree 管理、skills 与 plugins 等图形化能力。
macOS 安装：
访问 chatgpt.com/codex 下载 .dmg 文件（Apple Silicon 与 Intel 各有对应构建），双击挂载后将 Codex.app 拖入 Applications 目录。
或通过 Homebrew cask 安装：
brew install --cask codexWindows 安装：
通过 Microsoft Store 安装是最简单的路径，Codex 在 Microsoft Store 的应用页支持一键安装，并通过 Store 自动更新。
或使用 winget：
winget install --id 9PLM9XGG6VKS --source msstore从 CLI 启动桌面应用：如果已经安装了 Codex CLI，执行 codex app 会自动下载并安装桌面应用，省去手动下载步骤。
桌面应用首次启动时会引导完成 ChatGPT 账号 OAuth 登录，认证完成后即可创建项目。
方法二：Codex CLI 通过 npm 安装（跨平台）
最广泛的 CLI 安装方式，命令统一：
npm install -g @openai/codex包名陷阱必须注意：完整包名是 @openai/codex（含 @openai 命名空间），不是 codex。npm 上存在另一个完全无关的 codex 包（2012 年发布、与 OpenAI 无关），OpenAI 官方 README 明确标注误装该包是常见错误来源。安装前确认命令包含 @openai/ 前缀。
要求 Node.js 22 或更高版本。npm 路径下的 codex 命令是个 JavaScript shim，运行时检测平台架构，加载对应的 optional dependency（如 @openai/codex-darwin-arm64），spawn 实际的原生 Rust 二进制执行。本身不参与运行时计算。
禁止使用 sudo npm install -g。遇到 EACCES 权限错误时配置用户级 npm prefix：
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g @openai/codex升级 Codex CLI：
npm install -g @openai/codex@latest方法三：Codex CLI 通过 Homebrew（macOS 推荐）
不需要 Node.js，直接安装 Rust 原生二进制：
brew install --cask codex注意是 cask 而非 formula。brew install codex（不带 –cask）会失败或装到错误的包。Homebrew cask 同时安装 Codex CLI 与桌面应用——这是 2026 年初 Homebrew 包结构调整后的统一入口。
升级用：
brew upgrade --cask codex如果之前用旧的 formula 路径安装过，需先卸载再装 cask：
brew uninstall codex
brew install --cask codex方法四：Codex CLI 通过 GitHub Release 直接下载（零依赖）
适合不想引入 Node.js 或 Homebrew 的最小化部署场景，包括服务器、CI 环境、Docker 镜像等。访问 openai/codex GitHub Releases 页面下载对应平台归档：
- macOS Apple Silicon：codex-aarch64-apple-darwin.tar.gz
- macOS Intel：codex-x86_64-apple-darwin.tar.gz
- Linux x86_64：codex-x86_64-unknown-linux-musl.tar.gz（musl 静态链接，最大兼容性）
- Linux ARM64：codex-aarch64-unknown-linux-musl.tar.gz
每个归档解压后包含一个二进制文件，名字带平台标识，需重命名为 codex 并放到 PATH 中：
tar -xzf codex-x86_64-unknown-linux-musl.tar.gz
mv codex-x86_64-unknown-linux-musl ~/.local/bin/codex
chmod +x ~/.local/bin/codexLinux 二进制使用 musl 静态链接而非 glibc，同一个二进制可在 Alpine、Ubuntu、Debian、CentOS 等不同发行版直接运行。
方法五：Codex IDE 扩展（VS Code / Cursor / Windsurf）
Codex IDE 扩展把 agent 直接集成到编辑器内，支持读取打开的文件与选中代码作为上下文。
VS Code 安装：
打开 VS Code 扩展面板（Cmd+Shift+X on Mac，Ctrl+Shift+X on Windows/Linux），搜索 “Codex” 选择官方 OpenAI Codex 扩展安装。
Cursor / Windsurf 安装：
在各自的扩展市场搜索 “Codex” 安装。Cursor 与 Windsurf 是 VS Code 的 fork，扩展生态兼容。
IDE 扩展与 CLI、桌面应用共用 ~/.codex/config.toml，认证状态自动同步——在任一表面登录后，IDE 扩展无需再次认证。
方法六：Windows 上的 WSL2 路径
如果项目托管在 WSL2 内、或需要 Linux 原生工具链，可在 WSL 内安装 Codex CLI：
# 在 PowerShell 管理员窗口安装 WSL（如未安装）
wsl --install -d Ubuntu
# 进入 WSL 后安装 Node.js 22 与 Codex CLI
nvm install 22
npm install -g @openai/codexWSL1 已停止支持。Codex 0.115 起 Linux 沙盒迁移到 bubblewrap，仅 WSL2 可用。
Windows 原生与 WSL 配置同步：Windows 原生 Codex 使用 %USERPROFILE%\.codex，WSL 内 Codex 默认使用 Linux ~/.codex。共享认证与会话历史在 WSL 中设置：
export CODEX_HOME=/mnt/c/Users/<windows-user>/.codex
echo 'export CODEX_HOME=/mnt/c/Users/<windows-user>/.codex' >> ~/.bashrc认证方式：ChatGPT 订阅与 API Key 的差异
Codex 所有本地表面（桌面应用、CLI、IDE 扩展）共享同一套认证体系，提供两种登录方式：
ChatGPT OAuth（推荐个人开发者）：自动打开浏览器，在 localhost:1455 启动 OAuth 回调服务器，登录 ChatGPT 账号后令牌存储到 ~/.codex/auth.json 或操作系统密钥库。直接绑定 ChatGPT 订阅额度，无需手动管理 Key。远程 SSH 或浏览器回调被阻断时使用设备码流程：
codex login --device-codeAPI Key（推荐 CI/CD 与自动化）：
export OPENAI_API_KEY=sk-...
codex或通过 stdin 传入：
printenv OPENAI_API_KEY | codex login --with-api-key关键差异：fast mode 等依赖 ChatGPT credits 的功能仅 OAuth 登录可用，API Key 路径走标准 API 计费。这意味着相同任务两种认证方式费用结构不同——OAuth 走订阅额度（消耗 ChatGPT 计划内的本地消息配额），API Key 按 token 计费。Codex 官方认证文档建议个人开发者使用 OAuth、CI/CD 流水线使用 API Key。
凭证存储位置可通过 ~/.codex/config.toml 中的 cli_auth_credentials_store 配置：
- file：存储在 ~/.codex/auth.json（明文，需视为密码保护）
- keyring：存储在操作系统密钥库（macOS Keychain、Windows Credential Manager、Linux Secret Service）
- auto：优先使用密钥库，不可用时回落到 file
模型选择：GPT-5.5、GPT-5.4 与 GPT-5-Codex
Codex 当前可用的模型：
- GPT-5.5：最新通用模型，复杂规划与多步推理首选
- GPT-5.4：稳定可用的前一代，支持 1M 上下文窗口（实验性）与 native computer use
- GPT-5.4 mini：轻量模型，适合代码库探索、大文件审查、subagent 工作
- GPT-5-Codex：基于 GPT-5 进一步针对 agentic coding 优化的版本，OpenAI 建议仅在 Codex 或类 Codex 环境中使用
在 CLI 中切换模型：
# 启动新会话时指定
codex --model gpt-5.5
# 会话内切换
/model或在 ~/.codex/config.toml 中持久化默认模型：
model = "gpt-5.5"注意：如果账号尚未开放 GPT-5.5 访问，回退到 gpt-5.4 即可。模型可见性按账号逐步开放，更新 CLI、IDE 扩展或桌面应用到最新版本可能解锁新模型选项。
常见问题排查
问题 1：误装了无关的 codex 包
原因：执行 npm install -g codex 装到的是 2012 年发布的同名无关包。
解决方案：
npm uninstall -g codex
npm install -g @openai/codex问题 2：Node.js 版本过旧
原因：npm 安装路径要求 Node.js 22+。
解决方案：执行 node –version 检查。低于 22 时通过 nvm install 22 升级，或改用 Homebrew / GitHub Release 路径。
问题 3：codex –version 提示 command not found
解决方案：关闭终端开新窗口；macOS/Linux 执行 source ~/.zshrc 或 ~/.bashrc；Windows 关闭并重开 PowerShell。仍找不到检查 npm config get prefix 输出对应 bin 目录是否在 PATH 中。
问题 4：npm 安装报 EACCES 权限错误
解决方案：不要使用 sudo。按方法二末尾配置用户级 npm prefix，或改用 Homebrew 路径。
问题 5：macOS 提示 “无法打开 codex，因为开发者无法验证”
解决方案：
- 系统设置 → 隐私与安全性 → 找到被阻断的 codex 条目，点击”仍要打开”
- 或在 Terminal 中：xattr -d com.apple.quarantine $(which codex)
问题 6：Codex 桌面应用 macOS 仅支持 Apple Silicon？
原因：早期版本仅 Apple Silicon 构建。
解决方案：当前 Codex 桌面应用同时提供 Apple Silicon 与 Intel 构建。在 Codex 桌面应用下载页选择 Intel 构建即可。
问题 7：OAuth 浏览器回调失败
原因：远程 SSH、devcontainer、严格防火墙环境下 localhost:1455 回调被阻断。
解决方案：使用设备码流程 codex login –device-code，或直接设置 OPENAI_API_KEY 环境变量。
问题 8：Windows 原生沙盒初始化失败
解决方案：在 ~/.codex/config.toml 切换到 unelevated 沙盒模式：
[windows]
sandbox = "unelevated"问题 9：API Key 已设置但 Codex 仍要求登录
解决方案：检查当前 shell：echo $OPENAI_API_KEY；添加到 shell profile 持久化；首次运行按 onboarding 流程批准该 Key。
问题 10：国内网络无法完成 OAuth 或 API 调用
解决方案：
- 设置代理：export HTTPS_PROXY=http://proxy.example.com:port
- 或在 ~/.codex/config.toml 配置 custom model provider 指向第三方兼容端点（注意非官方端点不消耗 ChatGPT 订阅额度，按第三方 provider 计费）
验证安装与基础使用
CLI 验证：
# 检查版本
codex --version
# 验证认证状态
codex login status
# 查看 MCP 服务器配置
codex mcp list
# 启动交互式 TUI
codex桌面应用验证：启动后看到主界面 + 可创建新项目即说明安装成功。
进入 Codex CLI 后可使用以下内置命令：
# 切换模型
/model
# 会话状态与 token 用量
/status
# 查看当前生效配置
/config
# 压缩对话历史
/compact装完之后的关键三步：
- 在项目目录运行 codex（CLI）或在桌面应用中创建项目，让 Codex 探索代码库结构。Codex 会自动读取项目根目录的 AGENTS.md 作为持久上下文，类似 Claude Code 的 CLAUDE.md 机制
- 设置 approval mode 适配工作风格——–sandbox workspace-write 适合无人值守的局部任务，–ask-for-approval never 让 Codex 自主完成
- 通过 codex mcp add 接入 MCP 服务器，把 Codex 扩展为可调用 GitHub、数据库、内部 API 的完整 agent
卸载方式：不同安装路径对应不同清理步骤
- npm：npm uninstall -g @openai/codex
- Homebrew cask：brew uninstall –cask codex
- GitHub Release 手动安装：删除二进制所在路径（如 ~/.local/bin/codex）
- 桌面应用（macOS）：从 Applications 拖到废纸篓
- 桌面应用（Windows）：通过 Microsoft Store 卸载，或 winget uninstall 对应包
仅删除二进制并不能完全清理。配置目录 ~/.codex/（Windows 为 %USERPROFILE%\.codex）包含认证令牌、MCP 服务器配置、会话历史与执行规则，会被保留以便重装。彻底清理：
# macOS / Linux / WSL
rm -rf ~/.codex
# 或仅清除认证（保留其他配置）
codex logout注意安全：~/.codex/auth.json 存储 OAuth 令牌或 API Key 明文。卸载前如不打算重装，建议先 codex logout 显式撤销凭证。
OpenAI Codex 已经从单一 CLI 演化为覆盖终端、桌面、IDE、云端、GitHub 的完整 agent 矩阵，包含在 ChatGPT 订阅中的策略大幅降低了使用成本。但安装本身只是入口——真正决定生产力的是后续 AGENTS.md 上下文设计、approval mode 调优、skills 与 plugins 体系搭建以及 MCP 服务器集成。Codex 与 Claude Code 在 agent 工作流上互有取舍——Codex 矩阵更广（覆盖到桌面与 GitHub），Claude Code 更聚焦于命令行——对中文开发者而言两者并存往往比二选一更实用。