安装、登录与升级

系统要求

Linux 与 WSL2 上的命令沙箱依赖 bwrap，建议先安装 bubblewrap（sudo apt install bubblewrap 或 sudo dnf install bubblewrap）。找不到 bwrap 时 Codex 会退回内置的辅助程序，但它要求系统允许创建非特权用户命名空间；Ubuntu 24.04 上可能还要加载 AppArmor 配置，见官方 Sandbox 文档。

安装方式

官方安装脚本（推荐）

macOS / Linux：

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

Windows（PowerShell）：

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

脚本会识别平台（macOS Apple Silicon / Intel、Linux x64 / ARM64、Windows x64 / ARM64），优先从 https://releases.openai.com/codex 下载，不可用时回退到 GitHub Releases。程序本体放在 $CODEX_HOME/packages/standalone（默认 ~/.codex/packages/standalone），codex 命令放在 ~/.local/bin（Windows 为 %LOCALAPPDATA%\Programs\OpenAI\Codex\bin）。该目录不在 PATH 中时，脚本会把它写进 shell 启动文件（macOS 为 ~/.zprofile 或 ~/.bash_profile，Linux 为 ~/.zshrc 或 ~/.bashrc，其他 shell 为 ~/.profile，内容夹在 # >>> Codex installer >>> 标记之间）或 Windows 的用户级 Path。重新运行同一条命令即可升级。

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

$env:CODEX_RELEASE='0.158.0'; irm https://chatgpt.com/codex/install.ps1 | iex

npm

npm install -g @openai/codex

npm 包只是一个 Node.js 启动器（要求 Node.js 16+），原生程序在按平台拆分的可选依赖里（如 @openai/codex-linux-x64）。启动时若报 Missing optional dependency，说明平台包没装上，重新执行 npm install -g @openai/codex@latest 即可。用 pnpm、bun 或 Vite+（vp）全局安装的，同样能被 codex update 识别。

Homebrew

brew install --cask codex
brew upgrade --cask codex   # 升级

GitHub Releases 二进制

从最新 Release 下载对应平台的压缩包：macOS 为 codex-aarch64-apple-darwin.tar.gz（Apple Silicon）或 codex-x86_64-apple-darwin.tar.gz（Intel），Linux 为 codex-x86_64-unknown-linux-musl.tar.gz 或 codex-aarch64-unknown-linux-musl.tar.gz。压缩包里只有一个带平台名的可执行文件，解压后改名为 codex 并放进 PATH。Release 中还附带名为 codex 的 DotSlash 文件，可提交进仓库，让团队在各平台上统一版本。

验证安装

codex --version
codex doctor

codex doctor 检查系统与安装、配置、认证、更新、网络与连通性（含 WebSocket 与模型提供方的可达性）、MCP、沙箱、磁盘、Git、终端、本地状态库、app-server 与会话清单是否正常，只报告问题、不做修复，有检查失败时退出码为 1，报 issue 前建议先跑一遍。v0.156.0 起它还会逐个解析配置里授权的文件系统路径，慢或解析失败时给出警告，配置加载出错时只报告文件、行号与列号，不回显配置内容；v0.157.0 起会列出完整性检查失败的 SQLite 数据库路径。v0.158.0 起，诊断日志写不进本地 SQLite 数据库时，Codex 会给出一次警告，建议在关闭前用 /feedback 附带日志上报，或运行 codex doctor 排查。常用参数：--summary（只看分组结果与计数）、--all（展开较长的列表）、--json（输出脱敏的机器可读报告）、--no-color、--ascii（只用 ASCII 字符）。

登录

Codex 支持两种个人登录方式：

• ChatGPT 账号：使用套餐内的 Codex 用量，遵循 ChatGPT 工作区的权限与数据保留设置；Codex cloud 只支持这种方式。
• API key：按 OpenAI Platform 的 API 标准价格计费，适合 CI 等自动化场景；依赖 ChatGPT 工作区或云服务的部分功能受限或不可用。

首次运行 codex 会出现登录界面，可选 Sign in with ChatGPT、Sign in with Device Code 或 Provide your own API key（选 API key 时，若已设置 OPENAI_API_KEY 会自动预填）。v0.158.0 起，浏览器没有自动打开时，可以在登录界面按 c 复制登录链接，也可以直接用鼠标选中链接与设备码；TUI 连接本机的后台服务（app-server 守护进程）时，选 Sign in with ChatGPT 也会自动打开浏览器（此前不会）。也可以直接使用 codex login：

• --with-api-key 与 --with-access-token 只能二选一；旧版直接跟 key 的 --api-key 已废弃，使用时会报错并提示改用管道传入。
• 公司网络有 TLS 拦截代理或私有根证书时，登录前把 CODEX_CA_CERTIFICATE 指向 PEM 证书包（未设置时使用 SSL_CERT_FILE）；登录失败时可查看日志目录中的 codex-login.log。
• CI 中更推荐 API key：codex exec 与 codex review 会读取 CODEX_API_KEY，见环境变量。

在没有浏览器的远程机器上登录

1. 设备码（首选）：先在 ChatGPT 安全设置（个人账号）或工作区权限（管理员）中启用设备码登录，再运行 codex login --device-auth。
2. 转发回调端口：用 ssh -L 1455:127.0.0.1:1455 user@remote 登录远程机器后运行 codex login，在本机浏览器打开它打印的地址。远程的 1455 端口被占用时，回调会改用 1457，需要相应地转发 1457。
3. 复制凭据缓存：在有浏览器的机器上登录，再把 ~/.codex/auth.json 复制到远程机器的同一路径（仅适用于文件存储）：

ssh user@remote 'mkdir -p ~/.codex && cat > ~/.codex/auth.json' < ~/.codex/auth.json

凭据存储

登录信息会缓存并重复使用，ChatGPT 登录的 token 会在过期前自动刷新。缓存位置由 config.toml 中的 cli_auth_credentials_store 决定：

托管环境中，管理员可以用 forced_login_method = "chatgpt"（或 "api"）只允许一种登录方式，用 forced_chatgpt_workspace_id 把 ChatGPT 登录限定到指定工作区；凭据不符合限制时，Codex 会登出并退出。

升级

codex update 会识别当前的安装方式，执行对应的升级命令：

识别不出安装方式时（如手动放置的二进制）会提示手动更新。Codex 默认在启动时检查新版本并提示升级；版本由公司统一管理时，可设置 check_for_update_on_startup = false 关闭检查。

v0.155.0 起，安装脚本会记下你装的是 latest 还是指定版本。跟随 latest 的独立安装版，后台的 app-server 守护进程运行时会定期自动更新，也可以用 codex app-server daemon update 立即更新（设置方法见 SDK 与 App Server）；用 CODEX_RELEASE 或 --release 指定版本安装的，守护进程保持在该版本。更早用安装脚本装的，要重新用 latest 安装一次才会开始自动更新。

v0.156.0 起，新装的守护进程使用独立的安装包目录 CODEX_HOME/packages/app-server-daemon，和 codex 命令分开更新：codex update 只升级 CLI 本身，守护进程由它自己的更新程序、codex app-server daemon update 或 TUI 中的 /daemon 更新；之前启动过的旧守护进程仍与独立安装版共用 packages/standalone，执行一次 codex app-server daemon update 就会迁移过去。两者版本不一致时，TUI 启动时会给出提示。

Windows 与 WSL

原生 Windows：用 PowerShell 脚本安装即可。命令在原生 Windows 沙箱中运行，可在 config.toml 中选择沙箱实现：

[windows]
sandbox = "elevated" # 或 "unelevated"；v0.156.0 起还可以是 "mxc"

elevated（首选）使用专门的低权限沙箱用户、文件系统权限边界与防火墙规则，首次设置需要管理员批准；unelevated（回退）使用当前用户派生的受限令牌，隔离较弱，可在会话中用 /setup-default-sandbox 改走 elevated 设置。推荐 Windows 11；Windows 10 需 1809 及以上版本（依赖 ConPTY）。

v0.158.0 起，在 Windows 上自动启动后台服务时，如果启动 Codex 的程序不允许后台进程脱离它继续运行（如 cargo run），Codex 改用内嵌服务并给出警告，不再直接启动失败；以管道方式启动的子进程也不再弹出控制台窗口（启动 code-mode host 与本地 stdio MCP 服务器时的弹窗已在 v0.157.1 修复）。

WSL2：需要 Linux 原生工具链、或项目本就在 WSL 中时选择它。在管理员 PowerShell 中执行 wsl --install 装好发行版，再在 WSL 里用 macOS / Linux 的安装脚本安装并装好 bubblewrap。仓库尽量放在 Linux 家目录（如 ~/code）而不是 /mnt/c 下，I/O 更快。自 0.115 起 Linux 沙箱改用 bubblewrap，WSL1 不再受支持。

卸载

官方文档未单独说明卸载，以下依据各安装方式的行为整理：

用过后台服务的，先运行 codex app-server daemon stop 停掉守护进程；v0.156.0 起它的安装包单独放在 ~/.codex/packages/app-server-daemon（Windows 为 %USERPROFILE%\.codex\packages\app-server-daemon），也要一并删除。

如果还要清除配置、凭据与会话记录（不可恢复），先运行 codex logout（凭据存放在系统凭据库时，只删目录清除不了它们），再删除 ~/.codex（或你设置的 CODEX_HOME）。桌面应用与 IDE 扩展也使用这个目录，删除前请确认。