安装 Codex CLI,最重要的不是把一条命令粘进终端,而是三件事:确认命令来自官方,安装后系统能找到 codex,并且版本和帮助信息都能正常输出。只要这三项都通过,后面的登录、配置 API Key 和使用就都有了可靠的起点。
这篇教程按操作系统拆开写,每个系统都给出安装命令、验证方法和常见问题。所有安装命令都来自 OpenAI Codex CLI 官方文档和 AI Code With 的 Codex 终端文档。如果你看到这里的命令和官方页面不一致,请以官方页面为准,因为安装方式会随着版本更新调整。
还没下载安装包?官方下载地址见《Codex 下载》。装好之后怎么用,看《Codex 怎么用》。
2026 年 10 月实测:当前版本和安装耗时
我们在 2026-10-26 用一台 Linux x64 机器把三条安装路线各跑了一遍,装完都执行 codex --version 确认版本。当天 npm 上的最新版本是 0.164.0(npm view @openai/codex version 的输出),官方安装脚本解析到的也是 0.164.0。
| 实测项 | 命令 | 耗时 | 输出 |
|---|---|---|---|
| 官方安装脚本 | curl -fsSL https://chatgpt.com/codex/install.sh | sh | 约 4.8 秒 | Codex CLI 0.164.0 installed successfully. |
| npm 官方源 | npm install -g @openai/codex | 约 4.2 秒 | codex-cli 0.164.0 |
| npm 国内镜像 | npm install -g @openai/codex --registry=https://registry.npmmirror.com/ | 约 4.3 秒 | codex-cli 0.164.0 |
| 接入本站后最小对话 | codex exec "只回复:安装成功" | 约 3.0 秒 | 返回「安装成功」 |
| 故意填错 Key | codex exec "hi" | 约 7.7 秒 | 重连 5 次后报 401(见报错对照表) |
耗时和网络环境关系很大,国内网络下官方脚本可能明显更慢,这时换 npm 镜像通常更快。0.164 这一版新增了哪些预设和推理强度切换,见《Codex CLI 0.164 更新:预设、模型与推理强度》。
安装前先选一条路线
OpenAI 目前提供四种安装入口:macOS/Linux 独立安装脚本、Windows 独立安装脚本、npm 和 Homebrew。它们装出来的都是同一个 Codex CLI,区别只在于依赖什么、以后怎么升级。
| 安装方式 | 适合谁 | 需要的前置条件 | 升级方式 |
|---|---|---|---|
| 官方安装脚本(macOS/Linux) | 不想装 Node.js 的用户 | curl 和能访问官方地址的网络 | 重新运行同一条安装命令 |
| 官方安装脚本(Windows) | Windows 用户首选 | PowerShell | 重新运行同一条安装命令 |
| npm | 已经在用 Node.js 的开发者 | Node.js 18+ 和 npm | npm install -g @openai/codex |
| Homebrew | macOS 上习惯用 brew 的用户 | Homebrew | brew upgrade --cask codex |
如果你在国内网络环境下,官方安装脚本有时下载不稳定,这时 npm 加国内镜像通常更顺。AI Code With 文档里给出的就是 npm 路线,要求 Node.js 版本为 18 及以上。
macOS 安装步骤
方式一:官方安装脚本
打开「终端」,执行官方给出的独立安装命令:
curl -fsSL https://chatgpt.com/codex/install.sh | sh
以后需要升级时,再运行一次同一条命令即可。
方式二:Homebrew
如果你已经装了 Homebrew,可以用官方提供的 cask 安装:
brew install --cask codex
升级命令是:
brew upgrade --cask codex
方式三:npm
先确认 Node.js 已经安装,并且版本在 18 以上:
node --version
npm --version
如果还没有 Node.js,可以按 AI Code With 文档的做法,用 Homebrew 安装:
brew install node
然后安装 Codex CLI。国内用户可以加上镜像参数:
npm install -g @openai/codex
npm install -g @openai/codex --registry=https://registry.npmmirror.com/
两条命令选一条执行就行,第二条走的是国内镜像。
macOS 验证安装
安装完成后,重新打开一个终端窗口,然后依次检查:
command -v codex
codex --version
codex --help
第一条能输出 codex 的路径,第二条能输出版本号,第三条能打印帮助信息,就说明安装成功了。成功的标准不是"安装器没有报错",而是这三条都能正常输出。
Windows 安装步骤
方式一:官方 PowerShell 安装脚本
OpenAI 官方文档建议从新开的 PowerShell 窗口里执行下面这条命令:
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"
不要长期照搬旧博客里的 PowerShell 命令。官方安装入口会更新,执行前最好打开官方页面确认一下当前命令。
方式二:npm
先去 Node.js 官网下载并安装 LTS 版本,然后按 Win + R,输入 powershell 打开 PowerShell,检查版本:
node --version
npm --version
确认 Node.js 版本在 18 以上之后,安装 Codex CLI:
npm install -g @openai/codex
国内用户可以改用镜像:
npm install -g @openai/codex --registry=https://npmreg.proxy.ustclug.org
如果 PowerShell 提示"在此系统上禁止运行脚本",AI Code With 文档给出的处理方式是:用管理员权限打开 PowerShell,执行 Set-ExecutionPolicy Unrestricted。这一步会放宽当前系统的脚本执行策略,请确认你理解它的影响后再操作。
Windows 验证安装
关闭当前 PowerShell,重新打开一个,然后检查:
Get-Command codex
codex --version
codex --help
如果 Get-Command codex 找不到命令,先不要重装,往下看"安装完却找不到 codex"一节。
Linux 安装步骤
方式一:官方安装脚本
Linux 和 macOS 用的是同一条独立安装命令:
curl -fsSL https://chatgpt.com/codex/install.sh | sh
方式二:npm
如果系统里还没有 Node.js,AI Code With 文档给出的 Debian/Ubuntu 安装方式是(需要 root 权限):
curl -fsSL https://deb.nodesource.com/setup_lts.x | bash -
apt-get install -y nodejs
确认版本后安装 Codex CLI:
node --version
npm install -g @openai/codex --registry=https://registry.npmmirror.com/
其他发行版请用自己的包管理器安装 Node.js LTS,然后执行同样的 npm 命令。
Linux 验证安装
command -v codex
codex --version
codex --help
如果你是在没有图形界面的服务器上安装,下一步登录时浏览器流程可能走不通,这种情况的处理方法写在后面的常见问题里。
为什么每次都要重新打开终端
很多"装好了却找不到命令"的问题,其实只是终端没有重新打开。终端在启动时会读取一次环境变量,安装程序往 PATH 里加的新目录,只对之后新开的终端窗口生效。已经开着的窗口还在用旧的 PATH,自然找不到刚装好的 codex。
所以本文每个系统的验证步骤,都要求先关掉当前窗口、重新打开一个再检查。如果你在 VS Code 等编辑器的内置终端里安装,同样需要关闭整个编辑器再打开,只新建一个终端标签页有时不够。
另外,Windows 上如果你一会儿用 PowerShell、一会儿用命令提示符或 Git Bash,它们读取的环境变量可能不一样。建议安装和使用都固定在 PowerShell 里,排查问题时会简单很多。
安装完却找不到 codex
这是安装阶段最常见的问题。原因通常不是"没装上",而是系统 PATH 里没有 Codex 所在的目录,或者当前终端还在用旧的环境变量。
先排查 PATH,macOS / Linux:
command -v codex
printf '%s\n' "$PATH"
Windows:
Get-Command codex -ErrorAction SilentlyContinue
$env:Path -split ';'
处理顺序建议是:先重新打开终端;还不行,再确认可执行文件实际装在哪个目录(npm 路线可以用 npm prefix -g 查看全局安装位置);最后只把这一个目录加进 PATH。不要把一个来源不明的目录整个加入系统 PATH。
安装后会多出哪些文件
装好并登录之后,Codex 会在你的用户目录下使用一个配置目录,默认是 ~/.codex(可以通过环境变量 CODEX_HOME 改到别的位置)。新手最需要知道的是两个文件:
config.toml:Codex 的配置文件,模型、Provider、权限等设置都写在这里;auth.json:登录缓存。官方文档说明,Codex 会把登录信息缓存在这个明文文件里,或者存进系统的凭据库。
如果你更希望把凭据放进系统凭据库,而不是明文文件,官方提供了 cli_auth_credentials_store 这个配置项,可选值有 file、keyring、auto 和 ephemeral:file 存在 auth.json 里;keyring 存进系统凭据库,凭据库不可用时会报错;auto 优先用凭据库,不可用时退回 auth.json;ephemeral 只在当前进程的内存里保存。个人电脑上用默认设置就够了;如果是多人共用的机器,建议考虑 keyring。
不管用哪种方式,都要记住:auth.json 里有访问令牌,等同于密码。不要把它提交到 Git 仓库,不要贴进工单,也不要发到群里。分享配置给同事时,只发 config.toml,并且先确认里面没有直接写入密钥。
公司网络和代理环境下安装
很多公司网络会经过 TLS 代理,或者使用私有根证书。这种环境下,安装脚本能下载成功,但第一次登录时可能报证书错误。官方给出的做法是:在登录之前,把环境变量 CODEX_CA_CERTIFICATE 设置为公司提供的 PEM 证书文件路径,然后再运行登录命令:
export CODEX_CA_CERTIFICATE=/path/to/corporate-root-ca.pem
codex login
如果没有设置 CODEX_CA_CERTIFICATE,Codex 会退回使用 SSL_CERT_FILE。这个证书设置同时作用于登录、普通 HTTPS 请求和 WebSocket 连接,所以设置一次就能覆盖后续的调用。证书文件请向公司 IT 部门索取,不要从网上随便下载。
另外,如果你需要通过代理才能访问外网,npm 路线可以先配置 npm 自己的代理,或者直接改用国内镜像,这通常比折腾系统代理更省事。
换一种安装方式之前,先卸载旧的
如果你一开始用 npm 装了,后来又想换成官方脚本或 Homebrew,最好先把旧的卸载掉,否则 PATH 里可能先找到旧版本,出现"明明升级了,版本号却没变"的情况。
npm 安装的,用 npm 卸载:
npm uninstall -g @openai/codex
Homebrew 安装的,用 Homebrew 卸载:
brew uninstall --cask codex
卸载后重新打开终端,用 command -v codex(Windows 用 Get-Command codex)确认已经找不到旧命令,再用新的方式安装。卸载 CLI 不会自动删除 ~/.codex 目录,你的配置和登录缓存还在,重新安装后可以直接继续使用。
第一次启动和登录
进入一个测试项目,再启动 Codex:
cd /你的/测试项目
codex
第一次运行时,官方文档说明你可以选择 Sign in with ChatGPT 或其他可用的登录方式。常见的两种是:
- ChatGPT 账号登录:运行
codex login,在弹出的浏览器里完成登录,用的是订阅额度。 - API Key 登录:官方给出的写法是
printenv OPENAI_API_KEY | codex login --with-api-key,走 API Key 的用量。
登录后可以用 codex login status 查看当前使用的认证方式。登录信息会缓存在本地的 ~/.codex/auth.json 或系统凭据库里,这个文件相当于密码,不要提交到 Git,也不要发给别人。
用 AICodeWith 的 API Key 接入 Codex
装好 Codex 以后,不用 codex login,直接在全局配置文件里加一个自定义 Provider 就能用本站的 Key。配置文件位置:macOS / Linux 是 ~/.codex/config.toml,Windows 是 %USERPROFILE%\.codex\config.toml。文件不存在就新建一个。
model = "gpt-6.1-sol"
model_reasoning_effort = "medium"
model_provider = "aicodewith"
[model_providers.aicodewith]
name = "aicodewith"
base_url = "https://api.aicodewith.ai/chatgpt/v1"
wire_api = "responses"
experimental_bearer_token = "你的 API Key"
几个容易填错的地方:
base_url是 Codex 专用地址https://api.aicodewith.ai/chatgpt/v1,不要换成其他客户端用的地址;name = "aicodewith"和model_provider = "aicodewith"要对应同一个 Provider;- Key 写在
experimental_bearer_token里,配置写在全局文件,不要放进项目仓库,也不要提交到 Git。
写好后在任意测试目录跑一次最小调用:
codex exec --skip-git-repo-check "只回复:安装成功"
我们实测的输出开头会打印当前使用的模型和 Provider,看到 provider: aicodewith 就说明配置生效了:
OpenAI Codex v0.164.0
--------
model: gpt-6.1-sol
provider: aicodewith
approval: never
sandbox: read-only
reasoning effort: medium
--------
user
只回复:安装成功
codex
安装成功
更完整的接入步骤和可用模型见 Codex 接入 AICodeWith,配置项的含义和优先级见《Codex config.toml 配置指南》。用起来以后额度怎么算、为什么有时掉得快,见《Codex 怎么收费、额度为什么掉得快》。
常见报错对照表
| 报错或现象 | 常见原因 | 解决方法 |
|---|---|---|
| command not found: codex / Get-Command 找不到 | 安装目录不在 PATH 里,或终端没有重新打开 | 重开终端;用 npm prefix -g 找到安装位置,只把这一个目录加进 PATH |
| npm: command not found | 没装 Node.js,或 Node.js 没加入 PATH | 先装 Node.js LTS,确认 node --version 和 npm --version 都能输出 |
| npm 安装后启动报错,Node 版本过低 | AI Code With 文档要求 Node.js 18+ | 升级 Node.js 到 LTS 版本后重装 |
| PowerShell 提示"在此系统上禁止运行脚本" | Windows 脚本执行策略限制 | 管理员 PowerShell 执行 Set-ExecutionPolicy Unrestricted(了解影响后再改) |
| npm 下载很慢或超时 | 访问 npm 官方源不稳定 | 加上 --registry=https://registry.npmmirror.com/ 等国内镜像 |
| 服务器上 codex login 打不开浏览器 | 无图形界面,或本地回调端口 localhost:1455 被拦截 | 用 codex login --device-auth 设备码登录,或用 SSH 转发 1455 端口 |
| 公司网络下登录报证书错误 | 企业 TLS 代理或私有根证书 | 登录前设置 CODEX_CA_CERTIFICATE 指向 PEM 证书文件 |
| 首次启动提示 "this folder is not version controlled" | 当前目录不是 Git 仓库,Codex 在确认权限 | 在测试目录可以按提示选择;正式项目建议先 git init 再用 |
| WARNING: Multiple managed Codex installs can be ambiguous because PATH order decides which one runs. | 官方安装脚本发现机器上已有 npm 装的 Codex | 留一种安装方式:先 npm uninstall -g @openai/codex,再用 command -v codex 确认实际调用的是哪一个 |
| unexpected status 401 Unauthorized: {"error":"请在请求中提供有效的 API Key。"} | experimental_bearer_token 填错、多了空格,或 Key 已停用 | 重新复制 Key 粘到配置里;报错前出现的 Reconnecting... 1/5 到 5/5 是 Codex 自动重试,不用等它 |
| 调用报 404 或路径错误 | base_url 少了 /chatgpt/v1,或填成了其他客户端的地址 | 改回 https://api.aicodewith.ai/chatgpt/v1,并确认 wire_api = "responses" |
| 装完提示要把 PATH 写进 shell 配置 | 官方脚本默认装到 ~/.local/bin,会把 PATH 追加到 ~/.profile | 按提示在当前终端执行一次 export,或者直接新开一个终端 |
如果装好之后调用时遇到 401 或 429,那就不是安装问题了,分别看《Codex 401 Unauthorized 怎么解决》和《Codex 429 Too Many Requests 怎么解决》。
常见问题
Codex CLI 安装需要 Node.js 吗?
不一定。官方独立安装脚本(macOS/Linux 的 install.sh、Windows 的 install.ps1)不依赖 Node.js;只有走 npm 路线时才需要,AI Code With 文档要求 Node.js 18 及以上。
Windows 上应该用哪种方式安装?
优先用官方 PowerShell 安装脚本。如果你已经在用 Node.js,或者官方脚本下载不稳定,可以改用 npm 加国内镜像。两种方式装出来的是同一个 Codex CLI。
怎么升级 Codex CLI?
用什么方式装的,就用什么方式升级:安装脚本重新运行一次;npm 再执行一次 npm install -g @openai/codex;Homebrew 用 brew upgrade --cask codex。升级后用 codex --version 确认版本号变了。
安装成功了,但启动后要求登录,该选哪个?
有 ChatGPT 订阅就选 ChatGPT 登录,用的是订阅额度;想走 API 用量或在 CI 里用,就用 API Key。如果你想用 AI Code With 的 Key,先注册账号,再按 Codex 配置文档写入 Provider 配置。
没有图形界面的 Linux 服务器怎么登录?
官方推荐设备码登录:运行 codex login --device-auth,在另一台有浏览器的设备上打开链接并输入一次性代码。也可以在本机登录后,把 ~/.codex/auth.json 复制到服务器上的同一位置。
可以同时装多个版本吗?
不建议。npm、Homebrew 和安装脚本混装,很容易出现 PATH 里先找到旧版本的情况。选定一种方式,另一种卸载掉,再用 command -v codex 确认实际调用的是哪一个。
现在最新的 Codex CLI 是哪个版本?
以 2026-10-26 为准,npm 和官方安装脚本给出的都是 0.164.0。版本更新很快,自己查最准:npm view @openai/codex version 看线上最新版,codex --version 看本机版本。
官方安装脚本能装指定版本吗?
据官方 install.sh 脚本源码,它读取环境变量 CODEX_RELEASE(默认 latest)决定装哪个版本,读取 CODEX_INSTALL_DIR(默认 ~/.local/bin)决定装到哪里。需要固定版本时,用 npm 写明版本号更直观:npm install -g @openai/codex@0.164.0。
npm 路线到底要求哪个 Node.js 版本?
npm 包自己声明的下限是 Node.js 16(npm view @openai/codex engines 的输出是 { node: '>=16' }),AI Code With 文档建议 18 及以上。直接装当前 LTS 最省事。
怎么确认 Codex 走的是 AICodeWith?
运行 codex exec 时输出开头会打印 provider: 一行,显示 aicodewith 就对了。交互模式下也可以在会话里看当前模型和 Provider。
配置 Key 以后还需要 codex login 吗?
不需要。用 experimental_bearer_token 配好自定义 Provider 后,Codex 直接用这把 Key 发请求,我们实测没有执行 codex login 也能正常对话。
下一步
装好之后,建议按这个顺序继续:
- 《Codex 怎么用:从启动到完成第一个可验收任务》:跑通第一个小任务;
- 《Codex API Key 怎么配置》:接入 API Key 和第三方 Provider;
- 《Codex config.toml 配置指南》:弄清配置文件位置和优先级。
- 《Codex CLI 0.164 更新》:了解当前版本的新功能。



