Codex 安装与登录教程（Mac / Windows / Linux）

📚 系列导航：上一篇 Codex 核心概念教程 把 Codex 的几个关键词（代理、沙箱、审批、本地 / 云端）讲明白了。这一篇带你真正把它装到自己电脑上——桌面 App 和 CLI 两条线都覆盖，登录授权、三平台差异、常见装机故障一次说透。下一篇 Codex 订阅与计费说明 再聊钱的事。

Codex 安装教程要解决的不是“复制哪条命令”，而是帮你选对入口、装完能验证、登录卡住知道往哪修。macOS、Windows、Linux 都能用 CLI；macOS 和 Windows 还可以在 ChatGPT 桌面 App 里直接使用 Codex。

Codex 现在有网页版、ChatGPT 桌面 App、CLI 和 IDE 扩展几个入口。我自己从 CLI 一路用到桌面 App，最直观的感受是——装哪个、怎么装，官方说法跟你随手搜到的老教程经常对不上。

其实，装 Codex 本身不难，难的是没人告诉你哪条路是官方的正路、哪条是过时的坑。这篇就把每个平台、每种装法的正路标清楚，让你别重蹈我朋友的覆辙。

看完这一篇，你会拿到：

• ChatGPT 桌面 App 与 CLI 两条安装线，在 Mac / Windows / Linux 上各自怎么走（带预期输出，能自己验证装没装成功）
• CLI 三种装法（官方脚本 / Homebrew / npm）的对比，知道自己该选哪个
• 两种登录方式（ChatGPT 账号 / API key）的区别，以及远程 / 服务器环境登录卡住的标准解法
• 一份「报错 → 怎么修」的速查表，覆盖大多数新手会撞上的坑

安装前的准备工作

别急着敲命令。太多人装到一半才发现「原来这平台还没桌面版」「公司账号不让用本地 Codex」，白折腾。三件事先确认一下。

这张图先帮你把路口认清：想在本机装东西，盯住桌面 App、CLI 和 IDE 扩展三条本地线；网页版跑在云端，不属于这一篇的安装范围。

选择使用入口：桌面 App 还是 CLI

Codex 有四个入口，但安装这件事上，真正要选的是两条线：

• ChatGPT 桌面 App 里的 Codex：图形界面、点点就能用，适合不爱碰终端的人。目前桌面 App 提供 macOS 和 Windows 版本，Linux 用户先走 CLI。
• CLI（命令行）：跑在终端里的编程代理，三大平台全支持，也是开发者最常用的方式。

我的建议：开发者直接学 CLI，它最通用、跨平台没死角。 这篇以 CLI 为主线，桌面 App 单开一节讲下载和首次登录。装哪个先用都行——登录态在 CLI 和 IDE 扩展之间共享，桌面 App 则在自己的登录入口完成授权，后面的登录章节会讲。

准备 ChatGPT 账号或 OpenAI API key

新手最容易忽略的一条：Codex 跟着 ChatGPT 套餐走。

官方明确：ChatGPT 的 Plus、Pro、Business、Edu、Enterprise 套餐都包含 Codex 用量。你也可以不绑套餐、改用 OpenAI API key 按量付费——但用 API key 登录时，部分依赖 ChatGPT 工作区的功能会受限或不可用（比如云端 Codex 就强制要 ChatGPT 登录）。

用 API key 跑本地 CLI 是 OK 的，OpenAI 按标准 API 价格从你的 Platform 账户扣费，跟套餐里那份额度是两本账。

账号和计费的细节，下一篇 Codex 订阅与计费说明 专门展开。本篇默认你手里有一个能用的 ChatGPT 套餐或 API key。

确认 OpenAI 网络访问

Codex 不管哪个入口都要联网，而且会访问 chatgpt.com、platform.openai.com 等 OpenAI 服务。开装前先用你所在地区和组织允许的网络环境确认这些地址能正常打开；如果公司网络做了 TLS 检查或拦截，本地安装可能没问题，登录和实际跑任务却会卡住。

💡 一句话总结：开装前确认三件事——入口按场景选、账号是 ChatGPT 套餐或 API key、网络能正常访问 OpenAI 服务，这三关过了再敲命令。

在 ChatGPT 桌面 App 中使用 Codex（Mac / Windows）

不爱碰终端的，从 ChatGPT 桌面 App 里的 Codex 入门最省事。装完登录、选择本地项目并切到 Codex，就能在图形界面里发任务、看改动和审查结果。

类比：桌面 App 就像装了个「带工程目录的 ChatGPT」。 你平时用 ChatGPT 网页版怎么聊天，它就怎么聊；区别是它能绑定你电脑上的一个文件夹，在里面读文件、改代码、跑命令——相当于把聊天框、IDE 工程目录、长期记忆三样缝在了一起。

真实场景：

• 你是产品 / 设计，不写代码但想让 AI 帮你改个小需求、看看项目里某个功能怎么实现的。
• 你想多个项目并行——A 项目让它跑测试的同时，切到 B 项目继续提需求。
• 你想要图形化的「审查面板」一行行看它改了什么，再决定接不接受。

下载 ChatGPT 桌面 App 安装包

打开 ChatGPT 桌面 App 官方说明，下载对应平台的安装包：

首次登录并打开 Codex

装好打开 App，按三步走：

1. 登录：选择继续登录，按浏览器提示完成 ChatGPT 授权；也可以从其他登录方式中使用 API key。
2. 切到 Codex：在桌面 App 里选择 Codex，再挑一个想让它工作的本地项目文件夹。
3. 发第一条消息：确认任务跑在本地项目中，再把需求打进输入框。

第一次进去先别急着上手复杂功能，把注意力放在「对话」和「项目」两样上：对话就是你下任务的地方；项目绑定电脑上的一个文件夹，Codex 的本地操作围着它展开。界面会随版本调整，大致结构如下：

💡 一句话总结：桌面 App 目前走 macOS / Windows 两条线；装好就三步——登录、切到 Codex、选本地项目后发消息。

Codex CLI 安装方法（Mac / Windows / Linux）

先给结论：所有平台都优先用官方安装脚本（standalone installer，独立安装器）。它不依赖 Node.js，下个独立二进制就能跑，最干净。

类比：官方脚本就像应用商店「一键安装」。 点一下，它自己下载、自己放到位、不挖你系统其它东西；老的 npm 方式更像「先装个包管理器、再用它装应用」——多一层依赖（Node.js），多一处可能出岔子的地方。

图里右边这条就是本节主线：装好 codex 命令、完成登录、看到终端界面。左边桌面 App 的路线刚讲完，两条路最后都要落到“身份验证成功，能发任务”。

macOS 和 Linux 安装 Codex CLI

打开终端，粘这一行：

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

网络提示：如果下载卡住或超时，先确认当前网络允许访问 chatgpt.com。公司网络还可能因为代理或企业证书拦住 TLS 连接，别一上来就怪安装脚本。

预期结果：安装器打印完成信息和 codex 所在目录。若它提示需要把 ~/.local/bin 加进 PATH，按提示做完，再开一个新终端验证。

如果是写自动化脚本、CI 里无人值守安装（不想要任何交互提示），官方提供了一个环境变量：

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

Windows 原生安装 Codex CLI

在 PowerShell 里跑（提示符长这样 PS C:\>）：

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

预期结果：安装器把 codex 放进用户安装目录，并提示安装完成。完成后新开 PowerShell，别在旧窗口里死磕找不到命令。

无人值守版本（CI / 脚本）：

$env:CODEX_NON_INTERACTIVE=1; irm https://chatgpt.com/codex/install.ps1 | iex

这里 -ExecutionPolicy ByPass 是临时放行一次脚本执行，不会永久改你系统的策略；irm（Invoke-RestMethod）拉下脚本，iex（Invoke-Expression）执行它。看到 irm is not recognized 说明你跑在 CMD 里了，去开一个 PowerShell 窗口。

Homebrew 和 npm 安装 Codex CLI

官方脚本之外还有两条备选道，列个对比按需挑：

Homebrew Cask 的版本可能和官方独立安装器不同步，所以别把“brew 显示最新版”自动等同于“Codex 官方刚发布的版本”。安装前看一眼 brew info --cask codex，心里有数就行。

Homebrew（macOS）：

brew install --cask codex

npm（任意平台，需先有 Node.js）：

npm install --global @openai/codex

几个坑提前说：

• npm 那条要不要加 sudo，看你的 Node 环境。很多老教程直接写 sudo npm install -g，但 sudo 全局装 npm 包是出了名地容易留下权限烂摊子。我自己的习惯是——用 nvm / Volta 把 Node 装在用户目录下，全程不碰 sudo；真撞上权限报错，与其 sudo 硬怼，不如直接换官方脚本那条路，根本不经过 npm。
• Homebrew 是 --cask 不是普通 formula，别漏掉 --cask，也别写成别的包名——包名就是 codex。

💡 一句话总结：CLI 闭眼选官方脚本，Mac/Linux 用 curl ... | sh，Windows 用 irm，独立二进制不依赖 Node；Homebrew / npm 是备选，npm 尽量别 sudo。

Windows 安装 Codex：原生与 WSL2 选择

Windows 是 Codex 三平台里讲究最多的一个，单开一节说清。

先给选择：默认从原生 Windows 开始，需要 Linux 原生工具链或项目本来就在 WSL2 时再进 WSL2。 选对以后，代码放在对应文件系统里，别让 Windows 和 Linux 两边来回拖慢。

官方给了三种实际跑法：

• 原生 Windows + elevated 沙箱：首选。用专门的低权限沙箱用户、文件系统边界、防火墙规则把 Codex 圈在工作目录里，安全性最强。
• 原生 Windows + unelevated 沙箱：退路。当公司电脑策略不让做 elevated 那套管理员级配置时用，比 elevated 弱一些但仍有保护。
• WSL2（Windows 里的 Linux 子系统）：跑在 Linux 环境里，用 Linux 那套沙箱。需要 Linux 原生工具链、或你的代码仓库本来就在 WSL2 里时选它。

官方对照表：

几条硬提醒：

• Windows 版本：官方推荐 Windows 11；Windows 10 是「尽力支持」，要求 1809 或更新（依赖 ConPTY 等现代控制台组件），更老的 Win10 不推荐。
• winget 得能用：缺了就先更新 Windows 或装上 Windows 包管理器。
• WSL1 已经不支持了：从 Codex 0.115 起 Linux 沙箱换成了 bubblewrap，WSL1 在 0.114 之后就被砍了，要用就上 WSL2。

走 WSL2 的话，按三步来：

1. 在管理员 PowerShell 里安装默认 Linux 发行版：

   wsl --install

2. 重启系统（如果 Windows 提示需要），再进入 WSL：

   wsl

3. 提示符变成 Linux 样式后，安装并启动 Codex：

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

   预期结果：Codex 在 WSL 的 Linux 环境里启动，而不是回到 PowerShell 里运行。

一个 WSL 性能坑：别把代码仓库放在 /mnt/c/... 这种 Windows 挂载路径下，I/O 会明显慢，还容易出 symlink、权限问题。放在 Linux 主目录（如 ~/code/my-app ）下最快。需要从 Windows 访问这些文件时，去资源管理器输 \\wsl$ 进去找。

上面这张图就一句话：优先原生 elevated，被公司策略卡了退到 unelevated，需要 Linux 环境才上 WSL2。

💡 一句话总结：Windows 首选原生 + elevated 沙箱，被策略卡住退到 unelevated，要 Linux 环境才上 WSL2；注意 WSL1 已被砍、Win11 最稳。

验证 Codex 是否安装成功

CLI 装完别急着用，花十秒确认一下。重新打开终端再查版本，既能验证二进制装好了，也能顺手确认 PATH 已经生效；看到 codex-cli 和版本号，这条安装链路就算跑通。

1. 关闭刚才用于安装的终端窗口，再打开一个新窗口。

2. 运行版本检查：

   codex --version

3. 确认输出是一行版本信息。数字会随着更新变化，正常：

   codex-cli x.y.z

看到版本号 = 装成功了。 如果报 command not found: codex（Windows 上是 'codex' is not recognized ），先别重装——大概率是 PATH 没配好（安装目录没进系统搜索路径），后面的常见报错章节有修法。

如果你装的是支持自更新的版本，还可以运行 codex update 检查更新；某些包管理器安装的版本仍应交给对应包管理器升级。拿不准就先跑 codex --help，它比一篇写死旧命令的教程靠谱。

桌面 App 和独立 CLI 可能带着不同的 Codex 版本，功能对不上时别先怀疑自己眼花，先分别更新 App 和 CLI。

💡 一句话总结：CLI 用 codex --version 出版本号就成了；升级 / 版本参数以官方和 codex --help 为准，别迷信老教程里写死的命令。

Codex 登录方式与授权

装好的 Codex 还是个「不认识你」的空壳，得登录绑上账号才能干活。多数人直接用 ChatGPT 账号；自动化或按 API 用量计费的场景才选 API key。登录成功后用 codex login status，能看见当前认证方式。

先在你的项目目录里启动 CLI：

codex

没有有效登录态时，它会默认引导你用 ChatGPT 登录，弹出浏览器走授权流程，授权完浏览器把凭据送回 CLI，就登上了。想把登录单独做完，也可以直接运行 codex login。

ChatGPT 账号登录 vs API key 登录：如何选择

我自己日常开发用 ChatGPT 账号登录——套餐里那份额度够用，还能用上云端任务。API key 我只在写自动化脚本、放进 CI 时才用，因为它不需要浏览器交互，适合无人值守；但官方也提醒：别把带 API key 的 Codex 跑在不可信或公开环境里。

如果你明确要用 API key，别把 key 直接拼在 codex login 后面。先用你系统的安全方式或密钥管理工具放进 OPENAI_API_KEY，再通过标准输入交给 Codex：

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

PowerShell 对应写法：

$env:OPENAI_API_KEY | codex login --with-api-key

登录后检查一次：

codex login status

预期结果：状态里能看到当前认证方式。key 本身不会被重新打印出来；如果终端回显完整密钥，先停下来检查你是不是把命令写错了。

Codex 登录凭据存储位置

登录成功后，凭据缓存在本地，下次启动直接复用，不用重登。两个关键点：

• CLI 和 IDE 扩展共享同一份登录缓存——在一边登出，另一边下次启动也得重登。
• 缓存存在本地明文文件 ~/.codex/auth.json 里，或 OS 系统凭据存储里（macOS 上可能走 Keychain）；用 cli_auth_credentials_store 可指定 file、keyring 或 auto，具体写法见 Codex config.toml 配置详解。

⚠️ ~/.codex/auth.json 里装着你的 access token，把它当密码看：别提交进 Git、别贴进工单、别发到聊天里。

ChatGPT 登录的会话，Codex 会在过期前自动刷新 token，所以正常用着一般不用反复登。

远程服务器和 WSL 登录 Codex

这是开头我朋友踩的那个坑：在远程服务器、headless 环境、或本机网络挡了 localhost 回调时，浏览器登录这条路走不通——要么浏览器开在另一台机器上，要么 OAuth 回调回不来。官方首选解法是设备码登录（Device Code Login）。

在交互登录界面选 Sign in with Device Code，或直接运行：

codex login --device-auth

这是测试版（beta）功能。它会给你一个链接和一次性验证码，你在任意能上网的浏览器打开链接、输码，就登上了，完全不依赖服务器有没有图形界面。

设备码登录是否可用，还会受个人安全设置或工作区管理员策略影响。如果命令没有给出设备码，先确认账号和工作区允许这种登录方式；仍然失败时查看 Codex 的登录诊断日志，再交给管理员或官方支持，比手工搬运 auth.json 安全。

我后来给那位朋友就是用的设备码登录——一行 codex login --device-auth，复制链接到自己电脑浏览器、贴个码，三十秒搞定，比之前傻等浏览器弹窗强太多。

💡 一句话总结：默认用 ChatGPT 账号登录，凭据可能存在 ~/.codex/auth.json 或系统凭据库里；远程 / 服务器环境记住 codex login --device-auth，走不通再检查账号和工作区策略。

Codex 首次运行流程

光装好不算数，实际跑一遍确认链路通。这个最小流程不依赖已有项目，新建一个 Git 目录就能做；最后看到 test.py 和 Git 变更，才算安装、登录、执行三段都通了。

1. 创建测试目录，并初始化 Git。

   mkdir codex-test && cd codex-test
   git init

   预期结果：终端提示已经初始化空仓库。这样做还有个好处——Codex 在版本控制目录里通常会采用适合日常开发的工作区写入边界。

2. 启动 Codex。

   codex

   第一次启动会引导你登录，按前面的登录步骤走完。看到终端界面和输入框，就能发第一条任务。

3. 让它干件实事。

   在 test.py 里写一个打印 hello world 的函数

   预期结果：日常 workspace-write 边界下，Codex 可以直接在当前工作区创建 test.py；只有动作要越过沙箱边界，或者你的权限档位更严格时，它才会停下来问。别把“没有每次弹 Yes”误会成权限失效，这恰恰是沙箱和审批两个旋钮在各管各的。

4. 退出并检查结果。

   按 Ctrl + C 或输入 /exit 退出，再运行：

   git status --short

   看到类似 ?? test.py，说明文件已经创建，而且 Git 能把这次改动照出来。打开 test.py 看一眼内容，别只确认“有文件”，还要确认它写的是你刚才要的函数。

到这步，你已经完整跑通了「装 → 登录 → 给指令 → Codex 改文件 → Git 看结果」的全流程。我头一回碰到审批弹窗时，确实有种“这玩意儿真能干活、而且知道出门前敲门”的实感；但敲不敲门看边界，不是每改一行都来烦你。

⚠️ 这个空目录只是试车场。进真实项目之前，先确认 git status 干净并提交现有改动；那才是能让你放心回退的“Codex 动手前检查点”。

💡 一句话总结：新建 Git 目录就能跑通全流程——codex 启动登录、大白话下指令、git status --short 验结果；真实项目里先打 Git 检查点，再让它动手。

Codex 常见安装报错与解决方法

装这东西报错基本逃不掉，但绝大多数有标准解法。把最高频的几类整理成速查表——先对症，再下药，别一报错就重装。

挑两个最高频的展开说。

报错：command not found: codex

跑 codex 说找不到命令——不是没装上，是装好的目录没进系统搜索路径（PATH）。

类比：PATH 就是系统的「门牌号清单」。 程序装好好比房子盖好了，但系统只会去清单上登记过的地址挨个找。codex 的房子盖好了，地址却没登记进清单，自然喊它不应。

修法（macOS 默认是 Zsh，先确认安装脚本把 codex 放在哪个目录，再把那个目录加进 PATH）：

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

上面假设安装目录是 ~/.local/bin ；你实际的目录以安装脚本的输出提示为准（脚本装完通常会打印它放到了哪、要不要你手动加 PATH）。Linux 大多默认 Bash，把 ~/.zshrc 换成 ~/.bashrc 。Windows 则把对应安装目录加进用户 PATH 环境变量，然后重启终端。

改完验证：

codex --version

出版本号就修好了。

报错：多个 codex 安装版本冲突

如果先 npm 装过、又官方脚本装一遍，可能同时存在好几个 codex，版本对不上、行为诡异，甚至卸载后还能跑。先看看 PATH 上有几个：

which -a codex

列出来不止一个，只留你想用的那个（一般是官方脚本装的），其余删掉。比如卸掉 npm 全局安装：

npm uninstall -g @openai/codex

很多时候 which -a codex 一跑，就会发现 npm 和官方脚本各装了一个在抢同一个命令名——删掉多余的、理顺 PATH，瞬间清静。我自己就吃过这亏：先用 npm 装着玩，后来换官方脚本，结果 codex --version 显示的一直是那个老的 npm 版本，查了半天才发现 PATH 里 npm 的目录排在前面。

💡 一句话总结：报错先查表对因，别条件反射重装；找不到命令多半是 PATH，行为诡异 / 卸不干净多半是装了好几个在打架，which -a codex 一照便知。

小结：

这一篇把「装好并用起来」彻底过了一遍：

• 装前确认三件事：入口按场景选、账号是 ChatGPT 套餐或 API key、网络能正常访问 OpenAI 服务。
• 两条安装线：ChatGPT 桌面 App 提供 macOS / Windows 版本；CLI 三平台全有，认准官方脚本（curl ... | sh / Windows irm），Homebrew、npm 是备选。
• Windows 讲究多：首选原生 + elevated 沙箱，被策略卡住退到 unelevated，要 Linux 环境才上 WSL2；WSL1 已被砍。
• 登录默认走 ChatGPT 账号，凭据放在 ~/.codex/auth.json 或系统凭据库；远程 / 服务器记住 codex login --device-auth。
• 报错先查表对因：找不到命令查 PATH，行为诡异查多重安装。

这篇 Codex 安装教程走到这里，你应该能在自己机器上独立装好 Codex（App 或 CLI）、登录、跑通第一个例子，遇到常见报错也知道往哪查。

常见问题

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

不必须。官方独立安装脚本会直接安装可执行文件，不依赖 Node.js；只有你主动选择 npm install --global @openai/codex 这条备选路线时，才需要先有 Node.js。怕 Node 版本和全局权限绕成一团，直接走独立安装器最省心。

Windows 安装 Codex 必须使用 WSL2 吗？

不必须，原生 Windows 才是多数人的起点。项目和工具链本来就在 Linux 环境里，或者原生沙箱在你的公司电脑上实在配不起来时，再用 WSL2；WSL1 已经不支持。

官方安装脚本把 codex 命令放在哪里？

默认情况下，macOS / Linux 放在 ~/.local/bin，Windows 放在 %LOCALAPPDATA%\Programs\OpenAI\Codex\bin。如果你设置过 CODEX_INSTALL_DIR，就以自定义目录为准；报 command not found 时，先检查这个目录有没有进 PATH。

ChatGPT 桌面 App 和 Codex CLI 可以同时安装吗？

可以，它们是不同入口，不会因为同时存在就互相顶掉。只是桌面 App 和独立 CLI 可能包含不同版本，某个功能一边有、一边没有时，先分别更新，再判断是不是入口差异。

codex --version 正常，为什么还是登录失败？

版本号正常只说明安装和 PATH 已经通了，登录还要经过网络、浏览器回调和账号策略。远程服务器优先试 codex login --device-auth；本地仍失败时，再检查 OpenAI 服务访问、企业证书和工作区登录限制。

下一篇 Codex 订阅与计费说明：装好只是拿到了工具，先把 ChatGPT 套餐额度和 API key 计费算明白，才能放开手用。