> ## Documentation Index
> Fetch the complete documentation index at: https://aicoding.cscitech.top/llms.txt
> Use this file to discover all available pages before exploring further.

# 01-安装与登录

> 在 Windows、macOS、Linux 和 WSL 上安装 Codex CLI，完成 PATH、登录、代理、版本验证、升级、卸载与安全回滚。

## 本页目标

本页用于把 Codex CLI 从未安装状态带到“可以安全登录并完成一次最小验证”的状态。

你将学会以下内容：

* 判断自己应该使用 Windows 原生、macOS、Linux 还是 WSL。
* 在四个平台上安装 Codex CLI，并知道每条命令的运行位置。
* 检查安装目录和 PATH，处理“找不到命令”的分支。
* 使用 ChatGPT OAuth 登录，或在适合自动化的场景使用 API key。
* 在浏览器不可用、远程主机或代理环境下完成登录。
* 验证版本、帮助信息、登录状态和最小请求。
* 升级、卸载、清理登录凭据，并在失败时回滚到原状。
* 识别网络、权限、证书、沙箱和重复安装造成的常见错误。

Codex 的安装器、命令行参数、模型名称和登录选项会随版本变化。本文只把相对稳定的操作写成命令；凡是涉及具体版本、升级子命令、实验性认证或平台限制，都必须以本机的 `codex --help`、相关子命令的 `--help` 和 OpenAI 官方文档为准。

## 先确定使用方式

Codex CLI 是终端程序。它和桌面 App、IDE 扩展、网页入口不是同一个安装包。

如果你希望在项目目录中查看文件、提出任务、审批命令并检查 diff，CLI 是最直接的入口。

如果你只需要图形界面，请从官方 Codex 页面下载对应的桌面 App；不要把桌面 App 的安装说明当作 CLI 的安装说明。

本页重点是 CLI。桌面 App 是否支持你的系统、安装包架构和登录界面，以官方当前下载页为准。

### 平台选择

| 环境         | 推荐入口               | 适用情况                         |
| ---------- | ------------------ | ---------------------------- |
| Windows 原生 | PowerShell 中安装 CLI | 项目和工具链主要位于 Windows           |
| macOS      | Terminal 中安装 CLI   | Apple Silicon 或 Intel Mac    |
| Linux      | Shell 中安装 CLI      | 本机 Linux、服务器或 CI             |
| WSL2       | WSL shell 中安装 CLI  | 需要 Linux 工具链，仓库位于 Linux 文件系统 |

Windows 用户通常先尝试原生 PowerShell。

当项目依赖 Linux shell、Linux 包管理器或 Linux 文件权限时，再选择 WSL2。

WSL1 不应作为新安装目标。是否支持某个旧版本 Windows 或 WSL 发行版，必须查看当前官方说明和本机帮助信息。

## 安装前的安全检查

安装命令会从网络下载程序或脚本。请先确认你在可信网络中，并且命令来自官方文档或你所在组织批准的来源。

不要把安装脚本保存到生产目录后直接执行。

不要把 API key 写进命令历史、Git 仓库、`README`、截图或工单。

不要为了绕过权限错误长期使用管理员权限或 `sudo`。

先创建一个专用测试目录，避免一开始就在包含客户数据的项目中试用：

```bash theme={null}
mkdir -p ~/codex-install-check
cd ~/codex-install-check
```

Windows PowerShell 的等价命令是：

```powershell theme={null}
New-Item -ItemType Directory -Force "$HOME\codex-install-check" | Out-Null
Set-Location "$HOME\codex-install-check"
```

安装前记录系统信息，故障时便于判断是系统问题还是安装问题。

macOS 或 Linux：

```bash theme={null}
uname -a
printf 'shell=%s\n' "$SHELL"
printf 'home=%s\n' "$HOME"
```

PowerShell：

```powershell theme={null}
$PSVersionTable
Get-Location
$env:Path -split ';'
```

预期结果是能看到系统版本、当前 shell、用户主目录和 PATH 条目。

如果你不确定命令是在 CMD、PowerShell、Git Bash 还是 WSL 中执行，先运行：

```text theme={null}
Windows PowerShell: $PSVersionTable.PSEdition
Git Bash:           uname -s
Linux/WSL:          uname -a
```

PowerShell 通常输出 `Desktop` 或 `Core`。

Git Bash 或 WSL 通常输出以 `MINGW`、`Linux` 等开头的信息。

## 一、Windows 原生安装

### 1. 准备 PowerShell

打开“开始”菜单，搜索并启动 PowerShell。

不要在 CMD 中执行 `irm`、`Invoke-RestMethod` 或 `$env:...` 形式的命令。

查看 PowerShell 版本：

```powershell theme={null}
$PSVersionTable.PSVersion
```

预期会输出版本对象，例如：

```text theme={null}
Major  Minor  Patch
-----  -----  -----
7      ...    ...
```

版本号的具体要求以当前官方安装说明为准。

### 2. 使用官方 Windows 安装器

在 PowerShell 中运行官方安装命令：

```powershell theme={null}
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"
```

这条命令中的 `-ExecutionPolicy ByPass` 只对本次启动的 PowerShell 生效。

它不等于永久修改系统执行策略。

`irm` 是 `Invoke-RestMethod` 的缩写。

`iex` 是 `Invoke-Expression` 的缩写。

执行前请核对 URL 是否来自当前 OpenAI 官方文档。

如果公司安全策略禁止下载并直接执行脚本，停止执行，改用组织批准的安装包或让管理员审核脚本。

安装成功时，安装器通常会提示安装目录、PATH 变更或重新打开终端的要求。

这些提示可能随版本变化，务必保留完整输出。

### 3. 重新打开终端

安装器修改 PATH 后，已经打开的 PowerShell 不一定能看到新值。

关闭当前窗口，重新打开 PowerShell。

然后运行：

```powershell theme={null}
Get-Command codex -All
codex --version
```

预期输出包括一个指向 Codex 可执行文件的路径，以及一行版本信息：

```text theme={null}
CommandType     Name    Version    Source
-----------     ----    -------    ------
Application     codex              C:\Users\你的用户名\...\codex.exe
```

版本字符串可能是 `codex-cli ...` 或其他格式，不要依赖固定文字。

只要命令成功返回版本信息，即可进入登录步骤。

### 4. Windows PATH 故障分支

如果看到：

```text theme={null}
codex : The term 'codex' is not recognized as the name of a cmdlet...
```

先不要重复安装。

检查命令是否存在于常见用户目录：

```powershell theme={null}
Get-Command codex -All -ErrorAction SilentlyContinue
where.exe codex
```

如果两个命令都没有输出，回看安装器输出，确认安装是否中途失败。

如果找到了 `codex.exe` 但当前命令不可用，说明其目录未加入 PATH，或当前窗口尚未刷新环境变量。

临时测试 PATH 可以使用：

```powershell theme={null}
$env:Path = "$HOME\.local\bin;$env:Path"
codex --version
```

上面的目录只是示例，必须替换成安装器实际报告的目录。

长期修改用户 PATH，推荐使用 Windows 的“环境变量”界面，新增安装目录，不要覆盖已有 PATH。

修改后必须重新打开 PowerShell，并再次运行 `Get-Command codex`。

如果 `where.exe codex` 显示多个路径，先记录每个路径和版本：

```powershell theme={null}
where.exe codex
Get-Command codex -All | Format-List Source
```

重复安装会造成版本和卸载行为混乱，后文有清理步骤。

## 二、macOS 安装

### 1. 识别芯片架构

在 Terminal 中运行：

```bash theme={null}
uname -m
```

常见结果如下：

```text theme={null}
arm64
```

表示 Apple Silicon；

```text theme={null}
x86_64
```

表示 Intel。

如果使用桌面 App，下载包的架构必须与机器匹配；CLI 独立安装器是否自动选择架构，以官方安装器行为为准。

### 2. 使用官方安装器

在 Terminal 中运行官方 macOS/Linux 安装命令：

```bash theme={null}
curl -fsSL https://chatgpt.com/codex/install.sh | sh
```

运行前先确认当前 URL 来自官方文档。

`curl` 返回非零状态时，`-f` 会使 HTTP 错误直接失败，`-sS` 保留错误信息，便于定位。

安装结束后，记录安装器报告的文件路径和 PATH 提示。

如果需要无人值守安装，只有在你已确认本机帮助和官方文档仍支持该变量时才使用：

```bash theme={null}
CODEX_NON_INTERACTIVE=1 curl -fsSL https://chatgpt.com/codex/install.sh | sh
```

无人值守安装不等于无人审核。

CI 中应使用固定的网络出口、最小权限账号和密钥管理服务。

### 3. 检查 PATH

新开 Terminal 窗口后运行：

```bash theme={null}
command -v codex
codex --version
```

预期第一条命令输出一个绝对路径，第二条输出当前版本。

如果安装器把程序放到用户目录但没有加入 PATH，先确认文件是否存在：

```bash theme={null}
ls -l "$HOME/.local/bin/codex" 2>/dev/null
```

确认存在后，可在 zsh 中临时测试：

```bash theme={null}
export PATH="$HOME/.local/bin:$PATH"
codex --version
```

长期配置前，检查 `~/.zshrc` 是否已有 PATH 逻辑：

```bash theme={null}
test -f "$HOME/.zshrc" && grep -n 'local/bin' "$HOME/.zshrc"
```

确认没有重复或相互覆盖后再添加：

```bash theme={null}
printf '\nexport PATH="$HOME/.local/bin:$PATH"\n' >> "$HOME/.zshrc"
source "$HOME/.zshrc"
codex --version
```

如果你使用 Bash，把配置文件换成 `~/.bashrc`；macOS 默认通常是 zsh。

不要把安装目录写死成别人的用户名。

### 4. macOS 权限分支

如果出现 `permission denied`，先查看文件和目录权限：

```bash theme={null}
ls -ld "$HOME/.local" "$HOME/.local/bin" 2>/dev/null
ls -l "$HOME/.local/bin/codex" 2>/dev/null
```

优先修复用户目录的所有权和安装方式，不要直接使用 `sudo` 覆盖安装。

如果你通过 Homebrew 管理工具，也可以使用官方支持的 Homebrew 方案（若本机帮助或官方文档仍列出）：

```bash theme={null}
brew install --cask codex
```

检查来源和安装结果：

```bash theme={null}
brew info --cask codex
command -v codex
codex --version
```

Homebrew、官方安装器和 npm 不应无目的地混装。

## 三、Linux 安装

### 1. 确认发行版和 shell

运行：

```bash theme={null}
uname -m
cat /etc/os-release
printf 'shell=%s\n' "$SHELL"
```

重点记录 CPU 架构、发行版、发行版版本和当前 shell。

不要只依据“Linux 能运行”推断某个发行版的沙箱、证书或 libc 一定兼容。

### 2. 安装 CLI

优先使用官方 shell 安装器：

```bash theme={null}
curl -fsSL https://chatgpt.com/codex/install.sh | sh
```

如果服务器没有 `curl`，先使用发行版批准的包管理器安装 `curl`，例如 Debian/Ubuntu：

```bash theme={null}
sudo apt update
sudo apt install -y curl ca-certificates
```

执行 `sudo` 前核对主机、软件源和组织权限。

安装器完成后，打开新 shell：

```bash theme={null}
exec "$SHELL" -l
command -v codex
codex --version
```

预期能看到 Codex 路径和版本信息。

### 3. Linux PATH 分支

Bash 用户可以按安装器提示检查 `~/.bashrc` 或 `~/.profile`：

```bash theme={null}
printf '%s\n' "$PATH"
ls -l "$HOME/.local/bin/codex" 2>/dev/null
```

只为当前会话测试：

```bash theme={null}
export PATH="$HOME/.local/bin:$PATH"
codex --version
```

确认路径后再写入对应启动文件：

```bash theme={null}
printf '\nexport PATH="$HOME/.local/bin:$PATH"\n' >> "$HOME/.bashrc"
source "$HOME/.bashrc"
```

如果登录 shell 不读取 `.bashrc`，将同样的 PATH 设置放入发行版实际读取的文件，并重新登录。

### 4. Linux 依赖和沙箱分支

如果命令能启动但执行任务时报沙箱、权限或系统调用错误，先运行：

```bash theme={null}
codex --help
codex sandbox --help
```

只有当本机帮助列出该子命令时，才继续查看它的选项。

不要从旧教程复制已经删除的沙箱参数。

在容器、精简发行版或受限服务器中，缺少 `bubblewrap`、证书、伪终端或用户命名空间都可能导致任务失败。

先记录完整错误、发行版信息和 `codex --version`，再按官方支持矩阵补依赖。

## 四、WSL2 安装

### 1. 在管理员 PowerShell 启用 WSL2

以管理员身份打开 PowerShell，运行：

```powershell theme={null}
wsl --install
```

安装完成后按系统提示重启。

查看发行版和 WSL 状态：

```powershell theme={null}
wsl --status
wsl --list --verbose
```

预期发行版的 VERSION 列为 `2`。

若当前发行版为 WSL1，可在确认名称后转换：

```powershell theme={null}
wsl --set-version <发行版名称> 2
```

尖括号内容必须替换为实际名称，例如 `Ubuntu`。

转换可能耗时，并且会占用磁盘空间；开始前备份重要数据。

### 2. 将仓库放在 Linux 文件系统

进入 WSL：

```powershell theme={null}
wsl
```

在 WSL 中检查：

```bash theme={null}
uname -a
pwd
```

推荐将工作区放在 `~/code` 或其他 Linux 路径：

```bash theme={null}
mkdir -p ~/code/codex-test
cd ~/code/codex-test
```

不建议把高频读写仓库放在 `/mnt/c/...`。

Windows 挂载路径可能带来较慢的 I/O、权限差异和符号链接问题。

如果必须访问 Windows 文件，可在资源管理器打开 `\\wsl$`，但不要因此把所有构建目录都放回 `/mnt/c`。

### 3. 在 WSL shell 安装

不要在管理员 PowerShell 中执行 Linux 的 `curl | sh`。

进入 WSL 后运行：

```bash theme={null}
curl -fsSL https://chatgpt.com/codex/install.sh | sh
exec "$SHELL" -l
command -v codex
codex --version
```

这里的安装位置和 PATH 属于 WSL 用户环境，不等于 Windows 原生环境中的 Codex。

在 PowerShell 运行 `where.exe codex`，以及在 WSL 运行 `command -v codex`，可能得到两个不同结果，这是正常的双环境现象。

### 4. WSL 网络和代理分支

WSL 可能不能自动继承 Windows 代理。

先在 WSL 中测试 DNS 和 HTTPS：

```bash theme={null}
getent hosts chatgpt.com
curl -I --max-time 15 https://chatgpt.com
```

如果 Windows 能访问而 WSL 失败，检查 WSL 的 DNS、代理环境变量和公司网络策略。

不要把 Windows 代理的 `localhost` 端口直接假定为 WSL 的 `localhost`。

需要时查 Windows 主机地址，再按组织代理规范配置；完成后不要把代理账号密码写入 shell 历史。

## 五、PATH 的系统化排查

PATH 是系统寻找可执行文件的目录列表。

“已安装但找不到命令”通常是 PATH 没刷新、路径写错或存在多个安装。

macOS/Linux 使用：

```bash theme={null}
command -v codex
which -a codex
printf '%s\n' "$PATH"
```

Windows PowerShell 使用：

```powershell theme={null}
Get-Command codex -All
where.exe codex
$env:Path -split ';'
```

先确认当前 shell，再确认实际文件，再确认 PATH，最后才考虑重新安装。

成功标准是：命令解析到预期路径，且 `codex --version` 返回 0。

如果路径有空格，始终使用引号访问文件系统路径。

如果更改 PATH 后仍无效，关闭所有相关终端并重新打开；IDE 内置终端也可能需要重启 IDE。

## 六、登录方式和选择建议

Codex 常见的两类认证是 ChatGPT OAuth 和 API key。

| 方式            | 适合场景                       | 主要边界                           |
| ------------- | -------------------------- | ------------------------------ |
| ChatGPT OAuth | 人在终端前交互使用、需要 ChatGPT 工作区能力 | 需要浏览器、网络和有效 ChatGPT 权益         |
| API key       | CI/CD、脚本、无人值守任务            | 按 API 用量计费，部分 ChatGPT 工作区功能不可用 |

日常本地开发通常优先 OAuth。

自动化任务才考虑 API key，并使用密钥管理服务或 CI Secret。

不要把个人 API key 放进共享机器、公开仓库或未经审核的 MCP/插件配置。

具体套餐、额度和计费以官方 pricing 页面当前内容为准。

第三方模型提供商不是本页默认方案；它们还涉及 Responses API 或 Chat Completions 兼容性、配置文件和额外凭据风险，应单独核验官方文档。

## 七、使用 ChatGPT OAuth 登录

### 1. 从项目目录启动

先进入非生产测试目录：

```bash theme={null}
cd ~/codex-install-check
codex
```

Windows PowerShell：

```powershell theme={null}
Set-Location "$HOME\codex-install-check"
codex
```

首次启动通常会显示登录引导。

按界面选择 ChatGPT 登录，并在浏览器中完成授权。

不要把浏览器地址栏中的授权 URL、回调参数或令牌复制到聊天和工单。

### 2. 预期成功信号

成功后，CLI 通常回到会话界面并允许输入任务。

界面文案可能不同，不能把某一个固定提示当作唯一成功标准。

可用以下低风险动作检查会话：

```text theme={null}
/status
```

如果当前版本不支持 `/status`，运行 `codex --help` 或查看会话内帮助，以本机提示为准。

### 3. OAuth 失败分支

如果浏览器没有自动打开，复制 CLI 提供的官方地址到浏览器。

如果授权后终端没有回到会话，先检查回调端口是否被防火墙、VPN 或安全软件拦截。

如果你在 SSH、服务器或无桌面环境中，跳到“设备码和远程登录”一节。

如果提示账号没有 Codex 权益，检查当前登录账号、工作区和官方套餐说明，不要用未经授权的他人账号。

## 八、API key 登录

### 1. 创建和保护 key

只在 OpenAI Platform 官方页面创建 API key，并给它最小权限、合理预算和可追踪的使用范围。

创建后立即保存到密码管理器或 CI Secret。

不要在教程、脚本、配置文件中写真实 key。

以下命令中的 `<你的_API_KEY>` 只是占位符。

### 2. 临时设置环境变量

macOS/Linux/WSL：

```bash theme={null}
export OPENAI_API_KEY='<你的_API_KEY>'
```

PowerShell：

```powershell theme={null}
$env:OPENAI_API_KEY = '<你的_API_KEY>'
```

验证变量是否存在时只显示长度，不显示内容：

```bash theme={null}
[ -n "$OPENAI_API_KEY" ] && printf 'OPENAI_API_KEY is set\n'
```

PowerShell：

```powershell theme={null}
if ($env:OPENAI_API_KEY) { 'OPENAI_API_KEY is set' }
```

环境变量通常只对当前 shell 及其子进程有效。

### 3. 通过 CLI 登录

运行：

```bash theme={null}
codex login
```

然后按照本机提示选择 API key 登录方式。

登录子命令和选项可能变化，先查看：

```bash theme={null}
codex login --help
```

如果本机明确支持直接读取标准环境变量，CLI 会按当前版本规则使用它；不要自行假定某个旧教程中的参数仍存在。

登录后运行：

```bash theme={null}
codex --version
codex --help
```

再启动会话，使用一个不包含敏感数据的小任务验证请求链路。

### 4. API key 计费和撤销

API key 请求按 Platform 当前价格和用量规则计费，不等同于 ChatGPT 订阅额度。

建议设置预算、用量告警和项目级隔离。

发现 key 泄露时，立即在 Platform 后台撤销旧 key，创建新 key，并检查使用记录。

仅删除本地环境变量不能撤销已经泄露的远端凭据。

## 九、设备码、远程主机和无浏览器环境

### 1. 先检查本机支持情况

运行：

```bash theme={null}
codex login --help
```

只有当帮助输出明确列出设备码或类似选项时，才使用对应命令。

某些版本可能支持：

```bash theme={null}
codex login --device-auth
```

这是可能变化的认证入口，不要在帮助未列出时强行使用。

CLI 若显示一次性链接和验证码，应只在你信任的浏览器中打开官方域名。

验证码通常是短时、一次性凭据，不要公开分享。

### 2. SSH 端口转发

如果 OAuth 回调需要回到远程主机，可在本地建立转发；端口号必须以当前 CLI 输出为准。

示例形式如下：

```bash theme={null}
ssh -L <本地端口>:127.0.0.1:<远程端口> user@remote
```

不要盲目假定某个固定端口。

保持 SSH 会话运行，在同一个远程 shell 中执行 `codex login`，再用本地浏览器完成授权。

### 3. 不要随意搬运认证文件

如果必须迁移认证缓存，先确认官方文档允许这种方式，并使用加密传输和最小权限。

认证文件可能包含可复用令牌，不能发邮件、提交 Git 或放进共享目录。

迁移结束后，检查目标机器权限，并在不用时退出登录或删除缓存。

## 十、代理、证书和网络故障

### 1. 先区分安装失败和请求失败

安装脚本失败，通常是下载 URL、DNS、代理、证书或公司网关问题。

安装成功但登录失败，通常是 OAuth 回调、浏览器、账号权限或代理问题。

登录成功但任务请求失败，通常是 API 访问、超时、额度、模型或组织策略问题。

分别记录失败阶段，不要用“重装”覆盖线索。

### 2. 测试 HTTPS

macOS/Linux/WSL：

```bash theme={null}
curl -I --max-time 15 https://chatgpt.com
curl -I --max-time 15 https://platform.openai.com
```

PowerShell：

```powershell theme={null}
Test-NetConnection chatgpt.com -Port 443
Test-NetConnection platform.openai.com -Port 443
```

预期是能建立 HTTPS 或 TCP 连接；HTTP 状态码本身还要结合重定向和认证判断。

### 3. 临时代理环境变量

在组织代理明确要求 HTTP CONNECT 的情况下，macOS/Linux/WSL 可按代理文档设置：

```bash theme={null}
export HTTPS_PROXY='http://127.0.0.1:<端口>'
export HTTP_PROXY="$HTTPS_PROXY"
export NO_PROXY='127.0.0.1,localhost'
```

PowerShell：

```powershell theme={null}
$env:HTTPS_PROXY = 'http://127.0.0.1:<端口>'
$env:HTTP_PROXY = $env:HTTPS_PROXY
$env:NO_PROXY = '127.0.0.1,localhost'
```

不要把包含用户名和密码的代理 URL 写入历史记录。

不要把 `NO_PROXY` 配得过宽，以免把本应经过企业网关的请求绕开审计。

代理变量的支持范围可能因安装器、CLI 和子进程不同而不同。

以当前官方网络说明和实际错误输出为准。

### 4. 证书错误

如果看到 `certificate verify failed`、`unable to get local issuer certificate` 等信息，不要用关闭 TLS 校验的方式解决。

先检查系统时间、根证书、企业 HTTPS 检查策略和代理证书安装方式。

macOS/Linux 可确认 CA 包是否存在：

```bash theme={null}
command -v update-ca-certificates || command -v trust || true
```

企业环境应让 IT 提供正式的根证书安装方案。

## 十一、版本和帮助验证

安装完成后，至少运行以下命令：

```bash theme={null}
codex --version
codex --help
codex login --help
```

预期结果：

* `--version` 返回版本信息并以成功状态结束。
* `--help` 显示用法、选项或子命令。
* `login --help` 显示当前版本实际支持的登录入口。

不要把本文某个示例版本号当作验收标准。

可以把本机输出保存到不含密钥的诊断文件：

```bash theme={null}
codex --version > codex-version.txt
codex --help > codex-help.txt
```

保存前检查输出，确认没有令牌、邮箱或内部路径。

Windows PowerShell：

```powershell theme={null}
codex --version | Out-File -Encoding utf8 codex-version.txt
codex --help | Out-File -Encoding utf8 codex-help.txt
```

如果输出中包含个人信息，改为手工记录版本，不要上传文件。

## 十二、最小验收任务

安装和登录都完成后，在空测试目录执行：

```bash theme={null}
printf '# Codex smoke test\n' > README.codex-test.md
codex
```

在会话中输入一个低风险请求：

```text theme={null}
只读取当前目录，不修改任何文件。说明你看到的文件名，并明确表示没有执行写操作。
```

预期是 Codex 返回目录观察结果，不应修改文件。

退出方式以当前界面提示为准，常见方式包括 `Ctrl+C` 或 `/exit`。

退出后检查：

```bash theme={null}
git status --short
```

如果测试目录不是 Git 仓库，可以检查文件时间和内容：

```bash theme={null}
ls -la
```

如果 Codex 请求修改文件或运行命令，先拒绝审批，再缩小任务。

## 十三、升级

升级前先记录当前版本和安装来源：

```bash theme={null}
codex --version
command -v codex
```

Windows：

```powershell theme={null}
codex --version
Get-Command codex -All
```

官方独立安装器通常可以再次运行以获取更新，但是否支持该行为必须核对当前官方文档。

如果使用 Homebrew，先查看帮助和信息：

```bash theme={null}
brew info --cask codex
brew outdated --cask codex
```

只有确认存在更新后，才运行：

```bash theme={null}
brew upgrade --cask codex
```

如果使用 npm 作为安装来源，先查看当前包和版本：

```bash theme={null}
npm ls -g --depth=0 @openai/codex
npm view @openai/codex version
```

是否继续用 npm、以及包名是否变化，以官方文档为准。

升级完成后必须重新打开终端并复跑 `codex --version`、`codex --help` 和登录验证。

不要在升级失败时同时切换安装来源；先保留错误输出，避免出现多个二进制。

## 十四、卸载

卸载前确认你要删除的是哪个来源的 Codex：

```bash theme={null}
command -v codex
which -a codex
```

Windows：

```powershell theme={null}
Get-Command codex -All
where.exe codex
```

Homebrew 安装的卸载示例：

```bash theme={null}
brew uninstall --cask codex
```

npm 安装的卸载示例：

```bash theme={null}
npm uninstall -g @openai/codex
```

官方独立安装器的卸载方式以当前安装器或官方文档为准；不要猜目录后批量删除。

卸载后重新打开终端并运行：

```bash theme={null}
command -v codex
which -a codex
```

Windows 使用 `where.exe codex`。

如果仍能找到 Codex，说明还有其他安装来源或 PATH 中残留的旧副本。

不要把项目目录、Git 数据或 `~/.codex` 配置目录当作程序目录一起删除。

## 十五、退出登录和凭据清理

先查看当前版本支持的登录子命令：

```bash theme={null}
codex login --help
```

如果帮助中列出登出命令，按该命令执行；常见形式可能是：

```bash theme={null}
codex logout
```

具体命令以本机帮助为准。

退出登录后，检查是否仍能启动新会话并发起请求。

如果需要手工清理缓存，先阅读官方认证说明，确认当前凭据存储位置和格式。

不要在不了解影响的情况下删除整个用户配置目录，因为其中可能还有模型、代理或项目设置。

删除前可以先改名备份：

```bash theme={null}
mv "$HOME/.codex" "$HOME/.codex.backup-$(date +%Y%m%d%H%M%S)"
```

Windows PowerShell 示例：

```powershell theme={null}
Rename-Item "$HOME\.codex" ".codex.backup-$(Get-Date -Format yyyyMMddHHmmss)"
```

备份目录仍包含敏感凭据，必须限制权限并在确认不需要后安全删除。

如果 key 曾经暴露，必须在提供商后台撤销，而不是只删除本地文件。

## 十六、常见错误与故障分支

| 现象                         | 先判断                 | 处理                                    |
| -------------------------- | ------------------- | ------------------------------------- |
| `command not found: codex` | PATH 或安装失败          | 查 `command -v`、安装器输出并重开终端             |
| `codex is not recognized`  | PowerShell PATH 未刷新 | 查 `Get-Command`、重开 PowerShell         |
| `irm is not recognized`    | 在 CMD 或错误 shell 执行  | 切换 PowerShell                         |
| 下载超时                       | DNS、代理或网络出口         | 用 `curl -I`/`Test-NetConnection` 分段测试 |
| 证书校验失败                     | CA 或企业代理            | 修复信任链，不关闭 TLS 校验                      |
| OAuth 回调失败                 | 浏览器、端口或防火墙          | 改用设备码或按当前端口做 SSH 转发                   |
| API key 无效                 | 变量、key、组织或额度        | 重设环境变量，后台检查并撤销泄露 key                  |
| 401                        | 认证未被接受              | 检查登录方式和凭据来源                           |
| 403                        | 权限、工作区或策略           | 检查账号、组织政策和套餐权限                        |
| 429                        | 限流或额度不足             | 降低并发、等待窗口恢复或检查账单                      |
| 模型不存在                      | 模型名过期或无权使用          | 用当前官方模型列表和本机帮助核验                      |
| 沙箱启动失败                     | 系统依赖或策略限制           | 查看 `sandbox --help` 和官方平台要求           |
| 卸载后仍可运行                    | 多个安装来源              | `which -a`/`where.exe` 找出剩余副本         |

### `command not found` 的完整处理

先确认 shell 和 PATH：

```bash theme={null}
printf 'shell=%s\n' "$SHELL"
printf '%s\n' "$PATH"
command -v codex
```

再确认安装器报告的目标文件是否存在。

如果文件存在，临时加入正确目录并验证。

如果临时验证成功，再把路径写入正确的 shell 启动文件。

如果文件不存在，检查安装器是否因代理、权限或架构失败，然后重新运行经过核验的官方安装步骤。

### 登录后马上失败

先执行：

```bash theme={null}
codex login --help
```

确认使用的是当前版本支持的认证流程。

再检查网络：

```bash theme={null}
curl -I --max-time 15 https://chatgpt.com
```

最后确认账号和工作区，而不是反复清理配置。

### 400 协议或请求格式错误

如果你配置了第三方提供商，400 可能是接口协议不兼容，而不一定是 API key 错误。

检查第三方官方文档是否明确支持当前 Codex 所需的 API。

用 `codex --help` 和官方配置文档确认当前配置字段。

先恢复官方 OpenAI 提供商验证 CLI 本身，再判断是否继续第三方配置。

## 十七、安全边界

只在你拥有权限的目录和账号下运行 Codex。

第一次任务使用空目录或脱敏副本。

涉及删除、迁移、数据库、部署、网络外发和生产凭据时，必须人工审批每一步。

不要批准你看不懂的命令，尤其是递归删除、修改权限、下载并执行未知脚本的命令。

不要让 API key 通过命令行参数、日志、环境回显或截图泄露。

把 `~/.codex`、Windows 用户配置目录、SSH 配置和 CI Secret 当作敏感区域。

OAuth token、API key、设备码和回调 URL 都不应公开。

第三方代理、插件和 MCP server 可能读取请求上下文或凭据；启用前检查来源、权限和数据流向。

网络可达不代表目标可信；域名、证书、下载哈希和组织代理策略都应核对。

## 十八、回滚方式

### 未登录、未修改系统配置

删除测试目录即可；先确认目录内没有需要保留的文件：

```bash theme={null}
find ~/codex-install-check -maxdepth 2 -type f -print
```

Windows：

```powershell theme={null}
Get-ChildItem "$HOME\codex-install-check" -Force
```

确认后再按组织规则删除。

### PATH 改动

先备份当前 shell 配置：

```bash theme={null}
cp ~/.zshrc ~/.zshrc.codex-backup
```

撤销时只删除你新增的那一行，保留其他用户配置。

Windows 用户 PATH 应在环境变量界面中删除对应的 Codex 安装目录，不要清空整个 PATH。

### 升级失败

不要立即卸载所有版本。

保留当前版本、安装日志和 `command -v codex` 输出。

如果安装器支持回退版本，按官方文档执行；否则恢复你在升级前保存的安装包或使用新的、经过验证的安装来源。

回滚后重新运行：

```bash theme={null}
codex --version
codex --help
```

### 登录和凭据回滚

先执行当前版本支持的 logout 命令。

如果 key 泄露，撤销远端 key 并创建替代 key。

如果 OAuth 缓存损坏，用此前改名的 `.codex.backup-*` 恢复前先确认其中没有过期或泄露的凭据。

### Git 和项目文件回滚

本页的安装测试不应修改项目代码。

进入真实项目前，先检查：

```bash theme={null}
git status --short
git diff --stat
git diff --check
```

如果 Codex 修改了文件，先保存需要保留的补丁，再按项目约定用 Git 恢复。

不要在未确认同事改动的情况下执行 `git restore`、删除目录或重置分支。

## 十九、最终验收清单

逐项确认以下结果：

* [ ] 已确认使用的是 Windows 原生、macOS、Linux 或 WSL2。
* [ ] 已阅读当前安装器和认证选项的官方说明。
* [ ] `codex --version` 能返回当前版本。
* [ ] `codex --help` 能显示本机实际支持的选项。
* [ ] `codex login --help` 已核对登录入口。
* [ ] 已确认 `command -v codex` 或 `Get-Command codex` 指向预期安装。
* [ ] 没有无意中安装多个 Codex 副本。
* [ ] OAuth 登录完成，或 API key 已通过安全变量注入。
* [ ] 没有把 key、token、设备码或代理密码写入文件和日志。
* [ ] 已用 `curl` 或 `Test-NetConnection` 验证必要网络。
* [ ] 已在空目录完成一次只读 smoke test。
* [ ] 已检查 `git status --short`，确认没有无关变更。
* [ ] 已记录当前版本、安装来源和后续升级方式。
* [ ] 已知道如何退出登录、撤销 key 和恢复 PATH。
* [ ] 已知道遇到协议、额度或沙箱问题应保留错误输出。
* [ ] 未执行提交、推送、生产部署或未经确认的删除。

完成清单后，再阅读相邻页面中的项目准备、首次任务以及 diff、测试与回滚流程。

## 动态信息核验

本文不固定写死 Codex CLI 的版本号、模型名、套餐额度或升级子命令。

每次安装、升级或排错前，请依次运行：

```bash theme={null}
codex --version
codex --help
codex login --help
```

Windows PowerShell 使用相同的 `codex` 命令即可。

如需核对产品、认证、计费或第三方模型能力，请查阅 OpenAI 官方文档的当前页面。

当本页示例与本机帮助或官方文档冲突时，以本机帮助和官方文档为准，并记录冲突内容后再操作。

参考文件名：`03-install.md`、`04-pricing.md`、`05-third-party-models.md`。