如何安装 Codex CLI（macOS、Windows、Linux 一行命令安装指南）

在 macOS、Windows 与 Linux 上一行命令安装 OpenAI Codex CLI（官方 install.sh、PowerShell、npm 或 Homebrew），用 codex --version 验证并完成首次登录。

UniRoute · 2026年10月18日

按你的操作系统复制下方命令即可安装 OpenAI Codex CLI（@openai/codex），安装后运行 codex --version 验证：

系统 / 方式	推荐安装命令	验证命令
macOS（Apple Silicon 与 Intel）	`curl -fsSL https://chatgpt.com/codex/install.sh \| sh` （或 `brew install --cask codex`）	`codex --version`
Linux（`x86_64` 与 `arm64`）	`curl -fsSL https://chatgpt.com/codex/install.sh \| sh`	`codex --version`
Windows（PowerShell 或 WSL2）	`powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 \| iex"` （或在 WSL2 内运行 Linux 命令）	`codex --version`
npm 备选（需 Node.js >= 16）	`npm install -g @openai/codex`	`codex --version && codex doctor`

系统要求（2026-10-18 核验自 docs/install.md 与 @openai/codex@0.163.0 npm 元数据；install.sh 于 2026-10-27 核验自 Codex CLI 官方文档）：支持 macOS 12+、Ubuntu 20.04+ / Debian 10+ 或 Windows 11（原生 PowerShell 或 WSL2）；内存最低 4 GB（建议 8 GB）；Git 2.23+ 可选；仅在使用 npm 安装时才需要 Node.js >= 16。

下一步：首次运行与登录

当 codex --version 正常输出版本号后，即可在项目目录启动并登录：

使用 ChatGPT 账号登录： 运行 codex 并选择 Sign in with ChatGPT（支持 ChatGPT Plus、Pro、Business、Edu 或 Enterprise 套餐；若遇到套餐限额可参阅 Codex 用量限制指南）。
使用 API Key 登录（没有 ChatGPT 套餐，或套餐额度用完时）： 本地 Codex CLI 会话也支持使用 OpenAI 官方 API Key 或 UniRoute API Key（创建 API Key）按量计费。截至 2026-10-27，折扣渠道可用时，GPT 模型低至官方 API 价的约 28%（例如 GPT 6 Sol 为 $0.56 / $2.80 每百万输入/输出 Token，官方为 $2 / $10；GPT 5.6 Terra 为 $0.56 / $3.36，官方为 $2 / $12）；折扣渠道不可用时，会自动切到与官方同价的标准渠道（渠道说明；实时价格见 UniRoute 定价页）。一条命令即可完成配置：

npx --yes --package=https://uniroute.app/community/uniroute-setup-0.1.2.tgz uniroute-setup models
npx --yes --package=https://uniroute.app/community/uniroute-setup-0.1.2.tgz uniroute-setup configure codex --model MODEL_ID

完整说明请参阅 Codex CLI 接入文档与用 UniRoute API Key 接入 Codex 教程（手动编辑 config.toml 的字段说明见下文第 4 节）。

1. 常见安装与启动报错排查表

如果安装后执行 codex 报错，可按以下现象直接处理：

报错现象 / 提示信息	原因分析	解决方法
运行 `install.sh` 后提示 `command not found: codex`	当前终端会话尚未重新加载安装脚本更新的 shell 配置文件（macOS 为 `~/.zprofile` 或 `~/.bash_profile`，Linux 为 `~/.zshrc` 或 `~/.bashrc`，或 `~/.profile`，具体路径见脚本输出的 `"PATH was added to <profile>"`）。	新开一个终端窗口，或直接运行安装脚本末尾打印的命令：`export PATH="$HOME/.local/bin:$PATH" && codex`。
提示 `Multiple managed Codex installs can be ambiguous because PATH order decides which one runs`（或升级后版本号不变）	同一台机器上同时存在 Homebrew（`/opt/homebrew/bin/codex`）、npm 或 `~/.local/bin/codex` 等多个副本，且旧副本在 `PATH` 中靠前。	运行 `which -a codex`（macOS/Linux）或 `where.exe codex`（Windows），卸载多余的那一份（`brew uninstall --cask codex` 或 `npm uninstall -g @openai/codex`）。
`npm install -g @openai/codex` 报权限错误（`EACCES`）	全局 npm 前缀指向了当前用户无权写入的系统目录。	不要使用 `sudo npm install -g`；改用默认写入 `~/.local/bin` 的官方脚本 `install.sh`，或使用用户级 npm prefix / Node 版本管理器。
执行升级命令后 `codex --version` 仍显示旧版本	更新了其中一个包管理器，但 `PATH` 排第一的是另一套安装；或当前 shell 缓存了旧路径。	先用 `which -a codex` 确认路径并清理重复安装，随后在 `bash`/`zsh` 中执行 `hash -r`（或重开终端）。
`codex doctor` 提示 `websocket ⚠ Responses WebSocket failed; HTTPS fallback may still work`	到 Responses 端点的 WebSocket 探测未成功，但常规 HTTPS 请求可能仍可正常工作。	请先实际发送一次请求测试；正如 `codex doctor` 提示本身所说，HTTPS 回退可能仍可使用。若实际请求也失败，请检查代理、VPN、防火墙、DNS 或自定义 CA 证书设置。
Windows PowerShell 拦截脚本运行	当前 PowerShell 执行策略限制运行远程脚本。	使用 OpenAI README 给出的完整命令（已自带 `-ExecutionPolicy ByPass`）：`powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 \| iex"`。
需要查看详细的 TUI 运行日志	TUI 默认将诊断信息记录在本地有界存储中。	Codex 使用 Rust 编写，支持 `RUST_LOG` 环境变量。运行 `codex -c log_dir=./.codex-log` 并通过 `tail -F ./.codex-log/codex-tui.log` 查看明文日志（`codex exec` 默认使用 `RUST_LOG=error`，日志直接输出在终端中）。

2. 各安装方式对比与选择建议

OpenAI 提供了 4 种预编译分发渠道以及从源码编译。请尽量在同一台机器上只保留一种安装方式——同时用多种方式安装容易导致版本混乱，因为系统会按 PATH 顺序决定实际运行哪一个 codex。

安装方式	命令 / 来源	默认安装位置	优缺点与适用场景
1. 官方独立安装脚本	`curl -fsSL https://chatgpt.com/codex/install.sh \| sh`（macOS/Linux，2026-10-27 核验）或 `install.ps1`（Windows，2026-10-18 核验）	可执行文件软链位于 `${CODEX_INSTALL_DIR:-~/.local/bin}/codex`；发布包位于 `${CODEX_HOME:-~/.codex}/packages/standalone`；必要时更新 shell 配置文件 `PATH`	无需 Node.js 或 Homebrew。自动检测已有的 `npm`/`brew`/`bun` 安装并提示 `PATH` 冲突；若 `~/.local/bin` 不在 `PATH` 中，会自动写入对应 shell 配置文件并打印更新路径。
2. npm 全局安装	`npm install -g @openai/codex`	当前 Node/npm 的全局 `bin` 目录	适合前端/Node.js 开发者，便于锁定具体版本（如 `@openai/codex@0.163.0`）；需要本地已安装 Node.js（`engines.node >= 16`）。
3. Homebrew cask	`brew install --cask codex`	`$HOMEBREW_PREFIX/bin/codex`（如 Apple Silicon 上的 `/opt/homebrew/bin/codex`），并附带 bash/zsh/fish 自动补全	无需 Node.js，可随 `brew upgrade --cask codex` 统一升级。注意：必须带 `--cask`，Homebrew 中没有名为 `codex` 的普通 formula。
4. GitHub Release 二进制包	从 `github.com/openai/codex/releases/latest` 下载对应平台压缩包	解压后手动放入任意 `PATH` 目录（如 `~/.local/bin/codex`）	无需运行安装脚本或包管理器，适合离线或受控环境；解压后需手动将带平台后缀的文件重命名为 `codex`，且后续需手动更新。
5. 从源码编译	在 `codex-rs` 目录运行 `cargo build`（见 `docs/install.md`）	`codex-rs/target/debug/codex`	需要安装 Rust 工具链，仅在需要修改或调试 Codex 源码时使用。

Windows 特别说明：原生 PowerShell 安装脚本与 WSL2 的官方表述差异

截至 2026-10-18，OpenAI 在 openai/codex 同一仓库的两份官方文档中对 Windows 的表述存在差异：

仓库首页 README 提供了原生 Windows PowerShell 安装命令（powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"），同时 @openai/codex@0.163.0 的 npm 包也附带了 @openai/codex-win32-x64 与 @openai/codex-win32-arm64 平台二进制依赖。
与此同时，仓库内的 docs/install.md 系统要求表仍写明为 Windows 11 via WSL2（通过 WSL2 运行）。

如果你使用 Windows，可先尝试原生 PowerShell 或 npm 安装；若在原生终端遇到兼容性问题，建议切换到 WSL2（Ubuntu 20.04+ 或 Debian 10+）并按 Linux 方式安装。（关于 WinGet：部分第三方目录收录了 Codex 的 WinGet 条目，但 OpenAI 官方 README 与 docs/install.md 均未包含 WinGet 方式。）

3. 各操作系统安装细节与离线包说明

macOS（Apple Silicon `arm64` 与 Intel `x86_64`）

方式 A — 官方独立安装脚本（无需 Node.js 或 Homebrew）：

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

脚本默认优先从 https://releases.openai.com/codex 下载，不可用时自动回退到 GitHub Releases。如需直接强制从 GitHub Releases 下载，可设置 CODEX_INSTALLER_USE_RELEASES_OPENAI_COM=false：

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

方式 B — Homebrew cask 或 npm： 运行 brew install --cask codex 或 npm install -g @openai/codex。

Linux（`x86_64` 与 `arm64`）与 GitHub Release 二进制包

在 Linux 下运行 curl -fsSL https://chatgpt.com/codex/install.sh | sh 后，若 ~/.local/bin 此前不在 PATH 中，可按终端提示运行 export PATH="$HOME/.local/bin:$PATH" && codex 立即生效。

若需手动下载 GitHub Release .tar.gz 压缩包（前往 https://github.com/openai/codex/releases/latest）：

macOS Apple Silicon (arm64)： codex-aarch64-apple-darwin.tar.gz
macOS Intel (x86_64)： codex-x86_64-apple-darwin.tar.gz
Linux x86_64： codex-x86_64-unknown-linux-musl.tar.gz
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/codex

Windows（PowerShell 或 WSL2）

# 原生 PowerShell 安装（核验于 2026-10-18）
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

# 强制从 GitHub Releases 下载
$env:CODEX_INSTALLER_USE_RELEASES_OPENAI_COM='false'; irm https://chatgpt.com/codex/install.ps1 | iex

4. 运行 `codex doctor` 自检与手动 `config.toml` 配置参考

安装完成后，可通过以下命令确认实际生效路径并运行内置健康检查：

# 查看版本号与 PATH 中所有 codex 路径（macOS / Linux）
codex --version
which -a codex

# 诊断本地安装、配置、认证与运行时健康状态
codex doctor

在 Windows PowerShell 中，可用 Get-Command codex 与 where.exe codex 查看实际调用路径。

我们在 2026-10-18 的 Apple Silicon Mac（codex-cli 0.163.0）实测中，codex doctor 会重点检查三项：

安装一致性与 PATH 优先级： 输出 install consistent 并列出 PATH entries，若机器上同时装了 Homebrew 版与 npm 版会直接提示冲突。
认证状态： 未登录或未设置 API Key 时提示 auth ✗ no Codex credentials were found - Run codex login or provide an API key through a supported auth env var。
配置文件与网关连通性： 配置好 config.toml 与环境变量后，会确认 config.load ok、auth is provided by the active model provider 及 active provider endpoints are reachable over HTTP。

手动配置 `~/.codex/config.toml` 字段说明

如果不使用首屏的 uniroute-setup 一键脚本，也可以手动在 ~/.codex/config.toml（或 $CODEX_HOME/config.toml）中添加如下配置：

model = "MODEL_ID"
model_provider = "uniroute"

[model_providers.uniroute]
name = "UniRoute"
base_url = "https://api.uniroute.app/v1"
wire_api = "responses"
env_key = "UNIROUTE_API_KEY"
requires_openai_auth = false

wire_api = "responses"： Codex CLI 使用 OpenAI Responses API 协议（POST /v1/responses），而非 Chat Completions（详见 OpenAI Responses API 对比 Chat Completions 指南）。
env_key = "UNIROUTE_API_KEY"： 指定从哪个环境变量读取 API Key，避免将密钥明文写入配置文件。

5. 如何更新与卸载 Codex CLI

更新到最新版本

根据 Codex CLI 官方文档（2026-10-27），重新运行独立安装脚本 install.sh 即可更新已有安装；也可以使用内置 codex update 或包管理器升级：

# CLI 内置更新命令
codex update

# 官方独立脚本安装与更新命令
curl -fsSL https://chatgpt.com/codex/install.sh | sh

# npm 全局更新
npm install -g @openai/codex@latest

# Homebrew cask 更新
brew upgrade --cask codex

卸载 Codex CLI

# 卸载 npm 全局版本
npm uninstall -g @openai/codex

# 卸载 Homebrew cask 版本
brew uninstall --cask codex

# 卸载 install.sh 独立安装版本（默认路径）
rm -f "${CODEX_INSTALL_DIR:-$HOME/.local/bin}/codex" \
      "${CODEX_INSTALL_DIR:-$HOME/.local/bin}/codex-code-mode-host"
rm -rf "${CODEX_HOME:-$HOME/.codex}/packages/standalone"

注意保留 ~/.codex 配置目录： ~/.codex（或 $CODEX_HOME）下保存着 config.toml、登录凭据与本地会话记录。切换安装方式前请先备份 ~/.codex/config.toml 与 ~/.codex/auth.json；使用 Homebrew 卸载时请只运行普通的 brew uninstall --cask codex（不要加 --zap），以免清理配置目录。

6. 常见问题（FAQ）

安装 Codex CLI 必须先装 Node.js 吗？

只有在使用 npm install -g @openai/codex 安装时才需要 Node.js（@openai/codex@0.163.0 的 npm 元数据声明为 engines.node >= 16）。使用官方独立安装脚本（install.sh / install.ps1）、Homebrew cask（brew install --cask codex）或 GitHub Release 压缩包时安装的是预编译原生二进制文件，不需要 Node.js。

Codex CLI 是免费的吗？

Codex CLI 客户端本身是基于 Apache-2.0 许可证开源的免费软件；但实际运行编码任务时，需要登录符合条件的 ChatGPT 订阅账号（Plus、Pro、Business、Edu 或 Enterprise），或使用按量计费的 OpenAI / 兼容第三方 API 密钥。

没有管理员权限（`sudo`）可以安装 Codex CLI 吗？

可以。在 macOS 与 Linux 上，官方脚本 curl -fsSL https://chatgpt.com/codex/install.sh | sh 默认安装到用户主目录下（~/.local/bin/codex 与 ~/.codex/packages/standalone），也可通过 CODEX_INSTALL_DIR 和 CODEX_HOME 指定目录，无需 sudo。

`config.toml` 配置文件存放在哪里？

默认位于用户主目录下的 ~/.codex/config.toml；如果设置了 CODEX_HOME 环境变量，则位于 $CODEX_HOME/config.toml。

首次运行 Codex CLI 冒烟测试会消耗多少 Token？（2026-10-18 实测笔记）

在 2026-10-18 的实测中，我们在 Apple Silicon Mac（Node v22.23.3）上安装 @openai/codex@0.163.0 并通过 codex doctor 校验后，执行了一条只要求回复单个词的非交互式测试命令（codex exec --json --skip-git-repo-check --ephemeral -s read-only "Reply with exactly the word OK and nothing else."）。命令以退出码 0 正常返回 OK，但因 Codex CLI 在请求中附带了系统指令与工具定义，该次请求仍发送了 15,761 个输入 Token（含 4,224 缓存命中 Token）与 5 个输出 Token。即使是极简测试也并非零 Token，使用 API Key 测试时请在控制台核对实际用量记录。