先给答案:Codex 有三种形态,全部从 OpenAI 官方渠道下载。 终端用的 Codex CLI 当前最新版是 0.167.2(2026 年 11 月 12 日 06:50 北京时间发布到 npm),用官方安装脚本或 npm install -g @openai/codex 一条命令就能装;编辑器里用的是 VS Code 扩展市场里发布者为 OpenAI、ID 为 openai.chatgpt 的「Codex」插件;桌面版集成在 ChatGPT 桌面 App 里,macOS、Windows、Linux 都有。
不要去网盘或第三方站点下所谓的「Codex 安装包」。下面的表格和命令都对应官方来源,版本号是我们发文当天核对过的。
2026 年 11 月 12 日 17:17(北京时间,UTC+8),我们在一台 Linux x64(Debian 13,Node 24.22.2,npm 11.19.1)上把四种 CLI 下载方式都重新跑了一遍,记录耗时和 codex --version 的输出,并用 AI Code With 的 Key 跑了一个真实的 codex exec 任务。测试机在海外,下载耗时只代表这台机器的网络,国内网络的处理方法见后文。
一张表看懂:Codex 各形态从哪下
| 形态 | 官方下载方式 | 当前版本 | 适合谁 |
|---|---|---|---|
| Codex CLI | 官方安装脚本 / npm @openai/codex / Homebrew / GitHub Releases | 0.167.2 | 习惯终端、要写脚本或接 CI 的开发者 |
| VS Code 插件 | VS Code 扩展市场,扩展 ID openai.chatgpt | 26.51106.51428 | 想在编辑器侧边栏里改代码的人 |
| 桌面版 | ChatGPT 桌面 App(内含 Codex) | 以官网下载页为准 | 想用图形界面管多个项目的人 |
插件版本号来自 VS Code 扩展市场,最后更新于 2026 年 11 月 11 日;CLI 版本号来自 npm、GitHub Releases 和 Homebrew,三处都是 0.167.2。官方入口:CLI 文档在 developers.openai.com/codex/cli,插件页面在 VS Code 扩展市场,桌面版在 chatgpt.com/download。
Codex CLI 下载:按系统选命令
| 系统 | 推荐命令 | 备选 |
|---|---|---|
| macOS | curl -fsSL https://chatgpt.com/codex/install.sh 管道给 sh | brew install --cask codex 或 npm |
| Linux | curl -fsSL https://chatgpt.com/codex/install.sh 管道给 sh | npm 或 GitHub Releases 的 tar.gz |
| Windows | PowerShell 运行 install.ps1 | npm 或 GitHub Releases 的 exe / zip |
方式一:官方安装脚本(OpenAI 文档首推)
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"
脚本会先识别系统和 CPU 架构,从 releases.openai.com/codex 下载,连不上时自动回退到 GitHub Releases(这是我们读脚本源码确认的)。升级也是同一条命令。
实测:安装脚本用时 4.5 秒,输出 Resolved version: 0.167.2,程序装进 ~/.codex/packages/standalone/releases/0.167.2-x86_64-unknown-linux-musl,并把 ~/.local/bin 写进了 ~/.profile 的 PATH。脚本最后提示当前终端要先执行 export PATH="$HOME/.local/bin:$PATH",新开的终端直接能用。装完后 ~/.codex 目录约占 516 MB 磁盘。
方式二:npm
已经装了 Node.js 的话,npm 最省事:
npm install -g @openai/codex
codex --version
包名是 @openai/codex,带 @openai/ 前缀,npm 上名字相近的其他包都不是官方的。
实测:清空 npm 缓存后从 registry.npmjs.org 安装,用时 3.8 秒,输出 added 2 packages,codex --version 返回 codex-cli 0.167.2。两个包是一个很小的启动器加上对应平台的程序包(Linux x64 版解压后约 458 MB)。
方式三:Homebrew(macOS)
brew install --cask codex
Homebrew 上的 cask 名就是 codex,当前版本 0.167.2,安装包直接取自 OpenAI 的 GitHub Releases,详情见 formulae.brew.sh/cask/codex。
方式四:GitHub Releases 直接下安装包
想要离线安装包,或者公司电脑不能跑脚本,打开 github.com/openai/codex/releases/latest(当前是 rust-v0.167.2),按平台选文件:
| 平台 | 文件名 | 大小 |
|---|---|---|
| Apple Silicon Mac | codex-aarch64-apple-darwin.tar.gz | 108.6 MB |
| Intel Mac | codex-x86_64-apple-darwin.tar.gz | 117.9 MB |
| Linux x86_64 | codex-x86_64-unknown-linux-musl.tar.gz | 122.6 MB |
| Linux arm64 | codex-aarch64-unknown-linux-musl.tar.gz | 114.4 MB |
| Windows x64 | codex-x86_64-pc-windows-msvc.exe.zip | 206.4 MB |
| Windows arm64 | codex-aarch64-pc-windows-msvc.exe.zip | 192.0 MB |
同一页还有 codex-app-server-*、codex-exec-server-*、codex-symbols-* 等文件,那些是给桌面端、服务端和调试用的,日常只下上表这一个就够。
Linux 上实测:下载 122.6 MB 的压缩包用时 1.0 秒,解压出一个约 320 MB 的单文件 codex-x86_64-unknown-linux-musl,加执行权限后直接运行 --version,返回 codex-cli 0.167.2。把它改名为 codex 放进 PATH 里的目录即可:
tar xzf codex-x86_64-unknown-linux-musl.tar.gz
chmod +x codex-x86_64-unknown-linux-musl
mv codex-x86_64-unknown-linux-musl ~/.local/bin/codex
codex --version
下载完想要更详细的分系统安装步骤(PATH、权限、WSL),看《Codex 安装教程》。
Codex VS Code 插件下载
官方插件在 VS Code 扩展市场,名称「Codex – OpenAI's coding agent」,发布者 OpenAI(已验证域名),扩展 ID openai.chatgpt,当前版本 26.51106.51428,安装量约 1667 万。
- 网页地址:marketplace.visualstudio.com/items?itemName=openai.chatgpt
- 在 VS Code 扩展面板里搜
openai.chatgpt,认准发布者 OpenAI - 命令行安装:
code --install-extension openai.chatgpt
按 OpenAI 的 IDE 文档,Cursor、Windsurf、VS Code Insiders 用的是同一个插件;Xcode 和 JetBrains 系列 IDE 不装这个插件,而是在各自的 AI 助手里选择 Codex。装好后点侧边栏的 Codex 图标;看不到图标时,打开命令面板运行 Codex: Open Codex Sidebar。
Windows 上插件装好了却没反应,官方文档给的原因是缺少 C++ 运行组件:安装 Visual Studio Build Tools(C++ 工作负载)和 Microsoft Visual C++ Redistributable(x64)后完全重启 VS Code。插件里怎么接入 API Key、怎么排错,见《Codex VS Code 怎么用(Windows)》。
Codex 桌面版下载
Codex 桌面版现在就是 ChatGPT 桌面 App,不需要单独下载一个叫 Codex 的程序:
- 从 chatgpt.com/download 下载 ChatGPT 桌面 App,官方桌面 App 文档写明支持 macOS、Windows 和 Linux;
- 打开 App 登录后选择 Codex,点 New chat 新建对话,再选一个本地文件夹就能开始;
- Windows 版可以直接在 PowerShell 和 Windows 沙盒里运行,不需要 WSL,细节见 OpenAI 的 Windows 文档。
装完先校验:版本号和装了几份
codex --version
which -a codex
Windows PowerShell 用 Get-Command codex -All。
codex --version 返回 codex-cli 0.167.2 就说明拿到的是当前最新版。which -a 用来查有没有装重复:我们在已有 npm 版的机器上再跑安装脚本时,脚本提示 Detected existing npm-managed Codex 和 Multiple managed Codex installs can be ambiguous because PATH order decides which one runs。也就是说,npm 装一份、脚本再装一份,终端运行的是 PATH 里排在前面的那份,升级了一份另一份不会变。建议只保留一种安装方式,卸掉多余的那份(npm 版用 npm uninstall -g @openai/codex)。
下载安装报错怎么办
npm 网络超时(FETCH_ERROR / network timeout)
我们把 npm 指向一个连不上的地址复现了这个错误,输出是:
npm error code FETCH_ERROR
npm error network timeout at: http://10.255.255.1/@openai%2fcodex
network timeout at: 后面就是 npm 实际在连的地址。先看它是不是你想用的源,再按顺序处理:
- 检查当前源:
npm config get registry,官方源是https://registry.npmjs.org/; - 需要代理时给 npm 设代理:
npm config set proxy http://127.0.0.1:7890和npm config set https-proxy http://127.0.0.1:7890(端口以你的代理软件为准); - 网络不稳时调大超时:
npm install -g @openai/codex --fetch-timeout=120000; - 还是不行就换国内镜像源,见下一节,或者改用 GitHub Releases 的安装包。
国内下载慢或装不上:用 npm 镜像源
npm install -g @openai/codex --registry=https://registry.npmmirror.com
实测:通过 npmmirror 安装用时 5.4 秒,同样是 added 2 packages、codex-cli 0.167.2,镜像已经同步到当天的新版本。只想这一次用镜像,就像上面这样加 --registry 参数;不建议把全局源永久改掉,否则以后发布或安装别的包也会走镜像。镜像偶尔会比官方源晚几个小时,装完用 codex --version 对一下版本号。
官方安装脚本在国内也可能卡在下载步骤。它支持系统代理:先 export HTTPS_PROXY=http://127.0.0.1:7890 再跑 curl ... | sh;或者直接改用上面的 npm 镜像。
EACCES: permission denied
在 macOS、Linux 上用系统自带的 Node 时,全局安装目录属于 root,普通用户安装会报:
npm error code EACCES
npm error syscall mkdir
npm error path /usr/local/lib/node_modules/@openai
npm error Error: EACCES: permission denied, mkdir '/usr/local/lib/node_modules/@openai'
这是我们在测试机上用普通用户装到 /usr/local 时拿到的原文。npm 官方给的修法是不要用 sudo,而是二选一:用 nvm 这类 Node 版本管理器重装 Node,或者把全局目录换到自己的主目录下(npm 官方说明):
mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
npm install -g @openai/codex
用 zsh 的把 ~/.bashrc 换成 ~/.zshrc。不想碰 npm 的,直接用官方安装脚本,它装在 ~/.local/bin,不需要 root。
Node 版本过低
@openai/codex 在 npm 上声明的最低要求是 Node 16。我们专门用 Node 14.21.3(自带 npm 6.14.18)装了一次:用时 17.4 秒,安装过程刷出一屏 npm WARN notsup Unsupported engine ... wanted: {"node":">=16"},但最后仍是 added 2 packages,codex --version 正常返回 0.167.2。原因是 Codex 本体是一个独立程序,Node 只负责下载和启动它。
所以看到这类 WARN 不代表安装失败。为了避免以后的版本真的不兼容,还是建议从 nodejs.org 装一个当前的 LTS 版本;装不了 Node 的,直接用安装脚本或 GitHub Releases 的安装包,它们都不依赖 Node。
装好了但提示 command not found
- 安装脚本:当前终端执行
export PATH="$HOME/.local/bin:$PATH",或关掉终端重开; - npm:用
npm prefix -g查全局目录,把它下面的bin(Windows 是这个目录本身)加进 PATH; - 然后用
which -a codex确认只有一份。
下载之后:接入 API Key,跑第一个任务
装好 Codex 后,第一次运行会让你选择登录方式。如果你在国内,或者想用一个 Key 同时在 Codex、Claude Code、Cursor 里调用模型,可以接入 AI Code With,步骤如下。
第一步,注册并在控制台创建一个 Key(图文步骤见创建 API Key 文档):
第二步,打开(没有就新建)~/.codex/config.toml(Windows 是 %USERPROFILE%\.codex\config.toml),写入下面这段,把 sk-你的Key 换成刚创建的 Key:
model_provider = "aicodewith"
[model_providers.aicodewith]
name = "aicodewith"
base_url = "https://api.aicodewith.ai/chatgpt/v1"
wire_api = "responses"
experimental_bearer_token = "sk-你的Key"
注意 base_url 末尾是 /chatgpt/v1。每个字段的含义见《Codex config.toml 配置指南》,Key 的其他写法(auth.json)见《Codex API Key 怎么配置》,代理和 CI 里怎么注入见《Codex 环境变量怎么配》。
第三步,在项目目录里跑一个小任务验证:
codex exec --skip-git-repo-check "calc.py 里 add 函数有 bug,修好它,然后用 python3 -c 运行 add(2,3) 验证,最后只回复一行结果"
实测:刚用 npm 装好的 0.167.2、全新的配置目录、只写上面这段 config.toml,测试文件里 add 故意写成 return a - b。Codex 启动时显示 provider: aicodewith,先读了 calc.py,把 a - b 改成 a + b,再运行 python3 -c 'from calc import add; print(add(2,3))' 得到 5,最后输出:
已修复,python3 -c 验证 add(2,3) = 5。
整个任务用时 13.8 秒;单独发一句 codex exec --skip-git-repo-check "reply OK",2.5 秒返回 OK。
跑通之后,日常怎么用看《Codex 怎么用》,国内网络和支付问题的完整说明看《国内使用 Codex》。
接入后报 401 或 429
- 报
401 Unauthorized:大多是 Key 没填完整、前后多了空格,或model_provider = "aicodewith"没写在文件最上面,见《Codex 401 Unauthorized 怎么解决》; - 报
429 Too Many Requests:请求太密或额度用完,见《Codex 429 Too Many Requests 怎么解决》。
常见问题
Codex 最新版本是多少?
截至 2026 年 11 月 12 日,Codex CLI 最新正式版是 0.167.2(npm、GitHub Releases、Homebrew 一致),VS Code 插件是 26.51106.51428。随时用 npm view @openai/codex version 查 npm 上的最新版。
npm 上哪个才是官方 Codex 包?
@openai/codex。安装命令是 npm install -g @openai/codex。
Codex 安装包在哪下载?
官方安装包在 GitHub Releases(github.com/openai/codex/releases),按系统选 tar.gz 或 zip 文件。网盘里转发的安装包无法确认来源,不要用。
VS Code 里搜 Codex 出来好几个,装哪个?
装发布者为 OpenAI、扩展 ID 为 openai.chatgpt 的那个。
桌面版要单独下载 Codex 吗?
不需要。Codex 桌面版就在 ChatGPT 桌面 App 里,下载 ChatGPT 桌面 App 即可。
怎么升级 Codex?
用哪种方式装的就用哪种方式升级:安装脚本重跑同一条命令;npm 用 npm install -g @openai/codex@latest;Homebrew 用 brew upgrade --cask codex。
国内下载太慢怎么办?
npm 加 --registry=https://registry.npmmirror.com,实测镜像已同步 0.167.2;或者给安装脚本设 HTTPS_PROXY。装好后要在国内正常对话,还需要一个能直连的 API 地址,可以按上文接入 AI Code With。
相关阅读
- 《Codex 安装教程》
- 《Codex 怎么用》
- 《Codex API Key 怎么配置》
- 《Codex config.toml 配置指南》
- 《Codex 环境变量怎么配》
- 《Codex VS Code 怎么用(Windows)》
- 《国内使用 Codex:网络连不上、没有海外信用卡怎么解决》



