Codex CLI 四种安装方式怎么选，装完第一件事是跑 doctor

2026-08-09

第一次装 Codex（OpenAI Codex）的命令行版本时，最容易犯的错误不是命令敲错，而是随手挑了一种安装方式装上，之后再也说不清「我现在跑的这个 codex 到底是从哪来的」。等到需要升级、需要换渠道、或者机器上莫名其妙有两份的时候，就得从头刨 PATH。

这篇按新手的顺序走一遍：先看官方给的四种安装方式分别是什么、你该选哪一种，再讲装完为什么第一条命令应该是 codex doctor 而不是急着开对话，最后是登录。每一步都会说明「为什么这么做」和「跳过了会怎样」。

一、官方给的四种安装方式，原样抄

先把命令摆出来。这四条都来自官方文档，不要改写、不要自己拼，尤其是脚本地址。

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"

npm 全局安装（跨平台）：

npm install -g @openai/codex

Homebrew（macOS 侧的包管理器）：

brew install --cask codex

升级走：

brew upgrade --cask codex

四条命令的形式差别很直接：前两条是把远程脚本下载下来直接交给 shell 执行，后两条是走包管理器。这是官方给出的方式，用不用由你自己判断——如果你所在的团队对「管道执行远程脚本」有明确规定，那规定优先。

二、怎么选：从你手上有什么倒推

不要按「哪个更好」来选，按「你机器上已经有什么、你打算怎么升级」来选。

如果你是 Windows 用户，机器上没装 Node.js。 走 PowerShell 那条独立安装脚本。这是给 Windows 的官方渠道，不需要你先为了装一个 CLI 而把 Node 生态铺一遍。注意命令里的 -ExecutionPolicy ByPass 是官方这条命令自带的一部分，原样抄就行，不是让你去改系统的执行策略设置。

如果你已经在用 Node.js，日常就 npm install -g 装各种 CLI。 走 npm。好处是升级、卸载都在你已经熟悉的那套体系里。本站这台机器在 codex-cli 0.147.0（Windows 11）上走的就是 npm 全局安装。

如果你是 macOS 用户并且已经在用 Homebrew 管软件。 走 brew install --cask codex。理由同上——把升级职责交给你本来就会定期跑的那个包管理器，比多记一条升级命令靠谱。

如果你是 macOS / Linux 用户但不想引入包管理器。 走 install.sh 那条脚本。

做错了会怎样？ 最常见的翻车是「两种方式各装了一遍」。比如先跑了脚本，过两天又图省事 npm install -g @openai/codex，机器上就可能同时存在两份可执行文件，PATH 里谁在前面谁生效。表现出来是：你明明升级了，codex --version 却纹丝不动；或者你在 A 终端里是新版本，B 终端里是旧版本。这类问题排查起来很浪费时间，而避免它的办法就是下一节的那条命令。

三、装完先跑 doctor，别急着开对话

装完之后你的第一反应可能是马上试试它能干什么。建议先跑这两条：

codex --version
codex doctor --summary

codex doctor 的官方说明是 “Diagnose local Codex installation, config, auth, and runtime health”——它就是专门用来体检安装、配置、认证与运行时的。

在 codex-cli 0.147.0（Windows 11）上，codex doctor 的抬头是 Codex Doctor v<版本> · <平台三元组> 这种形式，本机显示的平台是 windows-x86_64。下面按组列检查项，本机观测到的分组是：

分组	本机观测到的检查项
Notes	`rollouts`
Environment	`system` / `runtime` / `install` / `search` / `git` / `terminal` / `title` / `state` / `threads`
Configuration	`config` / `auth` / `mcp` / `sandbox`
Updates	`updates`
Connectivity	`network` / `websocket` / `reachability`
Background Server	`app-server`

状态符号本机观测到四种：✓（ok）、○（idle）、⚠（notes/warn）、✗（fail）。结尾会打一行统计，形如 17 ok · 1 idle · 1 notes · 0 warn · 0 fail ok，并提示可以用 --all 展开被截断的列表。

对刚装完的人来说，这一整屏里最该盯的是 Environment 组里的 runtime 和 install 两行。

runtime 行会告诉你当前这个 codex 是从哪种渠道装的、可执行文件落在哪。在 codex-cli 0.147.0（Windows 11）上，本机这行显示的是 npm (package …@openai/codex/node_modules/@openai/codex-win32-x64/vendor/… ) 这种形式——一眼就能确认「我用的是 npm 那份」。install 行本机显示 consistent，即安装状态一致。

这就把上一节说的那个坑直接解掉了：「我装了好几遍，现在到底在用哪个」这个问题，看 doctor 的 runtime 行比翻 PATH 快得多。 如果 install 行给出的不是 consistent，说明安装状态本身有问题，那就先解决它，别急着往下折腾配置。

顺带说个新手很容易被绕进去的现象：在这台机器上采集数据时，一开始 codex --version 输出的是 codex-cli 0.131.0，十几分钟后再执行同一条命令变成了 codex-cli 0.147.0，而整个过程中 which -a codex 只有一个可执行文件。Codex 是有自更新能力的（features 列表里有 in_app_updates，配置里有 check_for_update_on_startup，默认为 true），CLI 也提供 codex update 子命令，官方说明是 “Update Codex to the latest version”。所以**「我昨天记的版本号和今天不一样」是正常的**；排查任何跟版本有关的问题，都必须以当次 codex --version 的实时输出为准，别拿记忆里的版本号讨论。

四、doctor 还能帮你发现「配置根本没加载」

有一个一手结论值得单独说，因为它决定了排查顺序。

在 codex-cli 0.147.0（Windows 11）上，故意用 -c 传一段语法不合法的 TOML（codex -c 'features=[unclosed' doctor --summary），命令并没有崩溃退出，doctor 照常跑完，只是在结果里出现了这一行：

✗ config       config could not be loaded - Fix the reported config error, then rerun codex doctor.

这意味着两件事。第一，配置写坏了不会给你一个响亮的报错让你立刻发现，它可能就是「静悄悄地没生效」。第二，「我改了配置怎么没反应」这个问题的第一步就该是跑 doctor 看 config 这一行，而不是反复改配置文件试。

对新手还有一条相关的：顶层选项 --strict-config 的作用是「config.toml 里出现本版本不认识的字段时直接报错退出」，听起来像是拼写检查器。但在 codex-cli 0.147.0（Windows 11）上实测，codex -c model_reasoning_effortt=high --strict-config exec --help 会正常打印 help，没有报未知字段错误。说明这个校验发生在真正加载配置去跑会话的路径上，--help 这类不进入会话的路径不触发。别把它当成「任何情况下都能拦住我的拼写错误」。

如果你要把诊断结果贴给别人看，codex doctor --json 的官方说明是 “Emit a redacted machine-readable report”——是脱敏过的。这一点对「能不能把体检结果贴到工单或 issue 里」有直接结论意义。

五、登录：先决定走哪一种认证

体检过了才轮到登录。官方给的是两种认证方式：

方式	说明
ChatGPT 登录	用 ChatGPT workspace 凭据，浏览器完成认证；遵循 workspace 权限、RBAC 与企业留存设置
API Key	需要 OpenAI 控制台的 API key，按标准 API 费率通过 OpenAI Platform 账户计费

选哪个的判断依据其实很清楚：你是拿公司/个人的 ChatGPT 账号在用，就走 ChatGPT 登录；你是要把它接进按 API 计费的流程里，就走 API Key。 前者会跟着 workspace 的权限与留存策略走，这对企业环境是加分项也是约束项，得提前和管理方对齐。

CLI 侧的入口：

codex login

用 API key 的话，官方给的写法是从 stdin 读：

printenv OPENAI_API_KEY | codex login --with-api-key

请注意这个写法的意图——key 是通过管道传进去的，不是打在命令行参数里，所以不会留在 shell 历史里。你自己写脚本时也保持这个形式，示例里一律用 <YOUR_API_KEY> 占位，别把真 key 写进任何会被提交的文件。codex login --help 里还有一个 --with-access-token，官方示例是 printenv CODEX_ACCESS_TOKEN | codex login --with-access-token。

查状态就一条：

codex login status

在 codex-cli 0.147.0（Windows 11）上，本机这条命令输出一行 Logged in using ChatGPT。这行是你确认「到底登的哪种」的最快方式。

凭据存在哪？ 两种之一：~/.codex/auth.json（明文文件），或者操作系统的凭据存储（keyring / Windows 凭据管理器）。控制它的配置项是：

cli_auth_credentials_store = "keyring"  # 可选 file | keyring | auto，默认 auto

官方对 auth.json 的原话是：“Treat ~/.codex/auth.json like a password: it contains access tokens. Don’t commit it, paste it into tickets, or share it in chat.” 翻成人话就是：它等同于密码，别提交、别贴进工单、别发到群里。新手最容易犯的就是排查问题时把整个 ~/.codex/ 目录打包发给同事——里面就有它。

六、几个装机阶段就会撞上的特殊情况

在没有浏览器的机器上装（服务器、容器）。 官方首选是设备码登录（beta 阶段）：

codex login --device-auth

按提示打开浏览器链接并输入一次性验证码。官方还给了两条备选：从有浏览器的机器上复制已缓存的凭据；或者用 SSH 隧道把 localhost 回调端口 1455 转发过去。

公司网络里登录失败。 如果你的网络有 TLS 代理或私有根 CA，官方的做法是在登录前设置环境变量 CODEX_CA_CERTIFICATE。另外，登录失败的诊断信息会写进配置的日志目录里的 codex-login.log——排查登录问题就去看这个文件，别对着终端上那一句报错猜。

装完发现磁盘涨得快。 这是真实存在的运维问题，不是错觉。在 codex-cli 0.147.0（Windows 11）上，doctor 的 Notes 区就提示了 rollouts 占用（本机为 405 active files · 3.07 GB on disk），~/.codex/ 下的 SQLite 日志库本机单个文件达到 763 MB。装机时可以先心里有数，尤其是系统盘紧张的笔记本。

七、这篇不管的部分

说清楚边界，免得你按这篇的思路去套不适用的场景：

桌面应用、IDE 扩展、Codex cloud 的安装与登录不在本文覆盖内。 CLI 的 codex app 子命令在 help 里的说明是 “Launch the Desktop app (opens the app installer if missing)“，但桌面应用本身我们没有实测；官方文档给的做法是，桌面应用在登出界面选 “Continue to sign in”（ChatGPT）或 “Sign in another way”（API key），IDE 扩展则是 “Sign in with ChatGPT” 或 “Use API Key”。这几处以官方文档为准。
企业 SSO 的具体配置、access token 的有效期、多账号切换，这几件事本文没有依据，不做猜测。
本文所有标注「本机实测」的内容都来自只读命令（--help、doctor、login status、故意构造的错误参数等），我们没有发起过任何模型对话请求，所以这里不会出现任何耗时、消耗或模型表现方面的数字。
特性阶段与默认值会随版本变。文中带版本号的结论只对 codex-cli 0.147.0 成立，你在自己机器上的第一步永远是 codex --version 加 codex doctor。

把顺序记住就行：选一种安装方式并且只用这一种 → codex --version 确认版本 → codex doctor --summary 看 runtime / install / config / auth 四行 → 再决定走哪种登录。这四步能省掉后面很多「明明装好了却不对劲」的时间。