Skip to main content

​
本页目标

本页用于把 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。 当项目依赖 Linux shell、Linux 包管理器或 Linux 文件权限时，再选择 WSL2。 WSL1 不应作为新安装目标。是否支持某个旧版本 Windows 或 WSL 发行版，必须查看当前官方说明和本机帮助信息。

​
安装前的安全检查

安装命令会从网络下载程序或脚本。请先确认你在可信网络中，并且命令来自官方文档或你所在组织批准的来源。 不要把安装脚本保存到生产目录后直接执行。 不要把 API key 写进命令历史、Git 仓库、README、截图或工单。 不要为了绕过权限错误长期使用管理员权限或 sudo。 先创建一个专用测试目录，避免一开始就在包含客户数据的项目中试用：
Windows PowerShell 的等价命令是：
安装前记录系统信息，故障时便于判断是系统问题还是安装问题。 macOS 或 Linux：
PowerShell：
预期结果是能看到系统版本、当前 shell、用户主目录和 PATH 条目。 如果你不确定命令是在 CMD、PowerShell、Git Bash 还是 WSL 中执行，先运行：
PowerShell 通常输出 Desktop 或 Core。 Git Bash 或 WSL 通常输出以 MINGW、Linux 等开头的信息。

​
一、Windows 原生安装

​
1. 准备 PowerShell

打开“开始”菜单，搜索并启动 PowerShell。 不要在 CMD 中执行 irm、Invoke-RestMethod 或 $env:... 形式的命令。 查看 PowerShell 版本：
预期会输出版本对象，例如：
版本号的具体要求以当前官方安装说明为准。

​
2. 使用官方 Windows 安装器

在 PowerShell 中运行官方安装命令：
这条命令中的 -ExecutionPolicy ByPass 只对本次启动的 PowerShell 生效。 它不等于永久修改系统执行策略。 irm 是 Invoke-RestMethod 的缩写。 iex 是 Invoke-Expression 的缩写。 执行前请核对 URL 是否来自当前 OpenAI 官方文档。 如果公司安全策略禁止下载并直接执行脚本，停止执行，改用组织批准的安装包或让管理员审核脚本。 安装成功时，安装器通常会提示安装目录、PATH 变更或重新打开终端的要求。 这些提示可能随版本变化，务必保留完整输出。

​
3. 重新打开终端

安装器修改 PATH 后，已经打开的 PowerShell 不一定能看到新值。 关闭当前窗口，重新打开 PowerShell。 然后运行：
预期输出包括一个指向 Codex 可执行文件的路径，以及一行版本信息：
版本字符串可能是 codex-cli ... 或其他格式，不要依赖固定文字。 只要命令成功返回版本信息，即可进入登录步骤。

​
4. Windows PATH 故障分支

如果看到：
先不要重复安装。 检查命令是否存在于常见用户目录：
如果两个命令都没有输出，回看安装器输出，确认安装是否中途失败。 如果找到了 codex.exe 但当前命令不可用，说明其目录未加入 PATH，或当前窗口尚未刷新环境变量。 临时测试 PATH 可以使用：
上面的目录只是示例，必须替换成安装器实际报告的目录。 长期修改用户 PATH，推荐使用 Windows 的“环境变量”界面，新增安装目录，不要覆盖已有 PATH。 修改后必须重新打开 PowerShell，并再次运行 Get-Command codex。 如果 where.exe codex 显示多个路径，先记录每个路径和版本：
重复安装会造成版本和卸载行为混乱，后文有清理步骤。

​
二、macOS 安装

​
1. 识别芯片架构

在 Terminal 中运行：
常见结果如下：
表示 Apple Silicon；
表示 Intel。 如果使用桌面 App，下载包的架构必须与机器匹配；CLI 独立安装器是否自动选择架构，以官方安装器行为为准。

​
2. 使用官方安装器

在 Terminal 中运行官方 macOS/Linux 安装命令：
运行前先确认当前 URL 来自官方文档。 curl 返回非零状态时，-f 会使 HTTP 错误直接失败，-sS 保留错误信息，便于定位。 安装结束后，记录安装器报告的文件路径和 PATH 提示。 如果需要无人值守安装，只有在你已确认本机帮助和官方文档仍支持该变量时才使用：
无人值守安装不等于无人审核。 CI 中应使用固定的网络出口、最小权限账号和密钥管理服务。

​
3. 检查 PATH

新开 Terminal 窗口后运行：
预期第一条命令输出一个绝对路径，第二条输出当前版本。 如果安装器把程序放到用户目录但没有加入 PATH，先确认文件是否存在：
确认存在后，可在 zsh 中临时测试：
长期配置前，检查 ~/.zshrc 是否已有 PATH 逻辑：
确认没有重复或相互覆盖后再添加：
如果你使用 Bash，把配置文件换成 ~/.bashrc；macOS 默认通常是 zsh。 不要把安装目录写死成别人的用户名。

​
4. macOS 权限分支

如果出现 permission denied，先查看文件和目录权限：
优先修复用户目录的所有权和安装方式，不要直接使用 sudo 覆盖安装。 如果你通过 Homebrew 管理工具，也可以使用官方支持的 Homebrew 方案（若本机帮助或官方文档仍列出）：
检查来源和安装结果：
Homebrew、官方安装器和 npm 不应无目的地混装。

​
三、Linux 安装

​
1. 确认发行版和 shell

运行：
重点记录 CPU 架构、发行版、发行版版本和当前 shell。 不要只依据“Linux 能运行”推断某个发行版的沙箱、证书或 libc 一定兼容。

​
2. 安装 CLI

优先使用官方 shell 安装器：
如果服务器没有 curl，先使用发行版批准的包管理器安装 curl，例如 Debian/Ubuntu：
执行 sudo 前核对主机、软件源和组织权限。 安装器完成后，打开新 shell：
预期能看到 Codex 路径和版本信息。

​
3. Linux PATH 分支

Bash 用户可以按安装器提示检查 ~/.bashrc 或 ~/.profile：
只为当前会话测试：
确认路径后再写入对应启动文件：
如果登录 shell 不读取 .bashrc，将同样的 PATH 设置放入发行版实际读取的文件，并重新登录。

​
4. Linux 依赖和沙箱分支

如果命令能启动但执行任务时报沙箱、权限或系统调用错误，先运行：
只有当本机帮助列出该子命令时，才继续查看它的选项。 不要从旧教程复制已经删除的沙箱参数。 在容器、精简发行版或受限服务器中，缺少 bubblewrap、证书、伪终端或用户命名空间都可能导致任务失败。 先记录完整错误、发行版信息和 codex --version，再按官方支持矩阵补依赖。

​
四、WSL2 安装

​
1. 在管理员 PowerShell 启用 WSL2

以管理员身份打开 PowerShell，运行：
安装完成后按系统提示重启。 查看发行版和 WSL 状态：
预期发行版的 VERSION 列为 2。 若当前发行版为 WSL1，可在确认名称后转换：
尖括号内容必须替换为实际名称，例如 Ubuntu。 转换可能耗时，并且会占用磁盘空间；开始前备份重要数据。

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

进入 WSL：
在 WSL 中检查：
推荐将工作区放在 ~/code 或其他 Linux 路径：
不建议把高频读写仓库放在 /mnt/c/...。 Windows 挂载路径可能带来较慢的 I/O、权限差异和符号链接问题。 如果必须访问 Windows 文件，可在资源管理器打开 \\wsl$，但不要因此把所有构建目录都放回 /mnt/c。

​
3. 在 WSL shell 安装

不要在管理员 PowerShell 中执行 Linux 的 curl | sh。 进入 WSL 后运行：
这里的安装位置和 PATH 属于 WSL 用户环境，不等于 Windows 原生环境中的 Codex。 在 PowerShell 运行 where.exe codex，以及在 WSL 运行 command -v codex，可能得到两个不同结果，这是正常的双环境现象。

​
4. WSL 网络和代理分支

WSL 可能不能自动继承 Windows 代理。 先在 WSL 中测试 DNS 和 HTTPS：
如果 Windows 能访问而 WSL 失败，检查 WSL 的 DNS、代理环境变量和公司网络策略。 不要把 Windows 代理的 localhost 端口直接假定为 WSL 的 localhost。 需要时查 Windows 主机地址，再按组织代理规范配置；完成后不要把代理账号密码写入 shell 历史。

​
五、PATH 的系统化排查

PATH 是系统寻找可执行文件的目录列表。 “已安装但找不到命令”通常是 PATH 没刷新、路径写错或存在多个安装。 macOS/Linux 使用：
Windows PowerShell 使用：
先确认当前 shell，再确认实际文件，再确认 PATH，最后才考虑重新安装。 成功标准是：命令解析到预期路径，且 codex --version 返回 0。 如果路径有空格，始终使用引号访问文件系统路径。 如果更改 PATH 后仍无效，关闭所有相关终端并重新打开；IDE 内置终端也可能需要重启 IDE。

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

Codex 常见的两类认证是 ChatGPT OAuth 和 API key。 日常本地开发通常优先 OAuth。 自动化任务才考虑 API key，并使用密钥管理服务或 CI Secret。 不要把个人 API key 放进共享机器、公开仓库或未经审核的 MCP/插件配置。 具体套餐、额度和计费以官方 pricing 页面当前内容为准。 第三方模型提供商不是本页默认方案；它们还涉及 Responses API 或 Chat Completions 兼容性、配置文件和额外凭据风险，应单独核验官方文档。

​
七、使用 ChatGPT OAuth 登录

​
1. 从项目目录启动

先进入非生产测试目录：
Windows PowerShell：
首次启动通常会显示登录引导。 按界面选择 ChatGPT 登录，并在浏览器中完成授权。 不要把浏览器地址栏中的授权 URL、回调参数或令牌复制到聊天和工单。

​
2. 预期成功信号

成功后，CLI 通常回到会话界面并允许输入任务。 界面文案可能不同，不能把某一个固定提示当作唯一成功标准。 可用以下低风险动作检查会话：
如果当前版本不支持 /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：
PowerShell：
验证变量是否存在时只显示长度，不显示内容：
PowerShell：
环境变量通常只对当前 shell 及其子进程有效。

​
3. 通过 CLI 登录

运行：
然后按照本机提示选择 API key 登录方式。 登录子命令和选项可能变化，先查看：
如果本机明确支持直接读取标准环境变量，CLI 会按当前版本规则使用它；不要自行假定某个旧教程中的参数仍存在。 登录后运行：
再启动会话，使用一个不包含敏感数据的小任务验证请求链路。

​
4. API key 计费和撤销

API key 请求按 Platform 当前价格和用量规则计费，不等同于 ChatGPT 订阅额度。 建议设置预算、用量告警和项目级隔离。 发现 key 泄露时，立即在 Platform 后台撤销旧 key，创建新 key，并检查使用记录。 仅删除本地环境变量不能撤销已经泄露的远端凭据。

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

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

运行：
只有当帮助输出明确列出设备码或类似选项时，才使用对应命令。 某些版本可能支持：
这是可能变化的认证入口，不要在帮助未列出时强行使用。 CLI 若显示一次性链接和验证码，应只在你信任的浏览器中打开官方域名。 验证码通常是短时、一次性凭据，不要公开分享。

​
2. SSH 端口转发

如果 OAuth 回调需要回到远程主机，可在本地建立转发；端口号必须以当前 CLI 输出为准。 示例形式如下：
不要盲目假定某个固定端口。 保持 SSH 会话运行，在同一个远程 shell 中执行 codex login，再用本地浏览器完成授权。

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

如果必须迁移认证缓存，先确认官方文档允许这种方式，并使用加密传输和最小权限。 认证文件可能包含可复用令牌，不能发邮件、提交 Git 或放进共享目录。 迁移结束后，检查目标机器权限，并在不用时退出登录或删除缓存。

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

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

安装脚本失败，通常是下载 URL、DNS、代理、证书或公司网关问题。 安装成功但登录失败，通常是 OAuth 回调、浏览器、账号权限或代理问题。 登录成功但任务请求失败，通常是 API 访问、超时、额度、模型或组织策略问题。 分别记录失败阶段，不要用“重装”覆盖线索。

​
2. 测试 HTTPS

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

​
3. 临时代理环境变量

在组织代理明确要求 HTTP CONNECT 的情况下，macOS/Linux/WSL 可按代理文档设置：
PowerShell：
不要把包含用户名和密码的代理 URL 写入历史记录。 不要把 NO_PROXY 配得过宽，以免把本应经过企业网关的请求绕开审计。 代理变量的支持范围可能因安装器、CLI 和子进程不同而不同。 以当前官方网络说明和实际错误输出为准。

​
4. 证书错误

如果看到 certificate verify failed、unable to get local issuer certificate 等信息，不要用关闭 TLS 校验的方式解决。 先检查系统时间、根证书、企业 HTTPS 检查策略和代理证书安装方式。 macOS/Linux 可确认 CA 包是否存在：
企业环境应让 IT 提供正式的根证书安装方案。

​
十一、版本和帮助验证

安装完成后，至少运行以下命令：
预期结果：
  • --version 返回版本信息并以成功状态结束。
  • --help 显示用法、选项或子命令。
  • login --help 显示当前版本实际支持的登录入口。
不要把本文某个示例版本号当作验收标准。 可以把本机输出保存到不含密钥的诊断文件：
保存前检查输出，确认没有令牌、邮箱或内部路径。 Windows PowerShell：
如果输出中包含个人信息，改为手工记录版本，不要上传文件。

​
十二、最小验收任务

安装和登录都完成后，在空测试目录执行：
在会话中输入一个低风险请求：
预期是 Codex 返回目录观察结果，不应修改文件。 退出方式以当前界面提示为准，常见方式包括 Ctrl+C 或 /exit。 退出后检查：
如果测试目录不是 Git 仓库，可以检查文件时间和内容：
如果 Codex 请求修改文件或运行命令，先拒绝审批，再缩小任务。

​
十三、升级

升级前先记录当前版本和安装来源：
Windows：
官方独立安装器通常可以再次运行以获取更新，但是否支持该行为必须核对当前官方文档。 如果使用 Homebrew，先查看帮助和信息：
只有确认存在更新后，才运行：
如果使用 npm 作为安装来源，先查看当前包和版本：
是否继续用 npm、以及包名是否变化，以官方文档为准。 升级完成后必须重新打开终端并复跑 codex --version、codex --help 和登录验证。 不要在升级失败时同时切换安装来源；先保留错误输出，避免出现多个二进制。

​
十四、卸载

卸载前确认你要删除的是哪个来源的 Codex：
Windows：
Homebrew 安装的卸载示例：
npm 安装的卸载示例：
官方独立安装器的卸载方式以当前安装器或官方文档为准；不要猜目录后批量删除。 卸载后重新打开终端并运行：
Windows 使用 where.exe codex。 如果仍能找到 Codex，说明还有其他安装来源或 PATH 中残留的旧副本。 不要把项目目录、Git 数据或 ~/.codex 配置目录当作程序目录一起删除。

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

先查看当前版本支持的登录子命令：
如果帮助中列出登出命令，按该命令执行；常见形式可能是：
具体命令以本机帮助为准。 退出登录后，检查是否仍能启动新会话并发起请求。 如果需要手工清理缓存，先阅读官方认证说明，确认当前凭据存储位置和格式。 不要在不了解影响的情况下删除整个用户配置目录，因为其中可能还有模型、代理或项目设置。 删除前可以先改名备份：
Windows PowerShell 示例：
备份目录仍包含敏感凭据，必须限制权限并在确认不需要后安全删除。 如果 key 曾经暴露，必须在提供商后台撤销，而不是只删除本地文件。

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

​
command not found 的完整处理

先确认 shell 和 PATH：
再确认安装器报告的目标文件是否存在。 如果文件存在，临时加入正确目录并验证。 如果临时验证成功，再把路径写入正确的 shell 启动文件。 如果文件不存在，检查安装器是否因代理、权限或架构失败，然后重新运行经过核验的官方安装步骤。

​
登录后马上失败

先执行：
确认使用的是当前版本支持的认证流程。 再检查网络：
最后确认账号和工作区，而不是反复清理配置。

​
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 可能读取请求上下文或凭据；启用前检查来源、权限和数据流向。 网络可达不代表目标可信；域名、证书、下载哈希和组织代理策略都应核对。

​
十八、回滚方式

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

删除测试目录即可；先确认目录内没有需要保留的文件：
Windows：
确认后再按组织规则删除。

​
PATH 改动

先备份当前 shell 配置：
撤销时只删除你新增的那一行，保留其他用户配置。 Windows 用户 PATH 应在环境变量界面中删除对应的 Codex 安装目录，不要清空整个 PATH。

​
升级失败

不要立即卸载所有版本。 保留当前版本、安装日志和 command -v codex 输出。 如果安装器支持回退版本，按官方文档执行；否则恢复你在升级前保存的安装包或使用新的、经过验证的安装来源。 回滚后重新运行：

​
登录和凭据回滚

先执行当前版本支持的 logout 命令。 如果 key 泄露，撤销远端 key 并创建替代 key。 如果 OAuth 缓存损坏，用此前改名的 .codex.backup-* 恢复前先确认其中没有过期或泄露的凭据。

​
Git 和项目文件回滚

本页的安装测试不应修改项目代码。 进入真实项目前，先检查：
如果 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 的版本号、模型名、套餐额度或升级子命令。 每次安装、升级或排错前，请依次运行：
Windows PowerShell 使用相同的 codex 命令即可。 如需核对产品、认证、计费或第三方模型能力，请查阅 OpenAI 官方文档的当前页面。 当本页示例与本机帮助或官方文档冲突时，以本机帮助和官方文档为准，并记录冲突内容后再操作。 参考文件名：03-install.md、04-pricing.md、05-third-party-models.md。